amazon-ads-sp-search-term-explorer v0.4.3A

Immutable. This exact content never changes and is served at /api/v1/blob/09f70ddd5179592c.

---
name: amazon-ads-sp-search-term-explorer
description: >
  Mine Sponsored Products search terms end-to-end via the Amazon Ads MCP:
  generate the SP Search Term report via allv1_AdsApiv1CreateReport using v1
  dotted field IDs (searchTerm.value, metric.totalCost, metric.sales,
  budgetCurrency.value — not legacy Console headers), pre-flight validate with
  report_fields before CreateReport, filter adProduct.value SPONSORED_PRODUCTS,
  download CSV and parse with the v1 DictReader pattern, partition PAT ASINs in
  searchTerm.value, elicit brand markers and thresholds, segment into generic
  and branded gold tables, surface negatives, sufficiency-gated rising stars,
  and PAT stream. Never use metric.cost / metric.spend or legacy CSV column
  names. Trigger on: SP search term mining, search term gold, search term
  negatives, search term report, PAT vs keyword, brand vs generic split,
  rising stars, exact-match harvest, attribution window questions, or any
  variant of "find me wasted spend / scale-worthy keywords / branded
  defenders" via the Amazon Ads MCP.
compatibility: Requires amazon_ads MCP server >= 0.3.1 (report_fields, CreateReport, RetrieveReport, QueryAdvertiserAccount, download_export, read_download)
license: PolyForm-Shield-1.0.0 (see LICENSE.txt)
metadata:
  version: "0.4.3"
---

# Amazon Ads — SP Search Term Explorer

## Overview

End-to-end SP Search Term mining via the `amazon_ads` MCP server. This skill owns the full surface: report **generation** (CreateReport / poll / download), **parsing** with v1 dotted field IDs, **partition** of PAT ASINs from customer queries, **threshold elicitation**, **segmentation** into generic and branded gold + rising + negatives, **sufficiency gating**, and the final **deliverable template**.

Downloaded CSV headers are **v1 catalog IDs** (`searchTerm.value`, `metric.totalCost`, …) — not legacy `Customer Search Term` / `7 Day Total Sales` style exports. The skill does not handle hand-uploaded console CSVs or warehouse extracts; everything assumes input generated by this skill's own report-creation flow.

## Account-context recovery

If Amazon account scope, identifier type, marketplace mapping, or account relationships become unclear, consult `amazon-ads-accounts` when it is available. Resume this skill after resolving the ambiguity. If it is unavailable, use equivalent read-only discovery and ask the user when multiple valid choices remain. Never guess or interchange identifier types.

**Reference layout:**
- **Report generation:** [`mcp-workflow.md`](references/mcp-workflow.md)
- **CSV parsing (v1 DictReader, required-column check, ASIN partition):** [`agent-codegen-v1.md`](references/agent-codegen-v1.md)
- **Column vocabulary + pinned field list:** [`column-mapping-hints.md`](references/column-mapping-hints.md)
- **Segmentation logic + sufficiency gates:** [`segment-rules.md`](references/segment-rules.md)
- **Output deliverable:** [`report-template.md`](references/report-template.md)
- **Four-question threshold elicitation:** [`threshold-elicitation.md`](references/threshold-elicitation.md)
- **Attribution-window contract:** [`attribution-window.md`](references/attribution-window.md)
- **Pre-handoff checklist:** [`execution-checklist.md`](references/execution-checklist.md)
- **Format-agnostic regex / aggregation helpers:** [`agent-codegen-patterns.md`](references/agent-codegen-patterns.md) (Patterns 3–4 for brand/generic regex)

## When to use

- `amazon_ads` tools available; user wants **CreateReport** SP search term data
- You need **`report_fields` `mode=validate`** before spending report quota

## Workflow

**Order:** elicit **brand markers** and **thresholds** before **`CreateReport`** when possible — segmentation is planned up front and outputs always target **two gold tables** (generic + branded). See [`threshold-elicitation.md`](references/threshold-elicitation.md) for the four-question elicitation.

1. **Confirm scope** — SP only (filter `adProduct.value` = `SPONSORED_PRODUCTS`). Date range → `window_days` for sufficiency.
2. **Session + context** — `get_session_state` → `set_context` if needed (session-scoped = set once per conversation; request-scoped = per block). See [`mcp-workflow.md`](references/mcp-workflow.md).
3. **Resolve `advertiserAccountId`** — via `allv1_QueryAdvertiserAccount`. This is the `amzn1.ads-account.g.*` value, not the numeric profile ID.
4. **Pre-flight validate** — `report_fields` `mode=validate` with the **pinned** `FIELDS` list in [`mcp-workflow.md`](references/mcp-workflow.md) (includes `budgetCurrency.value` with `metric.totalCost`). If invalid, **stop** — do not `CreateReport`.
5. **CreateReport + poll + download** — see [`mcp-workflow.md`](references/mcp-workflow.md).
6. **Parse CSV** — headers are **v1 dotted names**; use [`agent-codegen-v1.md`](references/agent-codegen-v1.md) (DictReader, required-column check, **no** legacy renaming).
7. **Partition** — `searchTerm.value`: ASIN-shaped (`^B0[A-Z0-9]{8}$`) vs customer query; keyword segments run **only** on query rows.
8. **Aggregate** — sum `metric.*` per `searchTerm.value` on keyword rows; then ACoS/CVR on totals.
9. **Sufficiency + segment** — apply gates and segmentation per [`segment-rules.md`](references/segment-rules.md); fill deliverable per [`report-template.md`](references/report-template.md). Provenance: `reportId`, `datePeriod`, `advertiserAccountId`.
10. **Checklist** — run [`execution-checklist.md`](references/execution-checklist.md) before handoff.

## Safety guards

- **`metric.totalCost` + `budgetCurrency.value`** always together in the query.
- **Never** keyword-negate ASIN-shaped `searchTerm.value`.
- **Never** one combined gold table without generic/branded split (unless documented opt-out).

## What not to do

- Use `metric.cost`, `metric.spend`, `metric.spendAmount`, `metric.sales7d`, `keyword.text`, or `sponsoredProducts.*` column prefixes — none of these exist on the v1 path. The pre-flight `report_fields` `mode=validate` will catch them, but knowing this up front avoids the round-trip.
- Apply legacy Console column names (`Customer Search Term`, `7 Day Total Sales`, etc.) to the MCP CSV — the dotted v1 IDs are the source of truth.
- Skip the brand/generic split. A single combined gold table mixes navigational and discovery intent and produces misleading "scale" recommendations.
- Issue keyword negatives for ASIN-shaped `searchTerm.value` rows — those belong in product-targeting workflows, not keyword negation.
- Run strict negative recommendations on thin windows. See [`segment-rules.md`](references/segment-rules.md) sufficiency gates.

## Resources

| Path | Contents |
|------|----------|
| [`references/mcp-workflow.md`](references/mcp-workflow.md) | Pinned FIELDS, validate, create, filter, session notes, v1 vs legacy |
| [`references/agent-codegen-v1.md`](references/agent-codegen-v1.md) | DictReader, required-column check, ASIN partition, aggregate by `searchTerm.value` |
| [`references/column-mapping-hints.md`](references/column-mapping-hints.md) | Role → v1 field ID table + pinned field list + "do not expect" list |
| [`references/segment-rules.md`](references/segment-rules.md) | Brand/generic split, ASIN-vs-query partition, sufficiency gates, interest-only mode |
| [`references/report-template.md`](references/report-template.md) | Full deliverable: §0 scope → §1 header → portfolio summary → negatives → generic/branded gold → rising → PAT → recommendations → caveats |
| [`references/threshold-elicitation.md`](references/threshold-elicitation.md) | Four questions to ask the user before segmenting |
| [`references/attribution-window.md`](references/attribution-window.md) | Attribution window contract; v1 unsuffixed-fields quirk |
| [`references/execution-checklist.md`](references/execution-checklist.md) | Pre-handoff verification |
| [`references/agent-codegen-patterns.md`](references/agent-codegen-patterns.md) | Format-agnostic regex/aggregation helpers (brand vs generic Patterns 3–4 still useful) |

## Related skills

This skill owns the **paid SP search-term** lifecycle (generate → partition → segment → deliverable). For phrase-level decisions on top of the segmented output, or for the organic counterpart, chain into the trilogy:

- **Optional sub-skill:** Use `ngram-keyword-framework` when it is installed and the user wants phrase-level n-gram or skip-gram bid, negative, scale, or pullback decisions from the segmented paid-search output.
- **Related skill:** Use `amazon-sp-sqp-asin-ngram` for the organic SP-API Brand Analytics counterpart at `{search_query, asin}` grain when the user wants per-ASIN PDP, SEO, price, or shipping recommendations beside the paid keyword view.

Trigger handoff explicitly when chaining. The boundary is clean: this skill ends at the segmented gold / negative / rising tables; `ngram-keyword-framework` picks up from there with `data_mode: ads` and emits phrase-level decision records.

## Quality bar

- Validation → create → CSV columns match v1 required set; ASIN-vs-query partition done before any keyword segment; two gold tables (generic + branded) unless brand markers explicitly opted out; `reportId` in §1 of the deliverable; [`execution-checklist.md`](references/execution-checklist.md) satisfied or gaps explained.