amazon-ads-sb-performance-review v0.1.3A

Immutable. This exact content never changes and is served at /api/v1/blob/3e97216c80097ec4.

---
name: amazon-ads-sb-performance-review
description: >
  Produce a Sponsored Brands (SB) campaign performance review from SB Campaigns
  Report data: portfolio summary, top and worst campaigns by efficiency, low-CTR
  creative signals, new-to-brand (NTB) analysis when present, placement or
  format splits if columns exist, and actionable recommendations. Use when users
  ask for Sponsored Brands audits, SB headline/video/store spotlight reviews,
  brand awareness efficiency, NTB share, SB CTR vs benchmarks, or SB campaign
  deep-dives. The agent must fetch and parse the report for the user’s
  environment — do not assume a global variable, fixed file path, or stable
  Amazon export schema; write loader and column-mapping code after inspecting
  the actual artifact.
license: PolyForm-Shield-1.0.0 (see LICENSE.txt)
metadata:
  version: "0.1.3"
---

# Sponsored Brands performance review

## Overview

Turn **Sponsored Brands Campaigns Report** data (any ingest path: CSV upload, Ads API export, warehouse table, notebook variable) into a structured markdown report. This skill defines **what** to measure and **how** to validate inputs — not drop-in Python tied to a specific `reports[0]['report_data']` shape or column names.

## 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.

## When to Use

- SB portfolio health: spend, sales/attributed sales, ACoS/ROAS, CTR, CPC, impressions
- Ranking best vs worst SB campaigns with **minimum spend** thresholds so tiny rows do not dominate
- Flagging **low CTR** vs category-style SB benchmarks (guidance, not law)
- **NTB** (new-to-brand) orders/sales share when columns exist
- Creative / targeting / budget reallocation recommendations grounded in the numbers actually present

## Agent workflow (required)

1. **Confirm scope** — Marketplaces, date range, currency, SB only (exclude SP/SD unless the user wants combined). State assumptions explicitly if unknown.
2. **Acquire data** — Ask how the SB Campaigns Report is provided, or use the user’s stated tool (API, file, SQL). **Do not** assume a variable name like `reports` or a nested key like `report_data` exists.
3. **Introspect before mapping** — After load, print or log: column names, dtypes, row count, and 3–5 sample rows. If the artifact is nested JSON, write code to traverse keys until tabular rows are found.
4. **Build a semantic map** — Map **observed** columns to roles: campaign key (name or ID), cost/spend, sales (or attributed sales — be consistent), impressions, clicks, optional budget/state, optional NTB fields, optional placement or ad-type splits. See `references/column-mapping-hints.md` for **heuristics only**; the agent must confirm against real headers.
5. **Validate** — Refuse or narrow analysis if cost and campaign identity are missing. If sales/revenue is missing, report spend/click/CTR only and say ACoS cannot be computed.
6. **Compute with guards** — Use safe division (e.g. avoid divide-by-zero; define ACoS only when sales > 0). Filter to enabled/active rows only if a status column exists; document if not.
7. **Deliver** — Use the report template in `references/report-template.md`. Tie every claim to the mapped columns and date range.

## What not to do

- Do not ship or copy a single script that assumes `reports[0]['report_data']`, a fixed pandas schema, or heuristic column detection without re-running introspection on the user’s file.
- Do not treat Amazon export column names as stable across API versions, locales, or report templates — always verify.
- Do not mix Sponsored Products or Display into SB-only conclusions unless the report clearly includes only SB or the user asks for blended retail media.

## Core metrics (semantic definitions)

Define these **after** mapping columns; names below are logical, not API field names.

| Metric | Definition | Notes |
|--------|------------|--------|
| CTR | clicks / impressions | Use impressions > 0; express as % if comparing to benchmarks in reference doc |
| CPC | cost / clicks | clicks > 0 |
| ACoS | cost / sales | sales > 0; align sales with the same attribution window as cost |
| ROAS | sales / cost | cost > 0 |
| NTB order share | NTB orders / orders | Only if both columns exist |
| NTB sales share | NTB sales / sales | Only if both columns exist |

Portfolio rollups = sum over rows after filters (e.g. enabled campaigns). Campaign-level tables = one row per campaign key unless the report is daily grain — then aggregate by campaign first if the user wants campaign rankings.

## Rankings and thresholds (tune with user)

- **Top performers**: among campaigns with spend ≥ user-defined floor (default: exclude zero spend; suggest a minimum such as 5–10% of portfolio spend or a fixed currency floor if the user provides targets).
- **Worst performers**: same floor; surface highest ACoS among meaningful spenders.
- **Low CTR**: flag rows below a threshold only after confirming impression volume; default narrative threshold in `references/benchmarks-and-interpretation.md`.

## Resources

| Path | Contents |
|------|----------|
| `references/report-template.md` | Markdown sections and emoji headings for the deliverable |
| `references/benchmarks-and-interpretation.md` | SB CTR guidance, NTB interpretation, recommendation patterns |
| `references/column-mapping-hints.md` | Non-authoritative name patterns; always verify on data |
| `references/agent-codegen-patterns.md` | Safe patterns for agent-authored loaders and mappers |

## Quality bar

- Every section of the output template should either be filled with numbers from **this** run or explicitly marked **N/A** with reason (missing columns, empty report, wrong report type).
- Recommendations must reference specific campaigns or metrics from the analysis, not generic Amazon best practices only.