agentleFS
DeltologicDeltologic/datadoe-ai-skills/skills/ppc-bid-optimizer-apply/SKILL.md

ppc-bid-optimizer-apply

Skill8 starsChanged 45 days agoMITView on GitHub

Recompute Sponsored Products keyword bids toward a target ACoS and apply them through DataDoe Actions - always a dryRun preview first, and a real change only on your explicit approval. The write follow-through to the wasted-spend watchdog. Live from DataDoe, runs in chat. Use for "optimize bids", "fix ACoS", "lower my bids", "raise bids on winners", "adjust keyword bids", or "bid optimization".

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 3 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    After the Wasted-Spend Watchdog flags bleeders, to actually fix the bids.

    line 27
  2. Distinctive:

    Min bid floor 0.02: never set a bid below Amazon's practical minimum of 0.02 (the schema allows any value > 0, but < 0.02 is not …

    line 46
  3. Very specific:

    Read (performance), preferred when the org has it: amazon_ads_profit_by_target_and_date [premium] - per target/day: action_target_id (the …

    line 53
  4. Very specific:

    Read (performance), fallback: amazon_ads_search_terms_by_campaign_by_date - per keyword/day: ad_keyword_id, ad_keyword, ad_keyword_bid …

    line 64
  5. Very specific:

    Write: AMAZON_ADS_TARGETS_UPDATE action, gated behind a dryRun step.

    line 82
  6. Very specific:

    Performance: prefer amazon_ads_profit_by_target_and_date (premium export, 5 AI Tokens) when it has rows: filter is_attribution_mature = …

    line 109
  7. Very specific:

    UPDATE payload and by the table-sourced fallback).

    line 115
  8. Distinctive:

    Write skill. The live update needs the Action enabled and Read and write access.

    line 197

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

PPC Bid Optimizer (with apply)

Recomputes Sponsored Products keyword bids toward a target ACoS and applies them through DataDoe Actions - always dryRun first, real change only on your approval. The write follow-through to the Wasted-Spend Watchdog. MCP-native end to end.

When to use this

  • After the Wasted-Spend Watchdog flags bleeders, to actually fix the bids.
  • Weekly bid tuning toward a target ACoS.
  • Trigger phrases: "optimize bids", "lower my bids", "fix ACoS", "adjust keyword bids", "bid optimization", "reduce ad spend on losing keywords".

The framework. Target-ACoS bidding

For each keyword: new bid = current bid x (target ACoS / actual ACoS), clamped by the guardrails below.

  • ACoS too high (bleeder) -> cut bid toward target.
  • ACoS well below target + converting -> raise bid modestly to win volume.
  • Zero conversions / not enough clicks -> leave alone (insufficient data).

Bid guardrails (apply on every run):

  • Min clicks to act: skip any keyword with < 5 clicks in the window - too little signal to move a bid on.
  • Max change per run: cap the step at +/-30% of the current bid (default; user may raise to at most +/-50%) so one pass can't wildly swing a bid. One step per run - PPC needs time to settle; revisit next week.
  • Min bid floor 0.02: never set a bid below Amazon's practical minimum of 0.02 (the schema allows any value > 0, but < 0.02 is not actionable). Honour the user's own min/max if tighter.

Configuration

  • MCP base: https://mcp.datadoe.com/mcp/v1
  • Read (performance), preferred when the org has it: amazon_ads_profit_by_target_and_date [premium] - per target/day: action_target_id (the Ads targetId, ready for the UPDATE payload), ad_campaign_type (the table also holds Sponsored Brands, Display and Television targets - filter to SPONSORED_PRODUCTS), ad_campaign_id / ad_group_id (the UPDATE scope - keep them when grouping), target_entity_type (KEYWORD / PRODUCT_OR_AUTO_TARGET), ad_target_bid (latest fetched bid, keyword or target), ad_keyword_bid (bid recorded in the report, can be stale), estimated_break_even_acos (compare actual ACoS against it instead of a flat target when available), is_attribution_mature (skip rows where it is false instead of guessing a 7-day cut-off). Premium note: a premium export costs 5 AI Tokens instead of 2 - nothing else differs, and the table is part of the always-on default dataset, so it is never disabled. A 0-row export means no data in the window or an initial load still in progress - say which, and fall back to the source below; never render zeros. Note: estimated_break_even_acos is null when the account has no COGS uploaded - then use the user's target ACoS.
  • Read (performance), fallback: amazon_ads_search_terms_by_campaign_by_date - per keyword/day: ad_keyword_id, ad_keyword, ad_keyword_bid (current bid), ad_campaign_id, ad_group_id, ad_spend, ad_sales, ad_clicks, ad_orders, ad_match_type, ad_campaign_type. Aggregate by keyword for ACoS. NOTE: ad_sales / ad_orders are 7-day attributed - exclude ~the last 7 days (see the workflow) so recent under-attribution doesn't trigger over-aggressive cuts.
  • Resolve targetId + live bid: the AMAZON_ADS_TARGETS_FIND action returns the targetId and the live bid. Filter with adProductFilter.include: ["SPONSORED_PRODUCTS"] (FIND requires exactly one ad product) plus campaignIdFilter / keywordFilter / targetIdFilter. FIND is a read Action. It runs on a Seller or Vendor with Read only or Read and write access. Do not skip it because the account is Read only. Use the table fallback only when FIND is unavailable, for example when that Action type is disabled for the Organization: amazon_ads_profit_by_target_and_date.action_target_id is the Ads targetId (for Sponsored Products it equals ad_keyword_id on keyword rows and ad_target_id on auto/product rows), with ad_target_bid as the bid (else ad_keyword_bid) and ad_campaign_id / ad_group_id from the same grouped export (step 2) as the scope - flag those bids as table-sourced (up to a day stale). The real risk is a stale bid or the wrong campaign/ad group, not a different id.
  • Write: AMAZON_ADS_TARGETS_UPDATE action, gated behind a dryRun step. Confirmed payload shape (max 25 targets per action - schema maxItems: 25; split longer lists):
    actions_start(type="AMAZON_ADS_TARGETS_UPDATE", sellerOrVendorId="...", dryRun=true,
      details={"targets":[{"targetId":"<id>","campaignId":"<id>","adGroupId":"<id>",
        "adProduct":"SPONSORED_PRODUCTS","bid":0.21}]})
    bid must be a number with exclusiveMinimum: 0 and maximum: 999999999.99 (floor at 0.02 in practice). A dryRun: true call returns status: VALIDATED, valid: true, actionId: null - nothing is queued or sent to Amazon. marketplaceScope / marketplaces are accepted by TARGETS_UPDATE on Sponsored Products (dryRun 2026-10-03: VALIDATED with and without them) but are not needed - the targetId already scopes the change. Only AMAZON_ADS_TARGETS_ADD rejects them.
  • Live state, not snapshots: amazon_ads_targets_raw / amazon_ads_campaigns_raw / amazon_ads_ad_groups_raw are 72-hour snapshots. Never take the "current" bid from them before a write - read it live with AMAZON_ADS_TARGETS_FIND (step 3).
  • Inputs from user: target ACoS (e.g. 30%), min/max bid, max step (default +/-30%).
  • Prerequisites: AMAZON_ADS_TARGETS_FIND runs on Read only and Read and write accounts. The live apply needs Read and write (Accounts page), and the AMAZON_ADS_TARGETS_UPDATE Action type must be enabled (Settings > Actions). A dry run still validates the write on a Read only account and does not queue it. The analysis and preview always run. Use table-sourced bids only when FIND itself is unavailable.

Step-by-step workflow (MCP-native)

  1. sellers_and_vendors_list -> pick the seller.
  2. Performance: prefer amazon_ads_profit_by_target_and_date (premium export, 5 AI Tokens) when it has rows: filter is_attribution_mature = true and ad_campaign_type = SPONSORED_PRODUCTS (one UK month held 235 Sponsored Brands and 3 Display targets beside the Sponsored Products ones, and the FIND / UPDATE below are Sponsored Products only); groupBy ["action_target_id", "target_entity_type", "ad_campaign_id", "ad_group_id", "ad_keyword", "ad_match_type"] (the campaign and ad-group ids are required in the UPDATE payload and by the table-sourced fallback); sum spend/sales/clicks/orders with distinct aliases; max(ad_target_bid) and max(ad_keyword_bid) - use the first as the table bid and fall back to the second when it is null. Otherwise exports_create on amazon_ads_search_terms_by_campaign_by_date, trailing 30-60d but ending ~7 days ago (exclude the last 7 days - SP sales/orders are 7-day attributed, so a fresh window under-counts conversions). groupBy [ad_keyword_id, ad_keyword, ad_match_type, ad_campaign_id, ad_group_id], sum ad_spend/ad_sales/ad_clicks/ad_orders, take the bid as max(ad_keyword_bid) (a non-grouped column cannot be carried through a grouped export), filter ad_campaign_type = SPONSORED_PRODUCTS. Compute ACoS per keyword. Many actionable rows are SP auto targets, not keywords - treat them as targets.
  3. Resolve targetId + live bid: actions_start AMAZON_ADS_TARGETS_FIND with adProductFilter.include: ["SPONSORED_PRODUCTS"] (exactly one) + campaignIdFilter / keywordFilter / targetIdFilter; poll actions_get -> targetId + live bid (+ campaignId, adGroupId) per target. Read only access is enough for FIND. If FIND is refused because the Action type is disabled, use action_target_id and the table bid as in Configuration and label the bids table-sourced.
  4. Compute new bid per the framework + guardrails (>= 5 clicks, +/-30% step cap, 0.02 floor, user min/max). Build the change list, biggest ACoS offenders first; max 25 targets per action - batch longer lists into several actions.
  5. dryRun: actions_start AMAZON_ADS_TARGETS_UPDATE with dryRun: true and the payload shape above. Confirm status: VALIDATED, valid: true, actionId: null, then show the full before/after bid table.
  6. On explicit approval only: actions_start again with dryRun: false, poll actions_get, report per-target acceptance. Otherwise stop - nothing changed.

Output format

Bid Optimizer (dry run) - {marketplace} - target ACoS {t}%

keyword              match   ACoS   cur bid   -> new bid   why
{kw}                 PHRASE  156%   {cur}0.55    {cur}0.35  cut to target
{kw}                 EXACT   14%    {cur}0.40    {cur}0.48  raise (headroom)

Dry run: {n} bids validated, 0 issues.
Reply "apply" to push these bids, or edit targets/target-ACoS first.

Worked example (illustrative)

A phrase keyword might show ~€182 spend / ~€117 sales / 176 clicks / 14 orders -> ACoS ~156%. At a 30% target, new bid = current x (30/156) ~= a large cut, but clamped to the +/-30% step cap + 0.02 floor, so likely one capped cut this run, revisit next week. Contrast a keyword at ~18% ACoS - leave it or nudge up. The AMAZON_ADS_TARGETS_UPDATE dryRun validates cleanly (status: VALIDATED, valid: true, actionId: null) even when Actions are disabled - so the preview is always safe to show.

Quality self-check

  • Did I take targetId and the bid from FIND? Read only access is enough. Use action_target_id with the bids flagged as table-sourced only when FIND was refused because the Action type is disabled.
  • Did I filter the target-profit export to Sponsored Products and keep ad_campaign_id / ad_group_id in its groupBy, so every proposed update has a valid SP scope?
  • Did I exclude ~the last 7 days so 7-day attribution didn't trigger over-aggressive cuts?
  • Did I skip keywords with < 5 clicks, cap the step at +/-30%, and floor at 0.02?
  • Did I split the batch so no action carries more than 25 targets?
  • Did I dryRun and confirm VALIDATED / actionId: null + show before/after before any real write?
  • Explicit approval before dryRun: false?
  • Right marketplace + currency for the account?

Common mistakes

  • Slashing a bid to zero on one bad week (over-correction).
  • Reading amazon_ads_profit_by_target_and_date without an ad_campaign_type filter, or grouping it by action_target_id alone - Brands and Display targets get proposed as Sponsored Products updates, and the table-sourced fallback has no campaign / ad group to build the payload from.
  • Raising bids on high-ACoS "converting" keywords (they're still unprofitable).
  • Sending the bid to ad_keyword_id instead of the FIND-resolved targetId - it lands on the wrong target (or nothing).
  • Cutting bids on a fresh window - SP sales are 7-day attributed; exclude the last ~7 days.
  • Acting on < 5 clicks (noise), or moving a bid more than +/-30% in one run.
  • Taking the "current" bid from amazon_ads_targets_raw - a 72-hour snapshot; use the live bid from AMAZON_ADS_TARGETS_FIND.
  • Sending more than 25 targets in one AMAZON_ADS_TARGETS_UPDATE action.
  • Running the live update without the Action enabled, or without Read and write access. TARGETS_FIND runs on Read only access. Only the live TARGETS_UPDATE needs Read and write.

Notes

  • Write skill. The live update needs the Action enabled and Read and write access. FIND runs on Read only access. A dry run still validates the write and does not send it.
  • Pairs with ppc-wasted-spend-watchdog (find) and ppc-negative-keyword-applier (negate the truly dead terms).
  • A DataDoe skill, built on DataDoe amazon_ads_search_terms_by_campaign_by_date + the AMAZON_ADS_TARGETS_FIND / AMAZON_ADS_TARGETS_UPDATE actions.
  • Product profit bids (break-even from fees and product cost, a target ACoS from conversion, bid = sales per click × target) are ppc-profit-bid-apply. This skill still uses one target ACoS for the account.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.