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

参数

Parameter	Type	Required	Default	Description
store	string	yes	—	Store domain (e.g., mystore.myshopify.com)
status_filter	string	no	active	Product status to score: `active` , `draft` , or `all`
required_metafields	array	no	[]	List of `namespace.key` metafields that are required (e.g., `["custom.material"]` )
format	string	no	human	Output 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

评分规则

Field	Points
Description present (non-empty)	15
At least 1 image	15
SEO title present	10
SEO description present	10
At least 1 variant with barcode	10
At least 1 variant with cost	10
At least 1 variant with weight	10
All required metafields present	20 (split evenly)
Total	100

字段	分值
描述存在（非空）	15
至少1张图片	15
SEO标题存在	10
SEO描述存在	10
至少1个变体带有条形码	10
至少1个变体带有成本信息	10
至少1个变体带有重量信息	10
所有必填metafields都存在	20（按字段数量均分）
总计	100

Workflow Steps

工作流程步骤

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
```
Score each product per rubric; rank ascending by score

操作：
```
products
```
— 查询 输入：
```
query: "status:<status_filter>"
```
，
```
first: 250
```
，选择所有完整性相关字段，分页游标 预期输出： 包含所有打分字段的商品；分页直到
```
hasNextPage: false
```
按照规则为每个商品打分；按分数升序排序

GraphQL Operations

GraphQL操作

graphql

undefined

graphql

undefined

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

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

错误处理

Error	Cause	Recovery
`THROTTLED`	API rate limit exceeded	Wait 2 seconds, retry up to 3 times
No products match filter	Empty catalog or wrong filter	Exit 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通常意味着商品缺失基础内容（描述或图片），在修复前应推迟上线。
每月运行一次来跟踪长期的商品目录质量趋势；内容优化冲刺后的改进效果可在平均得分中直观体现。