---
name: sqp-showdown
description: >
  Compares the seller's Search Query Performance (SQP) data against competitor
  Brand Analytics (ABA) data to identify keyword gaps and diagnose why the
  seller is missing sales. Use this skill whenever the user wants to compare
  their SQP to competitor ABA data, asks about keyword gaps vs competitors,
  says "SQP showdown", "compare my keywords to competitors", "why am I missing
  sales on these keywords", or "what keywords are my competitors getting sales
  on that I'm not". Takes up to 5 seller ASINs and up to 10 competitor ASINs,
  analyzes the last 26 weeks, and produces a gap report with indexed diagnoses
  (not indexed / visibility issue / relevancy issue).
compatibility: "Helium 10 MCP (connected)"
---

# SQP Showdown Skill

Compares the seller's SQP purchase data against competitor Brand Analytics
conversion data over the last 26 weeks to surface keyword gaps and explain why
the seller is or isn't capturing sales on those keywords.

---

## STEP 1 — COLLECT ASINs & INTRODUCE THE SKILL

Tell the user:

> "This skill compares your Search Query Performance reports to your
> competitors' Brand Analytics data to find keyword gaps — keywords your
> competitors are converting on that you're missing or underperforming on.
>
> Please answer two questions:
> 1. Which ASINs are **yours**? (up to 5, comma-separated)
> 2. Which ASINs are your **competitors**? (up to 10, comma-separated)"

Wait for the user's reply before proceeding.

---

## STEP 2 — PULL SQP DATA (SELLER ASINs)

For each seller ASIN, pull the last 6 months of Search Query Performance data
using `get_search_query_performance`:

```
seller_id: A3SY09KI84R23C   ← Bradley's correct seller ID (not A2R7UX9BFSMS61)
asin: <seller_asin>
time_dimension: month
time_period: ['YYYY-MM', 'YYYY-MM', ...]   ← last 6 full months as array
marketplace: "US"
```

Note: multiple months can be passed as a single array call — no need for
one call per month.

Build `sqp_data{}` keyed by keyword. For each keyword across all uploaded months:
- `sqp_total_purchases` = sum of purchases across all months
- `sqp_months_with_purchases` = count of months where purchases > 0
- `sqp_best_org_rank` = lowest (best) organic rank seen across months
- `sqp_best_spon_rank` = lowest (best) sponsored rank seen across months
- `sqp_total_impressions` = sum of impressions
- `sqp_search_volume` = max SV seen (use as proxy for keyword SV)

If the seller has multiple ASINs, aggregate across all of them.

---

## STEP 3 — PULL ABA DATA (COMPETITOR ASINs)

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: <26 weeks ago>,
  period_to: <last complete week>,
  range_type: "weekly"
}
marketplace: "US"
```

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

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 track per-competitor presence per week.

Build `aba_data{}` keyed by keyword:
- `aba_total_score` = total (competitor_asin × week) pairs where that competitor
  appeared with ≥1% conversion share (sum across all competitors and weeks)
- `aba_weeks_active` = count of distinct `event_date` values the keyword appeared
- `aba_competitor_count` = number of distinct competitor ASINs that ever appeared
  for this keyword

---

## STEP 4 — CLASSIFY INTO TWO LISTS

**List A — They're winning, you're missing entirely**
Criteria: keyword appears in `aba_data{}` with `aba_total_score ≥ 3`
AND `sqp_total_purchases == 0` (you have zero SQP purchases on this keyword).

**List B — You're sporadic, they're consistent**
Criteria: keyword appears in `aba_data{}` with `aba_weeks_active ≥ 6`
AND `sqp_months_with_purchases ≤ 2` (you bought ≤ 2 months out of 6).
Exclude keywords already in List A.

---

## STEP 5 — DIAGNOSE EACH KEYWORD

For each keyword in List A and List B, apply this diagnosis logic in priority order:

1. **🔴 Not Indexed** — keyword does NOT appear in your SQP data at all
   (zero impressions, zero purchases, completely absent). You are not indexed
   for this keyword.

2. **🟠 Visibility Gap** — keyword appears in SQP (you get some impressions)
   but `sqp_best_org_rank > 20` AND `sqp_best_spon_rank > 10` (or no sponsored
   rank), AND `sqp_total_impressions < 0.30 × sqp_search_volume`.
   You're indexed but shoppers aren't seeing you.

3. **🟡 Ranking Gap** — you have impressions and some visibility, but rank is
   poor (org rank 11–20 or spon rank 6–10). Shoppers see you sometimes but
   you're not prominent enough to convert.

4. **🔵 Relevancy Issue** — impressions look reasonable (≥30% of SV) but
   `sqp_total_purchases == 0` or extremely low. Shoppers see you but don't
   click/buy. Listing or price may not match shopper intent.

---

## STEP 6 — BUILD REACT ARTIFACT REPORT

Produce a **React artifact** with the following sections:

### Header
- Title: "SQP Showdown — [ASIN(s)]"
- Subtitle: "Last 26 weeks · [date range]"

### Summary stat tiles (4 tiles)
1. List A keywords (they convert, you don't)
2. List B keywords (sporadic vs consistent)
3. Total competitor keywords analyzed
4. Your total SQP keywords (breadth check)

### Section 1 — List A: You're missing entirely
Table with columns:
**Keyword** | **Competitor ABA Score** | **# Competitors** | **Your Purchases**
| **Your Impressions** | **SV** | **Impression Ratio** | **Best Org Rank**
| **Best Spon Rank** | **Diagnosis**

Sort by Competitor ABA Score descending.

### Section 2 — List B: You're sporadic, they're consistent
Table with columns:
**Keyword** | **Competitor Weeks Active** | **Your Months w/ Purchases**
| **Your Total Purchases** | **Best Org Rank** | **Best Spon Rank**
| **Impression Ratio** | **Diagnosis**

Sort by Competitor Weeks Active descending.

### Diagnosis legend
Small legend at the bottom explaining the 4 diagnosis labels and what to do
for each one:
- 🔴 Not Indexed → add to back-end keywords / run PPC to force indexing
- 🟠 Visibility Gap → raise bids or add exact match campaign
- 🟡 Ranking Gap → increase bids, add to SB/SD, push organic rank
- 🔵 Relevancy Issue → review listing copy, images, price vs competitors

### Design
- Use Party On Tap brand colors (#00A8E0 accent, dark navy #1a1a2e bg) if
  those ASINs are involved; otherwise default to dark navy + blue accent
- Diagnosis badges use semantic colors: 🔴 red, 🟠 orange, 🟡 yellow, 🔵 blue
- Both tables are fully sortable by clicking column headers
- Include a **Download CSV** button for each table
- Tables default to showing top 50 rows; include "Show All" toggle

---

## TOOL REFERENCE

- `get_search_query_performance` → SQP data
- `search_amazon_brand_analytics` → competitor ABA/conversion data

Seller ID for Bradley's account: `A3SY09KI84R23C`