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".
In this repository26 other files it gives its agents.
- amazon-asin-search-auditorSkill
- amazon-listing-optimizerSkill
- buy-box-loss-root-causeSkill
- create-amazon-reconciliation-dashboardSkill
- create-orders-managerSkill
- daily-account-health-checkSkill
- daily-performance-health-checkSkill
- fba-inventory-ledger-reportSkill
- fba-stock-restock-plannerSkill
- keyword-rank-sqp-trackerSkill
- net-profit-pl-analyzerSkill
- ppc-asin-acos-alertSkill
- ppc-campaign-acos-alertSkill
- ppc-negative-keyword-applierSkill
- ppc-profit-bid-applySkill
- ppc-wasted-spend-watchdogSkill
- promotions-managerSkill
- restock-priority-alertSkill
- return-refund-analyzerSkill
- sales-movers-scannerSkill
- suppressed-inactive-listings-checkSkill
- vendor-inventory-reportSkill
- vendor-performance-dashboardSkill
- vendor-pnl-dashboardSkill
- weekly-business-reviewSkill
- weekly-sales-briefingSkill
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
- Distinctive: line 27
After the Wasted-Spend Watchdog flags bleeders, to actually fix the bids.
- Distinctive: line 46
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 …
- Very specific: line 53
Read (performance), preferred when the org has it: amazon_ads_profit_by_target_and_date [premium] - per target/day: action_target_id (the …
- Very specific: line 64
Read (performance), fallback: amazon_ads_search_terms_by_campaign_by_date - per keyword/day: ad_keyword_id, ad_keyword, ad_keyword_bid …
- Very specific: line 82
Write: AMAZON_ADS_TARGETS_UPDATE action, gated behind a dryRun step.
- Very specific: line 109
Performance: prefer amazon_ads_profit_by_target_and_date (premium export, 5 AI Tokens) when it has rows: filter is_attribution_mature = …
- Very specific: line 115
UPDATE payload and by the table-sourced fallback).
- Distinctive: line 197
Write skill. The live update needs the Action enabled and Read and write access.
≈ “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.
Files
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 AdstargetId, ready for the UPDATE payload),ad_campaign_type(the table also holds Sponsored Brands, Display and Television targets - filter toSPONSORED_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_acosis 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_ordersare 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_FINDaction returns thetargetIdand the livebid. Filter withadProductFilter.include: ["SPONSORED_PRODUCTS"](FIND requires exactly one ad product) pluscampaignIdFilter/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_idis the AdstargetId(for Sponsored Products it equalsad_keyword_idon keyword rows andad_target_idon auto/product rows), withad_target_bidas the bid (elsead_keyword_bid) andad_campaign_id/ad_group_idfrom 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_UPDATEaction, gated behind adryRunstep. Confirmed payload shape (max 25 targets per action - schemamaxItems: 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}]})bidmust be a number withexclusiveMinimum: 0andmaximum: 999999999.99(floor at 0.02 in practice). AdryRun: truecall returnsstatus: VALIDATED, valid: true, actionId: null- nothing is queued or sent to Amazon.marketplaceScope/marketplacesare accepted byTARGETS_UPDATEon Sponsored Products (dryRun 2026-10-03: VALIDATED with and without them) but are not needed - thetargetIdalready scopes the change. OnlyAMAZON_ADS_TARGETS_ADDrejects them. - Live state, not snapshots:
amazon_ads_targets_raw/amazon_ads_campaigns_raw/amazon_ads_ad_groups_raware 72-hour snapshots. Never take the "current" bid from them before a write - read it live withAMAZON_ADS_TARGETS_FIND(step 3). - Inputs from user: target ACoS (e.g. 30%), min/max bid, max step (default +/-30%).
- Prerequisites:
AMAZON_ADS_TARGETS_FINDruns on Read only and Read and write accounts. The live apply needs Read and write (Accounts page), and theAMAZON_ADS_TARGETS_UPDATEAction 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)
sellers_and_vendors_list-> pick the seller.- Performance: prefer
amazon_ads_profit_by_target_and_date(premium export, 5 AI Tokens) when it has rows: filteris_attribution_mature = trueandad_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)andmax(ad_keyword_bid)- use the first as the table bid and fall back to the second when it is null. Otherwiseexports_createonamazon_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], sumad_spend/ad_sales/ad_clicks/ad_orders, take the bid asmax(ad_keyword_bid)(a non-grouped column cannot be carried through a grouped export), filterad_campaign_type = SPONSORED_PRODUCTS. Compute ACoS per keyword. Many actionable rows are SP auto targets, not keywords - treat them as targets. - Resolve targetId + live bid:
actions_startAMAZON_ADS_TARGETS_FINDwithadProductFilter.include: ["SPONSORED_PRODUCTS"](exactly one) +campaignIdFilter/keywordFilter/targetIdFilter; pollactions_get->targetId+ livebid(+campaignId,adGroupId) per target. Read only access is enough for FIND. If FIND is refused because the Action type is disabled, useaction_target_idand the table bid as in Configuration and label the bids table-sourced. - 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.
- dryRun:
actions_startAMAZON_ADS_TARGETS_UPDATEwithdryRun: trueand the payload shape above. Confirmstatus: VALIDATED, valid: true, actionId: null, then show the full before/after bid table. - On explicit approval only:
actions_startagain withdryRun: false, pollactions_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
targetIdand the bid from FIND? Read only access is enough. Useaction_target_idwith 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_idin itsgroupBy, 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_datewithout anad_campaign_typefilter, or grouping it byaction_target_idalone - 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_idinstead of the FIND-resolvedtargetId- 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 fromAMAZON_ADS_TARGETS_FIND. - Sending more than 25 targets in one
AMAZON_ADS_TARGETS_UPDATEaction. - Running the live update without the Action enabled, or without Read and write access.
TARGETS_FINDruns on Read only access. Only the liveTARGETS_UPDATEneeds 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) andppc-negative-keyword-applier(negate the truly dead terms). - A DataDoe skill, built on DataDoe
amazon_ads_search_terms_by_campaign_by_date+ theAMAZON_ADS_TARGETS_FIND/AMAZON_ADS_TARGETS_UPDATEactions. - 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.
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
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.

