shopify-admin-agentic-description-enrichment

用途

本技能解决的是商品描述质量问题。当 AI 智能体判断是否推荐某件商品时，它会引用商品描述来证明匹配的合理性。若描述只有一行甚至为空，智能体拿不到任何可用信息，就无法确认商品是否契合买家意图，于是转向其他商品。

该技能会找出描述单薄的商品（纯文本描述低于字符阈值，或缺少关键属性），并将其改写为结构化文案：先是一句以利益点为引导的开场，随后是从商品自身元字段/选项/类型中提取的具体事实，例如材质、版型与尺码、尺寸、使用场景、养护方式。它用于修复商品描述质量，并强化智能体商品信息结构。

前提条件

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

参数

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

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human（默认）或 json
dry_run	bool	否	false	预览变更而不实际执行

技能专属参数：

参数	类型	必填	默认值	说明
collection_id	string	否	—	限定到某个集合 GID
tag	string	否	—	限定到某个商品标签
min_chars	int	否	120	纯文本描述短于此值的商品会被改写
overwrite	bool	否	false	为 false 时只丰富低于 min_chars 的商品；为 true 时重构所有目标商品
brand_voice	string	否	—	可选的语气指引（例如“平实、技术性、不夸张”）

安全性

第 3 步（productUpdate）会替换线上商品的 descriptionHtml。这可能是商家亲手撰写的内容。务必先运行 dry_run: true，导出改写前后的对比，并由人工批准后再提交。默认只触碰低于 min_chars 的商品。

工作流程步骤

OPERATION：products — 查询

输入：first: 100，可选筛选；字段 descriptionHtml、title、productType、options、tags、metafields(first: 30)；分页。
预期输出：剥离标签后的文本描述低于 min_chars 的商品，以及可用于丰富描述的结构化事实。

COMPUTE（不调用 API）：对每个描述单薄的商品，起草 descriptionHtml：一句利益点开场钩子 + 一段简短的事实列表，且仅基于真实商品数据构建（不得虚构规格），遵循 brand_voice。输出改写前后预览。

OPERATION：productUpdate — 变更

输入：每个已批准商品的 { id, descriptionHtml }。
预期输出：更新后的商品；收集 userErrors。

GraphQL 操作

# products:query — validated against api_version 2025-01
query EnrichProducts($first: Int!, $after: String, $query: String) {
  products(first: $first, after: $after, query: $query) {
    edges {
      node {
        id
        title
        descriptionHtml
        productType
        tags
        options { name values }
        metafields(first: 30) { edges { node { namespace key value type } } }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

# productUpdate:mutation — validated against api_version 2025-01
mutation EnrichProductDescription($input: ProductInput!) {
  productUpdate(input: $input) {
    product { id descriptionHtml }
    userErrors { field 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，则每个变更步骤前加 [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：已丰富数量 + 一份改写前后 CSV（product、old_len、new_len、new_description）。
json：{ products_enriched, products_skipped, errors, output_file }。

错误处理

错误	原因	恢复方式
THROTTLED	API 速率限制	等待 2 秒，最多重试 3 次
userErrors 非空	HTML 无效 / 字段长度问题	记录消息，跳过该商品，继续
无可用于丰富的事实	商品数据稀疏	跳过；建议先运行 shopify-admin-agentic-metafields-setup

最佳实践

从店铺已拥有的数据（元字段、选项、类型）中丰富描述——绝不虚构材质、认证或尺寸。
把买家常搜索的属性放在前面；智能体在匹配意图时会重点权重第一句话。
本技能可与 shopify-admin-agentic-metafields-setup 配合：结构化的元字段会让描述既更丰富，又更便于机器筛选。
对于主推/畅销商品，务必先让人工审批干跑差异，再提交。

适用场景

适用于 Shopify 商家对商品描述进行批量质量提升，尤其是希望让 AI 智能体能够引用商品描述进行推荐匹配的场景，例如按集合或标签批量处理描述过短的商品。

限制

需要已认证的 Shopify CLI 会话，并具备 read_products、write_products 权限。
变更会替换线上商品的 descriptionHtml，需人工审批。
当商品数据过于稀疏、无可用事实时无法丰富描述。
其他未在资料中说明的定价、平台兼容性或效果数据暂未提供。