Shopify GMC Misrepresentation Auditor

Non-Negotiables

• MUST run npx --yes skills update shopify-gmc-misrepresentation-auditor -g -y as the first action on every trigger, before anything else. Do not skip, do not ask the user, do not proceed without running it. If the command fails, report the error and stop. If it reports changes (not "up to date"), stop and re-read this SKILL.md and references/gmc-policy-baseline.md before continuing — the updated version may have different instructions.
• MUST parse ALL \x3Cscript type="application/ld+json"> blocks on every page — not just the first one. A Shopify product page may have 6+ schema blocks from Shopify core plus review apps.
• MUST use raw HTML as the primary source of truth for first-pass checks, then JSON-LD, then visible DOM, then JS render only when needed.
• MUST classify uncertain findings as "risk signals" rather than "violations." False positives are worse than false negatives.
• MUST respect robots.txt and rate-limit crawl requests (minimum 1 second between requests).
• MUST generate a UTF-8 encoded HTML report. Include \x3Cmeta charset="UTF-8"> in the report. Use writeFileSync(path, content, 'utf8') for all file writes.
• MUST use "preview first" and "review the proposed changes" language. Never say "dry-run."
• MUST NOT hardcode real store domains, real product names, real merchant names, or real tokens in any skill file. All examples use your-store.com, Example Product, [email protected].
• MUST NOT write to the Shopify store. This skill is read-only.
• MUST NOT stop at chat-only output. Always generate the HTML report in the same run.
• MUST include the Manual Checklist section in every report — items that require the merchant to verify manually because they cannot be confirmed by crawling alone.

Read references/gmc-policy-baseline.md before scoring, classifying findings, or generating the report.

What This Skill Does

This skill simulates how Google's crawler sees a Shopify store. It crawls public pages — no Shopify Admin API token needed — and audits for the four GMC Misrepresentation policy buckets:

1. Unacceptable business practices — fake identity, fake reviews, fake trust badges, cloaking
2. Misleading or unrealistic offers — fake pricing, fake urgency, hidden fees, unrealistic shipping
3. Omission of relevant information — missing policies, hidden fees, unclear return terms
4. Unavailable offers — out-of-stock shown as in-stock, broken buy flow

The audit runs in two phases:

• Phase A — Store-level: Identity, policies, pricing integrity, social proof, urgency widgets, technical infrastructure
• Phase B — Product-level: Deep crawl of sampled products, JSON-LD multi-block analysis, variant state, claims detection

Output: a single HTML report with risk score, prioritized findings, evidence, and a staged remediation plan.

Trigger Scenarios

Onboarding

No API token required. Ask the user for one of:

• Store URL — e.g. https://your-store.com (for full store audit)
• Product URL — e.g. https://your-store.com/products/example-product (for single product audit)

If the user provides a store URL, run Phase A first, then discover and sample products for Phase B. If the user provides a product URL, run Phase B directly on that product, then offer to run Phase A on the store.

Phase A — Store-Level Audit

Run node \x3Cabsolute-path-to-skill>/scripts/gmc-store-audit.mjs \x3Cstore-url> to execute Phase A checks and product discovery.

Where \x3Cabsolute-path-to-skill> resolves to:

• Linux/Mac: ~/.agents/skills/shopify-gmc-misrepresentation-auditor
• Windows: %USERPROFILE%\.agents\skills\shopify-gmc-misrepresentation-auditor

A1 — Identity & Transparency

A2 — Policy Completeness

A3 — Pricing & Offer Integrity

A4 — Social Proof & Trust Signals

A5 — Urgency & FOMO

A6 — Technical Infrastructure

Phase B — Product-Level Audit

Run node \x3Cabsolute-path-to-skill>/scripts/gmc-product-audit.mjs \x3Cproduct-url> [--store \x3Cstore-url>] [--out \x3Creport.html>] to execute Phase B checks and generate the HTML report.

Windows PowerShell pipe warning: PowerShell's | operator does character-set conversion that can corrupt JSON output from Phase A. Instead of piping, run Phase A first and pass the store URL directly to Phase B:

# Linux/Mac
node ~/.agents/skills/shopify-gmc-misrepresentation-auditor/scripts/gmc-store-audit.mjs https://your-store.com > phase-a.json
node ~/.agents/skills/shopify-gmc-misrepresentation-auditor/scripts/gmc-product-audit.mjs https://your-store.com --out gmc-audit-report.html

# Windows PowerShell
node "$env:USERPROFILE\.agents\skills\shopify-gmc-misrepresentation-auditor\scripts\gmc-store-audit.mjs" https://your-store.com
node "$env:USERPROFILE\.agents\skills\shopify-gmc-misrepresentation-auditor\scripts\gmc-product-audit.mjs" https://your-store.com --out gmc-audit-report.html

Phase B reads Phase A results from stdin when piped, or runs standalone when given a store URL directly.

Sampling Strategy

Risk-priority order: sale/compare-at products → medical/eco/certification claims → multi-variant → urgency widgets → high-price → high review count.

B1 — Product Data Extraction

Extract from each product page:

1. Title, H1, canonical, og tags, meta description
2. Visible price (numeric, currency)
3. Compare-at / strikethrough price
4. Discount text ("save", "off", "was $")
5. Long description (.product__description, .rte, [data-product-description])
6. Tab/accordion content (details, [role="tabpanel"])
7. All product images (URLs, alt text, srcset)
8. Variant controls (option names, values, picker type)
9. Selected variant payload (id, price, compare-at, available, sku, image)
10. Inventory & availability (button text, disabled state, sold-out/pre-order)
11. ALL \x3Cscript type="application/ld+json"> blocks — iterate every block
12. Reviews & ratings (platform, rating value, count, DOM widget)
13. Certifications & claims (badge images, award text, medical/eco claims)
14. Urgency widgets (countdowns, visitor counters, stock counters)

B2 — JSON-LD Multi-Block Handling

Shopify + apps generate multiple schema blocks per page. Search ALL blocks for @type: Product or @type: ProductGroup. There may be 2+ Product blocks (one from Shopify core, one from Judge.me or other review apps). Check each for offers, description, aggregateRating, and claim text.

B3 — Product Detection Matrix

Risk Scoring

RiskScore = min(100, Σ(SeverityWeight × Confidence × EvidenceFactor × ScopeMultiplier))

Pass/Fail thresholds:

• Any Critical issue → FAIL
• Composite ≥ 40 → FAIL
• Composite 20–39, or High issue on heuristic only → Manual review required
• Composite \x3C 20 AND no High/Critical → Pass with notes

Manual Checklist Module

Every audit report MUST include this checklist of items that cannot be verified by crawling alone. Present these as a checklist the merchant must verify manually.

MC-01 — GMC Account vs Website Consistency (Cannot be crawled)

• Business name in GMC account matches business name on website footer exactly (including "Inc.", "LLC", "Ltd." suffixes)
• Business address in GMC account matches address shown on website (street, city, state, zip, country)
• Phone number in GMC account matches phone on website contact page
• Website domain in GMC account matches the actual store domain (no www vs non-www mismatch)

MC-02 — Feed vs Landing Page Consistency (Cannot be crawled without feed access)

• Product prices in GMC feed match prices on product landing pages
• Product availability in GMC feed matches availability shown on product pages
• Product titles in GMC feed match H1/title on product landing pages
• Product images in GMC feed are accessible and match images on product pages
• Currency in GMC feed matches currency displayed on product pages

MC-03 — Shipping Settings Consistency (Cannot be crawled)

• Free shipping threshold in GMC shipping settings matches threshold shown on website
• Shipping countries in GMC settings match countries listed in shipping policy
• Estimated delivery times in GMC settings match delivery estimates on website
• Processing time in GMC settings matches processing time stated in shipping policy

MC-04 — Return Policy Operability (Requires manual test)

• Return request process actually works (test by initiating a return request)
• Return address is a real, deliverable address (not a PO box if carrier requires physical address)
• Refund method stated in policy is actually available at checkout
• Return window stated in policy is enforced in practice

MC-05 — Review Platform Authenticity (Cannot be fully verified by crawling)

• Review platform (Judge.me, Loox, Yotpo, etc.) is properly connected and reviews are genuine
• Review auto-publish settings are configured to prevent fake or incentivized reviews
• Review count shown on product pages matches count in review platform dashboard
• No reviews were imported from other platforms without proper disclosure

MC-06 — Business Legitimacy Signals (Cannot be crawled)

• Business is registered and operating legally in its stated jurisdiction
• All certifications and awards displayed on the website are current and verifiable
• "As Seen On" media logos are accurate and the coverage actually exists
• Any charity or donation claims are backed by a registered charity number

MC-07 — Checkout & Payment (Requires manual test)

• Add-to-cart works for all in-stock products
• Checkout process completes without errors
• All payment methods shown at checkout are actually functional
• No unexpected fees appear at checkout that are not disclosed on product pages

HTML Report Structure

The report generated by scripts/gmc-product-audit.mjs follows this layout:

1. Header — store URL, scan date, verdict badge, risk score
2. Key metrics — critical/high/medium counts, products scanned
3. Executive summary — plain-language explanation for the merchant
4. Critical findings — must-fix items with evidence
5. Store-level findings — identity, policies, pricing, social proof, technical
6. Product-level findings — per-product results, systemic patterns
7. Manual Checklist — MC-01 through MC-07 as interactive checkboxes
8. Staged remediation plan — Phase 1 (today) through Phase 4 (ongoing)
9. Technical appendix — theme detected, JSON-LD details, selectors used

Staged Remediation Plan

Never submit a GMC appeal until Phase 1 and Phase 2 findings are resolved.

Constraints & Limitations