amazon-ads

# Amazon Ads — Catalog > **PREREQUISITE:** Read `../amazon-shared/SKILL.md` for marketplace > TLD map, hamburger-menu navigation, sign-in / Ziniao / OTP handling, > and the ad-console vs seller-central account caveat. This skill is a **catalog**. The actual content lives in topical references in `references/`. Load whichever ones apply to the task. ## What this skill produces For tuning / audit tasks ("review the ads", "improve ACOS", "audit"): **one Markdown report** (`AD_AUDIT_<YYYY-MM-DD>.md`) + **two TSVs per active campaign** (`stores/<slug>/ads/<platform>/<country>/<id>.tsv` targets + `<id>.searchterms.tsv` full customer-query set). Every campaign is drilled in TWO layers on the same date window — targets AND search terms — proven by a `搜索词对账` reconciliation line the server reviewer parses. **START HERE — do NOT pre-read every reference (it buries the model and causes shortcutting). Just two files, then run:** 1. **[`output-spec.md`](references/output-spec.md)** — the report contract (what "done" looks like). 2. **[`audit-quickref.md`](references/audit-quickref.md)** — the entire procedure on one page. Load a heavy reference only when a step there tells you to. Then write the report and call `vibe_seller_set_task_result("./AD_AUDIT_<date>.md")`. The server's **completeness reviewer** replies with a short "what's still missing" list (under-drilled countries + bid-rule violations) and converges over rounds — **partial is accepted each round**, just fix the top gaps and re-submit until it returns nothing. No separate reviewer subagent or Stop-hook needed. ## Workflow references — the "what to do" thinking | Reference | Load when | |---|---| | [`output-spec.md`](references/output-spec.md) | **Read first for every audit.** The report contract the server completeness reviewer checks against — per-(platform,country) 进度 line, header table, per-campaign drills, the 4 bid rules, TSV-per-campaign. | | [`audit-quickref.md`](references/audit-quickref.md) | **The procedure, one page.** Run this top-to-bottom; it points to heavy refs on demand. | | [`format-anchor.md`](references/format-anchor.md) | _Legacy detail._ Per-campaign table column shape; load only if you need the exact table layout. (The mandatory subagent reviewer-loop is superseded by the server completeness reviewer — partial is accepted, it lists gaps each round.) | | [`reviewer-loop.md`](references/reviewer-loop.md) | Phase-4 **execution review** only (`EXEC_REVIEW_*`, Stop-hook enforced). For audit reports its Phase-3 format loop is superseded by the server completeness reviewer — don't spawn a review subagent for amazon/noon audits. | | [`tuning-workflow.md`](references/tuning-workflow.md) | User asks to tune ads, improve ACOS, "review last month's ads", harvest search terms, lower bids on losers, weekly ad review, "why is X campaign burning money", or any ongoing-campaign refinement task. | | [`tuning-campaign-types.md`](references/tuning-campaign-types.md) | A campaign isn't SP-Manual-Keyword. The skill defaults to SP-Manual-Keyword; for SP-Auto / SP-Manual-Product / Sponsored Brands / Sponsored Brands Video / Sponsored Display, this reference has the per-type sidebar tabs, Targeting-tab columns, and lever-applicability matrix observed on a live merchant account. Pair with `tuning-workflow.md` Phase 3 — that phase branches on type. | | [`tuning-thresholds.md`](references/tuning-thresholds.md) | Need to derive per-store thresholds (breakeven ACOS = margin %, target ACOS = 0.7 × breakeven, protect-zone, waste/harvest cutoffs). Always heuristic, never hardcoded. | | [`tuning-toolbox.md`](references/tuning-toolbox.md) | Picking the right lever — 8 levers + 2 advanced (dayparting, structural splits) disabled by default. Ordered surgical-first (search-term negate / harvest, per-keyword bid trim) → blanket-last (bidding strategy, pause campaign). For which levers apply per type, see `tuning-campaign-types.md`. | | [`tuning-funnel-diagnosis.md`](references/tuning-funnel-diagnosis.md) | Distinguishing listing-side problems (low CTR = image / title; low CVR = PDP / price / reviews) from ad-side problems (ACOS) before reaching for a bid lever. Bad CTR is not an ad-tuning problem. | | [`tuning-recommendation-format.md`](references/tuning-recommendation-format.md) | Composing the per-campaign output table at the end of a tuning session — header table → per-campaign data → per-problem subsections with per-entity data tables. Targeting-first, placement-second. Data table shape varies by type — see `tuning-campaign-types.md`. | | [`tuning-history.md`](references/tuning-history.md) | The per-campaign TSV under git that records every observed state (bid, status, suggested range, recent metrics) across audits. Read at Phase 2 to diff scrape against record (catches OBSERVED_DRIFT); read at Phase 3 for recency check before recommending changes (< 7 days since last change → downgrade to Hold); written at Phase 4 after each verified apply (cause-and-effect ledger). One TSV per campaign, written via `vibe_seller_write_workspace_file`; the workspace auto-commits. | ## Mechanics reference — the "how to click" lookup | Reference | Load when | |---|---| | [`bulk-operations.md`](references/bulk-operations.md) | **DEFAULT for creating a campaign or applying bids across keywords/campaigns.** Export → edit with `scripts/ads_bulk.py` → import → verify. Locale-general (positional 52-col schema, template-cloned headers) and guards the ASIN-as-SKU trap in code. The click paths below are the **fallback** — a single tweak, a field with no bulk column, or two failed imports. | | [`mechanics.md`](references/mechanics.md) | Any time you're about to issue a `browser-use` call against Amazon Ads or Coupons. Sections: § 0 preconditions, § 1 URLs, § 2 reading existing campaigns, § 3 creating a new campaign, § 4 bulk download / upload, § 5 coupons, § 6 wedged-daemon recovery, § 7 per-store conventions, § 8 reading playbook for tuning (Bid Adjustments date-range alignment rule, Search terms tab, bidding-strategy edit, daily-budget edit), § 9 scope. **§3 (UI create) and §4a0 (ag-Grid edits) are the fallback to `bulk-operations.md`.** | ## Safety rails - **Never auto-execute** any tuning change. Output is always a recommendations table; the user confirms each row before any click that modifies state. - **Derive thresholds from this store's data**, not from absolute numbers. Computed, not hardcoded. - **Verify the lever before recommending it.** Every numeric recommendation specifies field's current value, proposed value, valid range, direction. Never recommend a value the field will reject (e.g. negative placement modifiers — Amazon SP only allows 0% to +900%, increase-only). - **Don't kill the goose.** Order-driving keywords / campaigns get tagged PROTECT regardless of ACOS. Surface, never auto-cut. - **Per-run captures → `/tmp/<run-slug>/`** (per `amazon-shared § 5`). ## Default analysis window **Last 30 days** by default. The user may override with any window ("last 14 days", "March 1 – March 31", "year to date", custom calendar dates). When set, **pin the same window across every page in the session** — campaign top-tile, ad-group list, Bid Adjustments, Search terms, Targeting. Each of those pages has its own independent date picker; defaults drift. Misaligned dates cause the per-placement breakdown to not sum to the campaign top-tile and lead to wrong recommendations. ## What this skill is NOT - Not for new-campaign creation as a workflow → that's the separate `new-product-launch` skill (which uses this skill's mechanics reference for click paths). - Not for non-Amazon marketplaces — different platforms have different UI / mechanics; document those in their own skills. - Sponsored Brands tuning is **partially verified** (campaign + ad-group + Targeting tab observed; Bid adjustments tab present with "New" badge but cell semantics not yet drilled). Sponsored Brands Video and Sponsored Display are **listed-only** — the per-type playbook in `tuning-campaign-types.md` calls out which rows are verified vs inferred. For inferred-only types, mark Confidence accordingly and bias to conservative reversible actions.