A context engineering framework for building production Shopify stores using Claude Code primitives.
This is a complete AI-assisted Shopify development system built on Claude Code's native primitives: skills (slash commands), agents (specialist workers), and MCP server configurations. It's designed so that any developer with Claude Code can build production Shopify stores -- themes, headless storefronts, apps, checkout customizations, and full custom builds -- by invoking the right skill for their current phase.
The system is structured as three layers:
-
Semantic Web (
SEMANTIC-WEB.md) -- A recursive knowledge graph that maps every Shopify domain, tool, resource, and workflow. Nodes cross-reference each other so the AI can traverse from any concept to any related concept. -
Framework (
FRAMEWORK.md) -- The context engineering architecture. Defines how skills, agents, teams, and MCP servers compose. Includes workflow orchestration, team compositions for different build types, and community resource integration strategy. -
Claude Code Primitives (
.claude/) -- The executable system:- CLAUDE.md -- Always-loaded project context with platform rules, quality gates, and constraints
- 12 Skills -- Slash commands covering the full build lifecycle
- 6 Agents -- Specialist workers with deep Shopify domain knowledge
Shopify development is deceptively complex. What looks like "just a store" involves 10+ distinct technical domains:
- Liquid templating with Online Store 2.0 architecture
- GraphQL Admin API with cost-based rate limiting and quarterly versioning
- Hydrogen (React Router v7 headless framework) with RSC and edge deployment
- Shopify Functions (WebAssembly, 256KB/11M instruction limits)
- Checkout extensibility (Preact, 64KB bundle limits)
- Metafields/metaobjects data modeling
- Multi-market internationalization
- App development across 7+ extension surfaces
- Third-party integrations (ERP, CRM, fulfillment)
No single person masters all of these. This framework encodes the knowledge, constraints, and patterns across all domains so that Claude Code can act as a knowledgeable specialist in whichever domain the current task requires.
| Skill | Purpose | Phase |
|---|---|---|
/shopify-discovery |
Client requirements gathering interview | Discovery |
/shopify-architect |
Architecture decision (theme vs headless vs app) | Design |
/shopify-theme |
Liquid theme development workflow | Build |
/shopify-hydrogen |
Headless storefront development | Build |
/shopify-app |
Embedded app development | Build |
/shopify-checkout |
Checkout customization (Functions + UI extensions) | Build |
/shopify-content |
Content modeling (metafields, metaobjects) | Build |
/shopify-i18n |
Internationalization (markets, currencies, translations) | Build |
/shopify-integrate |
Third-party integrations (ERP, CRM, 3PL) | Build |
/shopify-deploy |
Deployment and CI/CD | Ship |
/shopify-audit |
Quality audit (Theme Check, Lighthouse, a11y) | Verify |
/shopify-handoff |
Client documentation and training materials | Deliver |
| Agent | Model | Specialization |
|---|---|---|
shopify-liquid-dev |
Sonnet | Liquid, OS 2.0 sections/blocks, schema design |
shopify-hydrogen-dev |
Sonnet | React Router v7, RSC, Storefront API, Oxygen |
shopify-api-dev |
Sonnet | GraphQL Admin API, OAuth, App Bridge, webhooks |
shopify-functions-dev |
Sonnet | Wasm Functions, checkout UI, checkout branding |
shopify-content-dev |
Haiku | Metafields, metaobjects, taxonomy, translations |
shopify-qa |
Sonnet | Theme Check, Lighthouse, accessibility, security |
- Claude Code installed
- Shopify CLI installed:
npm install -g @shopify/cli@latest - A Shopify Partner account with development store access
git clone https://github.com/domocarroll/shopify-builds.git
cd shopify-builds# MUST HAVE: Shopify platform knowledge (docs, schemas, validation)
claude mcp add shopify-dev -- npx -y @shopify/dev-mcp@latest
# MUST HAVE for themes: Offline Liquid reference (198 docs, sub-ms search)
# See: https://github.com/florinel-chis/shopify-liquid-mcp
claude mcp add shopify-liquid -- node /path/to/shopify-liquid-mcp/index.js
# MUST HAVE for store operations: 70+ Admin API tools
claude mcp add shopify-admin -- npx -y @ajackus/shopify-mcp-server# Open Claude Code in the project
claude
# Start with client discovery
/shopify-discovery
# Or jump to a specific phase
/shopify-theme
/shopify-hydrogen
/shopify-app/shopify-discovery -> /shopify-architect -> /shopify-content -> /shopify-theme -> /shopify-audit -> /shopify-deploy -> /shopify-handoff
Stack: Liquid + Online Store 2.0 + optional Vite Team: lead + liquid-dev + content-dev + qa
/shopify-discovery -> /shopify-architect -> /shopify-content -> /shopify-hydrogen -> /shopify-audit -> /shopify-deploy -> /shopify-handoff
Stack: Hydrogen + React Router v7 + Oxygen Team: lead + hydrogen-dev + api-dev + content-dev + qa
/shopify-discovery -> /shopify-architect -> /shopify-app -> /shopify-checkout -> /shopify-audit -> /shopify-deploy -> /shopify-handoff
Stack: React Router + Shopify API + Extensions Team: lead + api-dev + functions-dev + qa
All skills in sequence, team includes all specialists.
| Server | Purpose | Required |
|---|---|---|
| @shopify/dev-mcp | Shopify docs, API schemas, GraphQL introspection, Polaris, validation | Yes |
| shopify-liquid-mcp | 198 Liquid docs, offline, sub-ms search | Yes (themes) |
| @ajackus/shopify-mcp-server | 70+ Admin API tools | Yes (store ops) |
| apollo-mcp-server | Generic GraphQL introspection | Optional |
| ShopifyMockMCP | mock.shop proxy for safe testing | Optional |
| Shopify Storefront MCP | AI shopping agent integration | If building agents |
| Shopify Catalog MCP | Cross-merchant product discovery | If building discovery |
The framework, semantic web, skills, and agents are all built from deep research into Shopify's 2025-2026 platform. This is the knowledge scaffold. It has not yet been battle-tested on a real client build.
- Install and configure MCP servers --
@shopify/dev-mcpis highest priority. Test that all three must-have MCPs work end-to-end. - Evaluate community skills for merging -- wookstar-claude-code-plugins (6 Shopify skills), shopify-dev-toolkit-claude-plugins (16 agents), and Horizon Theme .cursorrules may have patterns worth integrating.
- Set up a test development store -- Create a Shopify Partner dev store to validate skills against real Shopify APIs.
- Run /shopify-discovery on a mock client brief -- Validate the interview flow produces useful requirements docs.
- Run /shopify-theme end-to-end -- Build a simple theme section to validate the full skill -> agent -> MCP pipeline.
- Refine skills based on real usage -- Skills that are too verbose, too vague, or missing steps get updated after each build.
- Calibrate agent constraints -- Verify that agent rules prevent actual mistakes (not just theoretical ones).
- Build client project templates -- Standardize the
clients/{name}/directory structure with.planning/docs. - Create team composition configs -- Formalize the 4 team types (theme, headless, app, full) as reusable configurations.
- Add Shopify CLI wrapper skills -- Skills that automate common multi-step CLI workflows (theme init + check + dev, app init + dev + deploy).
- Extract reusable section library -- Common sections (hero, product grid, testimonials, FAQ) as tested Liquid code.
- Build a Hydrogen starter template -- Opinionated Hydrogen starter with our patterns baked in.
- Create integration blueprints -- Tested patterns for common integrations (Klaviyo, ShipStation, NetSuite).
- Automate the quarterly update cycle -- Script that checks Shopify API changelog and flags what needs updating in our skills/agents.
- Performance benchmarking suite -- Automated Lighthouse runs against builds with regression tracking.
- Publish as a Claude Code skill package -- Make the framework installable by other Shopify developers.
- AI shopping agent templates -- Leverage Shopify's Storefront MCP and shop-chat-agent for AI-powered commerce experiences.
- Multi-store orchestration -- Skills for managing multiple Shopify stores (expansion stores, headless multi-brand).
- Contribute upstream -- Feed patterns back to Shopify's dev-mcp and community skill repos.
These are resources we've identified for evaluation and potential integration:
- wookstar-claude-code-plugins -- 6 Shopify skills + GA/GTM
- shopify-dev-toolkit-claude-plugins -- 16 agents covering themes, apps, Polaris
- claudekit-skills -- Shopify skill in marketplace format
- claude-code-templates/shopify-development -- Quick install via npx
- antigravity-awesome-skills -- 868+ skills including Shopify
- cursor.directory/rules/shopify -- Liquid best practices for AI
- cursor.directory/rules/liquid -- Liquid-focused rules
- Horizon Theme .cursorrules -- Official Shopify-authored AI rules
- Shopify/dawn -- Reference OS 2.0 theme
- Shopify/skeleton-theme -- Minimal starter with Vite
- Shopify/hydrogen-demo-store -- Full-featured Hydrogen template
- Shopify/shop-chat-agent -- AI shopping agent reference
- julionc/awesome-shopify -- Canonical resource list
- awesome-shopify -- Shopify dev resources
- awesome-hydrogen -- Headless commerce resources
- awesome-claude-code-toolkit -- Claude Code ecosystem
User invokes /shopify-theme
|
+-- CLAUDE.md loads (always) --> Shopify constraints, quality gates
|
+-- Skill prompt loads -------> Theme workflow, steps, delegation patterns
|
+-- Skill spawns agent -------> shopify-liquid-dev with Liquid expertise
|
+-- Agent queries MCP --------> @shopify/dev-mcp for live API docs
| shopify-liquid-mcp for Liquid reference
|
+-- Agent produces code ------> Validated against constraints at every layer
|
+-- QA agent verifies --------> Theme Check, Lighthouse, accessibility
Every layer adds context. Every layer constrains. The result is code that matches Shopify's actual platform, not what a model "remembers."
This is currently a private development studio tool. If you're interested in using or contributing to the framework, open an issue.
MIT