Back to Details

shopify-admin-product-data-completeness-score

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Purpose

用途

Calculates a data completeness score (0–100) for each active product based on the presence of key fields: description, images, SEO title, SEO description, variant weight, barcode, cost, and specified metafields. Produces a ranked list of products needing the most data work. Read-only — no mutations. Catalog health report in a single pass.
基于关键字段的存在情况为每个在售商品计算数据完整性得分（0-100分），考量字段包括：商品描述、图片、SEO标题、SEO描述、变体重量、条形码、成本以及指定metafields。输出需要补充最多数据的商品排名列表。只读模式——无修改操作，单次运行即可生成商品目录健康报告。

Prerequisites

前置要求

  • Authenticated Shopify CLI session: 
    shopify store auth --store <domain> --scopes read_products
  • API scopes: 
    read_products
  • 已完成身份认证的Shopify CLI会话：
    shopify store auth --store <domain> --scopes read_products
  • API权限范围：
    read_products

Parameters

参数

ParameterTypeRequiredDefaultDescription
storestringyes—Store domain (e.g., mystore.myshopify.com)
status_filterstringnoactiveProduct status to score: 
active
, 
draft
, or 
all
required_metafieldsarrayno[]List of 
namespace.key
metafields that are required (e.g., 
["custom.material"]
)
formatstringnohumanOutput format: 
human
or 
json
参数类型是否必填默认值描述
store字符串是—店铺域名（例如 mystore.myshopify.com）
status_filter字符串否active需要打分的商品状态：
active
（在售）、
draft
（草稿）或
all
（全部）
required_metafields数组否[]必填的
namespace.key
格式metafields列表（例如
["custom.material"]
）
format字符串否human输出格式：
human
（人类可读）或
json

Safety

安全性

ℹ️ Read-only skill — no mutations are executed. Safe to run at any time.
ℹ️ 只读技能——不会执行任何修改操作，随时运行都安全。

Scoring Rubric

评分规则

FieldPoints
Description present (non-empty)15
At least 1 image15
SEO title present10
SEO description present10
At least 1 variant with barcode10
At least 1 variant with cost10
At least 1 variant with weight10
All required metafields present20 (split evenly)
Total100
字段分值
描述存在（非空）15
至少1张图片15
SEO标题存在10
SEO描述存在10
至少1个变体带有条形码10
至少1个变体带有成本信息10
至少1个变体带有重量信息10
所有必填metafields都存在20（按字段数量均分）
总计100

Workflow Steps

工作流程步骤

  1. OPERATION: 
    products
    — query Inputs: 
    query: "status:<status_filter>"
    , 
    first: 250
    , select all completeness fields, pagination cursor Expected output: Products with all scored fields; paginate until 
    hasNextPage: false
  2. Score each product per rubric; rank ascending by score
  1. 操作： 
    products
    — 查询 输入： 
    query: "status:<status_filter>"
    ，
    first: 250
    ，选择所有完整性相关字段，分页游标 预期输出： 包含所有打分字段的商品；分页直到
    hasNextPage: false
  2. 按照规则为每个商品打分；按分数升序排序

GraphQL Operations

GraphQL操作

graphql
undefined
graphql
undefined

products:query — validated against api_version 2025-01

products:query — validated against api_version 2025-01

query ProductCompleteness($query: String!, $after: String) { products(first: 250, after: $after, query: $query) { edges { node { id title handle descriptionHtml images(first: 1) { edges { node { id } } } seo { title description } variants(first: 10) { edges { node { id barcode weight inventoryItem { unitCost { amount } } } } } metafields(first: 20) { edges { node { namespace key value } } } } } pageInfo { hasNextPage endCursor } } }
undefined
query ProductCompleteness($query: String!, $after: String) { products(first: 250, after: $after, query: $query) { edges { node { id title handle descriptionHtml images(first: 1) { edges { node { id } } } seo { title description } variants(first: 10) { edges { node { id barcode weight inventoryItem { unitCost { amount } } } } } metafields(first: 20) { edges { node { namespace key value } } } } } pageInfo { hasNextPage endCursor } } }
undefined

Session Tracking

会话跟踪

Claude MUST emit the following output at each stage. This is mandatory.
On start, emit:
╔══════════════════════════════════════════════╗
║  SKILL: Product Data Completeness Score      ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝
After each step, emit:
[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>
On completion, emit:
For 
format: human
(default):
══════════════════════════════════════════════
PRODUCT DATA COMPLETENESS REPORT
  Products scored:  <n>
  Avg score:        <pct>/100
  Score < 50:       <n> products (need urgent attention)
  Score 50–79:      <n> products
  Score ≥ 80:       <n> products

  Lowest scoring products:
    "<title>"  Score: <n>/100  Missing: description, SEO title
  Output: completeness_<date>.csv
══════════════════════════════════════════════
For 
format: json
, emit:
json
{
  "skill": "product-data-completeness-score",
  "store": "<domain>",
  "products_scored": 0,
  "avg_score": 0,
  "below_50_count": 0,
  "output_file": "completeness_<date>.csv"
}
Claude必须在每个阶段输出以下内容，该要求为强制项。
启动时输出：
╔══════════════════════════════════════════════╗
║  SKILL: Product Data Completeness Score      ║
║  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>
完成时输出：
format: human
（默认）场景下：
══════════════════════════════════════════════
PRODUCT DATA COMPLETENESS REPORT
  Products scored:  <n>
  Avg score:        <pct>/100
  Score < 50:       <n> products (need urgent attention)
  Score 50–79:      <n> products
  Score ≥ 80:       <n> products

  Lowest scoring products:
    "<title>"  Score: <n>/100  Missing: description, SEO title
  Output: completeness_<date>.csv
══════════════════════════════════════════════
format: json
场景下输出：
json
{
  "skill": "product-data-completeness-score",
  "store": "<domain>",
  "products_scored": 0,
  "avg_score": 0,
  "below_50_count": 0,
  "output_file": "completeness_<date>.csv"
}

Output Format

输出格式

CSV file 
completeness_<YYYY-MM-DD>.csv
with columns: 
product_id
, 
title
, 
score
, 
has_description
, 
image_count
, 
has_seo_title
, 
has_seo_description
, 
has_barcode
, 
has_cost
, 
has_weight
, 
missing_metafields
CSV文件
completeness_<YYYY-MM-DD>.csv
，包含以下列： 
product_id
, 
title
, 
score
, 
has_description
, 
image_count
, 
has_seo_title
, 
has_seo_description
, 
has_barcode
, 
has_cost
, 
has_weight
, 
missing_metafields

Error Handling

错误处理

ErrorCauseRecovery
THROTTLED
API rate limit exceededWait 2 seconds, retry up to 3 times
No products match filterEmpty catalog or wrong filterExit with 0 results
错误原因解决方案
THROTTLED
API速率限制超出等待2秒，最多重试3次
无符合过滤条件的商品商品目录为空或过滤条件错误退出，返回0条结果

Best Practices

最佳实践

  • Use this skill as a pre-launch gate — run before activating DRAFT products to ensure all required fields are filled.
  • Tune 
    required_metafields
    to your store's specific needs (e.g., 
    custom.material
    for apparel, 
    custom.ingredients
    for food).
  • A score below 50 typically means a product is missing foundational content (description or images) and should be deprioritized from launch until fixed.
  • Run monthly to track catalog quality trends over time; improvements after a content sprint should be visible in the average score.
  • 将此技能作为上线前检查关卡——在激活DRAFT草稿商品前运行，确保所有必填字段都已填写。
  • 可根据店铺的具体需求调整
    required_metafields
    （例如服装类店铺可配置
    custom.material
    ，食品类店铺可配置
    custom.ingredients
    ）。
  • 得分低于50通常意味着商品缺失基础内容（描述或图片），在修复前应推迟上线。
  • 每月运行一次来跟踪长期的商品目录质量趋势；内容优化冲刺后的改进效果可在平均得分中直观体现。