Add shopify-import skill: migrate products from 10 commerce platforms

[hamishrobertson-dev]

TL;DR

Merchant-facing agent skill that imports product catalogs into Shopify from 10 commerce platforms. Replaces the Store Migration app (2.7★) with an agent-powered approach. Works with shopify store execute (Shopify/cli#7122, shipped 2026-04-01).

Installable via: npx skill add shopify/agent-skills/shopify-import

What

When a merchant says "I want to move my products from Square to Shopify," the agent:

1. Loads the skill, routes to the platform-specific guide
2. Walks the merchant through exporting their CSV
3. Parses + validates via ./scripts/import.py --json
4. Executes each productSet mutation via shopify store execute

Supported platforms

Platform	Variant grouping	Skip logic
Square	Token-based	Archived, per-unit pricing
WooCommerce	Parent/child (variable+variation)	External/affiliate products
Etsy	VARIATION TYPE/VALUES combos	—
Wix	handleId + fieldType	—
Amazon	parent-child + variation-theme	Orphaned variants
eBay	Item ID + Variation Details	Auction listings
Clover	Single-variant	Hidden items, variable pricing
Lightspeed R-Series	Item name + Size/Color	—
Lightspeed X-Series	Handle + variant_option columns	—
Google Merchant Center	item_group_id + color/size/material	—

Google Merchant Center is new — not in shop-importer-app. Requested in the Tobi review on agentic (2026-03-31).

File structure

shopify-import/
├── SKILL.md                            # Agent skill definition
├── config.json
├── platforms/                          # 10 platform-specific export instructions + column mappings
├── scripts/
│   ├── parsers/                        # Modular CSV parsers — one per platform + shared common.py
│   ├── validate_csv.py                 # Pre-import validation (blocking errors + warnings)
│   ├── import.py                       # Parse + preview (default) or --json for agent/CLI consumption
│   └── testing/                        # Internal dev: tophat.py + shopify_api.py for direct API testing
├── test-data/                          # 10 platform fixture CSVs
└── tests/                              # 181 unit tests

How the execution path works

shopify store execute (Shopify/cli#7122) shipped yesterday. The flow is:

1. Merchant runs shopify store auth — OAuth flow, connects agent to store (no API tokens exposed)
2. Agent runs ./scripts/import.py products.csv --platform square --json — gets mutation payloads
3. Agent runs shopify store execute --store shop.myshopify.com --allow-mutations --query "mutation productSet(...)" --variables '{"input": <payload>}'

The --json output gives the agent machine-readable payloads that slot directly into shopify store execute. The agent does not need to understand CSV parsing or column mapping — it just pipes our output into the CLI.

Why this beats the app

The Store Migration app has a 2.7★ rating. Common complaints: broken SKU mapping, missing images, incorrect variant prices.

An LLM-powered skill can:

• Fuzzy-match columns when headers don't exactly match (e.g. localized exports)
• Ask the user when data is ambiguous instead of silently dropping it
• Handle edge cases conversationally — "This product has 5 option types but Shopify supports 3. Which 3 matter most?"
• Zero infrastructure — no Remix app, no Cloud Run, no Prisma DB, no PagerDuty

How to test

Unit tests (181 passing, <0.1s)

pytest shopify-import/tests/ -v

Preview import (no API needed)

python3 shopify-import/scripts/import.py \
  shopify-import/test-data/square-products.csv \
  --platform square

🎩 Tophat against a dev store

1. Create a dev store + custom app (scopes: write_products, read_products, write_inventory, read_inventory, read_locations)
2. Run:

export SHOPIFY_STORE=your-store.myshopify.com
export SHOPIFY_ADMIN_TOKEN=shpat_xxxxxxxxxxxxx
python3 shopify-import/scripts/testing/tophat.py

Expected: 22 products (43 variants), 4 skipped, 27 inventory quantities. All DRAFT, names prefixed with platform.

Full CLI loop (shopify store execute)

# Parse CSV
python3 shopify-import/scripts/import.py shopify-import/test-data/square-products.csv --platform square --json > /tmp/payload.json

# Execute first product
VARS=$(python3 -c "import json; d=json.load(open('/tmp/payload.json')); print(json.dumps({'input': d['products'][0]['input']}))")
shopify store execute --store your-store.myshopify.com --allow-mutations \
  --query 'mutation productSet($input: ProductSetInput!) { productSet(input: $input) { product { id title } userErrors { message } } }' \
  --variables "$VARS"

Scope and known gaps

This covers product import. Not yet a full replacement for the Store Migration app:

Gap	Impact
Customer import	6/9 platforms support it in the app. Column mappings documented but no parser.
Bulk import	Individual mutations work for ~50 products. Large catalogs need bulkOperationRunMutation.
Image handling	URLs passed in productSet; temporary/authenticated URLs may not work.
Amazon API	App uses Codisto OAuth→SQLite. We handle CSV only.
Location management	We use default location only.

Context

• Discussed in #devtools-proj-agent-plugins — consensus: this belongs here, not in dev-mcp
• Requested in the Tobi review on agentic (2026-03-31) — specifically Google Merchant Center catalog transformation
• Prior art: Shopify/shop-importer-app (2.7★, rigid CSV parsing)

[hamishrobertson-dev]

🎩 from local with pi

Successful import:

Sample of errors an agent would see: