shopify-admin-seo-metadata-audit

用途

扫描所有活跃商品、集合和页面，标记出缺失或过短的 SEO 标题（seo.title）和元描述（seo.description）的记录。输出按流量潜力排序的 SEO 缺口优先清单（商品 → 集合 → 页面）。只读，不执行任何写操作。

前置条件

已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_products,read_content
API 权限范围：read_products、read_content

参数

store（字符串，必填，无默认值）：店铺域名（例如 mystore.myshopify.com）
min_title_length（整数，可选，默认 10）：标记短于此长度的 SEO 标题（字符数）
min_description_length（整数，可选，默认 50）：标记短于此长度的元描述（字符数）
scope（字符串，可选，默认 all）：扫描范围，可选 products、collections、pages 或 all
format（字符串，可选，默认 human）：输出格式，可选 human 或 json

安全性

只读技能，不执行任何写操作，可随时安全运行。

工作流程

商品查询（当 scope 包含 products 时）：query 为 "status:active"，first: 250，获取 seo { title, description } 及分页游标。预期输出所有带 SEO 字段的活跃商品，分页直到 hasNextPage: false。
集合查询（当 scope 包含 collections 时）：first: 250，获取 seo { title, description } 及分页游标。预期输出所有带 SEO 字段的集合。
页面查询（当 scope 包含 pages 时）：first: 250，获取 SEO 字段及分页游标。预期输出所有带 SEO 字段的页面。
标记记录：缺失标题、缺失描述、标题短于 min_title_length、描述短于 min_description_length。

GraphQL 操作

商品查询（已针对 api_version 2025-01 校验）：

query ProductSEO($after: String) {
  products(first: 250, after: $after, query: "status:active") {
    edges {
      node {
        id
        title
        handle
        seo {
          title
          description
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

集合查询（已针对 api_version 2025-01 校验）：

query CollectionSEO($after: String) {
  collections(first: 250, after: $after) {
    edges {
      node {
        id
        title
        handle
        seo {
          title
          description
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

页面查询（已针对 api_version 2025-04 校验）：

query PageSEO($after: String) {
  pages(first: 250, after: $after) {
    edges {
      node {
        id
        title
        handle
        seoTitle: metafield(namespace: "global", key: "title_tag") { value }
        seoDescription: metafield(namespace: "global", key: "description_tag") { value }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪

Claude 必须在每个阶段输出以下内容，这是强制要求。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: SEO Metadata Audit                   ║
║  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>

完成时输出：

human 格式（默认）：

══════════════════════════════════════════════
SEO METADATA AUDIT
  Products scanned:     <n>  |  Missing SEO: <n>
  Collections scanned:  <n>  |  Missing SEO: <n>
  Pages scanned:        <n>  |  Missing SEO: <n>

  Top gaps (products):
    "<title>" — missing: description
    "<title>" — title too short (<n> chars)
  Output: seo_audit_<date>.csv
══════════════════════════════════════════════

json 格式：

{
  "skill": "seo-metadata-audit",
  "store": "<domain>",
  "summary": {
    "products": { "scanned": 0, "missing_title": 0, "missing_description": 0, "short_title": 0, "short_description": 0 },
    "collections": { "scanned": 0, "missing_title": 0, "missing_description": 0 },
    "pages": { "scanned": 0, "missing_title": 0, "missing_description": 0 }
  },
  "output_file": "seo_audit_<date>.csv"
}

输出格式

生成 CSV 文件 seo_audit_<YYYY-MM-DD>.csv，列为：type, id, title, handle, seo_title, seo_description, issue。

错误处理

THROTTLED：API 速率限制超限。等待 2 秒，最多重试 3 次。
Empty store：没有商品/集合/页面。以摘要退出：0 条记录。

最佳实践

优先修复热销商品缺失的元描述——描述会出现在搜索结果摘要中，直接影响点击率。
良好的 SEO 标题长度为 50–60 个字符；元描述应为 120–160 个字符。调整 min_title_length 和 min_description_length 以匹配这些目标。
每月作为商品目录卫生例行工作的一部分运行，尤其是在批量导入商品后（批量导入常遗漏 SEO 字段）。
修复缺口后，可搭配 product-data-completeness-score 获得全面的商品目录质量视图。