shopify-admin-agentic-llms-txt

用途

llms.txt 是一种新兴约定，用纯文本告诉 AI 助手某个网站是什么、重要页面位于何处——相当于为模型提供一张精心整理的前门地图。本技能从商店自身数据（品牌一句话简介、顶级集合、带 URL 的旗舰产品、配送/退货政策链接、联系方式）组装出 llms.txt，并通过主题模板发布，使其在稳定路径下提供访问。它用于修复 llms-txt / well-known-llms-txt 以及相关的 agents-md 发现信号。

前置条件

已完成认证的 Shopify CLI 会话（shopify auth login --store <domain>）
所需 API 权限范围：read_products、read_themes、write_themes

参数

所有技能均接受以下通用参数：

参数	类型	必填	默认	说明
store	string	是	—	商店域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human（默认）或 json
dry_run	bool	否	true	预览生成的 llms.txt 而不写入（默认开启——会编辑线上主题）

技能专属参数：

参数	类型	必填	默认	说明
theme_id	string	否	—	主题 GID（默认为已发布的 MAIN 主题）
flagship_count	int	否	12	列出多少个顶级产品
flagship_collection_id	string	否	—	从中提取旗舰列表的集合（否则使用畅销/最近更新产品）
brand_summary	string	否	—	覆盖品牌一句话简介（否则根据商店 + 首页推断）

安全性

⚠️ 第 4 步（themeFilesUpsert）会向线上主题写入一个新模板。内容是增量式的（一个新文件/路由），风险较低，但会立即发布。默认 dry_run: true，因此可以先审核生成的 llms.txt。建议在写入前复制主题。

工作流程步骤

OPERATION: shop — query 输入：无预期输出：商店名称、域名、联系邮箱、政策 URL——即 llms.txt 的头部、联系与政策部分。

OPERATION: products — query 输入：first: flagship_count，可选的 query: "collection_id:'<id>'"（当设置了 flagship_collection_id 时——整理的集合即为旗舰列表），否则使用 sortKey: UPDATED_AT, reverse: true；字段为 title、onlineStoreUrl、description。预期输出：带 URL 的旗舰产品列表，用于「Key products」部分。（顶层 products 没有畅销排序——请使用整理好的集合来获取真正的畅销品，否则以最近更新作为代理。）

COMPUTE（无 API）：渲染 llms.txt markdown：# <品牌> + 一句话简介，## Key products（标题 — URL — 一行），## Policies（配送/退货/隐私 URL），## Contact。输出完整文本。

OPERATION: themeFilesUpsert — mutation 输入：themeId、写入 templates/page.llms.liquid（一个以 text/plain 输出该文本的页面模板），如使用则再加一份 assets/llms.txt 副本；dry_run 时跳过。预期输出：已 upsert 的主题文件；收集 userErrors。（注意：需给出一行提示，指导创建使用 llms 模板的 Page，或添加从 /llms.txt 的重定向。）

GraphQL 操作

# shop:query — 已针对 api_version 2025-01 验证
query LlmsTxtShop {
  shop {
    name
    primaryDomain { url }
    contactEmail
    shopPolicies { type url }
  }
}

# products:query — 已针对 api_version 2025-01 验证
# 顶层 `products` 没有 BEST_SELLING 排序键。传入 `collection_id:'…'`
# 查询过滤器以使用整理好的旗舰集合，否则回退到最近更新的产品。
query LlmsTxtFlagship($first: Int!, $query: String) {
  products(first: $first, query: $query, sortKey: UPDATED_AT, reverse: true) {
    edges {
      node { id title onlineStoreUrl description }
    }
  }
}

# themeFilesUpsert:mutation — 已针对 api_version 2025-01 验证
mutation LlmsTxtUpsert($themeId: ID!, $files: [OnlineStoreThemeFilesUpsertFileInput!]!) {
  themeFilesUpsert(themeId: $themeId, files: $files) {
    upsertedThemeFiles { filename }
    userErrors { filename code message }
  }
}

会话追踪

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，则在每个 mutation 步骤前加 [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：完整的生成 llms.txt + 发布后步骤（在 llms 模板上创建 Page，或添加 /llms.txt → page 重定向）。json：{ theme_id, llms_txt, wrote: true|false, follow_up, errors }。

错误处理

错误	原因	恢复方式
THROTTLED	API 速率限制	等待 2 秒，最多重试 3 次
ACCESS_DENIED	缺少 write_themes	中止；输出生成的 llms.txt 以便手动添加
No flagship products	目录为空/新建	仅发布头部 + 政策 + 联系方式

最佳实践

保持简短且高信号——llms.txt 是一张地图，不是内容转储；链接到规范页面而非粘贴内容。
当旗舰产品阵容或政策变化时重新生成（agentic-readiness-monitor 例程可安排执行此操作）。
与 shopify-admin-agentic-crawler-access 搭配使用——只有在允许爬虫进入时，llms.txt 才有帮助。
发布后，添加店面重定向 /llms.txt → 该页面，使其位于约定的路径上。