用途
该技能在 Shopify 后台内部执行一次“智能体商务就绪度”（Agentic Commerce Readiness）扫描，回答与公开 agentiq.report 审计相同的问题，但基于后台内的完整目录数据作答。它评估 AI 购物智能体（ChatGPT、Gemini、Perplexity、智能体结账）能否发现（FIND）、读取（READ）并推荐（RECOMMEND）店铺商品，然后输出按优先级排列的差距清单，每项差距都标明可修复它的同级智能体技能。该技能为只读，不改变任何内容。建议首先运行（并按计划定期运行），以决定应执行哪些修复技能。
前提条件
需要已认证的 Shopify CLI 会话（shopify auth login --store <domain>）。
所需 API 权限范围：read_products、read_files、read_content（主题）、read_online_store_pages。
参数
所有技能均接受以下通用参数：
- store：字符串，必填，无默认值，店铺域名（例如 mystore.myshopify.com）。
- format：字符串，可选，默认 human，输出格式：human（默认）或 json。
- dry_run：布尔值，可选，默认 false，此处为空操作——该技能从不修改数据。
技能专属参数：
- sample_size：整数，可选，默认 250，用于目录数据检查的商品采样数量。
- min_description_chars：整数，可选，默认 120，低于该阈值的描述被视为“单薄”。
工作流程步骤
-
OPERATION: shop — query 输入：无。 预期输出：店铺名称、主域名、社交 sameAs 链接以及政策是否存在——用于身份与政策检查。
-
OPERATION: themes — query 输入：roles: [MAIN]，然后 theme.files(filenames: ["templates/robots.txt.liquid", "layout/theme.liquid", "assets/llms.txt", "templates/llms.txt.liquid"])。 预期输出：已发布主题是否允许 AI 爬虫（robots）、是否包含 Organization JSON-LD 块、是否提供 llms.txt——用于发现与身份检查。
-
OPERATION: metafieldDefinitions — query 输入：ownerType: PRODUCT。 预期输出：已定义哪些结构化属性（材质、规格、特性）——用于元字段覆盖检查。
-
OPERATION: products — query（分页至 sample_size） 输入：first: 250，fields: descriptionHtml, category, media, metafields, variants{ barcode, sku, price }。 预期输出：每个商品的完整度——描述长度、图片 alt 文本覆盖率、条码/GTIN 是否存在、是否分配分类、元字段填充情况。
-
OPERATION: files — query 输入：first: 50，query: "media_type:IMAGE"（采样）——在文件层面佐证 alt 文本覆盖率。 预期输出：商品媒体资源的 alt 文本填充率。
-
COMPUTE（无 API）：将发现汇总为 0–100 的就绪度分数，覆盖五个维度——Discoverable（robots/llms.txt）、Trusted（Organization schema、sameAs、政策）、Readable（描述、alt 文本、JSON-LD 字段）、Structured（元字段、分类、条码）、Matchable（标题/标签/元字段对意图的丰富度）——并将每个未达标维度映射到其修复技能。
GraphQL 操作
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 } } }
会话跟踪
Claude 必须在每个阶段输出以下内容。这是强制要求。
开始时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: <skill name> ║ ║ Store: <store domain> ║ ║ Started: <YYYY-MM-DD HH:MM UTC> ║ ╚══════════════════════════════════════════════╝
每个步骤后输出：
[N/TOTAL] <QUERY|MUTATION> <OperationName> → Params: <brief summary of key inputs> → Result: <count or outcome>
如果 dry_run: true，则在每个变更步骤前加 [DRY RUN] 前缀，且不执行该步骤。
完成时输出：
对于 format: human（默认）：
══════════════════════════════════════════════ OUTCOME SUMMARY <Metric label>: <value> Errors: 0 Output: <filename or "none"> ══════════════════════════════════════════════
对于 format: json，输出：
{ "skill": "<skill-slug>", "store": "<domain>", "started_at": "<ISO8601>", "completed_at": "<ISO8601>", "dry_run": false, "steps": [ { "step": 1, "operation": "<OperationName>", "type": "query", "params_summary": "<string>", "result_summary": "<string>", "skipped": false } ], "outcome": { "metric_key": 0, "errors": 0, "output_file": null } }
输出格式
一份就绪度记分卡。human：总体 0–100 分 + 各维度条形图（Discoverable / Trusted / Readable / Structured / Matchable）+ 按优先级排列的差距表，每行为 差距 → 影响 → 应运行的智能体技能。json：{ score, grade, pillars{...}, gaps:[{ pillar, audit_signal, finding, fix_skill }], sampled_products }。每个 fix_skill 值都是同级技能名称（例如 shopify-admin-agentic-image-alt-text），以便操作者直接链入修复流程。
错误处理
- THROTTLED：API 速率限制。等待 2 秒，最多重试 3 次。
- ACCESS_DENIED reading themes：缺少 read_content 权限范围。跳过主题维度，将 Discoverable/Trusted 标记为“unknown”，继续执行。
- Empty catalog：新店/空店。报告“无可评估商品”；仍检查主题与政策。
最佳实践
- 首先运行此技能，并在每次修复技能后重新运行——它是告诉你还剩什么、什么已改善的记分板。
- 采样而非全量爬取：250 个商品足以估算填充率；仅当采样显示维度处于临界状态时才审计完整目录。
- 将未分配分类和缺失条码视为最高杠杆的差距——它们同时解锁 AI 检索（Matchable）和 Product JSON-LD（Readable）。
- 该技能为只读，从不需要 dry_run。它引导你运行的技能确实会修改数据——请先以 dry_run: true 运行那些技能。