From shopify-admin-skills
Normalizes inconsistent Shopify product variant option values (e.g., Sm/Small/S) to canonical mappings via bulk GraphQL queries and mutations. Fixes size/color filters and search grouping.
npx claudepluginhub 40rty-ai/shopify-admin-skills --plugin shopify-admin-skillsThis skill uses the workspace's default tool permissions.
Scans product variants for inconsistent option values (e.g., "Sm", "Small", "small", "S" all meaning the same size) and bulk-updates them to a canonical set you define. Inconsistent option naming breaks size filters, causes customer confusion, and prevents search apps from grouping variants correctly.
Manages Shopify product catalogs: products, variants, options, collections, metafields, metaobjects, inventory, bulk operations, taxonomy, media via GraphQL API.
Manages Shopify products, variants, collections, and inventory with GraphQL Admin API. Handles CRUD for catalog integrations, including product options and inventory quantities.
Creates and manages Shopify products via GraphQL Admin API or CSV imports. Bulk import/update variants, inventory, images, assign to collections.
Share bugs, ideas, or general feedback.
Scans product variants for inconsistent option values (e.g., "Sm", "Small", "small", "S" all meaning the same size) and bulk-updates them to a canonical set you define. Inconsistent option naming breaks size filters, causes customer confusion, and prevents search apps from grouping variants correctly.
shopify store auth --store <domain> --scopes read_products,write_productsread_products, write_products| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| store | string | yes | — | Store domain (e.g., mystore.myshopify.com) |
| option_name | string | yes | — | Option to normalize (e.g., Size, Color) |
| mapping | object | yes | — | Map of non-standard → canonical values (e.g., {"Sm": "S", "small": "S", "Sml": "S"}) |
| filter | string | no | — | Optional product filter (e.g., tag:apparel) |
| dry_run | bool | no | true | Preview changes without executing mutations |
| format | string | no | human | Output format: human or json |
⚠️
productVariantsBulkUpdatemodifies variant option values. Option value changes affect how the variant appears to customers in the storefront and may break existing cart links or saved wishlists. Run withdry_run: trueto review all affected variants before committing.
OPERATION: products — query
Inputs: query: <filter> (or all products if no filter), first: 250, select options, variants { selectedOptions }, pagination cursor
Expected output: Products with variant option values; paginate until hasNextPage: false
Match variant option values against mapping keys — collect variants needing update
OPERATION: productVariantsBulkUpdate — mutation
Inputs: productId, array of variants { id, options: [<normalized_value>] } for affected variants
Expected output: productVariants { id, selectedOptions }, userErrors
# products:query — validated against api_version 2025-01
query ProductVariantOptions($query: String!, $after: String) {
products(first: 250, after: $after, query: $query) {
edges {
node {
id
title
options {
id
name
values
}
variants(first: 100) {
edges {
node {
id
title
sku
selectedOptions {
name
value
}
}
}
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
# productVariantsBulkUpdate:mutation — validated against api_version 2025-01
mutation ProductVariantsBulkUpdate($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
productVariantsBulkUpdate(productId: $productId, variants: $variants) {
productVariants {
id
title
selectedOptions {
name
value
}
}
userErrors {
field
message
}
}
}
Claude MUST emit the following output at each stage. This is mandatory.
On start, emit:
╔══════════════════════════════════════════════╗
║ SKILL: Variant Option Normalizer ║
║ 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
Products scanned: <n>
Variants needing fix: <n>
Variants updated: <n>
Errors: <n>
Output: option_normalizer_<date>.csv
══════════════════════════════════════════════
For format: json, emit:
{
"skill": "variant-option-normalizer",
"store": "<domain>",
"started_at": "<ISO8601>",
"completed_at": "<ISO8601>",
"dry_run": true,
"option_name": "Size",
"outcome": {
"products_scanned": 0,
"variants_needing_fix": 0,
"variants_updated": 0,
"errors": 0,
"output_file": "option_normalizer_<date>.csv"
}
}
CSV file option_normalizer_<YYYY-MM-DD>.csv with columns:
product_id, product_title, variant_id, sku, option_name, old_value, new_value
| Error | Cause | Recovery |
|---|---|---|
THROTTLED | API rate limit exceeded | Wait 2 seconds, retry up to 3 times |
userErrors on bulk update | Option value conflict within product | Log error, skip product, continue |
| No matching variants | Mapping keys not found in catalog | Exit with 0 matches, review mapping |
mapping by first running with dry_run: true and reviewing the detected option values — you may discover more variants than expected.option_name at a time (Size, then Color separately) to keep the mapping manageable and reduce error risk.