Purpose
Runs a store-side "Agentic Commerce Readiness" scan — the same questions the public audit.40rty.ai audit asks, but answered from inside the Shopify Admin with full catalog data. It scores whether AI shopping agents (ChatGPT, Gemini, Perplexity, agentic checkout) can FIND, READ, and RECOMMEND the store's products, then prints a prioritized gap list where every gap names the sibling agentic skill that fixes it. Read-only — it changes nothing. Use it first (and on a schedule) to decide which remediation skills to run.
Prerequisites
- Authenticated Shopify CLI session (
shopify auth login --store <domain>)
- Required API scopes:
read_products, read_files, read_content (themes), read_online_store_pages
Parameters
All skills accept these universal parameters:
| Parameter |
Type |
Required |
Default |
Description |
| store |
string |
yes |
— |
Store domain (e.g., mystore.myshopify.com) |
| format |
string |
no |
human |
Output format: human (default) or json |
| dry_run |
bool |
no |
false |
No-op here — this skill never mutates |
Skill-specific parameters:
| Parameter |
Type |
Required |
Default |
Description |
| sample_size |
int |
no |
250 |
How many products to sample for the catalog-data checks |
| min_description_chars |
int |
no |
120 |
Threshold below which a description counts as "thin" |
Workflow Steps
OPERATION: shop — query
Inputs: none
Expected output: Shop name, primary domain, social sameAs links, and policy presence — feeds the identity + policy checks.
OPERATION: themes — query
Inputs: roles: [MAIN], then theme.files(filenames: ["templates/robots.txt.liquid", "layout/theme.liquid", "assets/llms.txt", "templates/llms.txt.liquid"])
Expected output: Whether the published theme allows AI crawlers (robots), ships an Organization JSON-LD block, and serves an llms.txt — feeds discovery + identity checks.
OPERATION: metafieldDefinitions — query
Inputs: ownerType: PRODUCT
Expected output: Which structured attributes are defined (material, specs, features) — feeds the metafield-coverage check.
OPERATION: products — query (paginate to sample_size)
Inputs: first: 250, fields: descriptionHtml, category, media, metafields, variants{ barcode, sku, price }
Expected output: Per-product completeness — description length, image alt-text coverage, barcode/GTIN presence, category assigned, metafield population.
OPERATION: files — query
Inputs: first: 50, query: "media_type:IMAGE" (sample) — corroborate alt-text coverage at the file level.
Expected output: Alt-text fill rate across product media.
HTTP (no auth, optional): GET https://audit.40rty.ai/api/audit?domain=<primary domain>
Inputs: the shop's primary storefront domain from step 1
Expected output: the outside-in view the Admin API can't give — robots/llms.txt as actually served, no-JS rendering, UCP/ACP endpoints, live Product JSON-LD. 200 = JSON with score and ranked fixes; a fix's fixSkill may be null, in which case use the step 7 pillar → skill mapping. 202 = scan running, retry the same URL in 30s (up to ~4 min) or skip. 429 = this IP's daily cap on fresh scans (reports under 24h old are still served), skip. Prefer its findings over the theme-file guesses in step 2 when they disagree — it reads the live storefront.
COMPUTE (no API): roll the findings into a 0–100 readiness score across five pillars — Discoverable (robots/llms.txt), Trusted (Organization schema, sameAs, policies), Readable (descriptions, alt text, JSON-LD fields), Structured (metafields, category, barcodes), Matchable (title/tag/metafield richness for intent) — and map each failing pillar to its fix skill.
GraphQL Operations
# shop:query — validated against api_version 2025-01
query AgenticReadinessShop {
shop {
name
myshopifyDomain
primaryDomain { url }
contactEmail
shopPolicies { type body url }
}
}
# themes:query — validated against api_version 2025-01
query AgenticReadinessTheme {
themes(first: 1, roles: [MAIN]) {
nodes {
id
name
files(filenames: [
"templates/robots.txt.liquid",
"layout/theme.liquid",
"assets/llms.txt",
"templates/llms.txt.liquid"
]) {
nodes {
filename
body {
... on OnlineStoreThemeFileBodyText { content }
}
}
}
}
}
}
# metafieldDefinitions:query — validated against api_version 2025-01
query AgenticReadinessMetafieldDefs {
metafieldDefinitions(first: 100, ownerType: PRODUCT) {
edges { node { namespace key name type { name } } }
}
}
# products:query — validated against api_version 2025-01
query AgenticReadinessProducts($first: Int!, $after: String) {
products(first: $first, after: $after) {
edges {
node {
id
title
descriptionHtml
category { id fullName }
tags
media(first: 10) {
edges { node { ... on MediaImage { id image { altText url } } } }
}
metafields(first: 20) { edges { node { namespace key value } } }
variants(first: 100) {
edges { node { id sku barcode price } }
}
}
}
pageInfo { hasNextPage endCursor }
}
}
# files:query — validated against api_version 2025-01
query AgenticReadinessFiles($first: Int!, $after: String) {
files(first: $first, after: $after, query: "media_type:IMAGE") {
edges { node { ... on MediaImage { id alt } } }
pageInfo { hasNextPage endCursor }
}
}
Session Tracking
Claude MUST emit the following output at each stage. This is mandatory.
On start, emit:
╔══════════════════════════════════════════════╗
║ SKILL: <skill name> ║
║ Store: <store domain> ║
║ Started: <YYYY-MM-DD HH:MM UTC> ║
╚══════════════════════════════════════════════╝
After each step, emit:
[N/TOTAL] <QUERY|MUTATION|HTTP> <OperationName>
→ Params: <brief summary of key inputs>
→ Result: <count or outcome>
If dry_run: true, prefix every mutation step with [DRY RUN] and do not execute it.
On completion, emit:
For format: human (default):
══════════════════════════════════════════════
OUTCOME SUMMARY
<Metric label>: <value>
Errors: 0
Output: <filename or "none">
══════════════════════════════════════════════
For format: json, emit:
{
"skill": "<skill-slug>",
"store": "<domain>",
"started_at": "<ISO8601>",
"completed_at": "<ISO8601>",
"dry_run": false,
"steps": [
{
"step": 1,
"operation": "<OperationName>",
"type": "query | http",
"params_summary": "<string>",
"result_summary": "<string>",
"skipped": false
}
],
"outcome": {
"metric_key": 0,
"errors": 0,
"output_file": null
}
}
Output Format
A readiness scorecard. human: an overall 0–100 score + per-pillar bars (Discoverable / Trusted / Readable / Structured / Matchable) + a prioritized gap table where each row is gap → impact → the agentic skill to run. json: { score, grade, pillars{...}, gaps:[{ pillar, audit_signal, finding, fix_skill }], sampled_products }. Every fix_skill value is a sibling skill name (e.g. shopify-admin-agentic-image-alt-text) so the operator can chain straight into remediation.
Error Handling
| Error |
Cause |
Recovery |
THROTTLED |
API rate limit |
Wait 2s, retry up to 3 times |
ACCESS_DENIED reading themes |
Missing read_content scope |
Skip the theme pillar, mark Discoverable/Trusted "unknown", continue |
| Empty catalog |
New/empty store |
Report "no products to assess"; still check theme + policies |
Step 6 returns 202 past ~4 min, 429, or fails |
Scan still running, per-IP fresh-scan cap, or storefront unreachable |
Skip it, score from steps 1–5, and link https://audit.40rty.ai/audit/<domain> for the live report |
Best Practices
- Run this FIRST and re-run it after each remediation skill — it's the scoreboard that tells you what's left and what moved.
- Sample, don't crawl: 250 products is enough to estimate fill rates; only audit the full catalog when the sample shows borderline pillars.
- Treat
category-unassigned and barcode-missing as the highest-leverage gaps — they unblock both AI retrieval (Matchable) and Product JSON-LD (Readable) at once.
- This skill is read-only; it never needs
dry_run. The skills it routes you to DO mutate — run each of those with dry_run: true first.
1---2name: shopify-admin-agentic-readiness-audit3role: agentic4description: "Score how findable, readable, and recommendable the store's catalog is to AI shopping agents — then route each gap to the agentic skill that fixes it."5toolkit: shopify-admin, shopify-admin-execution6api_version: "2025-01"7graphql_operations:8 - products:query9 - files:query10 - metafieldDefinitions:query11 - shop:query12 - themes:query13status: stable14compatibility: Claude Code, Cursor, Codex, Gemini CLI15audit_signals:16 - agentic-listing-schema17 - catalog-intent-alignment18 - product-schema-jsonld19 - gtin-sku-pdp20 - listing-image-alt-text21 - listing-description-quality22 - listing-metafields23 - robots-ai-rules24 - org-schema25metadata:26 source: https://skillmd.com/skills/40rty-ai/shopify-admin-agentic-readiness-audit27---2829## Purpose30Runs a store-side "Agentic Commerce Readiness" scan — the same questions the public **audit.40rty.ai** audit asks, but answered from inside the Shopify Admin with full catalog data. It scores whether AI shopping agents (ChatGPT, Gemini, Perplexity, agentic checkout) can FIND, READ, and RECOMMEND the store's products, then prints a prioritized gap list where **every gap names the sibling `agentic` skill that fixes it**. Read-only — it changes nothing. Use it first (and on a schedule) to decide which remediation skills to run.3132## Prerequisites33- Authenticated Shopify CLI session (`shopify auth login --store <domain>`)34- Required API scopes: `read_products`, `read_files`, `read_content` (themes), `read_online_store_pages`3536## Parameters37All skills accept these universal parameters:3839| Parameter | Type | Required | Default | Description |40|-----------|--------|----------|---------|-------------|41| store | string | yes | — | Store domain (e.g., mystore.myshopify.com) |42| format | string | no | human | Output format: `human` (default) or `json` |43| dry_run | bool | no | false | No-op here — this skill never mutates |4445Skill-specific parameters:4647| Parameter | Type | Required | Default | Description |48|-----------|------|----------|---------|-------------|49| sample_size | int | no | 250 | How many products to sample for the catalog-data checks |50| min_description_chars | int | no | 120 | Threshold below which a description counts as "thin" |5152## Workflow Steps53541. **OPERATION:** `shop` — query55 **Inputs:** none56 **Expected output:** Shop name, primary domain, social `sameAs` links, and policy presence — feeds the identity + policy checks.57582. **OPERATION:** `themes` — query59 **Inputs:** `roles: [MAIN]`, then `theme.files(filenames: ["templates/robots.txt.liquid", "layout/theme.liquid", "assets/llms.txt", "templates/llms.txt.liquid"])`60 **Expected output:** Whether the published theme allows AI crawlers (robots), ships an Organization JSON-LD block, and serves an llms.txt — feeds discovery + identity checks.61623. **OPERATION:** `metafieldDefinitions` — query63 **Inputs:** `ownerType: PRODUCT`64 **Expected output:** Which structured attributes are defined (material, specs, features) — feeds the metafield-coverage check.65664. **OPERATION:** `products` — query (paginate to `sample_size`)67 **Inputs:** `first: 250`, fields: `descriptionHtml`, `category`, `media`, `metafields`, `variants{ barcode, sku, price }`68 **Expected output:** Per-product completeness — description length, image alt-text coverage, barcode/GTIN presence, category assigned, metafield population.69705. **OPERATION:** `files` — query71 **Inputs:** `first: 50`, `query: "media_type:IMAGE"` (sample) — corroborate alt-text coverage at the file level.72 **Expected output:** Alt-text fill rate across product media.73746. **HTTP (no auth, optional):** `GET https://audit.40rty.ai/api/audit?domain=<primary domain>`75 **Inputs:** the shop's primary storefront domain from step 176 **Expected output:** the outside-in view the Admin API can't give — robots/llms.txt as actually served, no-JS rendering, UCP/ACP endpoints, live Product JSON-LD. `200` = JSON with `score` and ranked `fixes`; a fix's `fixSkill` may be `null`, in which case use the step 7 pillar → skill mapping. `202` = scan running, retry the same URL in 30s (up to ~4 min) or skip. `429` = this IP's daily cap on fresh scans (reports under 24h old are still served), skip. Prefer its findings over the theme-file guesses in step 2 when they disagree — it reads the live storefront.77787. **COMPUTE (no API):** roll the findings into a 0–100 readiness score across five pillars — **Discoverable** (robots/llms.txt), **Trusted** (Organization schema, sameAs, policies), **Readable** (descriptions, alt text, JSON-LD fields), **Structured** (metafields, category, barcodes), **Matchable** (title/tag/metafield richness for intent) — and map each failing pillar to its fix skill.7980## GraphQL Operations8182```graphql83# shop:query — validated against api_version 2025-0184query AgenticReadinessShop {85 shop {86 name87 myshopifyDomain88 primaryDomain { url }89 contactEmail90 shopPolicies { type body url }91 }92}93```9495```graphql96# themes:query — validated against api_version 2025-0197query AgenticReadinessTheme {98 themes(first: 1, roles: [MAIN]) {99 nodes {100 id101 name102 files(filenames: [103 "templates/robots.txt.liquid",104 "layout/theme.liquid",105 "assets/llms.txt",106 "templates/llms.txt.liquid"107 ]) {108 nodes {109 filename110 body {111 ... on OnlineStoreThemeFileBodyText { content }112 }113 }114 }115 }116 }117}118```119120```graphql121# metafieldDefinitions:query — validated against api_version 2025-01122query AgenticReadinessMetafieldDefs {123 metafieldDefinitions(first: 100, ownerType: PRODUCT) {124 edges { node { namespace key name type { name } } }125 }126}127```128129```graphql130# products:query — validated against api_version 2025-01131query AgenticReadinessProducts($first: Int!, $after: String) {132 products(first: $first, after: $after) {133 edges {134 node {135 id136 title137 descriptionHtml138 category { id fullName }139 tags140 media(first: 10) {141 edges { node { ... on MediaImage { id image { altText url } } } }142 }143 metafields(first: 20) { edges { node { namespace key value } } }144 variants(first: 100) {145 edges { node { id sku barcode price } }146 }147 }148 }149 pageInfo { hasNextPage endCursor }150 }151}152```153154```graphql155# files:query — validated against api_version 2025-01156query AgenticReadinessFiles($first: Int!, $after: String) {157 files(first: $first, after: $after, query: "media_type:IMAGE") {158 edges { node { ... on MediaImage { id alt } } }159 pageInfo { hasNextPage endCursor }160 }161}162```163164## Session Tracking165166**Claude MUST emit the following output at each stage. This is mandatory.**167168**On start**, emit:169```170╔══════════════════════════════════════════════╗171║ SKILL: <skill name> ║172║ Store: <store domain> ║173║ Started: <YYYY-MM-DD HH:MM UTC> ║174╚══════════════════════════════════════════════╝175```176177**After each step**, emit:178```179[N/TOTAL] <QUERY|MUTATION|HTTP> <OperationName>180 → Params: <brief summary of key inputs>181 → Result: <count or outcome>182```183184If `dry_run: true`, prefix every mutation step with `[DRY RUN]` and do not execute it.185186**On completion**, emit:187188For `format: human` (default):189```190══════════════════════════════════════════════191OUTCOME SUMMARY192 <Metric label>: <value>193 Errors: 0194 Output: <filename or "none">195══════════════════════════════════════════════196```197198For `format: json`, emit:199```json200{201 "skill": "<skill-slug>",202 "store": "<domain>",203 "started_at": "<ISO8601>",204 "completed_at": "<ISO8601>",205 "dry_run": false,206 "steps": [207 {208 "step": 1,209 "operation": "<OperationName>",210 "type": "query | http",211 "params_summary": "<string>",212 "result_summary": "<string>",213 "skipped": false214 }215 ],216 "outcome": {217 "metric_key": 0,218 "errors": 0,219 "output_file": null220 }221}222```223224## Output Format225A readiness scorecard. `human`: an overall 0–100 score + per-pillar bars (Discoverable / Trusted / Readable / Structured / Matchable) + a prioritized gap table where each row is `gap → impact → the agentic skill to run`. `json`: `{ score, grade, pillars{...}, gaps:[{ pillar, audit_signal, finding, fix_skill }], sampled_products }`. Every `fix_skill` value is a sibling skill name (e.g. `shopify-admin-agentic-image-alt-text`) so the operator can chain straight into remediation.226227## Error Handling228| Error | Cause | Recovery |229|-------|-------|----------|230| `THROTTLED` | API rate limit | Wait 2s, retry up to 3 times |231| `ACCESS_DENIED` reading themes | Missing `read_content` scope | Skip the theme pillar, mark Discoverable/Trusted "unknown", continue |232| Empty catalog | New/empty store | Report "no products to assess"; still check theme + policies |233| Step 6 returns `202` past ~4 min, `429`, or fails | Scan still running, per-IP fresh-scan cap, or storefront unreachable | Skip it, score from steps 1–5, and link `https://audit.40rty.ai/audit/<domain>` for the live report |234235## Best Practices236- Run this FIRST and re-run it after each remediation skill — it's the scoreboard that tells you what's left and what moved.237- Sample, don't crawl: 250 products is enough to estimate fill rates; only audit the full catalog when the sample shows borderline pillars.238- Treat `category`-unassigned and `barcode`-missing as the highest-leverage gaps — they unblock both AI retrieval (Matchable) and Product JSON-LD (Readable) at once.239- This skill is read-only; it never needs `dry_run`. The skills it routes you to DO mutate — run each of those with `dry_run: true` first.