saleor avatar

saleor-configurator

AI-powered Saleor e-commerce configuration through natural language

version
2.1.0
GitHub stars
30

Install

/plugin install saleor-configurator@saleor-configurator

Run it inside Claude Code after adding the marketplace with /plugin marketplace add saleor/configurator.

Contents

Discovered from source

Skills 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" }
  ]
}
FieldTypeDescription
commandstringCommand name (validate, diff, deploy, introspect)
versionstringCLI version
exitCodenumberExit code (0-7)
resultobjectCommand-specific result data
logsarrayLog entries collected during execution
errorsarrayStructured 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 flags
  • configurator-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-modeling or configurator-schema instead

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

FlagCommandsDescription
--urldeploy, diff, introspectSaleor GraphQL endpoint URL
--tokendeploy, diff, introspectSaleor API authentication token
--jsonAllForce JSON envelope output
--textAllForce human-readable output
--drift-checkintrospectExit code 1 if remote differs from local
--includedeploy, diff, introspectComma-separated entity types to include
--excludedeploy, diff, introspectComma-separated entity types to exclude
--fail-on-deletedeployExit code 6 if deletions detected
--fail-on-breakingdeployExit code 7 if breaking changes detected
--plandeployShow plan without executing changes
--report-pathdeployCustom path for deployment report
--skip-mediadeploy, diffSkip media file comparison/upload
--entity-typediffFilter to one entity type
--entitydiffFilter 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

CodeMeaningAction
0SuccessOperation completed
1Unexpected errorCheck error message and logs
2Authentication errorVerify URL and token
3Network errorCheck connectivity
4Validation errorFix config.yml syntax/schema
5Partial failureSome operations failed, check errors array
6Deletion blocked--fail-on-delete triggered
7Breaking 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

MistakeFix
Deploying without previewing firstAlways run diff or deploy --plan before deploy
Wrong URL formatURL must end with /graphql/ (e.g., https://store.saleor.cloud/graphql/)
Expired or invalid tokenRegenerate your API token in Saleor Dashboard
Not using --drift-check for CI drift detectionUse introspect --drift-check to fail CI if remote config has drifted
Forgetting --fail-on-delete in CIPrevents accidental deletions
Using SALEOR_API_URLCorrect env var is SALEOR_URL

diff vs deploy --plan

diffdeploy --plan
PurposeShow field-level differences between local and remoteShow what operations deploy would execute
OutputPer-field changes (old → new values)Operation summary (creates, updates, deletes)
Scoping--entity-type, --entity for drill-downNo entity-level scoping
Use whenDebugging what changed, reviewing individual fieldsPre-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

Related Skills

  • configurator-schema - Config.yml structure and validation rules
  • saleor-domain - Entity relationships and Saleor concepts
  • agent-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-cli instead
  • When NOT designing custom product types -- use product-modeling instead

Available Recipes

RecipeBest ForKey Features
Fashion StoreApparel, shoes, accessoriesSize/color variants, seasonal collections, multi-currency
Electronics StoreTech products, gadgetsSpecs attributes, storage/RAM variants, warranty info
Subscription ServiceRecurring products, SaaSPlan 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:

  1. Rename channels to match your brand and regions
  2. Adjust currency and country codes for your markets
  3. Modify categories for your actual product catalog
  4. Add or remove product types you don't need
  5. Test on staging first before deploying to production

Common Mistakes

MistakeFix
Using a recipe without customizing identifiersUpdate all slugs and names to match your brand before deploying
Not adjusting currency/country codesChange currencyCode and defaultCountry to your actual markets
Deploying a recipe straight to productionAlways test on a staging instance first
Keeping entity types you don't needRemove unused product types, categories, etc. to keep your config clean
Forgetting to update channel referencesProducts 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:

  1. Header comment — recipe name, description, customization checklist
  2. At least one channel — with valid currency and country codes
  3. Product types — with product and variant attributes defined
  4. Categories — at least a basic hierarchy
  5. 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 rules
  • product-modeling - Product type design and attribute selection
  • saleor-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-modeling instead

Schema Concepts

Treat config.yml as four conceptual groups instead of memorizing a long top-level key list:

  1. Store foundations: shop, channels
  2. Catalog model: productAttributes, contentAttributes, productTypes, modelTypes/pageTypes
  3. Catalog data: categories/collections/products/models
  4. 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:

IdentifierEntity Types
slugchannels, categories, collections, products, warehouses, menus, models
nameproductTypes, 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

  1. Required fields -- each entity type has required fields (e.g., channels need name, slug, currencyCode)
  2. Unique identifiers -- slugs/names must be unique within their entity type
  3. Valid references -- cross-entity references must match (e.g., a product's productType must match a defined product type name)
  4. Currency codes -- valid ISO 4217 (USD, EUR, GBP, etc.)
  5. Country codes -- valid ISO 3166-1 alpha-2 (US, DE, GB, etc.)

Dependency Concepts

You usually model in this order:

  1. Foundations (shop, channels)
  2. Reusable types and attributes (productAttributes, contentAttributes, productTypes, modelTypes)
  3. Concrete catalog entities (categories, collections, products, models)
  4. Operational entities (warehouses, shippingZones, taxClasses, menus)

Configurator handles execution order, but this mental model helps diagnose missing-reference errors.

Common Mistakes

MistakeFix
Changing a slug or name to "rename" an entityThis creates a new entity. To rename, delete the old one and create new.
Duplicate slugs within an entity typeEach slug must be unique. Check for copy-paste errors.
Product references a nonexistent productTypeThe productType field must exactly match a name in your productTypes section.
Missing required fieldsCheck the error message -- it tells you which field is missing.
Products defined before their productTypeNot a YAML order issue (Configurator handles order), but the referenced type must exist in the file.

Best Practices

  1. Use meaningful slugs -- womens-summer-dresses not cat-123
  2. Consistent naming -- match display names to slugs when possible
  3. Comment complex sections -- use YAML comments for documentation
  4. 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 rules
  • configurator-cli - CLI commands for deploying configurations
  • product-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-schema instead
  • When NOT designing product types -- use product-modeling first

Core Workflow

  1. Detect format -- CSV, Excel, JSON, or unknown
  2. Extract columns -- read headers and sample data
  3. Map interactively -- you confirm field mappings
  4. Transform -- convert to Saleor schema
  5. 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:

  1. Show you all columns with sample values
  2. Ask which column maps to each Saleor field
  3. Mark unmapped columns as potential attributes

Required Fields

Saleor FieldTypical Source Columns
product.name"name", "title", or any descriptive column
product.slugGenerated from name, or "handle"/"ID" column
variant.sku"SKU", "External ID", "Code"
productType"type" column or you specify it

Optional Fields

FieldNotes
priceIf missing, imports as catalog-only
quantityIf missing, skips stock tracking
categoryFrom category/region column
descriptionIf present in source data
Other columnsBecome 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

MistakeFix
Assuming column names without checkingAlways inspect headers first -- column names vary wildly between sources
Not handling missing SKUsGenerate SKUs from product name + variant attributes, or use a unique ID column
Importing without validating firstReview the generated YAML before deploying -- check for duplicates and missing fields
Duplicate products from multi-row variantsEnsure rows sharing a product name are grouped as variants, not separate products
Forgetting to create product types firstDesign 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 techniques
  • references/field-mapping.md -- Mapping strategies for various data shapes
  • references/shopify-format.md -- Shopify-specific handling
  • references/transformations.md -- Data transformation rules

See Also

Related Skills

  • configurator-schema - Config.yml structure and field requirements
  • product-modeling - Product type design before importing
  • saleor-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-schema instead
  • When NOT looking for CLI commands -- use configurator-cli instead

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:

QuestionIf 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:

QuestionIf 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

AttributeProductVariantWhy
BrandxSame for all variants
SizexCreates separate SKUs
ColorxCreates separate SKUs
MaterialxUsually same for product
Storage (64GB/128GB)xDifferent prices
Care InstructionsxSame for all variants
WeightxMay 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 CountAssessmentRecommendation
1-10ManageableGood for most products
11-50ModerateFine for fashion, needs inventory planning
51-100HighConsider splitting into multiple products
100+Too manySimplify -- 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:

PatternProduct-Level AttrsVariant-Level AttrsTypical SKUs
ApparelBrand, Material, CareSize, Color30/product
ElectronicsBrand, Screen, Processor, FeaturesStorage, Color20/product
FurnitureBrand, Style, Capacity, DimensionsFabric, Color16/product
Food & BeverageOrigin, Roast, Flavor, CertificationsSize, Grind12/product
Digital ProductsPublisher, Platform, FeaturesLicense Type, Duration9/product

For complete YAML examples of each pattern, see references/industry-patterns.md.

Categories vs Collections

Both organize products, but they serve different purposes:

AspectCategoryCollection
StructureHierarchical (tree)Flat (list)
Assignment1 product = 1 category1 product = many collections
PurposeTaxonomy, navigationMerchandising, promotions
ExamplesElectronics > 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

  1. List all product characteristics -- write down every field/attribute
  2. Categorize each -- apply the decision framework (product vs variant)
  3. Select types -- use the attribute type decision tree
  4. Calculate SKU count -- ensure the variant matrix is manageable
  5. Write the YAML -- create the ProductType configuration
  6. Validate -- deploy with --plan to check structure

Common Mistakes

MistakeFix
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 fieldsIf it doesn't create a separate SKU (like Care Instructions), it's a product attribute
Product attributes that should varyIf value differs by size (e.g., Weight), move to variant level
Too many product typesReuse types when products share the same attribute structure
Skipping variant planningAlways calculate SKU count before creating product types

Additional Resources

Reference Files

Examples

  • examples/fashion-product-types.yml -- apparel product types
  • examples/electronics-product-types.yml -- tech product structures
  • examples/perfume-store-models.yml -- Models for custom entities
  • examples/navigation-structures.yml -- Menu configurations

Related Skills

  • configurator-schema - Complete YAML schema reference
  • saleor-domain - Entity relationships and Saleor concepts
  • configurator-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-modeling instead
  • When NOT writing YAML config -- use configurator-schema instead

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.

EntityIdentifierMutable?
Channel, Category, Collection, Product, Warehouse, Menu, PageslugNo -- creates new
ProductType, PageType, Attribute, TaxClass, ShippingZonenameNo -- 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 ManagesRuntime Only
Product structure and pricingOrders
Categories and collectionsCustomers
Attributes and channelsCheckouts
Warehouses and shipping zonesPayments
Tax classesWebhooks

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

MistakeFix
Confusing slug-based vs name-based entitiesCheck 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 existsProduct types must be defined first. Configurator handles deploy order, but the type must be in your config.
Not understanding channel scopeProducts 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

Related Skills

  • configurator-schema - Config.yml structure and validation rules
  • product-modeling - Product type design and attribute selection
  • configurator-cli - CLI commands for deploying configurations

Commands 6

Configurator Fix

Required Skills

  • configurator-schema — config.yml structure and valid field values
  • configurator-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-schema for valid field values
  • saleor-domain for entity relationships
  • configurator-cli for 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 strategies
  • configurator-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-importer agent
  • Generic CSV/Excel → Use csv-importer agent

4. Delegate to Agent

The agent will:

  1. Analyze columns and sample data
  2. Guide interactive field mapping
  3. Generate config.yml content
  4. 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 planning
  • saleor-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:

CharacteristicRecommended TypeReasoning
BrandDROPDOWNSingle choice from predefined list
SizeDROPDOWNSingle choice from sizes
ColorSWATCHVisual color selection
FeaturesMULTISELECTMultiple can apply
DescriptionRICH_TEXTLong formatted text
WeightNUMERICNumber with unit
Is OrganicBOOLEANYes/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 CountAssessment
1-10Manageable
11-50Moderate - requires inventory management
51-100High - 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:

  1. Create new config.yml with the productType
  2. Or add to existing config.yml (append to productTypes section)

Step 9: Next Steps

After generating the ProductType:

  1. 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"
    
  2. Suggest running /configurator validate to check the configuration

  3. 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:

  1. Identify the entity - What is it? (Brand, Ingredient, Profile)
  2. Define attributes - What fields does it need?
  3. Generate PageType - Create the schema
  4. Create Model instances - Add specific entries
  5. Link to Products - Use REFERENCE attribute

Model Decision Framework:

Use CaseUse ModelUse 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 types
  • reference/industry-patterns.md - 10+ industry patterns
  • reference/models-and-structures.md - Complete Models & Structures guide

Examples:

  • examples/fashion-product-types.yml
  • examples/electronics-product-types.yml
  • examples/perfume-store-models.yml - Models with REFERENCE attributes
  • examples/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 rules
  • configurator-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

  1. Check for existing config:
test -f config.yml && echo "CONFIG_EXISTS" || echo "NO_CONFIG"
  1. If exists, ask user:

    • Backup and replace (creates config.yml.backup)
    • Cancel initialization
  2. Copy skeleton template:

cp ${CLAUDE_PLUGIN_ROOT}/skills/configurator-recipes/templates/skeleton.yml config.yml
  1. 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.)
  2. Validate YAML syntax:

python3 -c "import yaml; yaml.safe_load(open('config.yml'))"
  1. 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 edit to fix issues
  • Run /configurator validate again

Operation: edit

Interactive menu for modifying existing configuration.

Main Menu

Present options via AskUserQuestion:

  1. Add new entity (product type, category, product, etc.)
  2. Modify existing entity
  3. Remove entity
  4. View configuration summary
  5. 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

  1. Select entity type
  2. List existing entities
  3. Select which one
  4. Show current values
  5. 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:

  1. Validate YAML syntax
  2. Check for broken references
  3. Suggest /configurator validate for full validation
  4. 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 init completes
  • /configurator edit makes changes
  • /recipe applies a template
  • /discover generates config

No Argument Behavior

If /configurator is called without arguments, show interactive menu:

Question: "What would you like to do with your configuration?" Options:

  1. Initialize new config.yml
  2. Validate existing config
  3. Edit configuration
  4. Review configuration
  5. View summary

Skills Referenced

  • configurator-cli for CLI commands
  • configurator-schema for config structure
  • saleor-domain for 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 rules
  • configurator-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:

  1. Explore existing website (requires URL)
  2. Introspect Saleor instance (requires credentials)
  3. 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:

  1. Get website URL:

    • Ask user for site URL
    • Validate URL format
    • Check if accessible
  2. 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]"}'
  1. 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 '{}'
  1. Explore category pages:

    • Navigate to main categories
    • Analyze product listings
    • Extract product structure
    • Identify filtering options (these become attributes)
  2. Analyze product pages:

    • Navigate to sample products
    • Extract product details
    • Identify variant options (size, color, etc.)
    • Note pricing structure
    • Check shipping info
  3. 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:

  1. Run introspect command:
npx configurator introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN
  1. Analyze generated config:

    • Count entities
    • Identify patterns
    • Note complexity
  2. Ask user about filtering:

    • Include all products or sample?
    • Include inactive entities?
    • Simplify or preserve full details?
  3. 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):

  1. Business Type:

    • What do you sell?
    • Physical or digital products?
    • Variants needed?
  2. Product Structure:

    • Main product categories?
    • How do products vary? (size, color, model, etc.)
    • Example products?
  3. Attributes:

    • What options do customers choose?
    • Which options change price/SKU?
    • Attribute types (dropdown, swatch, text)?
  4. 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:

  1. 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
  1. Ask for refinements:

    • "Does this structure match your business?"
    • "Any categories missing?"
    • "Should I add sample products?"
  2. Apply refinements

  3. Validate:

python3 -c "import yaml; yaml.safe_load(open('config.yml'))"
  1. 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 session
  • navigate_page - Navigate to URLs
  • take_screenshot - Capture page state
  • evaluate_script - Extract page data
  • list_pages - Manage browser tabs
  • close_page - Clean up

Graceful Fallback

If chrome-devtools not available:

  1. Inform user
  2. Explain benefits of using it
  3. Offer installation guide
  4. 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-domain for entity relationships
  • configurator-schema for config structure
  • configurator-recipes for pattern matching
  • configurator-cli for 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 guidance
  • configurator-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

RecipeBest ForIncludes
fashionApparel, shoes, accessoriesSize/Color variants, seasonal collections, style attributes
electronicsTech, gadgets, computersStorage/RAM variants, specs, warranties
foodGrocery, restaurants, deliveryWeight/Volume, expiry, dietary attributes
subscriptionSaaS, digital, recurringBilling cycles, tiers, digital delivery
generalMixed retail, marketplaceFlexible 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

  1. Load recipe template:
cat ${CLAUDE_PLUGIN_ROOT}/skills/configurator-recipes/templates/[recipe-type].yml
  1. Apply customizations (if any)

  2. 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: [...]
  1. Write to config.yml

Step 5: Validation & Review

After generating config:

  1. Validate YAML syntax:
python3 -c "import yaml; yaml.safe_load(open('config.yml'))"
  1. Proactively launch config-review agent:

    • Check for any issues
    • Validate recipe completeness
    • Suggest improvements
  2. 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:

  1. Dry-run first:
npx configurator deploy --url=[url] --token=[token] --plan
  1. Show what will change:

    • Count: creates, updates, deletes
    • Warn about deletions
    • Preview entity changes
  2. Confirm deployment: Ask user: "Ready to deploy? This will create [N] entities on your Saleor instance."

  3. Deploy:

npx configurator deploy --url=[url] --token=[token]
  1. 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:

  1. Preserve existing:

    • Channels (don't duplicate)
    • Existing products
    • Custom attributes
  2. Add from recipe:

    • New product types (if name doesn't exist)
    • New categories (merge hierarchies)
    • New attributes (if name doesn't exist)
  3. 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-recipes for recipe templates
  • configurator-schema for config structure
  • saleor-domain for entity relationships
  • configurator-cli for 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:

ScoreLevelMeaningAction
90-100CriticalWill cause deployment failureMust fix before deploy
75-89HighBest practice violation, likely causes issuesShould fix
60-74MediumPotential issue, worth reviewingConsider fixing
Below 60LowMight be intentional, uncertainDo 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:

ScoreExample Finding
98Product references productType "Dres" — no type with that name exists (typo of "Dress")
95Duplicate SKU "TSHIRT-BLK-M" found in two different products
85Channel "staging" is inactive but 12 products have listings in it
7815 products have no description — poor SEO and customer experience
65Category "misc" exists but has no products or children assigned
45Slug "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:

  1. Orphaned entities: Product types with no products
  2. Empty collections: Collections with no products
  3. Inactive everything: All channels inactive
  4. Missing prices: Variants without channel prices
  5. Broken hierarchy: Categories with missing parents
  6. 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:

  1. Verify each finding has confidence score
  2. Confirm no findings below threshold (60) are included
  3. Check that critical findings (90+) are truly deployment-blocking
  4. Ensure fixes are specific and actionable
  5. 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: fix config.yml errors 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):

  1. Parse .errors array for failed entities
  2. For each failed entity, drill down:
    pnpm dlx @saleor/configurator diff --entity "Type/name" --json 2>/dev/null
    
  3. Analyze field-level differences
  4. Suggest config.yml fixes
  5. 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

CodeAction
0Success - report to user
1Unexpected - check .errors and .logs
2Auth - verify SALEOR_URL and SALEOR_TOKEN
3Network - verify URL is reachable
4Validation - run validate, fix errors
5Partial - drill down with --entity, fix, redeploy
6Deletions blocked - show deletions, ask user
7Breaking 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-delete in 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:

  1. Understand what columns exist
  2. Help the user map them to Saleor fields
  3. Handle missing fields gracefully
  4. 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

  1. Never assume column names - Always show what exists and ask
  2. Handle missing data - No price? Catalog-only import. No SKU? Generate one.
  3. Unmapped = attributes - Extra columns become product attributes
  4. 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:

  • Handle groups 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/Value define 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)

ShopifySaleor
Handleproduct.slug
Titleproduct.name
Body (HTML)product.description
TypeproductType.name
Variant SKUvariant.sku
Variant Pricevariant.channelListings[].price
Variant Inventory Qtyvariant.stocks[].quantity
Option[N] Valuevariant.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:

  1. Querying live Saleor instances (when MCP is available)
  2. Analyzing storefront code for Saleor integration patterns
  3. Generating configuration documentation
  4. 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:

  1. Channels: Ask about their sales channels
  2. Products: Ask about product categories and types
  3. Attributes: Ask about product characteristics
  4. 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:

  1. Generate config.yml:

    npx configurator introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN
    
  2. Compare with expected: Based on analysis, check if actual config matches what was discovered

  3. Document gaps: Identify configuration that exists in code but not in Saleor (or vice versa)

Graceful Degradation

If Saleor MCP is not available:

  1. Inform user that live queries aren't possible
  2. Offer storefront code analysis instead
  3. Guide through manual discovery process
  4. 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:

  1. Understand what went wrong
  2. Identify the root cause
  3. Fix the issue
  4. 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

CodeNameDiagnosis
0SUCCESSNo error (user may have questions about output)
1UNEXPECTEDCheck .errors and .logs in envelope
2AUTHENTICATIONInvalid token, expired credentials, wrong URL
3NETWORKConnection refused, DNS failure, timeout
4VALIDATIONYAML syntax, schema violations, missing fields
5PARTIAL_FAILURESome entities failed - drill down with --entity
6DELETION_BLOCKED--fail-on-delete triggered
7BREAKING_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:

  1. Verify SALEOR_URL ends with /graphql/ and uses HTTPS
  2. Regenerate token in Saleor Dashboard
  3. 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:

  1. Run introspect to pull current state
  2. Modify existing entity instead of creating
  3. Use a different slug
Invalid Reference
Error: ProductType "NonExistent" not found

Fix:

  1. Check exact spelling of the referenced type
  2. Ensure the referenced entity is defined in config.yml
  3. Entity types must be deployed before entities that reference them
Rate Limiting

Fix: The CLI has built-in rate limiting. If still hitting limits:

  1. Reduce GRAPHQL_MAX_CONCURRENCY (default: 4)
  2. 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]

MCP servers 2

Sponsors

Details

Marketplace
saleor/configurator
Source
plugin
Category
Development
Keywords
saleor, e-commerce, configurator, yaml, graphql, commerce-as-code