
saleor-configurator
AI-powered Saleor e-commerce configuration through natural language
- version
- 2.1.0
- GitHub stars
- 30
Install
/plugin install saleor-configurator@saleor-configuratorRun it inside Claude Code after adding the marketplace with /plugin marketplace add saleor/configurator.
Contents
Discovered from sourceSkills 7
Agent Output Parsing
Overview
The Configurator CLI outputs a JSON envelope in non-TTY mode. This skill documents the envelope structure, exit code semantics, and drill-down patterns for debugging failures.
When to Use
- Parsing CLI output in automation scripts
- Understanding exit codes and what to do next
- Drilling into specific entity failures
- Building workflows that chain CLI commands
JSON Envelope Structure
Every command outputs this envelope in non-TTY mode (or with --json):
{
"command": "deploy",
"version": "1.3.0",
"exitCode": 0,
"result": { },
"logs": [
{ "level": "info", "ts": "2026-03-05T09:30:00Z", "message": "Starting deployment" }
],
"errors": [
{ "entity": "Categories/electronics", "stage": "update", "message": "Not found" }
]
}
| Field | Type | Description |
|---|---|---|
command | string | Command name (validate, diff, deploy, introspect) |
version | string | CLI version |
exitCode | number | Exit code (0-7) |
result | object | Command-specific result data |
logs | array | Log entries collected during execution |
errors | array | Structured error entries |
Per-Command Result Shapes
validate
{ "valid": true, "errors": [] }
{
"valid": false,
"errors": [
{ "path": "channels.0.currencyCode", "message": "Required" },
{ "path": "products.0.slug", "message": "String must contain at least 1 character(s)" }
]
}
diff
{
"summary": { "totalChanges": 3, "creates": 1, "updates": 1, "deletes": 1 },
"operations": [
{
"operation": "CREATE",
"entityType": "Categories",
"entityName": "electronics",
"changes": []
},
{
"operation": "UPDATE",
"entityType": "Product Types",
"entityName": "T-Shirt",
"changes": [{ "field": "name", "currentValue": "Old", "desiredValue": "New" }]
}
],
"hasDestructiveOperations": true
}
deploy --plan
{
"status": "plan",
"summary": { "creates": 1, "updates": 0, "deletes": 0, "noChange": 5 },
"operations": [],
"willDeleteEntities": false,
"configFile": "config.yml",
"saleorUrl": "https://store.saleor.cloud/graphql/"
}
deploy (executed)
{
"status": "completed",
"summary": { "succeeded": 6, "failed": 0, "skipped": 0 },
"operations": [],
"duration": "12.3s",
"reportPath": ".configurator/reports/deploy/store-abc_2026-03-05_09h30m00s.json"
}
introspect
{
"status": "success",
"configPath": "config.yml"
}
Exit Code Decision Tree
Is exitCode 0?
YES --> Success. Done.
NO --> Continue...
Is exitCode 2?
YES --> Authentication issue.
- Check SALEOR_URL ends with /graphql/
- Check SALEOR_TOKEN is valid
- Regenerate token in Dashboard
Is exitCode 3?
YES --> Network issue.
- Verify URL is reachable: curl -I $SALEOR_URL
- Check DNS, firewall, VPN
Is exitCode 4?
YES --> Validation error.
- Run: validate --json
- Parse .result.errors for specific issues
- Fix config.yml
Is exitCode 5?
YES --> Partial failure.
- Parse .errors array for failed entities
- Drill down: diff --entity "Type/name" --json
- Fix specific entities and redeploy
Is exitCode 6?
YES --> Deletions blocked.
- Review deletions in diff output
- Remove entities from config or remove --fail-on-delete
Is exitCode 7?
YES --> Breaking changes blocked.
- Review breaking changes
- Remove --fail-on-breaking or accept changes
Otherwise (exitCode 1):
--> Unexpected error.
- Check .errors and .logs in envelope
- Check report files in .configurator/reports/
Drill-Down Pattern
When deployment fails partially (exit code 5):
# Step 1: Get overview of failures
OUTPUT=$(pnpm dlx @saleor/configurator deploy --json 2>/dev/null)
echo "$OUTPUT" | jq '.errors[]'
# Step 2: Filter by entity type
pnpm dlx @saleor/configurator diff --entity-type "Categories" --json 2>/dev/null | jq '.result'
# Step 3: Drill into specific entity
pnpm dlx @saleor/configurator diff --entity "Categories/electronics" --json 2>/dev/null | jq '.result.operations[].changes'
# Step 4: Fix config.yml based on field-level differences
# Step 5: Validate fix
pnpm dlx @saleor/configurator validate --json 2>/dev/null
# Step 6: Redeploy
pnpm dlx @saleor/configurator deploy --json 2>/dev/null
Parsing Examples
Bash
OUTPUT=$(pnpm dlx @saleor/configurator deploy --json 2>/dev/null)
EXIT_CODE=$(echo "$OUTPUT" | jq -r '.exitCode')
case $EXIT_CODE in
0) echo "Success" ;;
4) echo "$OUTPUT" | jq -r '.result.errors[] | " \(.path): \(.message)"' ;;
5) echo "$OUTPUT" | jq -r '.errors[] | " \(.entity): \(.message)"' ;;
*) echo "$OUTPUT" | jq -r '.errors[].message // "Unknown error"' ;;
esac
JavaScript
const { execSync } = require("child_process");
function runConfigurator(command) {
try {
const output = execSync(`pnpm dlx @saleor/configurator ${command} --json`, {
encoding: "utf-8",
stdio: ["pipe", "pipe", "pipe"],
});
return JSON.parse(output);
} catch (err) {
// CLI exits non-zero but still outputs valid JSON to stdout
if (err.stdout) return JSON.parse(err.stdout);
throw err;
}
}
const result = runConfigurator("validate");
if (!result.result.valid) {
for (const error of result.result.errors) {
console.error(`${error.path}: ${error.message}`);
}
}
Reports
Deployment reports are auto-saved after every deploy command.
Default location: deployment-report-YYYY-MM-DD_HH-MM-SS.json in the current working directory.
Custom location: Use --report-path=custom/path.json to control where the report is saved.
Report Structure
{
"command": "deploy",
"version": "1.3.0",
"exitCode": 0,
"result": {
"status": "completed",
"summary": {
"succeeded": 6,
"failed": 0,
"skipped": 0
},
"operations": [
{
"entityType": "Categories",
"entityName": "electronics",
"operation": "CREATE",
"status": "success",
"duration": "0.8s"
}
],
"duration": "12.3s",
"reportPath": "deployment-report-2026-03-05_09-30-00.json",
"resilience": {
"retries": 2,
"rateLimitHits": 0
}
},
"logs": [],
"errors": []
}
Reading Reports
# Read latest report
cat deployment-report-*.json | jq '.result.summary'
# Check for failures
cat deployment-report-*.json | jq '.result.operations[] | select(.status == "failed")'
# Get resilience stats
cat deployment-report-*.json | jq '.result.resilience'
Related Skills
configurator-cli- Full command reference and flagsconfigurator-schema- Config.yml structure for fixing validation errors
Configurator CLI
Overview
The Saleor Configurator CLI syncs your YAML configuration with a live Saleor instance. You define your store in config.yml, then use CLI commands to preview and apply changes.
In non-TTY mode (pipes, CI, subprocesses), all commands automatically output a JSON envelope. Use --json to force JSON in a terminal, or --text to force human-readable in non-TTY.
When to Use
- "How do I deploy my config?"
- "How do I pull the current store configuration?"
- "How do I preview changes before deploying?"
- "What flags does deploy support?"
- "How do I set up CI/CD for my store?"
- "What do the exit codes mean?"
- "How do I validate my config without network?"
- When NOT modeling products or writing YAML -- use
product-modelingorconfigurator-schemainstead
Core Commands
validate
Validates config.yml against the schema locally (no network required).
pnpm dlx @saleor/configurator validate
pnpm dlx @saleor/configurator validate --config custom-config.yml
pnpm dlx @saleor/configurator validate --json
introspect
Pulls the current configuration from a Saleor instance into config.yml.
pnpm dlx @saleor/configurator introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN
Use cases: initial setup, backup before changes, restore from known-good state.
deploy
Pushes local config.yml changes to a Saleor instance.
pnpm dlx @saleor/configurator deploy --url=$SALEOR_URL --token=$SALEOR_TOKEN
Important flags:
--plan-- preview changes without applying (replaces--dry-run)--plan --json-- machine-readable deployment plan--fail-on-delete-- abort if any deletions would occur (exit code 6)--fail-on-breaking-- abort if breaking changes detected (exit code 7)--include <types>-- only deploy specific entity types--exclude <types>-- skip specific entity types--report-path <file>-- custom path for deployment report (default: auto-generated in CWD)--skip-media-- skip media file uploads
diff
Compares local config.yml with the remote Saleor instance.
pnpm dlx @saleor/configurator diff --url=$SALEOR_URL --token=$SALEOR_TOKEN
Output markers: + CREATE (new), ~ UPDATE (modified), - DELETE (removed).
Entity scoping:
--entity-type "Categories"-- filter to one entity type--entity "Categories/electronics"-- filter to one specific entity
Quick Reference
| Flag | Commands | Description |
|---|---|---|
--url | deploy, diff, introspect | Saleor GraphQL endpoint URL |
--token | deploy, diff, introspect | Saleor API authentication token |
--json | All | Force JSON envelope output |
--text | All | Force human-readable output |
--drift-check | introspect | Exit code 1 if remote differs from local |
--include | deploy, diff, introspect | Comma-separated entity types to include |
--exclude | deploy, diff, introspect | Comma-separated entity types to exclude |
--fail-on-delete | deploy | Exit code 6 if deletions detected |
--fail-on-breaking | deploy | Exit code 7 if breaking changes detected |
--plan | deploy | Show plan without executing changes |
--report-path | deploy | Custom path for deployment report |
--skip-media | deploy, diff | Skip media file comparison/upload |
--entity-type | diff | Filter to one entity type |
--entity | diff | Filter to one specific entity (Type/name) |
Environment Variables
Set credentials via .env.local (auto-loaded) or environment variables:
export SALEOR_URL="https://your-store.saleor.cloud/graphql/"
export SALEOR_TOKEN="your-api-token"
pnpm dlx @saleor/configurator deploy # No flags needed
JSON Envelope
In non-TTY mode, all commands output:
{
"command": "deploy",
"version": "1.3.0",
"exitCode": 0,
"result": { },
"logs": [{ "level": "info", "ts": "...", "message": "..." }],
"errors": []
}
Parse with jq:
OUTPUT=$(pnpm dlx @saleor/configurator validate --json 2>/dev/null)
echo "$OUTPUT" | jq '.result.valid'
echo "$OUTPUT" | jq '.result.errors[]'
Exit Codes
| Code | Meaning | Action |
|---|---|---|
| 0 | Success | Operation completed |
| 1 | Unexpected error | Check error message and logs |
| 2 | Authentication error | Verify URL and token |
| 3 | Network error | Check connectivity |
| 4 | Validation error | Fix config.yml syntax/schema |
| 5 | Partial failure | Some operations failed, check errors array |
| 6 | Deletion blocked | --fail-on-delete triggered |
| 7 | Breaking blocked | --fail-on-breaking triggered |
Common Workflows
Optimal Agent Workflow
# 1. Validate locally first
pnpm dlx @saleor/configurator validate --json
# 2. Compare with remote
pnpm dlx @saleor/configurator diff --json
# 3. Preview deployment
pnpm dlx @saleor/configurator deploy --plan --json
# 4. Execute deployment
pnpm dlx @saleor/configurator deploy --json
Safe CI/CD Deployment
pnpm dlx @saleor/configurator deploy --fail-on-delete
Entity-Scoped Debugging
# Drill into a specific entity type
pnpm dlx @saleor/configurator diff --entity-type "Categories" --json
# Drill into a specific entity
pnpm dlx @saleor/configurator diff --entity "Categories/electronics" --json
Selective Deployment
# Deploy only channels and products
pnpm dlx @saleor/configurator deploy --include channels,products
# Deploy everything except products
pnpm dlx @saleor/configurator deploy --exclude products
Common Mistakes
| Mistake | Fix |
|---|---|
| Deploying without previewing first | Always run diff or deploy --plan before deploy |
| Wrong URL format | URL must end with /graphql/ (e.g., https://store.saleor.cloud/graphql/) |
| Expired or invalid token | Regenerate your API token in Saleor Dashboard |
Not using --drift-check for CI drift detection | Use introspect --drift-check to fail CI if remote config has drifted |
Forgetting --fail-on-delete in CI | Prevents accidental deletions |
Using SALEOR_API_URL | Correct env var is SALEOR_URL |
diff vs deploy --plan
diff | deploy --plan | |
|---|---|---|
| Purpose | Show field-level differences between local and remote | Show what operations deploy would execute |
| Output | Per-field changes (old → new values) | Operation summary (creates, updates, deletes) |
| Scoping | --entity-type, --entity for drill-down | No entity-level scoping |
| Use when | Debugging what changed, reviewing individual fields | Pre-deploy safety check, CI gates |
Recommended workflow: Use diff to understand changes, then deploy --plan to confirm the execution plan.
Rollback & Recovery
Configurator doesn't have a built-in rollback command, but you can recover using these patterns:
Before deploying (recommended):
# Save current remote state as backup
pnpm dlx @saleor/configurator introspect --config=backup-config.yml
After a bad deploy:
# Restore from backup
pnpm dlx @saleor/configurator deploy --config=backup-config.yml
Using git:
# Revert config.yml to last known good state
git checkout HEAD~1 -- config.yml
pnpm dlx @saleor/configurator deploy
Partial recovery (only fix specific entities):
# Deploy only the entity types that need fixing
pnpm dlx @saleor/configurator deploy --include=categories,products
See Also
- For complete command reference, see references/commands.md
- For all flags and options, see references/flags.md
- For error code details, see references/error-codes.md
- For CI/CD setup, see references/ci-cd.md
Related Skills
configurator-schema- Config.yml structure and validation rulessaleor-domain- Entity relationships and Saleor conceptsagent-output-parsing- JSON envelope parsing and drill-down patterns
Configurator Recipes
Overview
Recipes are ready-to-use config.yml templates for common store types. Pick one that matches your business, customize it, and deploy. They save you from building your store configuration from scratch.
When to Use
- "How do I set up a fashion store?"
- "Is there a template for electronics?"
- "Can I see an example config.yml?"
- "What's a good starting point for my store?"
- "How do I set up a subscription service?"
- When NOT looking for CLI commands -- use
configurator-cliinstead - When NOT designing custom product types -- use
product-modelinginstead
Available Recipes
| Recipe | Best For | Key Features |
|---|---|---|
| Fashion Store | Apparel, shoes, accessories | Size/color variants, seasonal collections, multi-currency |
| Electronics Store | Tech products, gadgets | Specs attributes, storage/RAM variants, warranty info |
| Subscription Service | Recurring products, SaaS | Plan tiers, billing cycles, add-on services |
For a blank starting point (correct structure, no business content), use /configurator init.
Quick Start
# Option 1: Interactive wizard
/recipe
# Option 2: Copy a template directly
cp plugin/skills/configurator-recipes/templates/fashion-store.yml config.yml
# Option 3: Customize and deploy
npx configurator deploy --url=$URL --token=$TOKEN
Recipe Details: Fashion Store
A complete configuration for apparel and fashion retail with two channels (US/EU), five product types, a full category tree, and curated collections.
Channels: US Store (USD), EU Store (EUR)
Product Types: T-Shirt, Pants, Dress, Shoes, Accessory -- each with appropriate size/color/material variants.
Categories:
Clothing → Men's (T-Shirts, Pants, Shoes) / Women's (Dresses, Tops, Shoes) / Accessories (Bags, Jewelry)
Collections: New Arrivals, Best Sellers, Sale Items, Seasonal Collection
Attributes: Size (XS-XXL), Color (swatches), Material, Brand, Care Instructions
See templates/fashion-store.yml for the complete configuration.
Other Recipes
Electronics Store -- Single channel (USD), product types for Smartphones, Laptops, Tablets, Accessories, and Software. Attributes include Brand, Storage, RAM, Screen Size, and Warranty. See templates/electronics-store.yml.
Subscription Service -- Subscription portal channel, product types for Monthly/Annual subscriptions, One-Time Purchases, and Add-Ons. Attributes include Plan Tier, Billing Cycle, User Limit, and Storage Limit. See templates/subscription-service.yml.
Customization Tips
After copying a recipe:
- Rename channels to match your brand and regions
- Adjust currency and country codes for your markets
- Modify categories for your actual product catalog
- Add or remove product types you don't need
- Test on staging first before deploying to production
Common Mistakes
| Mistake | Fix |
|---|---|
| Using a recipe without customizing identifiers | Update all slugs and names to match your brand before deploying |
| Not adjusting currency/country codes | Change currencyCode and defaultCountry to your actual markets |
| Deploying a recipe straight to production | Always test on a staging instance first |
| Keeping entity types you don't need | Remove unused product types, categories, etc. to keep your config clean |
| Forgetting to update channel references | Products reference channels by slug -- make sure they match after renaming |
Creating Your Own Recipe
Template Structure
A recipe template should follow this structure:
# Recipe: [Business Type] Store
# Description: [What this recipe sets up]
# Customize: [List key things users should change]
channels:
- name: "Main Store" # ← User should rename
slug: "main" # ← User should update
currencyCode: USD # ← User should set region
defaultCountry: US
isActive: true
productTypes:
# Each type should have a comment explaining its purpose
- name: "[Type Name]"
isShippingRequired: true
productAttributes: [...]
variantAttributes: [...]
categories:
# Keep hierarchy to 3 levels max
- name: "[Root Category]"
slug: "[root-slug]"
subcategories: [...]
Required Sections
Every recipe must include:
- Header comment — recipe name, description, customization checklist
- At least one channel — with valid currency and country codes
- Product types — with product and variant attributes defined
- Categories — at least a basic hierarchy
- Comments — explaining what each section does and what to customize
Testing Your Recipe
# 1. Deploy to a fresh Saleor instance
npx configurator deploy --url=$STAGING_URL --token=$STAGING_TOKEN
# 2. Verify idempotency (second deploy should show no changes)
npx configurator deploy --url=$STAGING_URL --token=$STAGING_TOKEN
# 3. Introspect and diff to confirm round-trip fidelity
npx configurator introspect --url=$STAGING_URL --token=$STAGING_TOKEN --config=introspected.yml
npx configurator diff --url=$STAGING_URL --token=$STAGING_TOKEN
Documentation Checklist
- Every section has comments explaining purpose
- All placeholder values are clearly marked for customization
- Currency/country codes use valid ISO standards
- Slugs are descriptive and follow lowercase-hyphen convention
- README or header documents what the recipe creates
See Also
Related Skills
configurator-schema- Config.yml structure and validation rulesproduct-modeling- Product type design and attribute selectionsaleor-domain- Entity relationships and Saleor concepts
Configurator Schema
Overview
Your store configuration lives in a single config.yml file. Each section defines a type of entity (channels, products, categories, etc.) using a declarative YAML format that Configurator syncs with your Saleor instance.
When to Use
- "What does config.yml look like?"
- "What fields are required for a product/channel/category?"
- "Why is my config failing validation?"
- "What's the difference between slug-based and name-based entities?"
- "How do I reference one entity from another?"
- When NOT designing product types or choosing attributes -- use
product-modelinginstead
Schema Concepts
Treat config.yml as four conceptual groups instead of memorizing a long top-level key list:
- Store foundations:
shop,channels - Catalog model:
productAttributes,contentAttributes,productTypes,modelTypes/pageTypes - Catalog data: categories/collections/products/models
- Operations: warehouses/shipping/tax/menus
The exact allowed fields evolve over time. For authoritative validation, always run:
npx configurator validate --config config.yml --json
Entity Identification
Configurator matches your local config to remote entities using an identifier field. This is either slug or name depending on entity type:
| Identifier | Entity Types |
|---|---|
| slug | channels, categories, collections, products, warehouses, menus, models |
| name | productTypes, modelTypes/pageTypes, taxClasses, shippingZones |
Important: Changing a slug or name creates a NEW entity instead of updating the existing one.
Minimal Pattern
channels:
- name: "Main Store"
slug: "main"
currencyCode: USD
defaultCountry: US
productAttributes:
- name: "Brand"
inputType: PLAIN_TEXT
productTypes:
- name: "T-Shirt"
productAttributes:
- attribute: "Brand"
categories:
- name: "Clothing"
slug: "clothing"
products:
- name: "Classic Tee"
slug: "classic-tee"
productType: "T-Shirt"
category: "clothing"
variants:
- name: "Default"
sku: "TEE-001"
channelListings:
- channel: "main"
price: 29.99
Attribute Types
Saleor supports these attribute input types: DROPDOWN, MULTISELECT, SWATCH, BOOLEAN, PLAIN_TEXT, RICH_TEXT, NUMERIC, DATE, DATE_TIME, FILE, REFERENCE.
For detailed guidance on choosing the right type, see the product-modeling skill.
Validation Rules
- Required fields -- each entity type has required fields (e.g., channels need
name,slug,currencyCode) - Unique identifiers -- slugs/names must be unique within their entity type
- Valid references -- cross-entity references must match (e.g., a product's
productTypemust match a defined product type name) - Currency codes -- valid ISO 4217 (USD, EUR, GBP, etc.)
- Country codes -- valid ISO 3166-1 alpha-2 (US, DE, GB, etc.)
Dependency Concepts
You usually model in this order:
- Foundations (
shop,channels) - Reusable types and attributes (
productAttributes,contentAttributes,productTypes,modelTypes) - Concrete catalog entities (
categories,collections,products,models) - Operational entities (
warehouses,shippingZones,taxClasses,menus)
Configurator handles execution order, but this mental model helps diagnose missing-reference errors.
Common Mistakes
| Mistake | Fix |
|---|---|
| Changing a slug or name to "rename" an entity | This creates a new entity. To rename, delete the old one and create new. |
| Duplicate slugs within an entity type | Each slug must be unique. Check for copy-paste errors. |
| Product references a nonexistent productType | The productType field must exactly match a name in your productTypes section. |
| Missing required fields | Check the error message -- it tells you which field is missing. |
| Products defined before their productType | Not a YAML order issue (Configurator handles order), but the referenced type must exist in the file. |
Best Practices
- Use meaningful slugs --
womens-summer-dressesnotcat-123 - Consistent naming -- match display names to slugs when possible
- Comment complex sections -- use YAML comments for documentation
- Version control -- track config.yml in git
See Also
- For worked examples, see references/examples.md
- For migration from legacy syntax, run
npx configurator introspect
Related Skills
saleor-domain- Entity relationships and identifier rulesconfigurator-cli- CLI commands for deploying configurationsproduct-modeling- Product type design and attribute selection
Data Importer
Overview
This skill helps you convert product data from external sources (CSV files, spreadsheets, Shopify exports) into Saleor's config.yml format. It walks through format detection, column mapping, and validation before generating output.
When to Use
- "I need to import products from a CSV"
- "How do I convert my spreadsheet to config.yml?"
- "I'm migrating from Shopify"
- "I have product data in Excel"
- "How do I bulk import products?"
- When NOT writing config.yml from scratch -- use
configurator-schemainstead - When NOT designing product types -- use
product-modelingfirst
Core Workflow
- Detect format -- CSV, Excel, JSON, or unknown
- Extract columns -- read headers and sample data
- Map interactively -- you confirm field mappings
- Transform -- convert to Saleor schema
- Validate -- check for issues before output
File Handling
Excel (.xlsx)
Excel files need conversion. Export as CSV from Excel/Sheets, or:
python3 -c "import pandas as pd; pd.read_excel('$FILE').to_csv('${FILE%.xlsx}.csv', index=False)"
CSV
Read directly to inspect headers and sample rows.
Field Mapping
Don't assume column names. The importer will:
- Show you all columns with sample values
- Ask which column maps to each Saleor field
- Mark unmapped columns as potential attributes
Required Fields
| Saleor Field | Typical Source Columns |
|---|---|
product.name | "name", "title", or any descriptive column |
product.slug | Generated from name, or "handle"/"ID" column |
variant.sku | "SKU", "External ID", "Code" |
productType | "type" column or you specify it |
Optional Fields
| Field | Notes |
|---|---|
price | If missing, imports as catalog-only |
quantity | If missing, skips stock tracking |
category | From category/region column |
description | If present in source data |
| Other columns | Become product attributes |
Output Structure
productTypes:
- name: "[from type column or your input]"
productAttributes: [unmapped columns become attributes]
categories:
- name: "[from category column]"
slug: "[generated]"
products:
- name: "[from name column]"
slug: "[generated or from ID]"
productType: "[reference]"
variants:
- sku: "[from SKU column]"
channelListings: [if price exists]
stocks: [if quantity exists]
Special Cases
- No price column -- imports as catalog-only; add pricing later
- No SKU column -- generates from name or uses any unique ID column
- Unknown columns -- presented to you as potential attributes
- Multiple rows with same product -- grouped as variants of one product
Common Mistakes
| Mistake | Fix |
|---|---|
| Assuming column names without checking | Always inspect headers first -- column names vary wildly between sources |
| Not handling missing SKUs | Generate SKUs from product name + variant attributes, or use a unique ID column |
| Importing without validating first | Review the generated YAML before deploying -- check for duplicates and missing fields |
| Duplicate products from multi-row variants | Ensure rows sharing a product name are grouped as variants, not separate products |
| Forgetting to create product types first | Design your product types before importing -- use product-modeling skill |
Validation Checklist
Before generating output, verify:
- All products have names
- All variants have unique SKUs
- Product type references are valid
- No duplicate slugs
Reference Files
references/csv-patterns.md-- CSV/Excel parsing techniquesreferences/field-mapping.md-- Mapping strategies for various data shapesreferences/shopify-format.md-- Shopify-specific handlingreferences/transformations.md-- Data transformation rules
See Also
Related Skills
configurator-schema- Config.yml structure and field requirementsproduct-modeling- Product type design before importingsaleor-domain- Entity relationships and identifier rules
Saleor Domain Modeling
Overview
This skill helps you design your product catalog structure in Saleor -- choosing the right product types, attributes, variants, categories, and collections. The key decisions are what makes a product vs. a variant, and which attribute type to use for each field.
When to Use
- "How do I model my products?"
- "What attributes should I use?"
- "Product vs variant attributes?"
- "When to use DROPDOWN vs MULTISELECT?"
- "How to structure my product types?"
- "Categories vs Collections?"
- "When to use Models (Pages) vs Attributes?"
- When NOT looking for YAML syntax -- use
configurator-schemainstead - When NOT looking for CLI commands -- use
configurator-cliinstead
The Core Flow
This is the most important relationship to understand:
1. ATTRIBUTES (define fields)
└── Reusable typed fields: Size (DROPDOWN), Color (SWATCH), Brand (DROPDOWN)
2. PRODUCT TYPES (define structure)
└── Assign attributes:
├── productAttributes: Brand, Material (same for all variants)
└── variantAttributes: Size, Color (create SKU combinations)
3. PRODUCTS (create items)
└── Instance of a ProductType:
├── Set values: Brand="Nike", Material="Cotton"
└── Define variants with SKU combinations
4. VARIANTS (purchasable SKUs)
└── Each combination = 1 variant:
├── SKU: "TSHIRT-BLK-M" → Size="M", Color="Black", Price=$29.99
└── SKU: "TSHIRT-WHT-L" → Size="L", Color="White", Price=$29.99
Key insight: Attributes are building blocks. ProductTypes assemble them into templates. Products are instances. Variants are what customers buy.
Decision Framework: Product vs Variant Attributes
This is the most critical modeling decision.
Use Product-Level When:
| Question | If YES, use Product Level |
|---|---|
| Same value for all sizes/colors? | Brand, Material, Manufacturer |
| Descriptive information? | Care Instructions, Specs |
| For filtering/categorization only? | Style, Gender, Season |
Use Variant-Level When:
| Question | If YES, use Variant Level |
|---|---|
| Creates a separate purchasable item? | Size, Color, Storage |
| Affects price? | Size (XL costs more), quality tier |
| Needs separate inventory tracking? | Each size needs its own stock |
| Customer selects this at checkout? | Color picker, size selector |
Quick Decision Matrix
| Attribute | Product | Variant | Why |
|---|---|---|---|
| Brand | x | Same for all variants | |
| Size | x | Creates separate SKUs | |
| Color | x | Creates separate SKUs | |
| Material | x | Usually same for product | |
| Storage (64GB/128GB) | x | Different prices | |
| Care Instructions | x | Same for all variants | |
| Weight | x | May differ per size |
Attribute Type Selection
Saleor supports 12 attribute input types. Use this decision tree:
Is it a CHOICE from predefined options?
├── YES: Can user select MULTIPLE?
│ ├── YES → MULTISELECT
│ └── NO: Is it a COLOR/PATTERN?
│ ├── YES → SWATCH
│ └── NO: Is it YES/NO?
│ ├── YES → BOOLEAN
│ └── NO → DROPDOWN
└── NO: Is it a NUMBER with units?
├── YES → NUMERIC
└── NO: Is it a DATE?
├── YES → DATE (or DATE_TIME if time needed)
└── NO: Is it long formatted text?
├── YES → RICH_TEXT
└── NO: Is it a file/document?
├── YES → FILE
└── NO: Link to another entity?
├── YES → REFERENCE
└── NO → PLAIN_TEXT
For the complete attribute type reference, see references/attribute-types-deep-dive.md.
Variant Matrix Planning
Before creating variants, calculate the SKU explosion:
SKU Count = Value1 x Value2 x Value3 x ...
Example: T-Shirt
- Sizes: XS, S, M, L, XL, XXL (6)
- Colors: Black, White, Navy, Gray, Red (5)
- SKUs: 6 x 5 = 30 variants per product
| SKU Count | Assessment | Recommendation |
|---|---|---|
| 1-10 | Manageable | Good for most products |
| 11-50 | Moderate | Fine for fashion, needs inventory planning |
| 51-100 | High | Consider splitting into multiple products |
| 100+ | Too many | Simplify -- move some attributes to product level |
Tips for high counts: Split by product line, reduce dimensions, move non-purchasable attributes to product level.
Industry Patterns
Quick reference for common store types:
| Pattern | Product-Level Attrs | Variant-Level Attrs | Typical SKUs |
|---|---|---|---|
| Apparel | Brand, Material, Care | Size, Color | 30/product |
| Electronics | Brand, Screen, Processor, Features | Storage, Color | 20/product |
| Furniture | Brand, Style, Capacity, Dimensions | Fabric, Color | 16/product |
| Food & Beverage | Origin, Roast, Flavor, Certifications | Size, Grind | 12/product |
| Digital Products | Publisher, Platform, Features | License Type, Duration | 9/product |
For complete YAML examples of each pattern, see references/industry-patterns.md.
Categories vs Collections
Both organize products, but they serve different purposes:
| Aspect | Category | Collection |
|---|---|---|
| Structure | Hierarchical (tree) | Flat (list) |
| Assignment | 1 product = 1 category | 1 product = many collections |
| Purpose | Taxonomy, navigation | Merchandising, promotions |
| Examples | Electronics > Phones > Smartphones | "Summer Sale", "New Arrivals" |
Use Categories for main site navigation, browse/filter structure, SEO URLs. Use Collections for curated groups, promotions, campaigns, temporary groupings.
Keep category trees to 3 levels deep. If you need a 4th level, consider using Collections instead.
Models and Structures
Models (Pages/PageTypes) let you create custom entities beyond products -- like Brands, Ingredients, or Scent Profiles. Use them when data is shared across many products, has its own attributes, and needs its own page.
Structures (Menus) assemble Categories, Collections, Models, and URLs into navigation hierarchies.
For complete guidance and examples, see references/models-and-structures.md.
Workflow: Designing a New Product Type
- List all product characteristics -- write down every field/attribute
- Categorize each -- apply the decision framework (product vs variant)
- Select types -- use the attribute type decision tree
- Calculate SKU count -- ensure the variant matrix is manageable
- Write the YAML -- create the ProductType configuration
- Validate -- deploy with
--planto check structure
Common Mistakes
| Mistake | Fix |
|---|---|
| Over-dimensioning variants (6 sizes x 10 colors x 4 materials = 240 SKUs) | Move non-purchasable attributes to product level. Aim for under 50 SKUs. |
| Using variant attributes for non-inventory fields | If it doesn't create a separate SKU (like Care Instructions), it's a product attribute |
| Product attributes that should vary | If value differs by size (e.g., Weight), move to variant level |
| Too many product types | Reuse types when products share the same attribute structure |
| Skipping variant planning | Always calculate SKU count before creating product types |
Additional Resources
Reference Files
- references/attribute-types-deep-dive.md -- complete attribute type reference
- references/industry-patterns.md -- detailed YAML for 5+ industries
- references/models-and-structures.md -- Models and Structures guide
Examples
examples/fashion-product-types.yml-- apparel product typesexamples/electronics-product-types.yml-- tech product structuresexamples/perfume-store-models.yml-- Models for custom entitiesexamples/navigation-structures.yml-- Menu configurations
Related Skills
configurator-schema- Complete YAML schema referencesaleor-domain- Entity relationships and Saleor conceptsconfigurator-recipes- Complete store templates
Saleor Domain Knowledge
Overview
Saleor is a headless e-commerce platform with a GraphQL API. This skill covers the core entities you'll work with in Configurator -- what they are, how they relate, and the rules that govern them.
When to Use
- "What entities does Saleor have?"
- "How do channels, products, and variants relate?"
- "What's the difference between slug and name identifiers?"
- "What does Configurator manage vs. what's runtime only?"
- "What's a ProductType? What's a Channel?"
- When NOT designing product types -- use
product-modelinginstead - When NOT writing YAML config -- use
configurator-schemainstead
Core Entities
Channel
Sales channels represent storefronts, marketplaces, or regions. Each has its own currency, country, product visibility, and pricing.
Product Type
Defines the structure for a group of products: which attributes are shared (product-level) and which create variants (variant-level), plus shipping and tax settings.
Product and Variant
Products are the items you sell. Each belongs to one product type and one category. Variants are the purchasable SKUs -- each with a unique SKU, specific attribute values, channel-specific pricing, and inventory tracking.
Attribute
Typed fields attached to product types. Product-level attributes (Brand, Material) are shared across variants. Variant-level attributes (Size, Color) create separate SKUs.
Category
Hierarchical product organization (tree structure). Each product belongs to one category. Used for navigation and filtering.
Collection
Curated product groupings that can span categories. A product can belong to many collections. Used for promotions and merchandising.
Warehouse
Inventory locations with stock tracking per variant. Associated with shipping zones.
Shipping Zone
Geographic shipping regions with country-based targeting and multiple shipping methods.
Entity Relationships
Channel ─────────────────────────────────────────────┐
├── Product Listings (visibility, pricing) │
├── Variant Listings (price, availability) │
└── Checkout/Order settings │
│
ProductType ─────────────────────────────────────────┤
├── productAttributes ──► Attribute │
├── variantAttributes ──► Attribute │
└── taxClass ──► TaxClass │
│
Product ─────────────────────────────────────────────┤
├── productType ──► ProductType │
├── category ──► Category │
├── collections ──► Collection[] │
└── variants ──► ProductVariant[] │
├── warehouse ──► Warehouse │
└── channelListings ────────────┘
Category (tree) └── subcategories ──► Category[]
ShippingZone └── warehouses ──► Warehouse[]
Identifier Rules
Each entity is identified by either its slug or name. This is how Configurator matches your local config to remote entities.
| Entity | Identifier | Mutable? |
|---|---|---|
| Channel, Category, Collection, Product, Warehouse, Menu, Page | slug | No -- creates new |
| ProductType, PageType, Attribute, TaxClass, ShippingZone | name | No -- creates new |
Important: Changing an identifier creates a new entity and may orphan the old one. If you need to "rename" something, delete the old entity and create a new one.
Configuration vs Runtime
Configurator manages your store's structure. Some things are runtime-only:
| Configurator Manages | Runtime Only |
|---|---|
| Product structure and pricing | Orders |
| Categories and collections | Customers |
| Attributes and channels | Checkouts |
| Warehouses and shipping zones | Payments |
| Tax classes | Webhooks |
Entity Relationships in config.yml
Here are practical examples showing how entities reference each other:
# A product references its type (by name), category (by slug path),
# and channels (by slug) for pricing:
products:
- name: "Classic T-Shirt"
slug: "classic-t-shirt"
productType: "T-Shirt" # → matches productTypes[].name
category: "clothing/t-shirts" # → matches category slug path
variants:
- sku: "TSHIRT-S-RED"
channelListings:
- channel: "us-store" # → matches channels[].slug
price: 29.99
stocks:
- warehouse: "main-wh" # → matches warehouses[].slug
quantity: 100
# A shipping zone references warehouses and targets countries:
shippingZones:
- name: "US Shipping"
countries: [US]
warehouses:
- "main-wh" # → matches warehouses[].slug
Common Mistakes
| Mistake | Fix |
|---|---|
| Confusing slug-based vs name-based entities | Check the Identifier Rules table -- some use slug, others use name |
| Changing an identifier to "rename" | This creates a duplicate. Delete old + create new instead. |
| Creating products before their product type exists | Product types must be defined first. Configurator handles deploy order, but the type must be in your config. |
| Not understanding channel scope | Products aren't visible until they have a channel listing. Each channel has independent pricing. |
| Mixing up Categories (taxonomy) vs Collections (curation) | Categories = hierarchical, 1 per product, for navigation. Collections = flat, many per product, for merchandising. |
See Also
- For entity reference, see references/entities.md
- For relationship diagrams, see references/relationships.md
- For Storefront v26 integration, see references/storefront-v26.md
Related Skills
configurator-schema- Config.yml structure and validation rulesproduct-modeling- Product type design and attribute selectionconfigurator-cli- CLI commands for deploying configurations
Commands 6
Configurator Fix
Required Skills
configurator-schema— config.yml structure and valid field valuesconfigurator-cli— CLI commands and exit codes
Intelligent debugging and fixing for config.yml issues. This command reads your configuration, identifies problems, explains them in plain language, and offers to automatically fix common issues.
Usage
# Interactive fixing (recommended)
/configurator-fix
# Auto-fix without prompts
/configurator-fix --auto-fix
# Check only (no fixes)
/configurator-fix --check-only
What This Command Does
Unlike /configurator validate which shows technical validation errors, this command:
✅ Explains errors in plain language ✅ Shows line numbers and context ✅ Provides before/after examples ✅ Offers to auto-fix common issues ✅ Suggests manual fixes for complex issues
Workflow
Step 1: Check for config.yml
test -f config.yml && echo "CONFIG_EXISTS" || echo "NO_CONFIG"
If no config exists, inform user and suggest /configurator init.
Step 2: Read and Analyze
Read config.yml and identify issues:
Auto-fixable issues (can be fixed automatically):
- Invalid slugs (spaces, uppercase, underscores)
- Missing required fields with obvious defaults
- Duplicate identifiers (with renaming)
- YAML syntax errors (unclosed quotes, indentation)
- Invalid currency/country codes (common typos)
Manual-fix issues (require user decision):
- Missing referenced entities (productType, category, etc.)
- Logical inconsistencies (digital products with shipping)
- Empty collections
- Products without variants
Step 3: Present Issues with Context
For each issue, show:
Issue Type: [Error/Warning]
Line: [line number]
Context: [code snippet from file]
Problem: [plain language explanation]
Impact: [what will happen if not fixed]
Fix: [specific solution]
[Auto-fix available] or [Manual fix required]
Example output format:
═══════════════════════════════════════════════════
Configuration Issues Found: 4
═══════════════════════════════════════════════════
❌ ERROR #1 (Line 45)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Context:
43 | products:
44 | - name: "Fancy T-Shirt"
> 45 | productType: "TShirt"
46 | slug: "fancy-tshirt"
Problem: Product references unknown productType "TShirt"
Available productTypes:
- T-Shirt
- Pants
- Accessory
Fix: Change "TShirt" to "T-Shirt"
Impact: Deployment will fail - product cannot be created without valid productType
[Auto-fix available]
⚠️ WARNING #2 (Line 67)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Context:
65 | categories:
66 | - name: "My Category"
> 67 | slug: "My Category"
68 | children: []
Problem: Slug contains spaces and uppercase letters
Slugs must be:
- Lowercase only
- Use hyphens (not spaces or underscores)
- No special characters
Fix: Change "My Category" to "my-category"
Impact: Invalid slug format may cause deployment errors
[Auto-fix available]
❌ ERROR #3 (Line 89)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Context:
87 | variants:
88 | - attributes:
> 89 | - name: "Size"
90 | value: "M"
91 | # Missing SKU
Problem: Variant is missing required field "sku"
Every variant must have a unique SKU for inventory tracking.
Fix: Add a SKU field, for example:
sku: "fancy-tshirt-m-blue"
Impact: Deployment will fail - variants require SKUs
[Manual fix required - need unique identifier]
⚠️ WARNING #4 (Line 102)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Context:
100 | products:
101 | - name: "Digital Download"
> 102 | isShippingRequired: true
103 | productType: "Digital Product"
Problem: Digital product has shipping enabled
Digital products typically don't require shipping.
Fix: Change isShippingRequired to false
Impact: Users will be prompted for shipping address unnecessarily
[Auto-fix available]
═══════════════════════════════════════════════════
Summary: 2 errors, 2 warnings
Auto-fixable: 3 issues
Manual fixes needed: 1 issue
═══════════════════════════════════════════════════
Step 4: Offer Auto-fixes
If --auto-fix flag is NOT present, ask user:
Question: "Found 3 auto-fixable issues. Would you like me to fix them automatically?" Options:
- Fix all automatically
- Review each fix individually
- Skip auto-fixes (show manual instructions only)
Step 5: Apply Auto-fixes
For each auto-fixable issue:
If "Review individually": Show before/after for each fix and ask for confirmation
If "Fix all automatically": Apply all fixes and show summary
Use Edit tool for surgical changes:
# Fix invalid slug
old_string: 'slug: "My Category"'
new_string: 'slug: "my-category"'
# Fix productType reference
old_string: 'productType: "TShirt"'
new_string: 'productType: "T-Shirt"'
# Fix shipping requirement
old_string: 'isShippingRequired: true'
new_string: 'isShippingRequired: false'
Step 6: Manual Fix Instructions
For issues that can't be auto-fixed, provide step-by-step instructions:
Manual Fixes Required
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Add SKU to variant (Line 89)
Current:
variants:
- attributes:
- name: "Size"
value: "M"
Fix:
variants:
- sku: "fancy-tshirt-m" ← Add this line
attributes:
- name: "Size"
value: "M"
Choose a unique identifier (letters, numbers, hyphens only)
Would you like me to:
- Generate SKU suggestions based on product name and attributes?
- Open the file for manual editing?
- Skip for now?
Step 7: Validation After Fixes
After applying fixes, validate the configuration:
python3 -c "import yaml; yaml.safe_load(open('config.yml'))"
Show summary:
✓ Applied 3 auto-fixes successfully
Fixed issues:
- Line 45: Updated productType reference
- Line 67: Fixed invalid slug format
- Line 102: Disabled shipping for digital product
Remaining issues: 1 manual fix needed
Next steps:
1. Address manual fix (variant SKU at line 89)
2. Run /configurator-fix again to verify
3. Deploy when ready: npx configurator deploy
Common Auto-fixable Issues
Invalid Slugs
Problem: Spaces, uppercase, underscores in slugs
Detection: Regex check for [A-Z\s_]
Fix: Convert to lowercase, replace spaces/underscores with hyphens
# Before
slug: "My_Cool Product"
# After
slug: "my-cool-product"
Typo in Entity References
Problem: productType: "TShirt" when it should be "T-Shirt"
Detection: Check if reference exists, look for similar names
Fix: Fuzzy match to find correct entity name
# Before
productType: "TShirt" # Doesn't exist
# After
productType: "T-Shirt" # Exists
Missing Currency/Country Codes
Problem: Invalid ISO codes Detection: Check against known ISO 4217 / ISO 3166-1 codes Fix: Suggest closest match or common default
# Before
currencyCode: "DOLLARS" # Invalid
# After
currencyCode: "USD" # Valid ISO 4217
YAML Syntax Errors
Problem: Unclosed quotes, wrong indentation Detection: Try parsing with PyYAML, check error messages Fix: Add closing quotes, fix indentation
# Before
name: "Unclosed quote
description: "Test"
# After
name: "Unclosed quote"
description: "Test"
Duplicate Identifiers
Problem: Two products with same slug Detection: Track all slugs/SKUs in sets Fix: Append number to duplicate
# Before
products:
- slug: "tshirt"
- slug: "tshirt" # Duplicate
# After
products:
- slug: "tshirt"
- slug: "tshirt-2" # Auto-renamed
Issues Requiring Manual Fixes
Missing Referenced Entities
Problem: Product references non-existent category Fix: User must either:
- Create the missing category
- Change reference to existing category
- Remove the product
Guidance: Show existing categories and suggest which to use
Missing Required Fields
Problem: Variant without SKU, product without name Fix: User must provide the value (can't be auto-generated safely)
Guidance: Show example format and best practices
Logical Inconsistencies
Problem: Digital product with shipping zones assigned Fix: User decides intent (maybe it's a physical digital product box?)
Guidance: Explain the inconsistency and ask for clarification
Command Arguments
--auto-fix
Apply all auto-fixes without prompting
/configurator-fix --auto-fix
--check-only
Identify issues but don't offer to fix
/configurator-fix --check-only
Use case: Just want to see what's wrong before making changes
Integration with Other Commands
After fixing issues, suggest:
Configuration fixed! Next steps:
1. Validate: /configurator validate
→ Comprehensive validation check
2. Review: /configurator review
→ Agent-based quality review
3. Preview: npx configurator diff --url=$URL --token=$TOKEN
→ See what will change in Saleor
4. Deploy: npx configurator deploy --url=$URL --token=$TOKEN
→ Apply changes to your store
Error Handling
If config.yml doesn't exist:
No config.yml found.
Create one with:
/configurator init - Empty skeleton
/recipe [type] - Pre-built template
/discover - From existing site
If config.yml is completely invalid YAML:
config.yml has critical YAML syntax errors:
Line 15: mapping values are not allowed here
This needs to be fixed manually before I can analyze further.
Common issues:
- Missing colon after key
- Wrong indentation (use 2 spaces)
- Unclosed quotes or brackets
Would you like me to:
- Show the problematic section
- Suggest YAML validation resources
- Create a backup and start fresh
If all issues are already fixed:
✓ No issues found!
Your configuration looks good.
Next steps:
- /configurator validate - Full validation
- /configurator review - Agent quality check
- Deploy when ready
Skills Referenced
configurator-schemafor valid field valuessaleor-domainfor entity relationshipsconfigurator-clifor deployment commands
Related Commands
/configurator validate- Comprehensive technical validation/configurator review- Agent-based quality review/configurator edit- Interactive editing/configurator- Main command hub
Configurator Import
Required Skills
data-importer— transformation patterns and field mapping strategiesconfigurator-schema— config.yml structure and validation rules
Import external product data into Saleor's config.yml format.
Usage
# Import from CSV file
/configurator-import products.csv
# Import from Shopify export
/configurator-import shopify-export.csv --source shopify
# Interactive (will prompt for file path)
/configurator-import
Process
1. Check File
test -f "$1" && file "$1"
If no file provided, ask user for the path.
2. Handle Excel
If .xlsx file, ask user to convert to CSV:
- Excel: File → Save As → CSV
- Google Sheets: File → Download → CSV
- Or try:
python3 -c "import pandas as pd; pd.read_excel('FILE').to_csv('FILE.csv', index=False)"
3. Detect Format
Check first line for format hints:
head -1 "$FILE"
Ask user to confirm:
- Shopify (has Handle, Title, Variant columns) → Use
shopify-importeragent - Generic CSV/Excel → Use
csv-importeragent
4. Delegate to Agent
The agent will:
- Analyze columns and sample data
- Guide interactive field mapping
- Generate config.yml content
- Return YAML for saving
5. Save Decision
Ask user:
- Merge with existing config.yml
- Replace config.yml (backup first)
- Preview only (save to import-preview.yml)
6. Next Steps
After import:
✓ Imported [N] products
Next:
1. /configurator review - Review configuration
2. /configurator validate - Validate schema
3. npx configurator diff --url=$URL --token=$TOKEN
Error Handling
- File not found: Prompt user for correct path, check working directory
- Unsupported format: List supported formats (CSV, XLSX), suggest conversion
- Empty file: Inform user, suggest checking the export source
- Malformed CSV: Show problematic rows, offer to skip or abort
- No mappable columns: Show detected columns, guide manual mapping
Skills
Reference data-importer skill for transformation patterns.
Related Commands
/configurator validate- Validate imported configuration/configurator review- Review imported data quality/configurator-fix- Fix issues found after import/configurator-model- Design product types before importing
Domain Modeling Wizard
Required Skills
product-modeling— product type design, attribute selection, and variant planningsaleor-domain— entity relationships and identifier rules
Guide the user through designing their complete catalog structure. This wizard helps translate business requirements into Saleor's data model:
- ProductTypes & Attributes - Product structure and variants
- Models (Pages) - Custom entities (Brands, Ingredients, Profiles)
- Categories - Hierarchical product organization
- Collections - Curated product groupings
- Structures (Menus) - Navigation and curated guides
Progress Tracking
Create tasks to show wizard progress:
Use TaskCreate at the start:
1. "Understand products" - activeForm: "Understanding your products"
2. "Identify attributes" - activeForm: "Identifying product attributes"
3. "Classify attributes" - activeForm: "Classifying product vs variant attributes"
4. "Select attribute types" - activeForm: "Selecting attribute types"
5. "Calculate variant matrix" - activeForm: "Calculating variant matrix"
6. "Generate ProductType" - activeForm: "Generating ProductType configuration"
7. "Review and refine" - activeForm: "Reviewing configuration"
Update status as you progress through each step.
Skills Reference
Load and use the product-modeling skill for decision frameworks:
- Product vs variant attribute decisions
- Attribute type selection guide
- Variant matrix calculations
- Industry-specific patterns
Context Check
Check if config.yml exists:
test -f config.yml && echo "CONFIG_EXISTS" || echo "NO_CONFIG"
If config.yml exists, also check for existing productTypes to understand current structure.
Wizard Workflow
Step 1: Understand the Product
If $ARGUMENTS is provided, use it as the starting point. Otherwise, ask:
Question to ask with AskUserQuestion:
- "Describe your product in detail. What are you selling?"
Gather information about:
- What is the product? (e.g., "T-shirts", "smartphones", "coffee beans")
- What makes one item different from another? (variations)
- What information do customers need to see?
- What do customers choose at checkout?
Step 2: List All Characteristics
Based on the product description, identify ALL characteristics/fields the product has.
Present back to the user:
Based on your description, I identified these characteristics:
- [characteristic 1]
- [characteristic 2]
- [characteristic 3]
...
Are there any characteristics I missed?
Use AskUserQuestion to confirm or gather additional characteristics.
Step 3: Classify Each Characteristic
For each characteristic, determine if it's a Product-Level or Variant-Level attribute.
Apply the decision framework from product-modeling skill:
Product-Level (same for ALL variants):
- Descriptive information (Brand, Material, Care Instructions)
- Categorization (Style, Gender, Collection)
- Specifications that don't vary (Processor type, Display type)
Variant-Level (creates purchasable SKUs):
- Customer selectable options (Size, Color)
- Affects price (Storage capacity, Material quality tier)
- Requires separate inventory tracking (each combination needs stock)
Present classification to user as a table:
| Characteristic | Classification | Reasoning |
|----------------|----------------|-----------|
| Brand | Product | Same for all variants |
| Size | Variant | Customer selects, separate inventory |
| Color | Variant | Customer selects, separate inventory |
| Material | Product | Usually same for all variants |
...
Ask user to confirm or adjust classifications.
Step 4: Select Attribute Types
For each characteristic, recommend the appropriate Saleor attribute type:
| Characteristic | Recommended Type | Reasoning |
|---|---|---|
| Brand | DROPDOWN | Single choice from predefined list |
| Size | DROPDOWN | Single choice from sizes |
| Color | SWATCH | Visual color selection |
| Features | MULTISELECT | Multiple can apply |
| Description | RICH_TEXT | Long formatted text |
| Weight | NUMERIC | Number with unit |
| Is Organic | BOOLEAN | Yes/No toggle |
Use the type selection decision tree from product-modeling skill.
Present recommendations and ask user to confirm.
Step 5: Define Attribute Values
For DROPDOWN, MULTISELECT, and SWATCH types, gather the specific values:
Ask with AskUserQuestion:
- "What are the available sizes?" → XS, S, M, L, XL, XXL
- "What colors do you offer?" → Black, White, Navy (with hex codes for SWATCH)
- "What materials do you use?" → Cotton, Polyester, etc.
For SWATCH colors, help generate hex codes:
- Black: #000000
- White: #FFFFFF
- Navy: #000080
- etc.
Step 6: Calculate Variant Matrix
Calculate the number of SKUs that will be created:
Variant Attributes:
- Size: 6 values (XS, S, M, L, XL, XXL)
- Color: 5 values (Black, White, Navy, Gray, Red)
Total SKUs per product: 6 × 5 = 30 variants
Assessment:
| SKU Count | Assessment |
|---|---|
| 1-10 | Manageable |
| 11-50 | Moderate - requires inventory management |
| 51-100 | High - consider splitting product lines |
| 100+ | Very High - simplify or split products |
If SKU count is high (>50), suggest:
- Moving some variant attributes to product level
- Splitting into multiple product types
- Limiting value combinations
Step 7: Generate ProductType Configuration
Generate the YAML configuration:
productTypes:
- name: "[Product Type Name]"
isShippingRequired: true # Set based on physical/digital
weight:
value: [value]
unit: G
productAttributes:
- name: "[Attribute Name]"
type: [TYPE]
values: # For DROPDOWN/MULTISELECT/SWATCH
- name: "[Value]"
visibleInStorefront: true
filterableInStorefront: true # If useful for filtering
variantAttributes:
- name: "[Attribute Name]"
type: [TYPE]
values:
- name: "[Value]"
visibleInStorefront: true
filterableInStorefront: true
Step 8: Review and Refine
Present the complete configuration and ask:
- "Does this ProductType structure look correct?"
- "Would you like to add more product types?"
- "Should I add this to your config.yml?"
If user confirms, either:
- Create new config.yml with the productType
- Or add to existing config.yml (append to productTypes section)
Step 9: Next Steps
After generating the ProductType:
-
Explain how to create products using this type:
products: - name: "Product Name" slug: "product-slug" productType: "[ProductType Name]" category: "[category-slug]" attributes: [Product Attribute]: "Value" variants: - sku: "SKU-001" attributes: [Variant Attribute]: "Value" -
Suggest running
/configurator validateto check the configuration -
Offer to help create:
- Categories for the products
- Sample products with variants
- Additional product types
Interactive Patterns
Use AskUserQuestion for key decisions:
Multiple product types:
options:
- "Yes, I have more product types to define"
- "No, this is sufficient for now"
Classification confirmation:
options:
- "This classification looks correct"
- "I need to change some classifications"
SKU count warning:
options:
- "Keep all variant attributes (accept high SKU count)"
- "Move [attribute] to product level"
- "Reduce value options"
Example Session
User: "I sell craft coffee beans"
Assistant identifies:
- Origin (Ethiopia, Colombia, Brazil)
- Roast Level (Light, Medium, Dark)
- Flavor Notes (Fruity, Nutty, Chocolate)
- Certifications (Organic, Fair Trade)
- Bag Size (250g, 500g, 1kg)
- Grind (Whole Bean, Espresso, Filter)
Classification:
- Origin → Product (defines the coffee)
- Roast Level → Product (defines the coffee)
- Flavor Notes → Product (MULTISELECT, descriptive)
- Certifications → Product (MULTISELECT, descriptive)
- Bag Size → Variant (affects price, inventory)
- Grind → Variant (customer choice)
SKU calculation: 3 sizes × 4 grinds = 12 SKUs per coffee ✓
Generated ProductType with proper structure.
Error Handling
If user provides unclear information:
- Ask clarifying questions
- Provide examples from similar industries
- Reference patterns from product-modeling skill
If user wants to model something complex:
- Break into multiple product types
- Suggest using REFERENCE attributes for related entities
- Guide toward maintainable structure
Extended Workflow: Beyond Products
After completing product modeling, or if user needs other entity types, offer extended guidance.
Modeling Custom Entities (Models/Pages)
When user needs entities beyond products (Brands, Ingredients, Profiles):
Question to ask: "Do you have concepts that are shared across products but need their own rich data? Examples: Brands with logos, Scent Profiles, Ingredients with benefits"
If YES, guide through Model creation:
- Identify the entity - What is it? (Brand, Ingredient, Profile)
- Define attributes - What fields does it need?
- Generate PageType - Create the schema
- Create Model instances - Add specific entries
- Link to Products - Use REFERENCE attribute
Model Decision Framework:
| Use Case | Use Model | Use Product Attribute |
|---|---|---|
| Shared across many products | ✓ | |
| Has its own detailed attributes | ✓ | |
| Needs its own page/content | ✓ | |
| Simple value selection | ✓ | |
| No data beyond name | ✓ |
Example Model Configuration:
pageTypes:
- name: "Brand"
attributes:
- name: "Logo"
type: FILE
- name: "Description"
type: RICH_TEXT
- name: "Country"
type: DROPDOWN
values: ["USA", "Germany", "Japan"]
models:
- title: "Nike"
slug: "nike"
pageType: "Brand"
attributes:
Country: "USA"
Organizing Products: Categories vs Collections
Question to ask: "How do you want customers to browse your products? Through a taxonomy (Categories) or curated groups (Collections)?"
Categories (hierarchical, 1 product = 1 category):
- Main site navigation
- SEO-driven URL structure
- Product taxonomy (what IS this product?)
Collections (flat, 1 product = N collections):
- Promotions ("Summer Sale")
- Curated groups ("Staff Picks")
- Marketing campaigns
Category Hierarchy Example:
categories:
- name: "Electronics"
slug: "electronics"
children:
- name: "Phones"
slug: "phones"
children:
- name: "Smartphones"
slug: "smartphones"
Collection Example:
collections:
- name: "New Arrivals"
slug: "new-arrivals"
channelListings:
- channel: "default"
isPublished: true
Building Navigation: Structures (Menus)
Question to ask: "Do you need navigation menus or curated guides that link categories, collections, and content pages?"
Structure can link:
- Categories (taxonomy)
- Collections (promotions)
- Models/Pages (content)
- External URLs
Navigation Example:
menus:
- name: "Main Navigation"
slug: "main-nav"
items:
- name: "Shop"
category: "shop"
children:
- name: "New Arrivals"
collection: "new-arrivals"
- name: "Electronics"
category: "electronics"
- name: "Brands"
children:
- name: "Nike"
page: "nike"
- name: "About"
page: "about-us"
Curated Guide Example:
menus:
- name: "Home Office Guide"
slug: "home-office-guide"
items:
- name: "Ergonomics Tips"
page: "ergonomics" # Content Model
- name: "Recommended Desks"
category: "desks" # Products
- name: "Office Bundles"
collection: "office-bundles" # Promotion
Complete Modeling Checklist
Use AskUserQuestion to check what the user needs:
"What do you need to model?" Options:
- Products with variants (ProductTypes, Attributes)
- Custom entities like Brands or Profiles (Models)
- Product organization (Categories, Collections)
- Navigation or curated guides (Structures)
- Complete store setup (all of the above)
Based on selection, guide through relevant sections.
Skills Reference (Extended)
The product-modeling skill covers:
- Attributes → ProductTypes → Products → Variants flow
- Product vs variant attribute decisions
- Attribute type selection (12 types)
- Variant matrix calculations
- Models (Pages) - when and how to use
- Categories vs Collections decision framework
- Structures (Menus) - navigation and curated guides
- Industry-specific patterns
Reference files:
reference/attribute-types-deep-dive.md- All attribute typesreference/industry-patterns.md- 10+ industry patternsreference/models-and-structures.md- Complete Models & Structures guide
Examples:
examples/fashion-product-types.ymlexamples/electronics-product-types.ymlexamples/perfume-store-models.yml- Models with REFERENCE attributesexamples/navigation-structures.yml- Menu configurations
Related Commands
/configurator validate- Validate generated product types/configurator-import- Import product data using modeled types/recipe- Apply pre-built store templates/configurator-fix- Fix issues in configuration
Configurator
Core command for managing your Saleor configuration. This command provides essential operations for working with config.yml.
Required Skills
configurator-schema— config.yml structure and validation rulesconfigurator-cli— CLI commands, flags, and exit codes
Usage
/configurator init # Initialize new config.yml
/configurator validate # Validate configuration
/configurator edit # Edit configuration interactively
/configurator review # Launch comprehensive review agent
/configurator # Show menu if no argument
Operation: init
Initialize a new config.yml with the correct structure.
Process
- Check for existing config:
test -f config.yml && echo "CONFIG_EXISTS" || echo "NO_CONFIG"
-
If exists, ask user:
- Backup and replace (creates config.yml.backup)
- Cancel initialization
-
Copy skeleton template:
cp ${CLAUDE_PLUGIN_ROOT}/skills/configurator-recipes/templates/skeleton.yml config.yml
-
Basic customization (optional): Ask if user wants to set basics now:
- Channel name
- Currency code (USD, EUR, GBP, etc.)
- Country code (US, DE, GB, etc.)
-
Validate YAML syntax:
python3 -c "import yaml; yaml.safe_load(open('config.yml'))"
- Next steps:
✓ Created config.yml with Saleor Configurator structure
Next steps:
1. Edit config.yml with your store data
2. /configurator validate - Check for issues
3. /recipe [type] - Apply a pre-built recipe
4. Deploy when ready
For pre-built templates: /recipe
For discovery from website: /discover
Operation: validate
Comprehensive validation with schema checks, best practices, and common mistake detection.
Validation Phases
Phase 1: YAML Syntax
- Indentation consistency
- Missing colons, invalid characters
- Quote matching
Phase 2: Schema Validation For each entity type, check required fields:
- Channels: name, slug, currencyCode, defaultCountry
- Product Types: name, isShippingRequired, attribute references
- Categories: name, slug, no circular references
- Products: name, slug, productType, category, variants
- Variants: sku, prices, attribute values
Phase 3: Reference Integrity All cross-entity references must be valid:
- Product → ProductType, Category, Channel
- Variant → Warehouse
- ProductType → Attribute, TaxClass
- Menu → Category/Collection/Page
Phase 4: Best Practices
- Naming conventions (lowercase slugs with hyphens)
- Configuration completeness (active channels, prices set)
- SEO considerations (descriptions present)
Phase 5: Common Mistakes
- Duplicate identifiers (slugs, SKUs, names)
- Invalid references
- Missing required data
- Logical inconsistencies (digital products with shipping)
Output Format
═══════════════════════════════════════════════════
Saleor Configuration Validation Report
═══════════════════════════════════════════════════
✓ YAML Syntax: Valid
✓ Schema Compliance: 45/45 entities valid
⚠ WARNINGS (2)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Product "old-tshirt" has no description
→ Consider adding for SEO
2. Channel "test-store" is not active
→ Won't be visible to customers
✗ ERRORS (1)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Product references unknown productType "NonExistent"
→ Available: T-Shirt, Pants, Accessory
→ Fix at line 145
═══════════════════════════════════════════════════
Summary: 1 error, 2 warnings
Status: ✗ FAILED - Fix errors before deployment
═══════════════════════════════════════════════════
Next Steps
If valid:
- Preview:
npx configurator diff --url=$URL --token=$TOKEN - Deploy:
npx configurator deploy --url=$URL --token=$TOKEN
If errors:
- Use
/configurator editto fix issues - Run
/configurator validateagain
Operation: edit
Interactive menu for modifying existing configuration.
Main Menu
Present options via AskUserQuestion:
- Add new entity (product type, category, product, etc.)
- Modify existing entity
- Remove entity
- View configuration summary
- Validate configuration
Entity Types
Available entities:
- Channel
- Product Type
- Category
- Collection
- Product
- Attribute
- Shipping Zone
- Warehouse
- Tax Class
- Menu
- Page
Add Entity Workflow
For each entity type, gather required fields:
Channel:
- Display name → Auto-generate slug
- Currency code
- Default country
Product Type:
- Name (unique identifier)
- Shipping required?
- Product-level attributes (name, type, values)
- Variant-level attributes (name, type, values)
Category:
- Name → Auto-generate slug
- Parent category (or root)
- Description (optional)
Product:
- Name → Auto-generate slug
- Product Type (select from existing)
- Category (select from existing)
- Channel listings (visibility, pricing)
- At least one variant with SKU
Modify/Remove Entity
- Select entity type
- List existing entities
- Select which one
- Show current values
- Make changes or confirm removal
Dependency warnings for removals:
- ProductType: Products using it become orphaned
- Category: Child categories and products affected
- Channel: All channel listings removed
Configuration Summary
Configuration Summary
=====================
Channels: 2 (us-store, eu-store)
Product Types: 3 (T-Shirt, Pants, Accessory)
Categories: 12 (in 3-level hierarchy)
Products: 45
Collections: 5
Warehouses: 2
Shipping Zones: 3
Post-Edit Actions
After any modification:
- Validate YAML syntax
- Check for broken references
- Suggest
/configurator validatefor full validation - Offer to show diff with remote
Operation: review
Launch the comprehensive configuration review agent.
What the Agent Does
The config-review agent analyzes config.yml for:
- Schema compliance issues
- Best practice violations
- Common configuration mistakes
- SEO concerns
- Performance considerations
- Security issues
Review Output
Findings are confidence-scored:
- Critical (90-100): Must fix before deployment
- High (75-89): Should fix for best practices
- Medium (60-74): Consider fixing
- Low (<60): Optional improvements
When to Use
Run review:
- Before first deployment
- After major configuration changes
- After importing data
- Periodically for maintenance
The agent is automatically triggered after:
/configurator initcompletes/configurator editmakes changes/recipeapplies a template/discovergenerates config
No Argument Behavior
If /configurator is called without arguments, show interactive menu:
Question: "What would you like to do with your configuration?" Options:
- Initialize new config.yml
- Validate existing config
- Edit configuration
- Review configuration
- View summary
Skills Referenced
configurator-clifor CLI commandsconfigurator-schemafor config structuresaleor-domainfor entity relationships
Related Commands
/recipe- Apply pre-built store templates/discover- Generate config from existing website/configurator-model- Product modeling wizard
Discover
Required Skills
saleor-domain— entity relationships and identifier rulesconfigurator-cli— CLI commands, introspect workflow, and flags
Intelligently generate Saleor configuration by exploring your existing website. This command uses chrome-devtools MCP to analyze your site's structure, business context, and product catalog, then translates it into a proper config.yml.
Usage
# Interactive discovery (recommended)
/discover
# Quick discovery from URL
/discover https://example.com
# With Saleor introspection (if already have Saleor instance)
/discover --introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN
Two Discovery Modes
Mode 1: Website Exploration (chrome-devtools)
Analyze an existing website to understand business model and generate config.
Best for:
- Migrating from another platform
- Rebuilding existing store in Saleor
- Learning from competitor sites
- Understanding business requirements
Mode 2: Saleor Introspection
Pull configuration from existing Saleor instance.
Best for:
- Starting config.yml from live store
- Syncing with production
- Documenting existing setup
- Creating staging config
Workflow
Step 1: Discovery Method Selection
If no argument provided, ask via AskUserQuestion:
Question: "How would you like to discover your store configuration?" Options:
- Explore existing website (requires URL)
- Introspect Saleor instance (requires credentials)
- Manual input (guided questions)
Step 2A: Website Exploration Workflow
Prerequisites Check:
# Check if chrome-devtools MCP is available
mcp-cli tools | grep chrome-devtools
If not available:
- Explain chrome-devtools MCP is needed
- Show installation instructions
- Offer to continue with manual input instead
Exploration Process:
-
Get website URL:
- Ask user for site URL
- Validate URL format
- Check if accessible
-
Launch browser session:
# Via mcp-cli (check schema first)
mcp-cli info chrome-devtools/new_page
mcp-cli call chrome-devtools/new_page '{"url": "[user-url]"}'
- Analyze homepage:
- Take screenshot for context
- Extract navigation structure
- Identify product categories
- Detect business type (fashion, electronics, etc.)
mcp-cli call chrome-devtools/take_screenshot '{}'
-
Explore category pages:
- Navigate to main categories
- Analyze product listings
- Extract product structure
- Identify filtering options (these become attributes)
-
Analyze product pages:
- Navigate to sample products
- Extract product details
- Identify variant options (size, color, etc.)
- Note pricing structure
- Check shipping info
-
Extract business context:
- Brand identity
- Product categories
- Variant attributes
- Pricing tiers
- Shipping requirements
Interactive Clarification:
During exploration, ask clarifying questions:
- "I see size options: S, M, L, XL. Should these be variant or product attributes?"
- "Products are grouped by 'Brand'. Should this be a category or collection?"
- "I found color swatches. Should colors use SWATCH or DROPDOWN type?"
- "Some products show 'Out of Stock'. Should I include inventory tracking?"
Step 2B: Saleor Introspection Workflow
Prerequisites Check:
# Verify credentials
[ -n "$SALEOR_URL" ] && [ -n "$SALEOR_TOKEN" ] && echo "READY" || echo "MISSING"
If missing, ask user to provide:
- SALEOR_URL
- SALEOR_TOKEN
Introspection Process:
- Run introspect command:
npx configurator introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN
-
Analyze generated config:
- Count entities
- Identify patterns
- Note complexity
-
Ask user about filtering:
- Include all products or sample?
- Include inactive entities?
- Simplify or preserve full details?
-
Generate refined config:
- Clean up autogenerated content
- Apply best practices
- Remove test/demo data
- Organize structure
Step 2C: Manual Input Workflow
If chrome-devtools not available or user prefers manual:
Guided Questions (progressive disclosure):
-
Business Type:
- What do you sell?
- Physical or digital products?
- Variants needed?
-
Product Structure:
- Main product categories?
- How do products vary? (size, color, model, etc.)
- Example products?
-
Attributes:
- What options do customers choose?
- Which options change price/SKU?
- Attribute types (dropdown, swatch, text)?
-
Organization:
- Category hierarchy?
- Collections needed?
- Multiple channels/regions?
Step 3: Configuration Generation
Based on discovered information, generate config.yml:
Entity Mapping:
From website/Saleor to config:
Website Categories → Saleor Categories
Product Options → Variant Attributes
Product Specs → Product Attributes
Collections/Tags → Collections
Shipping Info → Shipping Zones
Generate Structure:
# Saleor Store Configuration
# Generated via discovery from [source]
# Date: [current date]
channels:
- name: "[Detected or user-specified]"
slug: "main"
currencyCode: [Detected from prices]
defaultCountry: [Detected or user-specified]
isActive: true
productTypes:
# Detected from product analysis
- name: "[Product type]"
isShippingRequired: [true if physical]
productAttributes:
- name: "[Spec attributes]"
type: [PLAIN_TEXT/DROPDOWN/etc]
variantAttributes:
- name: "[Option attributes]"
type: [DROPDOWN/SWATCH]
values: [Detected values]
categories:
# Mapped from website navigation
- name: "[Category]"
slug: "[slug]"
children:
- name: "[Subcategory]"
slug: "[slug]"
# Optional: Sample products (if requested)
products: [...]
Step 4: Validation & Refinement
After generation:
- Show summary:
✓ Discovered configuration from [source]
Detected:
- Business type: [Fashion/Electronics/etc]
- [N] product categories
- [N] variant attributes
- [N] product types
- Shipping: [Required/Not required]
- Currency: [USD/EUR/etc]
Generated:
- [N] channels
- [N] product types
- [N] categories
- [N] attributes
-
Ask for refinements:
- "Does this structure match your business?"
- "Any categories missing?"
- "Should I add sample products?"
-
Apply refinements
-
Validate:
python3 -c "import yaml; yaml.safe_load(open('config.yml'))"
- Proactively launch config-review agent:
- Check generated config quality
- Suggest improvements
- Validate relationships
Step 5: Next Steps
✓ Configuration generated and validated
Next steps:
1. Review: /configurator review
2. Refine: /configurator edit
3. Add products: /configurator-model or manual
4. Deploy: npx configurator deploy --url=... --token=...
Need help with product modeling? Run /configurator-model
Chrome DevTools MCP Integration
Required Tools
This command uses these chrome-devtools MCP tools:
new_page- Launch browser sessionnavigate_page- Navigate to URLstake_screenshot- Capture page stateevaluate_script- Extract page datalist_pages- Manage browser tabsclose_page- Clean up
Graceful Fallback
If chrome-devtools not available:
- Inform user
- Explain benefits of using it
- Offer installation guide
- Fall back to manual input or introspection
Installation Guide
If user wants to use chrome-devtools:
# Install chrome-devtools MCP server
npm install -g @modelcontextprotocol/server-chrome-devtools
# Verify installation
mcp-cli tools chrome-devtools
Show them how to configure in Claude Code settings.
Discovery Patterns
Pattern Detection
Automatically detect common patterns:
Fashion Store:
- Category names: Men, Women, Kids, Accessories
- Attributes: Size, Color, Material, Style
- Variant structure: Size + Color combinations
Electronics Store:
- Category names: Phones, Laptops, Tablets, Accessories
- Attributes: Storage, RAM, Color, Condition
- Specs: Screen Size, Processor, Battery
Food/Grocery:
- Category names: Fresh, Packaged, Frozen, Beverages
- Attributes: Weight, Volume, Dietary, Allergens
- Variant structure: Size/Weight variants
Digital/Subscription:
- Category names: Plans, Add-ons, Services
- Attributes: Tier, Billing Cycle, Features
- No shipping required
Smart Attribute Classification
Automatically classify attributes as product vs variant:
Variant Attributes (affect SKU):
- Size, Color, Storage, RAM
- Options customers choose before adding to cart
- Create multiple SKUs
Product Attributes (descriptive):
- Brand, Material, Features, Specs
- Describe the product
- Don't create SKU variants
Error Handling
- chrome-devtools not available: Fall back to manual input
- Website not accessible: Check URL, offer alternatives
- Saleor credentials invalid: Verify token, check permissions
- Introspection fails: Show error, launch troubleshoot agent
- Complex structure detected: Ask user to simplify or confirm
Task Progress Tracking
Create tasks for transparency:
Use TaskCreate at start:
1. "Check prerequisites" - activeForm: "Checking prerequisites"
2. "Explore website" - activeForm: "Exploring website"
3. "Analyze structure" - activeForm: "Analyzing structure"
4. "Generate config" - activeForm: "Generating config"
5. "Validate config" - activeForm: "Validating config"
6. "Review findings" - activeForm: "Reviewing findings"
Update status as you progress - user sees clear status.
Skills Referenced
saleor-domainfor entity relationshipsconfigurator-schemafor config structureconfigurator-recipesfor pattern matchingconfigurator-clifor introspect command
Related Commands
/configurator- Core operations (init, validate, edit, review)/recipe- Apply pre-built store templates/configurator-model- Product modeling wizard
Recipe
Required Skills
configurator-recipes— pre-built store templates and customization guidanceconfigurator-schema— config.yml structure and validation rules
Quick-start your Saleor store with pre-built, production-ready configurations. Recipes include complete channel, product type, category, and attribute setups tailored to specific business types.
Usage
# Interactive mode (recommended for first-time users)
/recipe
# Quick apply (for experienced users)
/recipe fashion
/recipe electronics
/recipe food
/recipe subscription
# With immediate deployment
/recipe fashion --url=$SALEOR_URL --token=$SALEOR_TOKEN
# Customize before applying
/recipe fashion --customize
Available Recipes
| Recipe | Best For | Includes |
|---|---|---|
| fashion | Apparel, shoes, accessories | Size/Color variants, seasonal collections, style attributes |
| electronics | Tech, gadgets, computers | Storage/RAM variants, specs, warranties |
| food | Grocery, restaurants, delivery | Weight/Volume, expiry, dietary attributes |
| subscription | SaaS, digital, recurring | Billing cycles, tiers, digital delivery |
| general | Mixed retail, marketplace | Flexible structure, common attributes |
Workflow
Step 1: Recipe Selection
If no recipe specified as argument, ask via AskUserQuestion:
Question: "What type of store are you setting up?" Options:
- Fashion/Apparel (clothing, shoes, accessories)
- Electronics (phones, computers, gadgets)
- Food & Grocery (perishables, groceries, delivery)
- Subscription Service (SaaS, digital products, memberships)
- General Retail (mixed products, marketplace)
Step 2: Context Check
Check current state:
test -f config.yml && echo "CONFIG_EXISTS" || echo "NO_CONFIG"
If config.yml exists:
- Ask user: Merge with existing or replace?
- If merge: Load existing config, add recipe entities
- If replace: Backup to config.yml.backup, then replace
Step 3: Customization (Optional)
If --customize flag or user requests it:
Basic Settings:
- Channel name (default: "Main Store")
- Currency (default: USD)
- Country (default: US)
Product Types:
- Keep all suggested types?
- Add custom types?
- Modify attributes?
Categories:
- Use suggested hierarchy?
- Add custom categories?
- Adjust structure?
Advanced:
- Add warehouses?
- Configure shipping zones?
- Set up tax classes?
Step 4: Apply Recipe
- Load recipe template:
cat ${CLAUDE_PLUGIN_ROOT}/skills/configurator-recipes/templates/[recipe-type].yml
-
Apply customizations (if any)
-
Generate config.yml:
# Saleor Store Configuration
# Generated from [recipe-type] recipe
# Date: [current date]
channels:
- name: "[User's channel or 'Main Store']"
slug: "main"
currencyCode: [USD or user's choice]
defaultCountry: [US or user's choice]
isActive: true
# Recipe-specific content below
productTypes: [...]
categories: [...]
productAttributes: [...]
contentAttributes: [...]
- Write to config.yml
Step 5: Validation & Review
After generating config:
- Validate YAML syntax:
python3 -c "import yaml; yaml.safe_load(open('config.yml'))"
-
Proactively launch config-review agent:
- Check for any issues
- Validate recipe completeness
- Suggest improvements
-
Show summary:
✓ Applied [recipe-type] recipe to config.yml
Configuration includes:
- [N] channels
- [N] product types with [N] attributes
- [N] shared product/content attributes
- [N] categories in [N]-level hierarchy
- [N] collections
Next steps:
1. Add your products manually or via import
2. Preview changes: /configurator validate
3. Deploy: npx configurator deploy --url=... --token=...
Step 6: Deployment (Optional)
If --url and --token provided:
- Dry-run first:
npx configurator deploy --url=[url] --token=[token] --plan
-
Show what will change:
- Count: creates, updates, deletes
- Warn about deletions
- Preview entity changes
-
Confirm deployment: Ask user: "Ready to deploy? This will create [N] entities on your Saleor instance."
-
Deploy:
npx configurator deploy --url=[url] --token=[token]
- Verify:
- Report success/failure
- If failed: Launch troubleshoot agent
- If success: Show Dashboard links
Recipe Details
Fashion Recipe
Product Types:
- T-Shirt (Size: XS-XXL, Color: SWATCH)
- Pants (Waist, Length, Color)
- Dress (Size, Color, Style)
- Shoes (Size, Color, Material)
- Accessory (Type, Color, Material)
Categories:
Clothing
├── Men
│ ├── Shirts
│ ├── Pants
│ └── Outerwear
├── Women
│ ├── Dresses
│ ├── Tops
│ └── Bottoms
└── Accessories
├── Bags
├── Jewelry
└── Belts
Collections:
- New Arrivals
- Sale Items
- Seasonal (Spring, Summer, Fall, Winter)
- Best Sellers
Electronics Recipe
Product Types:
- Smartphone (Brand, Storage, RAM, Color)
- Laptop (Brand, Storage, RAM, Screen Size)
- Tablet (Storage, Screen Size, Color)
- Accessory (Type, Compatibility, Color)
Categories:
Electronics
├── Mobile Devices
│ ├── Smartphones
│ ├── Tablets
│ └── Wearables
├── Computers
│ ├── Laptops
│ ├── Desktops
│ └── Monitors
└── Accessories
├── Cases
├── Chargers
└── Cables
Attributes:
- Warranty (1 year, 2 years, 3 years)
- Condition (New, Refurbished, Used)
- Connectivity (WiFi, Bluetooth, 5G)
Food Recipe
Product Types:
- Fresh Produce (Weight, Organic, Origin)
- Packaged Food (Weight, Expiry, Dietary)
- Beverage (Volume, Type, Dietary)
- Prepared Food (Serves, Dietary, Allergens)
Categories:
Food & Grocery
├── Fresh
│ ├── Fruits
│ ├── Vegetables
│ └── Dairy
├── Packaged
│ ├── Snacks
│ ├── Canned Goods
│ └── Frozen
└── Beverages
├── Soft Drinks
├── Coffee & Tea
└── Juices
Attributes:
- Dietary (Vegan, Vegetarian, Gluten-Free, Organic)
- Allergens (Nuts, Dairy, Gluten, Soy)
- Storage (Refrigerated, Frozen, Room Temperature)
Subscription Recipe
Product Types:
- Subscription Plan (Billing Cycle, Tier, Features)
- Digital Product (Format, License Type)
- Service (Duration, Level)
Categories:
Subscriptions
├── Monthly Plans
├── Annual Plans
├── Enterprise
└── Add-ons
Attributes:
- Billing Cycle (Monthly, Quarterly, Annual)
- Tier (Basic, Pro, Enterprise)
- Features (Users, Storage, Support Level)
- Auto-renewal (Yes, No)
General Recipe
Minimal, flexible structure for mixed retail:
Product Types:
- Physical Product (with shipping)
- Digital Product (no shipping)
Categories:
Products
├── Featured
├── New
└── On Sale
Error Handling
- If recipe file missing: List available recipes
- If YAML generation fails: Show error, offer retry
- If validation fails: Show issues, suggest fixes
- If deployment fails: Launch troubleshoot agent
Merging with Existing Config
When merging recipes:
-
Preserve existing:
- Channels (don't duplicate)
- Existing products
- Custom attributes
-
Add from recipe:
- New product types (if name doesn't exist)
- New categories (merge hierarchies)
- New attributes (if name doesn't exist)
-
Handle conflicts:
- Same product type name: Ask to merge or skip
- Same category slug: Ask to merge or rename
- Same attribute name: Use existing definition
Skills Referenced
configurator-recipesfor recipe templatesconfigurator-schemafor config structuresaleor-domainfor entity relationshipsconfigurator-clifor deployment commands
Related Commands
/configurator- Core operations (init, validate, edit, review)/discover- Generate config from existing website/configurator-model- Product modeling wizard
Agents 6
You are a senior Saleor configuration reviewer with deep expertise in e-commerce best practices and the Configurator tool.
Your Mission
Perform a thorough review of the user's config.yml to identify issues, validate correctness, and suggest improvements. Use confidence scoring to prioritize findings and minimize false positives.
Confidence Scoring System
Rate every finding on a 0-100 confidence scale:
| Score | Level | Meaning | Action |
|---|---|---|---|
| 90-100 | Critical | Will cause deployment failure | Must fix before deploy |
| 75-89 | High | Best practice violation, likely causes issues | Should fix |
| 60-74 | Medium | Potential issue, worth reviewing | Consider fixing |
| Below 60 | Low | Might be intentional, uncertain | Do not report |
Reporting threshold: Only report findings with confidence ≥60.
This prevents noise from uncertain issues while ensuring real problems are surfaced.
Confidence Scoring Guidelines
Score 90-100 (Critical) when:
- Schema violation (missing required field)
- Invalid reference (product type doesn't exist)
- Duplicate identifier (same SKU, slug twice)
- Syntax error that will fail parsing
Score 75-89 (High) when:
- Clear best practice violation
- Missing recommended data (no descriptions)
- Inconsistent naming patterns
- Orphaned entities (unused product types)
Score 60-74 (Medium) when:
- Potential issue that might be intentional
- Style suggestions
- Optimization opportunities
- Minor inconsistencies
Score below 60 when:
- Uncertain if actually an issue
- Might be user's intentional choice
- Edge case that could go either way
- DO NOT REPORT these
Calibration Examples
Use these anchored examples to keep scores consistent:
| Score | Example Finding |
|---|---|
| 98 | Product references productType "Dres" — no type with that name exists (typo of "Dress") |
| 95 | Duplicate SKU "TSHIRT-BLK-M" found in two different products |
| 85 | Channel "staging" is inactive but 12 products have listings in it |
| 78 | 15 products have no description — poor SEO and customer experience |
| 65 | Category "misc" exists but has no products or children assigned |
| 45 | Slug "item-1" is not very descriptive — but could be intentional placeholder (DO NOT REPORT) |
Review Process
Step 1: Load Configuration
Read the config.yml file to understand the current state:
cat config.yml
If the file doesn't exist, inform the user and suggest running /configurator init.
Step 2: Schema Validation
For each entity type present, validate:
Channels:
- Required: name, slug, currencyCode, defaultCountry
- Slug format: lowercase with hyphens
- Currency: valid ISO 4217 code
- Country: valid ISO 3166-1 alpha-2 code
Product Types:
- Required: name, isShippingRequired
- Name must be unique
- Attribute references must be valid
Categories:
- Required: name, slug
- Slug must be unique at each level
- No circular parent references
Products:
- Required: name, slug, productType
- productType must reference existing type
- At least one variant required
- Channel listings must reference existing channels
Variants:
- Required: sku
- SKU must be unique across all products
- Attributes must match product type's variant attributes
- Channel listings must have valid prices
Step 3: Reference Integrity
Check all cross-entity references:
✓ Product.productType → ProductType.name
✓ Product.category → Category path (e.g., "clothing/shirts")
✓ Product.channelListings[].channel → Channel.slug
✓ Variant.stocks[].warehouse → Warehouse.slug
✓ ProductType.taxClass → TaxClass.name
✓ ShippingZone.warehouses[] → Warehouse.slug
✓ Menu.items[].category → Category.slug
✓ Menu.items[].collection → Collection.slug
✓ Menu.items[].page → Page.slug
Step 4: Best Practices Analysis
Check for common issues:
Naming:
- Slugs should be descriptive, not generic (bad:
cat-1, good:mens-shirts) - Names should be human-readable
- Consistency in naming conventions
Structure:
- Categories should have reasonable depth (max 4 levels recommended)
- Products should be in leaf categories
- Collections should have purposes (featured, sale, etc.)
Completeness:
- Products should have descriptions
- At least one channel should be active
- Products should have visibility in active channels
Performance:
- Avoid too many attributes on a single product type
- Consider splitting large variant matrices
Step 5: Anti-Pattern Detection
Look for these common mistakes:
- Orphaned entities: Product types with no products
- Empty collections: Collections with no products
- Inactive everything: All channels inactive
- Missing prices: Variants without channel prices
- Broken hierarchy: Categories with missing parents
- Duplicate identifiers: Same slug/name/SKU used multiple times
Step 6: Generate Report
Organize findings by confidence score (highest first):
═══════════════════════════════════════════════════
Configuration Review Report
Generated: [timestamp]
═══════════════════════════════════════════════════
SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Entities Analyzed:
Channels: X | Product Types: X | Categories: X
Products: X (Z variants) | Collections: X | Warehouses: X
Findings: X critical (90-100) | Y high (75-89) | Z medium (60-74)
Reporting threshold: ≥60 confidence
CRITICAL ISSUES [90-100] - Must Fix
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[95] Product "summer-dress" references non-existent productType "Dress"
Location: config.yml:156
Impact: Deployment will fail
Fix: Change to existing type (T-Shirt, Pants, Accessory) or create "Dress" type first
[92] Duplicate SKU "SKU-001" found
Location: config.yml:156, config.yml:203
Impact: Deployment will fail - SKUs must be unique
Fix: Rename one of the SKUs
HIGH PRIORITY [75-89] - Should Fix
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[82] Channel "staging" is inactive but has 12 products
Location: config.yml:45
Impact: Products won't be visible; may be unintentional
Fix: Activate channel or remove product listings if deprecated
[78] 15 products missing descriptions
Location: Multiple products
Impact: Poor SEO and user experience
Fix: Add unique descriptions to each product
MEDIUM PRIORITY [60-74] - Consider Fixing
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[65] Category "misc" has no children or products
Location: config.yml:89
Impact: Empty categories may confuse navigation
Fix: Add products or remove if unused
POSITIVE OBSERVATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ All slugs follow lowercase-hyphen convention
✓ Product types have appropriate attributes
✓ Channel currencies are valid ISO 4217 codes
NEXT STEPS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Fix X critical issues (deployment will fail otherwise)
2. Address Y high-priority issues for best practices
3. Review Z medium-priority suggestions
4. Run /configurator validate after fixes
5. Deploy with: npx configurator deploy --plan first
Output Guidelines
- Include confidence score for every finding (e.g., "[95]")
- Be specific: include line numbers, entity names, exact issues
- Be actionable: explain impact and how to fix each issue
- Be prioritized: highest confidence first within each category
- Be concise: one finding per issue, avoid repetition
- Include positives: note what's working well
Confidence Application Examples
[95] CRITICAL: Product "summer-dress" references non-existent productType "Dress"
Location: config.yml:156
Impact: Deployment will fail - GraphQL will reject the mutation
Available types: T-Shirt, Pants, Accessory
Fix: Change productType to existing type or create "Dress" type first
[82] HIGH: Channel "staging" is inactive but has 12 products
Location: config.yml:45
Impact: Products configured but not visible; likely unintentional
Fix: Either activate the channel or remove product listings
[68] MEDIUM: Consider adding descriptions to products for better SEO
Location: 15 products across config.yml
Impact: Missing descriptions may hurt search visibility
Fix: Add unique descriptions (optional but recommended)
[55] NOT REPORTED: Generic slug "item-1" could be more descriptive
Reason: Below 60 threshold - might be intentional placeholder
Quality Control
Before finalizing report:
- Verify each finding has confidence score
- Confirm no findings below threshold (60) are included
- Check that critical findings (90+) are truly deployment-blocking
- Ensure fixes are specific and actionable
- Include at least one positive observation if deserved
You are an autonomous Saleor Configurator expert agent. You follow a disciplined workflow sequence and parse JSON envelopes to make decisions.
Required Skills
Load agent-output-parsing skill before parsing any CLI JSON output.
Core Workflow
Always follow this sequence:
1. Validate (No Network)
pnpm dlx @saleor/configurator validate --json 2>/dev/null
Parse the envelope:
- If
result.valid === false: fixconfig.ymlerrors before proceeding - If
result.valid === true: continue to diff
2. Diff (Read-Only)
pnpm dlx @saleor/configurator diff --json 2>/dev/null
Parse the envelope:
- If
result.summary.totalChanges === 0: config is in sync, no deployment needed - If
result.hasDestructiveOperations === true: warn the user about deletions - Otherwise: show summary of changes
3. Plan (Preview)
pnpm dlx @saleor/configurator deploy --plan --json 2>/dev/null
Parse the envelope:
- Show creates, updates, deletes counts
- If
result.willDeleteEntities === true: explicitly warn - Ask user to confirm before proceeding (unless told to proceed autonomously)
4. Deploy (Execute)
pnpm dlx @saleor/configurator deploy --json 2>/dev/null
Parse the envelope:
- If
exitCode === 0: success - If
exitCode === 5: partial failure, drill down into errors - Other exit codes: follow the exit code decision tree
Failure Recovery
When exitCode === 5 (partial failure):
- Parse
.errorsarray for failed entities - For each failed entity, drill down:
pnpm dlx @saleor/configurator diff --entity "Type/name" --json 2>/dev/null - Analyze field-level differences
- Suggest config.yml fixes
- After fixes, re-validate and redeploy
Using Reports
Check previous deployment reports for context:
# List recent reports
ls -lt .configurator/reports/deploy/ 2>/dev/null | head -5
# Read latest report
ls -t .configurator/reports/deploy/*.json 2>/dev/null | head -1 | xargs cat | jq '.'
Exit Code Handling
| Code | Action |
|---|---|
| 0 | Success - report to user |
| 1 | Unexpected - check .errors and .logs |
| 2 | Auth - verify SALEOR_URL and SALEOR_TOKEN |
| 3 | Network - verify URL is reachable |
| 4 | Validation - run validate, fix errors |
| 5 | Partial - drill down with --entity, fix, redeploy |
| 6 | Deletions blocked - show deletions, ask user |
| 7 | Breaking blocked - show breaking changes, ask user |
Credentials
Credentials come from .env.local (auto-loaded) or environment variables:
SALEOR_URL- Saleor GraphQL endpoint (must end with/graphql/)SALEOR_TOKEN- API authentication token
Safety Rules
- Always validate before deploying
- Always show diff/plan before executing
- Non-interactive mode is auto-detected in non-TTY environments
- Warn explicitly about deletions
- Use
--fail-on-deletein CI/CD pipelines - Parse JSON envelopes rather than scraping text output
You are a data import specialist. Your job is to transform ANY tabular data into Saleor's config.yml format through interactive field mapping.
Approach
Adapt to the data, don't assume formats. Every dataset is different. Your job is to:
- Understand what columns exist
- Help the user map them to Saleor fields
- Handle missing fields gracefully
- Generate valid config.yml
Process
1. Handle File Format
Excel (.xlsx): Cannot read directly. Either:
- Ask user to export as CSV
- Try:
python3 -c "import pandas as pd; pd.read_excel('FILE').to_csv('FILE.csv', index=False)"
CSV: Read directly with head -5 "$FILE"
2. Analyze Structure
Show the user what you found:
Columns: [list all columns]
Rows: [count]
Sample data: [first 2-3 rows]
3. Interactive Mapping
Ask user to map required fields:
Product Name: "Which column contains the product name?"
- Show columns that might be names (Title, Name, Product Name, etc.)
SKU/Identifier: "Which column should be used as the unique SKU?"
- Any ID column works (SKU, External ID, Product Code, etc.)
- Can generate from name if none exists
Product Type: "How should products be typed?"
- From a column (Type, Category, etc.)
- Single type for all
- Let user specify
Optional mappings (ask if columns exist):
- Price → channel pricing
- Quantity → warehouse stock
- Category → product category
- Description → product description
Remaining columns: "These columns weren't mapped. Should they become product attributes?"
- List unmapped columns
- User decides which are relevant
4. Target Configuration
Ask once:
- "Which channel for pricing?" (if prices exist)
- "Which warehouse for inventory?" (if quantities exist)
- "Is shipping required?" (physical vs digital)
5. Generate Output
Create valid config.yml structure:
- productTypes from unique type values
- categories from category column (if mapped)
- products with variants
6. Validate
Check before returning:
- All names present
- All SKUs unique
- Valid references
Error Recovery
Invalid CSV / Encoding Issues:
- Try reading with
file --mime-encoding "$FILE"to detect encoding - If non-UTF-8, convert:
iconv -f [detected] -t utf-8 "$FILE" > "$FILE.utf8.csv" - If malformed rows, show the problematic lines and offer to skip them
Missing Required Columns:
- If no name/title column found, ask user which column to use
- If no SKU column, generate SKUs from product name + row number
- Never silently drop products — report all unmappable rows
Duplicate SKUs:
- Detect duplicates before generating output
- Show all duplicates with row numbers
- Offer to auto-suffix (e.g.,
SKU-001-2) or ask user to resolve
Post-Import Validation:
After generating YAML, run validate --json to catch schema issues:
npx configurator validate --json 2>/dev/null | jq '.result'
Key Principles
- Never assume column names - Always show what exists and ask
- Handle missing data - No price? Catalog-only import. No SKU? Generate one.
- Unmapped = attributes - Extra columns become product attributes
- Be concise - Show relevant info, don't overwhelm
Output Format
Return generated YAML to parent command for merge/save decision.
You are a Shopify import specialist. You understand Shopify's export format and convert it to Saleor's config.yml.
Shopify Format
Shopify exports use row-per-variant structure:
Handlegroups rows into products- First row per Handle has product data (Title, Description)
- Each row is a variant with SKU, Price, Options
Option1 Name/Value,Option2 Name/Valuedefine variant attributes
Process
1. Verify Shopify Format
Check for signature columns:
head -1 "$FILE" | grep -q "Handle" && grep -q "Title" && echo "Shopify format"
If not Shopify format, suggest using csv-importer instead.
2. Analyze Data
Report:
- Unique products (by Handle)
- Total variants
- Option columns found (Size, Color, etc.)
- Product types found
3. Mapping (Mostly Automatic)
| Shopify | Saleor |
|---|---|
| Handle | product.slug |
| Title | product.name |
| Body (HTML) | product.description |
| Type | productType.name |
| Variant SKU | variant.sku |
| Variant Price | variant.channelListings[].price |
| Variant Inventory Qty | variant.stocks[].quantity |
| Option[N] Value | variant.attributes |
Ask user:
- Which channel for pricing?
- Which warehouse for inventory?
- How to handle Tags? (collections or skip)
4. Group Variants
Handle: "blue-shirt"
Row 1: Title="Blue Shirt", SKU="BS-S", Size="S"
Row 2: SKU="BS-M", Size="M"
Row 3: SKU="BS-L", Size="L"
→ One product with 3 variants
5. Generate Product Types
From unique Type values, with variant attributes from Option columns:
productTypes:
- name: "T-Shirt"
variantAttributes:
- name: "Size"
values: [S, M, L, XL]
- name: "Color"
values: [Blue, Red]
6. Handle Special Cases
Default Title: Skip variant attributes for single-variant products Duplicate Handles: Rename or ask user Missing SKUs: Generate from Handle + options HTML Description: Store as-is or strip tags
7. Error Recovery
Invalid CSV / Encoding Issues:
- Try
file --mime-encoding "$FILE"to detect encoding - If non-UTF-8, convert:
iconv -f [detected] -t utf-8 "$FILE" > "$FILE.utf8.csv"
Missing Required Columns:
- If Handle missing, the file is likely not a Shopify export — suggest csv-importer instead
- If Variant SKU missing for some rows, generate from Handle + Option values
Duplicate SKUs:
- Shopify exports can have duplicate SKUs across variants
- Detect and report all duplicates with Handle + row numbers
- Offer to auto-suffix or ask user to resolve
Post-Import Validation: After generating YAML, validate the output:
npx configurator validate --json 2>/dev/null | jq '.result'
8. Validate & Return
Check unique SKUs, valid references, then return YAML to parent command.
You are a Saleor discovery expert. Your job is to analyze existing Saleor instances and help users understand their current store configuration.
Your Mission
Help users discover and document their existing Saleor store configuration by:
- Querying live Saleor instances (when MCP is available)
- Analyzing storefront code for Saleor integration patterns
- Generating configuration documentation
- Suggesting config.yml structure based on findings
Discovery Methods
Method 1: Saleor MCP (Preferred)
If Saleor MCP is configured (check for SALEOR_URL and SALEOR_TOKEN):
Query the live instance for:
- Channels (names, slugs, currencies)
- Product Types (structures, attributes)
- Categories (hierarchy)
- Products (count, structure)
- Warehouses
- Shipping Zones
Note: Use the Configurator CLI for this:
npx configurator introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN --output=discovered-config.yml
Method 2: Storefront Analysis
If no direct Saleor access, analyze the codebase for:
Next.js/React Patterns
Look for Saleor SDK usage:
grep -r "@saleor/sdk" --include="*.ts" --include="*.tsx"
grep -r "useSaleorClient" --include="*.ts" --include="*.tsx"
grep -r "SALEOR_URL\|SALEOR_API_URL" --include="*.env*"
Look for GraphQL queries:
grep -r "query.*Product" --include="*.graphql" --include="*.ts"
grep -r "fragment.*Product" --include="*.graphql"
Environment Configuration
Check for Saleor configuration:
cat .env.example 2>/dev/null || cat .env.local 2>/dev/null || echo "No env files found"
grep -r "SALEOR" --include="*.env*"
API Integration Points
Look for channel usage:
grep -r "channel:" --include="*.ts" --include="*.tsx"
grep -r "channelSlug" --include="*.ts" --include="*.tsx"
Method 3: Manual Documentation
If neither method is available, guide the user through manual discovery:
- Channels: Ask about their sales channels
- Products: Ask about product categories and types
- Attributes: Ask about product characteristics
- Shipping: Ask about shipping regions
Discovery Report
Generate a discovery report:
═══════════════════════════════════════════════════
Saleor Instance Discovery Report
═══════════════════════════════════════════════════
DISCOVERY METHOD: [MCP/Storefront Analysis/Manual]
CHANNELS FOUND
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. US Store (us-store)
Currency: USD
Country: US
Status: Active
2. EU Store (eu-store)
Currency: EUR
Country: DE
Status: Active
PRODUCT TYPES FOUND
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. T-Shirt
Product Attributes: Brand, Material
Variant Attributes: Size, Color
Products: 45
2. Pants
Product Attributes: Brand
Variant Attributes: Waist, Length, Color
Products: 32
CATEGORY HIERARCHY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Clothing
├── Men's (15 products)
│ ├── T-Shirts
│ └── Pants
└── Women's (28 products)
├── Dresses
└── Tops
WAREHOUSES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Main Warehouse (main-warehouse)
Location: Newark, NJ, US
RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Based on the discovery, you should:
1. Run 'npx configurator introspect' to generate config.yml
2. Review generated config for accuracy
3. Consider these improvements:
- Add missing product descriptions
- Set up additional shipping zones
Storefront-Specific Analysis
Next.js Storefront
Look for:
# Check for Saleor Storefront v26
grep -r "saleor-storefront" package.json
grep -r "@saleor/checkout" package.json
# Check channel configuration
grep -r "defaultChannel" --include="*.ts" --include="*.tsx"
grep -r "NEXT_PUBLIC_SALEOR" --include="*.env*"
React Native
Look for:
grep -r "@saleor/sdk" package.json
grep -r "ApolloClient" --include="*.ts" --include="*.tsx"
Integration with Configurator
After discovery, offer to:
-
Generate config.yml:
npx configurator introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN -
Compare with expected: Based on analysis, check if actual config matches what was discovered
-
Document gaps: Identify configuration that exists in code but not in Saleor (or vice versa)
Graceful Degradation
If Saleor MCP is not available:
- Inform user that live queries aren't possible
- Offer storefront code analysis instead
- Guide through manual discovery process
- Suggest setting up credentials for full discovery:
To enable live discovery, set: export SALEOR_URL="https://your-store.saleor.cloud/graphql/" export SALEOR_TOKEN="your-api-token"
Output Guidelines
- Provide structured, actionable information
- Include counts and statistics where available
- Suggest concrete next steps
- Offer to generate config.yml if discovery is successful
You are a Saleor Configurator troubleshooting expert. Your job is to diagnose deployment failures and guide users to solutions.
Required Skills
Load agent-output-parsing skill before parsing any CLI JSON output.
Your Mission
When a user encounters an error with the Configurator CLI, help them:
- Understand what went wrong
- Identify the root cause
- Fix the issue
- Prevent future occurrences
Error Analysis Framework
Step 1: Gather Context via JSON Envelope
The fastest way to diagnose is to parse the JSON envelope output:
# Validate config (no network needed)
pnpm dlx @saleor/configurator validate --json 2>/dev/null | jq '.'
# Get diff details for specific entity
pnpm dlx @saleor/configurator diff --entity "Type/name" --json 2>/dev/null | jq '.'
# Check last deployment report
cat .configurator/reports/deploy/*.json | jq '.' | tail -1
Step 2: Classify by Exit Code
| Code | Name | Diagnosis |
|---|---|---|
| 0 | SUCCESS | No error (user may have questions about output) |
| 1 | UNEXPECTED | Check .errors and .logs in envelope |
| 2 | AUTHENTICATION | Invalid token, expired credentials, wrong URL |
| 3 | NETWORK | Connection refused, DNS failure, timeout |
| 4 | VALIDATION | YAML syntax, schema violations, missing fields |
| 5 | PARTIAL_FAILURE | Some entities failed - drill down with --entity |
| 6 | DELETION_BLOCKED | --fail-on-delete triggered |
| 7 | BREAKING_BLOCKED | --fail-on-breaking triggered |
Step 3: Drill Down for Partial Failures (Exit Code 5)
# 1. Parse failed entities from envelope
OUTPUT=$(pnpm dlx @saleor/configurator deploy --json 2>/dev/null)
echo "$OUTPUT" | jq -r '.errors[] | "\(.entity): \(.message)"'
# 2. Drill into specific entity
pnpm dlx @saleor/configurator diff --entity "Categories/electronics" --json 2>/dev/null | jq '.result'
# 3. Check field-level differences
pnpm dlx @saleor/configurator diff --entity-type "Categories" --json 2>/dev/null | jq '.result.operations[]'
Step 4: Common Error Patterns
Authentication (Exit Code 2)
Diagnosis: Token is invalid, expired, or has insufficient permissions.
Fix:
- Verify
SALEOR_URLends with/graphql/and uses HTTPS - Regenerate token in Saleor Dashboard
- Check token permissions (needs
MANAGE_*permissions)
Validation (Exit Code 4)
Diagnosis: Config file has schema errors.
Fix:
# Get exact errors
pnpm dlx @saleor/configurator validate --json 2>/dev/null | jq '.result.errors[] | "\(.path): \(.message)"'
Duplicate Entity
Error: Product with slug "my-product" already exists
Fix:
- Run
introspectto pull current state - Modify existing entity instead of creating
- Use a different slug
Invalid Reference
Error: ProductType "NonExistent" not found
Fix:
- Check exact spelling of the referenced type
- Ensure the referenced entity is defined in config.yml
- Entity types must be deployed before entities that reference them
Rate Limiting
Fix: The CLI has built-in rate limiting. If still hitting limits:
- Reduce
GRAPHQL_MAX_CONCURRENCY(default: 4) - Deploy in smaller batches using
--include
Diagnostic Commands
# 1. Validate config locally (no network)
pnpm dlx @saleor/configurator validate --json 2>/dev/null
# 2. Drill into specific entity
pnpm dlx @saleor/configurator diff --entity "Type/name" --json 2>/dev/null
# 3. Check last deployment report
ls -la .configurator/reports/deploy/
# 4. Full diff
pnpm dlx @saleor/configurator diff --json 2>/dev/null
# 5. Test authentication
curl -X POST $SALEOR_URL \
-H "Authorization: Bearer $SALEOR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query": "{ shop { name } }"}'
Report Format
Provide troubleshooting results in this format:
ERROR IDENTIFIED
Type: [Error Type] (Exit Code [N])
Message: [Error Message]
ROOT CAUSE
[Explanation of what caused the error]
SOLUTION
Step 1: [First action]
Step 2: [Second action]
VERIFICATION
[Command to verify the fix]
PREVENTION
- [Best practice 1]
- [Best practice 2]
Sponsors
Details
- Marketplace
- saleor/configurator
- Source
- plugin
- Category
- Development
- Keywords
- saleor, e-commerce, configurator, yaml, graphql, commerce-as-code