agentleFS
chanktbchanktb/claude-shopify-growth/skills/product-analyze/SKILL.md

product-analyze

Skill2 starsChanged 5 months agoMITView on GitHub

Audit and score a Shopify product page (PDP) on a 5-category 100-point scoring system built for commercial product pages (NOT collections or blogs). Categories: Product Copy Quality (20), SEO + Commercial Intent (25), Product Schema + Technical (20), Trust & Conversion (20), GEO / AI-Citation Readiness (15). Pulls live data via the Shopify connector + WebFetch + GSC 90d. Generates prioritized recommendations (Critical/High/Medium/Low) with specific fixes and Merchant-Center feed risk flags. Use when the user says "analyze product page", "audit PDP", "product page score", "check product listing", "rate this product page", "product SEO audit", or any Shopify product-page review.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write the report to:

    line 241
  2. Very specific:

    Does NOT rewrite the description or title (use /product-optimize)

    line 260
  3. Distinctive:

    Does NOT auto-fix schema or push changes (audit-only)

    line 261
  4. Very specific:

    Does NOT analyze collection pages (use /collection-analyze)

    line 262

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Product Analyzer: Quality Audit & Scoring for Shopify Product Pages

Scores a Shopify product page (PDP) on a 0–100 scale across 5 commerce-focused categories. Pulls live data from the connected Shopify store (product, variants, images, price, inventory), fetches the public URL (curl for <head> + Product schema, a rendered read for visible markup), and overlays Google Search Console performance (90-day clicks / impressions / position / CTR).

This is NOT collection-analyze. A PDP is the money page — it carries transactional intent, a single-product schema (Product + Offer + AggregateRating), a buy box, variants, and reviews. "Good copy" here means a unique, benefits-first description that closes a buyer and feeds Google Shopping

  • AI Overviews — not category navigation.

Reference documents (paths from skill root):

  • references/product-rubric-100pt.md — full per-category checklist with decision rules, anti-patterns, tier adjustments, and gate details
  • references/product-schema.md — JSON-LD templates for Product, Offer, AggregateRating, Review, BreadcrumbList, and additionalProperty specs

Input Handling

  • URL: e.g. https://your-store.com/products/{handle}
  • Handle: e.g. {handle} (pair with --site your-store.com)

Flags

  • --site <domain> — required when input is a bare handle
  • --no-gsc — skip GSC pull (offline mode / no credentials; CTR signal falls back to neutral)
  • --tier hero|standard|variant-parent|technical|consumable|new — override the auto-detected tier (see Step 1.5)
  • --strict — N/A items earn 0/N instead of partial credit, surfacing content gaps directly
  • --format markdown|json — default markdown; JSON for pipeline consumption

Scoring Process

Step 1: Live Data Extraction

Pull data from THREE sources, in parallel where possible:

1a. Shopify Admin API (via your Shopify MCP connector's get-product and friends):

  • Product GID, title, handle, descriptionHtml, productType, vendor, tags, status
  • Variants (first 20): price, compareAtPrice, sku, barcode (GTIN), inventoryQuantity, availableForSale, selectedOptions
  • Images/media: count, altText per image, featuredMedia URL
  • SEO fields (seo.title, seo.description), metafields (specs, reviews app)
  • createdAt, updatedAt, publishedAt

1b. Fetch the public URL — use curl for anything in <head> and any JSON-LD, and a rendered read (WebFetch / headless) only for visible content:

⚠️ Do NOT use WebFetch for <title>, meta, canonical, OG tags, or JSON-LD. WebFetch converts the page to markdown and silently drops <head> tags and <script type="application/ld+json"> blocks — you will get a false "ABSENT". Always curl for schema + head:

curl -sL -A "Mozilla/5.0" "<url>" | grep -oE '"@type" *: *"[A-Za-z]+"' | sort | uniq -c
curl -sL "<url>" | grep -oiE '<link[^>]*rel="canonical"[^>]*>|<meta[^>]*name="description"[^>]*>'

A page can carry BreadcrumbList + Organization + WebSite schema yet have NO Product/Offer block — check for the Product @type specifically, not just "some JSON-LD exists".

GSC-aggregate trap: a green "Merchant listings / Product snippets: N valid" count in Search Console does NOT prove THIS product page has Product schema. That total can be inflated entirely by Product markup emitted on collection / category pages (the grid ItemList), so a store with zero PDP schema can still show thousands of "valid" items. Trust the per-URL curl check above, and if you open GSC, read the actual valid URLs — are they products or collections? A site-level "valid" total is not per-page coverage.

Extract (curl for head/schema, render for the rest):

  • <title>, meta description, canonical, OG/Twitter tags
  • H1 (must equal product name, single H1)
  • Description body: word count, uniqueness signal, bullet/scannability
  • Buy box: visible price, compare-at, stock badge, variant selector, add-to-cart, shipping/returns near buy box
  • Reviews: star rating + count visible, review block present
  • JSON-LD: Product, Offer, AggregateRating, Review, BreadcrumbList
  • Image count + zoom, spec/dimensions table presence, related-products block
  • FAQ / Q&A block, comparison content

1c. GSC 90-day pull (gsc-query skill or equivalent) for the product URL:

  • Total clicks, impressions, average position, CTR
  • Top 10 queries with clicks/impressions/position
  • Position distribution (1–3 / 4–10 / 11–20 / 21–30 / 31–100)

Skip 1c if --no-gsc; mark CTR-dependent SEO sub-checks as N/A.

Step 1.5: Tier Detection

Auto-detect the product's tier — the rubric weights certain checks higher per tier (see references/product-rubric-100pt.md §Tier Adjustments):

TierDetection ruleRubric emphasis
heroTop revenue/traffic product (GSC clicks high, or flagged best-seller)Reviews + schema + conversion weighted highest; a schema gap is Critical
variant-parent≥ 5 variants (size/color/style)Variant UX + canonical/variant-URL handling weighted higher
technicalproductType/title implies spec-driven durables (electronics, tools, appliances, equipment)Specs table + additionalProperty + compatibility weighted higher
consumableLow-differentiation, repeat-purchase, low pricePrice + availability + reviews weighted; unique-copy bar relaxed
newPublished in last 30 daysSchema + freshness weighted; Critical if Product schema missing
standardDefault when none of the aboveBalanced weighting

User can override with --tier. Pipeline mode (product-audit-pipeline) forces re-detection per product.

--strict mode

By default, N/A items (e.g. reviews sub-check when the store has no reviews app) earn partial credit (1/N). With --strict, N/A items earn 0/N, surfacing the content gap directly instead of masking it with vacuous full credit. Use --strict for site-wide pipeline runs, before/after re-audits, and hero-tier products.

Step 2: Score Each Category

Load references/product-rubric-100pt.md for the full checklist.

Category 1 — Product Copy Quality (20 points)

Design principle: a PDP description is benefits-first and unique. The #1 failure mode is pasting the manufacturer's boilerplate (thin, duplicated across every retailer). Lead with the benefit/use, then back it with specs.

CheckPointsPass Criteria
Product title clarity4Brand + product + key attribute + type; readable; not keyword-stuffed
Description depth (benefits-first)4Opens with core benefit/use, then specs; ≥150 words of unique copy
Unique (not manufacturer boilerplate)3<70% similarity to the manufacturer/other-retailer copy; an original angle
Buying-decision clarity3Answers who it's for, what problem it solves, what's in the box, how it compares
Human voice (AI-content signals)3≤0.3 em-dash / 100 words; ≤3 AI-trigger phrases; burstiness (varied sentence length, not uniform); concrete specifics over vague filler ("high quality" / "perfect for everyone"); no formulaic scaffolding
Scannability3Bullets for specs/features; short paragraphs; key info above the fold

Category 2 — SEO + Commercial Intent (25 points)

CheckPointsPass Criteria
<title> format + length450–60 chars; brand + product + key modifier; primary keyword front-loaded
Meta description3120–160 chars; benefit + soft CTA (free ship / in stock / N reviews)
H1 = product name2Single H1, matches the product; not boilerplate
URL structure2/products/{kebab-handle}; clean; no typos
Canonical + variant handling3Self-canonical; variant URLs (?variant=) canonical to the main product (no dup content)
Image alt text2Product images have descriptive alt (not IMG_1234 / empty)
GSC CTR signal3CTR ≥ benchmark at position 1–10. Position 1–10 but CTR < benchmark → title/meta drag
GSC position vs intent3Ranking queries match product/transactional intent (not informational leak)
Internal links INTO product3≥3 inbound links (parent collection, related products, blog) with anchor variety

Category 3 — Product Schema + Technical (20 points)

CheckPointsPass Criteria
Product JSON-LD present3@type Product with name, image, description, sku
Offer complete4price, priceCurrency, availability, url, priceValidUntil; matches the visible price
Brand + identifiers3brand; gtin/mpn/sku where available (Google Shopping requirement for known manufacturers)
AggregateRating + Review3ratingValue + reviewCount when reviews exist; individual Review markup
BreadcrumbList JSON-LD2Present; matches the visible breadcrumb (product ← collection ← home)
additionalProperty specs2Structured specs as additionalProperty / PropertyValue (feeds AI + rich results)
Valid + no errors2Passes the Rich Results Test; no schema errors; images meet minimum dimensions
LCP / mobile1LCP < 2.5s if measurable; else neutral

Category 4 — Trust & Conversion (20 points)

CheckPointsPass Criteria
Reviews present + visible4≥1 review; star rating + count near the top; not stale-only
Stock / availability clarity2In-stock / low-stock / backorder clearly stated
Shipping + returns info3Shipping cost/time + returns policy visible or linked near the buy box
Images: count + quality3≥4 images (angles + in-use + scale); zoomable; clean first image
Specs / dimensions table3Structured specs table (dimensions, materials, compatibility) present
Cross-sell / related2"Related" / "frequently bought together" / "complete the set" block
USP / benefit callouts2Key benefits as scannable callouts, not buried in prose
Variant UX1Clear variant selector (swatch/dropdown); price + stock update per variant

Category 5 — GEO / AI-Citation Readiness (15 points)

PDPs get cited in AI Overviews / ChatGPT / Perplexity for "best X", "X vs Y", "is X good for Z". This category scores how extractable + citable the page is.

CheckPointsPass Criteria
Direct-answer product Q&A / FAQ43–5 Q&A answering real buyer questions (compatibility, sizing, use, care); FAQPage schema
Comparison / "vs" content3How it compares to alternatives or variants (table or prose); citable passage
Structured, machine-readable specs3Specs as a table and additionalProperty so AI can extract them
Entity clarity2Consistent brand + model + category naming across title, schema, and copy
Use-case / "best for" framing3States who/what it's best for (maps to long-tail "best X for Y" AI queries)

Step 3: GATES (Hard fail flags)

Each GATE adds a 🔴 GATE flag at the top of the report and forces a "Critical" recommendation. GATES do not zero the score, but several also carry a Merchant-Center feed risk (Shopping disapproval):

  1. No Product JSON-LD AND the product is indexable (lost Shopping + AI-citation surface)
  2. Offer price in schema ≠ visible price (Merchant Center disapproval risk 🛑)
  3. availability schema wrong (says InStock when out of stock, or vice versa) 🛑
  4. Missing gtin/mpn AND brand is a known manufacturer (Shopping feed rejection risk 🛑)
  5. GSC: 0 clicks AND > 500 impressions in 90d (severe title/meta drag → rewrite)
  6. Description duplicated across > 5 products (manufacturer boilerplate → thin content)
  7. Image alt missing on > 50% of images (accessibility + image-search loss)
  8. Duplicate / conflicting schema — two Product blocks OR two AggregateRating blocks on one page (theme + a review app both emit). Invalid; Google may ignore or flag it.

Drift detection: GATE 2 (schema price ≠ visible price) is also how you catch a stale schema — a static block that fell out of sync after a price or stock change fails GATE 2. The fix is to live-bind the dynamic fields (see references/product-schema.md §0), not to re-push a fresh number.

Step 4: Generate Fix Recommendations

Each finding gets a severity tag:

  • 🔴 Critical — GATE-triggered OR a category scoring < 50% of its max
  • 🟠 High — a single check failing AND tied to traffic OR conversion loss
  • 🟡 Medium — a single check failing AND nice-to-fix
  • 🟢 Low — polish / consistency / long-tail

Each fix includes: the exact finding (current value + expected value), the proposed change (with example markup / copy snippet), the estimated lift (qualitative), and the location to edit (Shopify admin deep-link when possible).

Step 5: Export Markdown Report

Write the report to:

output/[site]/products/[product-handle]/product-quality-score.md

Report sections (in order):

  1. Header — product title, URL, tier, audit timestamp, version
  2. Composite score (e.g. 71 / 100) + category breakdown table
  3. 🔴 GATES triggered (with 🛑 Merchant-Center feed-risk flags)
  4. Critical / High / Medium / Low fixes
  5. GSC Snapshot (90d clicks / imps / position / CTR + top queries)
  6. Shopify Snapshot (variants, price range, inventory, image count)
  7. Schema Audit (what's present vs missing, with feed-risk callouts)
  8. Re-audit instructions ("re-run after fix X to verify")

JSON export available with --format json.

What This Skill Does NOT Do

  • Does NOT rewrite the description or title (use /product-optimize)
  • Does NOT auto-fix schema or push changes (audit-only)
  • Does NOT analyze collection pages (use /collection-analyze)

Composition with Other Skills

  • After: product-optimize — consumes this report as its baseline + gaps
  • Sibling: product-audit-pipeline — batch all products, rank by composite score
  • Reuses: gsc-query (GSC pull), seo-schema (Schema.org validation)

Output Convention

Per-product artifact:

output/[site]/products/[product-handle]/
├── product-quality-score.md       (this skill's output)
├── product-quality-score-vN.md    (iteration history)
├── shopify-snapshot.json          (raw connector pull, for re-use)
└── gsc-snapshot.json              (raw GSC pull, for re-use)

This mirrors the collection module's output/[site]/[handle]/ convention, keeping the ledger format consistent across the kit.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.