shopify-admin-agentic-product-jsonld-backfill
Backfill the structured product/variant fields that power Product JSON-LD — barcode (GTIN), SKU, vendor, product type, weight — so AI agents can quote exact, in-stock items instead of guessing.
40RTY-ai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-agentic-product-jsonld-backfill技能说明
name: shopify-admin-agentic-product-jsonld-backfill role: agentic description: "Backfill the structured product/variant fields that power Product JSON-LD — barcode (GTIN), SKU, vendor, product type, weight — so AI agents can quote exact, in-stock items instead of guessing." toolkit: shopify-admin, shopify-admin-execution api_version: "2025-01" graphql_operations:
- products:query
- productUpdate:mutation
- productVariantsBulkUpdate:mutation status: stable compatibility: Claude Code, Cursor, Codex, Gemini CLI audit_signals:
- product-schema-jsonld
- gtin-sku-pdp
- variant-metadata
Purpose
AI shopping agents read a product's structured data (the fields Shopify themes emit as schema.org/Product JSON-LD) to confirm price, availability, and identity. Missing barcodes (GTIN), SKUs, vendor, or product type leave the listing ambiguous — so the agent skips it or recommends a competitor whose data is complete. This skill finds products/variants with those gaps and backfills them: vendor and product type at the product level, barcode/SKU at the variant level. Fixes the agentiq.report findings product-schema-jsonld, gtin-sku-pdp, and variant-metadata.
Prerequisites
- Authenticated Shopify CLI session (
shopify auth login --store <domain>) - Required API scopes:
read_products,write_products
Parameters
All skills accept these universal parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| store | string | yes | — | Store domain (e.g., mystore.myshopify.com) |
| format | string | no | human | Output format: human (default) or json |
| dry_run | bool | no | false | Preview mutations without executing |
Skill-specific parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| collection_id | string | no | — | Limit to a collection GID (else whole catalog) |
| tag | string | no | — | Limit to a product tag |
| set_vendor | string | no | — | Vendor to apply where missing (else only reports) |
| set_product_type | string | no | — | Product type to apply where missing |
| barcodes_csv | string | no | — | Path to a CSV of sku,barcode to map GTINs onto matching variants |
| fields | string | no | all | Comma list of fields to backfill: vendor,product_type,barcode,sku |
Safety
⚠️ Step 3 (
productUpdate) and Step 4 (productVariantsBulkUpdate) write live product/variant data. Barcodes and SKUs are matched from yourbarcodes_csv; a wrong mapping mislabels a product's identity to every agent. Always rundry_run: truefirst and verify the change set CSV. This skill never overwrites a field that already has a value — it only fills blanks.
Workflow Steps
-
OPERATION:
products— query Inputs:first: 250, optionalquery: "tag:'<tag>'"or collection filter; fieldsvendor,productType,variants{ id sku barcode }; paginate untilhasNextPage: false. Expected output: Products/variants with missing target fields. -
COMPUTE (no API): build the change set — only blank fields, joined to
barcodes_csvby SKU for barcodes. Emit the preview CSV. -
OPERATION:
productUpdate— mutation Inputs: per product{ id, vendor?, productType? }(only where blank and a value is supplied). Expected output: Updated product; collectuserErrors. -
OPERATION:
productVariantsBulkUpdate— mutation Inputs: per productproductId+variants: [{ id, barcode?, inventoryItem: { sku? } }]for blank variant fields. Expected output: Updated variants; collectuserErrorsacross batches.
GraphQL Operations
# products:query — validated against api_version 2025-01
query BackfillProducts($first: Int!, $after: String, $query: String) {
products(first: $first, after: $after, query: $query) {
edges {
node {
id
title
vendor
productType
variants(first: 100) {
edges { node { id sku barcode } }
}
}
}
pageInfo { hasNextPage endCursor }
}
}
# productUpdate:mutation — validated against api_version 2025-01
mutation BackfillProductFields($input: ProductInput!) {
productUpdate(input: $input) {
product { id vendor productType }
userErrors { field message }
}
}
# productVariantsBulkUpdate:mutation — validated against api_version 2025-01
mutation BackfillVariantFields($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
productVariantsBulkUpdate(productId: $productId, variants: $variants) {
productVariants { id sku barcode }
userErrors { field message }
}
}
Session Tracking
Claude MUST emit the following output at each stage. This is mandatory.
On start, emit:
╔══════════════════════════════════════════════╗
║ SKILL: <skill name> ║
║ 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>
If dry_run: true, prefix every mutation step with [DRY RUN] and do not execute it.
On completion, emit:
For format: human (default):
══════════════════════════════════════════════
OUTCOME SUMMARY
<Metric label>: <value>
Errors: 0
Output: <filename or "none">
══════════════════════════════════════════════
For format: json, emit:
{
"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>",
"
阅读完整来源 ↗