# Shopify AEO Checker

> See how often a Shopify brand shows up when AI shopping agents search all of Shopify, versus competitors, from a single product link.

Shopify AEO Checker is an AI skill for sales & marketing teams that you can use in Claude Code, Codex, or type.com. It works with Shopify.

- Skill page: https://typestaging.com/library/skills/shopify-aeo-checker
- Raw SKILL.md: https://typestaging.com/library/skills/shopify-aeo-checker/SKILL.md
- Created by Hov from The Growth Chef
- Updated: September 30, 2026
- Package: 15 files

## What it does

- Score a brand's visibility and share of shelf on Shopify's Global Catalog.
- See which competitors own each shopper search and where the brand is missing.
- Get a Google-style results app in Type whose search bar runs new live searches.

## Before you start

- One public Shopify product link.
- Python 3.9+; no API keys needed (read-only public catalog search).

## How to use Shopify AEO Checker

1. **type.com:** Choose Use Skill to add Shopify AEO Checker to your type.com workspace.
2. **Claude Code:** Download the skill and extract it into ~/.claude/skills/shopify-aeo-checker/ (or .claude/skills/shopify-aeo-checker/ in a project). Then ask Claude to use Shopify AEO Checker.
3. **Codex:** Download the skill and extract it into ~/.agents/skills/shopify-aeo-checker/ (or .agents/skills/shopify-aeo-checker/ in a repository). Then ask Codex to use Shopify AEO Checker.

## Frequently asked questions

### What is Shopify AEO Checker?

Shopify AEO Checker is an AI skill for sales & marketing teams that you can use in Claude Code, Codex, or type.com. It works with Shopify.

### What does Shopify AEO Checker do?

See how often a Shopify brand shows up when AI shopping agents search all of Shopify, versus competitors, from a single product link.

### What do I need to use Shopify AEO Checker?

One public Shopify product link; Python 3.9+; no API keys needed (read-only public catalog search).

### Can I use Shopify AEO Checker in Claude Code or Codex?

Yes. Shopify AEO Checker is a standard Agent Skills folder with a SKILL.md file. Download it and extract it into ~/.claude/skills/ for Claude Code or ~/.agents/skills/ for Codex.

### Who created Shopify AEO Checker?

Hov from The Growth Chef created Shopify AEO Checker. The type.com team reviews every skill before it is published in the Skills Library.

## Example output

Example output from a sample run. Company names and figures are sample data.

```markdown
## AEO share of shelf: Northfield Knit, 2026-09-25

**Visibility score: 52/100 (Weak).** The brand holds **3 of 15 results (20%)** across three shopper searches on Shopify's Global Catalog and makes the top 10 on 2 of 3.

*Sample run on fictional stores. Source: Shopify Global Catalog (all Shopify stores), anonymous agent tier. This is what Shopify returns to AI shopping agents, not ChatGPT or Gemini final rankings.*

| Search | Brand results | Positions |
|---|---|---|
| mens merino sweater | 2 of 6 | #2, #3 (your product #3) |
| warm crew neck sweater | 1 of 5 | #5 |
| wool sweater gift | 0 of 4 | none |

### Who owns this shelf
1. Woolworth Mills: 6 results, best #1, on 3 of 3 searches
2. Basics Bros: 3 results, best #1, on 3 of 3 searches
3. Coastline Cashmere: 3 results, best #1, on 3 of 3 searches
4. **Northfield Knit (you):** 3 results, best #2, on 2 of 3 searches

### What to look at
- **High:** the brand is absent from the top 20 for "wool sweater gift". Woolworth Mills, Basics Bros and Coastline Cashmere lead it.

In Type, the skill also builds a Google-style results app whose search bar runs new live searches and updates the score and competitor list.
```

## Part of

- [BFCM Skills](https://typestaging.com/library/skills/bfcm-skills.md)

## Related skills

- [Budget Pacer](https://typestaging.com/library/skills/budget-pacer.md): Project month-end spend from a trailing run rate across campaigns and clients, flag over- and under-delivery beyond a tolerance, and recommend per-campaign daily budgets that reconcile exactly to each client's committed total.
- [BFCM Cohort Quality](https://typestaging.com/library/skills/bfcm-cohort-quality.md): Find out if last Black Friday's new customers were worth it: contribution, repeats and payback vs October and January buyers, by discount, source and product.
- [Holiday Support Macros](https://typestaging.com/library/skills/holiday-support-macros.md): Prepare your support team for BFCM: forecast holiday tickets and staffing, find policy gaps and stale macros, and generate holiday macros built only from your written policies.
- [Holiday Shipping Cutoff Checker](https://typestaging.com/library/skills/holiday-shipping-cutoffs.md): Find the last day customers can order on each shipping service and still get it by the holiday, check every delivery promise against it, and plan the switch to expedited and e-gift cards.
- [BFCM Live Pulse](https://typestaging.com/library/skills/bfcm-live-pulse.md): Turn hourly sales and ad spend into a BFCM status update with sales pacing, budget guardrails, checkout alerts, code-use anomalies and stock risk.
- [BFCM Offer & Discount Config QA](https://typestaging.com/library/skills/bfcm-offer-config-qa.md): Check your Shopify BFCM discounts against the offer plan before launch: stacking, sale windows, who gets each discount, code limits and free shipping, with test carts and a dated fix list.

## Package files

- DATA_CONTRACT.md
- LICENSE.txt
- SKILL.md
- app_template/convex/app.ts
- app_template/src/App.tsx
- app_template/src/aeo.css
- app_template/src/aeoTypes.ts
- examples/expected_global_output.txt
- examples/expected_output.txt
- examples/make_fixtures.py
- examples/make_global_fixtures.py
- examples/run.sh
- examples/run_global.sh
- scripts/aeo_check.py
- scripts/aeo_global.py

## SKILL.md

````markdown
---
name: shopify-aeo-checker
description: Check how a Shopify brand shows up to AI shopping agents. Takes ONE product link, works out the brand, writes shopper search terms from the product page, searches Shopify's cross-store Global Catalog, and shows how often the brand appears versus competitors. In Type it builds a Google-style results app, branded by The Growth Chef, whose search bar runs new live searches.
---

# Shopify AEO Checker (Global Catalog share of shelf)

Shows what AI shopping agents get back when a shopper searches across **all Shopify
stores**, and how much of that shelf a brand owns versus competitors. Input is a single
product link. Outputs: a text summary, `report.md`, `aeo-data.json`, and (in Type) a
**Type app**, a Google-style results page whose search bar runs new live searches and
updates the score and competitor list.

## Before you run

1. **Get the files.** The published package already contains `scripts/`, `examples/`, and `app_template/` in the right folders. Keep that layout when downloading or installing it. No `assets/` folder is required: live runs fetch the logo from The Growth Chef website, with its favicon as a fallback.
2. **Use exact copies.** Never run a script you summarised or rebuilt from memory. Watch for a trailing newline added on write.
3. **Run from the skill's folder** with explicit interpreters (`python3`, `bash`). Python 3.9+, standard library only, no API keys.
4. **Try the sample first.** `bash examples/run_global.sh` must match `examples/expected_global_output.txt` exactly. If not, stop and report the first differing line.

## Onboarding

Only ask for **one product link** (`https://<store>/products/<handle>`). Do not ask for the
domain, brand or search terms; work them out. Optional extras the user may give: shopper
phrases they already know, or a display name.

## Run it

1. **Read the product page:**
   `python3 scripts/aeo_global.py --product <url> --facts`
   This prints the title, vendor/shop name, product type, price, tags, options and description.
2. **Write 4-5 search terms yourself** from those facts, the way a shopper would type them *without knowing the brand*: category ("mens t-shirts"), format ("t-shirt packs for men"), fit or feature ("fitted crew neck t-shirts"), material ("cotton blend crew neck tees"), and one "best ..." intent ("best basic tees for men"). No brand names, no internal tags, no SKU jargon. Add any phrases the user gave.
3. **Run the search and record it:**
   ```bash
   python3 scripts/aeo_global.py --product <url> \
     --query "mens t-shirts" --query "t-shirt packs for men" --query "fitted crew neck t-shirts" \
     --query "cotton blend crew neck tees" --query "best basic tees for men" \
     --record aeo-<brand>/fixtures --out aeo-<brand>
   ```
   Flags: `--top N` results per search (default 20, max 50), `--country US`, `--brand "Name"`, `--date`, `--fixtures <dir>` to replay offline. If no `--query` is given, the script uses simple fallback terms from the product type.
4. **Build the results app (Type).** The run writes `aeo-<brand>/aeoData.ts` with the brand matching rules, the product, the recorded searches and the embedded Growth Chef logo.
   - Call `start_app_build` with a title like `AEO Share of Shelf – <Brand>`.
   - In the returned directory, copy `app_template/convex/app.ts` to `convex/app.ts`, `app_template/src/App.tsx` and `app_template/src/aeoTypes.ts` to `src/`, and `aeo-<brand>/aeoData.ts` to `src/aeoData.ts`. Append `app_template/src/aeo.css` to the end of `src/styles.css`, keeping the starter styles. Leave `convex/schema.ts` and every platform-owned file unchanged.
   - Call `prepare_app_build` with that directory. Follow the phase it returns. The app uses Type-owned build files, so validate it with Type's build step; a standalone local build is not the supported check.
   - For a new check on an existing app, use `checkout_app`, replace only `src/aeoData.ts`, then prepare again.
   - Do not deploy it anywhere else unless the user asks.
   - Outside Type, share `report.md` and use `aeo-data.json` with the template as a reference for rendering.
5. **How the app works.** Recorded searches load instantly. Typing in the search bar and pressing Enter calls the app's `searchCatalog` read-only backend action, which searches the Global Catalog server-side. The new search is added as a chip, and the score, share of shelf and "Who owns this shelf" list update. Chips can be removed with ×. New searches are not saved between visits; re-run the script to update the recorded set. The page is always light, like a Google results page.

## How it works

- **Brand.** Read from `/products/<handle>.js` (vendor) and `/meta.json` (shop name, myshopify domain). A result counts as the brand when the seller's myshopify domain, store domain or name matches.
- **Search.** Each term goes to `search_catalog` on `https://catalog.shopify.com/api/ucp/mcp` (Shopify Global Catalog, anonymous tier, Shopify's public example agent profile, ships-to context US), 1 second apart.
- **Numbers.**
  - Brand results per search, e.g. 12/20.
  - Brand's first position.
  - Whether the exact product appears.
  - Share of shelf: brand results ÷ all results shown.
  - Visibility score (0-100): the average of the brand's best position per search (#1 = 100, #2-3 = 85, #4-5 = 70, #6-10 = 50, #11-20 = 25, #21-50 = 10, absent = 0). Ratings: 80+ Strong, 60-79 Fair, 40-59 Weak, under 40 Poor.
  - Competitor list: sellers ranked by number of results across all searches.
- **App.** Google-style results page with an editable search bar. Chips switch between searches and show brand results per search (green: brand in the top 3; amber: top 10; red: lower or absent). Each result shows the seller as the site name. The brand's products are highlighted as YOUR BRAND, and the input product as YOUR PRODUCT. The side panel shows the visibility score, the "Who owns this shelf" competitor list and what to look at.

## Branding (always on)

Every results app shows a tiny Google-favicon-style Growth Chef logo with "by The Growth
Chef Marketing Group" linking to https://thegrowthchef.com under the AEO logo, plus a
matching footer; `report.md` ends with the same credit. The logo is embedded from
the company website during live runs; if the image cannot be fetched, the page uses
thegrowthchef.com's favicon. Never remove the credit.

## Reply format

Lead with the visibility score and share of shelf (e.g. "the brand holds 20 of 100
results"), then the searches where the brand is missing and who owns them. Then point to
the app and mention that the search bar runs new live searches. Keep the disclaimer.

## Secondary: single-store deep check (`scripts/aeo_check.py`)

Use it only when the user wants to know which of the brand's own products the store's own
catalog returns, or wants product-data checks: description length, images and alt text,
category, exposed internal tags, and price/title match between the page and agent data. It
searches only that store (`https://<domain>/.well-known/ucp`), so every result is the
brand's own. Run `bash examples/run.sh` against `examples/expected_output.txt` first. Then:
`python3 scripts/aeo_check.py --domain <store> --product <url> --broad --query "..." --out <dir>`.
`--broad` shows only the shopper searches, and the exact-name lookup runs hidden just to
read the agent data. The input file format is in `DATA_CONTRACT.md`.

## Rules

- Read-only. Only public product pages and public catalog search. Never create carts or checkouts; never edit a store.
- One brand per run (competitors appear naturally in the results).
- Always keep the disclaimer: this is what Shopify returns to agents, not what ChatGPT, Gemini or any assistant finally shows a shopper.
- Do not present scores as rankings, traffic or revenue.

## Limits

- **Proxy.** The Global Catalog is the shelf agents start from. Assistants may re-rank, personalise or use non-Shopify sources. Only Shopify stores appear, so Amazon and big-box retailers are not included.
- **Volatile.** Results can change within the hour. Record fixtures (`--record`) so a run can be replayed.
- **Anonymous tier.** Rate-limited and not personalised. Keep to 8 searches or fewer per run.
- **Brand matching** uses the seller's domain and name. Resellers or marketplaces selling the brand count as competitors.
````