---
name: brand-analytics
description: >
  Pulls 2 years of weekly Brand Analytics (ABA) data for a set of competitor
  ASINs and surfaces the keywords they are most consistently converting on.
  Use this skill whenever the user asks to analyze competitor Brand Analytics,
  find keywords competitors are consistently converting on, run a brand
  analytics report, score competitor keywords, or says "brand analytics skill",
  "what are my competitors converting on", "run brand analytics on these ASINs",
  or "find competitor keywords from ABA data". Accepts up to 20 competitor
  ASINs, scores each keyword by conversion consistency across the competitor
  set, enriches with search volume, and outputs a React artifact with a bar
  chart of top 30 keywords + a full sortable table with CSV download.
compatibility: "Helium 10 MCP (connected)"
---

# Brand Analytics Skill

Pulls 2 years of weekly Amazon Brand Analytics (ABA) data across up to 20
competitor ASINs, scores keywords by consistent conversion presence, enriches
with current Helium 10 search volume, and delivers a React artifact report.

---

## STEP 1 — COLLECT ASINs

Prompt the user:

> "Which competitor ASINs should I pull Brand Analytics data for?
> (Enter up to 20, comma-separated)"

Wait for the user's reply before proceeding.

---

## STEP 2 — PULL 2 YEARS OF WEEKLY ABA DATA

Run a **single** `search_amazon_brand_analytics` call with all competitor ASINs
passed together in the `products` array:

```
filters: {
  products: [<all competitor ASINs>],
  conversion_share_clicked_product_count_requirement: 1,   ← any ONE of the entered products
  conversion_share_comparison_operator: ">=",
  conversion_share_threshold: 1,
  period_from: <104 weeks ago>,
  period_to: <last complete week>,
  range_type: "weekly"
}
marketplace: "US"
```

**If the MCP cannot handle 104 weeks in one call**, split into two 52-week
calls (keeping all ASINs in the `products` array in both calls):
- Call A: last 52 weeks
- Call B: weeks 53–104

Merge results across both calls before scoring.

**Deduplication is mandatory.** Deduplicate by composite key `(phrase, event_date)`
before any aggregation — raw record counts can be ~24× the actual unique
week-phrase count.

**Note on revenue:** Revenue values are in cents — divide by 100 for dollar figures.

After deduplication, for each unique `(phrase, event_date)` record, check
which of the entered competitor ASINs appears in the
`clicked_product_1_amazon_standard_identification_number`,
`clicked_product_2_amazon_standard_identification_number`, or
`clicked_product_3_amazon_standard_identification_number` fields.
Use this to score per-competitor per-week presence.

---

## STEP 3 — SCORE KEYWORDS

Calculate an **ABA Score** for each keyword across the full competitor set:

```
For each (competitor_asin, event_date_week) where:
  - keyword appears in that ASIN's results for that week
  - conversion_share >= 1%

ABA Score = count of such (asin, week) pairs
```

In plain terms: 1 point per competitor ASIN per week where the keyword
drove ≥1% conversion share. A keyword appearing for 3 competitors in
10 weeks each = score of 30.

Also track:
- `weeks_active` = number of distinct weeks the keyword appeared for any competitor
- `competitor_count` = number of distinct competitor ASINs the keyword appeared for

If a user asks what the ABA Score means, explain:
> "A higher score means the keyword is more consistently and broadly
> converting across the competitor set — making it a high-priority target
> for your own campaigns."

Build `scored_keywords[]` sorted by ABA Score descending.

---

## STEP 4 — ENRICH WITH SEARCH VOLUME

Take the full `scored_keywords[]` list and batch it through
`analyze_keywords` (Helium 10 Cerebro batch enrichment) to get current
Helium 10 search volume for each keyword.

**Max 200 per call** — split into batches of 200 if the list exceeds 200
keywords. Merge all results.

Add `search_volume` to each entry in `scored_keywords[]`.

---

## STEP 5 — OUTPUT REACT ARTIFACT

Build a **React artifact** with the following components:

### Header
> "Brand Analytics Analysis | [N] competitor ASINs | Last 104 weeks
> | [total keyword count] keywords found"

### Component 1 — Bar Chart (Top 30)
Horizontal bar chart of the **top 30 keywords** by ABA Score:
- Y-axis: keyword phrase
- X-axis: ABA score
- Bar color: gradient from low score (grey/muted) to high score (blue accent)
- Tooltip on hover: keyword | ABA score | search volume | weeks active

### Component 2 — Full Sortable Table
Below the chart, render a full table of **all keywords** with columns:
| # | Keyword | ABA Score | Search Volume | Weeks Active |

Make all columns sortable by clicking the column header (asc/desc toggle).
Default sort: ABA Score descending.

### CSV Download
Include a **"Download CSV"** button above the table. When clicked, generate
and download a CSV with all rows using the same columns:
`#, Keyword, ABA Score, Search Volume, Weeks Active`

### Design defaults
- Dark navy background (`#1a1a2e`) with blue accent
- Adapt brand colors if ASINs are recognizably from a known brand context

---

## TOOL REFERENCE

- `search_amazon_brand_analytics` → weekly ABA conversion data
  - Key params: `marketplace_id: 1`, `range_type: "weekly"`, `conversion_share_threshold: 1`, `conversion_share_comparison_operator: ">="`
  - Always deduplicate by `(phrase, event_date)` before aggregating
  - Revenue values in cents → divide by 100
- `analyze_keywords` → search volume enrichment (max 200 per call)