Shopify Skill

Shopify Dev MCP + Admin GraphQL skill with auditable execution, safety guardrails, and reusable store analytics workflows.

For Chinese documentation, see 中文.

Table of Contents

• 1. Scope and Compatibility
• 2. Features
• 3. Repository Layout
• 4. Configure MCP (Multi-Agent)
• 5. Installation
• 6. Usage
• 7. Audit Outputs
• 8. Testing
• 9. Changelog
• 10. Release
• 11. License

1. Scope and Compatibility

This project is agent-agnostic and OS-agnostic.

• Agents: Codex, Claude, Antigravity, OpenClaw, or any runtime that can execute local scripts.
• OS: Windows, macOS, Linux.
• Devices: desktop/laptop, remote VM/server, CI runner.

Core execution is runtime-independent because it lives in scripts/admin_graphql_query.py.

2. Features

• Official-doc-first workflow (Dev MCP first, then execution).
• Unified CLI commands for query, stock operations, rollback, and reporting.
• Extra common commands: top-products, inventory-alerts, orders-export.
• Read-only by default; write requires explicit --apply.
• --max-changes guardrail for mass update prevention.
• Structured audit outputs for every run.
• Retry/backoff and error classification.
• File-based inputs: --query-file, --variables-file.

3. Repository Layout

• SKILL.md - skill behavior and triggering instructions.
• scripts/admin_graphql_query.py - unified CLI entry.
• references/ - MCP and GraphQL guidance.
• documentation/ - maintainable docs (MCP matrix, detailed changelog, planning notes).
• tests/ - unittest suite.

4. Configure MCP (Multi-Agent)

See full matrix: documentation/mcp-setup-matrix.md

Quick summary:

• Codex: ~/.codex/config.toml
• Claude Code: <project-root>/.mcp.json
• Claude Desktop: app settings / desktop MCP config
• Antigravity: MCP settings UI (or raw config if supported)
• OpenClaw: MCP settings if available, otherwise script-only mode

Server definition used across all runtimes:

command = "npx"
args = ["-y", "@shopify/dev-mcp@latest"]

5. Installation

5.1 Prerequisites

• Python 3.10+
• Node.js (for Shopify Dev MCP via npx)
• Shopify Admin API token

5.2 Clone into your agent's skills directory

Do not clone this repository into an arbitrary project folder. Clone it into the skills/extensions directory of the runtime (agent) you are currently using.

Codex:

git clone https://github.com/rwang23/shopify-skill.git ~/.codex/skills/shopify-skill

Claude:

git clone https://github.com/rwang23/shopify-skill.git ~/.claude/skills/shopify-skill

Antigravity:

git clone https://github.com/rwang23/shopify-skill.git ~/.gemini/antigravity/skills/shopify-skill

OpenClaw:

git clone https://github.com/rwang23/shopify-skill.git ~/.openclaw/skills/shopify-skill

Then open the cloned folder:

cd ~/.<agent>/skills/shopify-skill

Alternative: download ZIP from GitHub and extract it under the corresponding agent skills folder.

5.3 Configure project credentials

Create project-root .env:

SHOPIFY_SHOP=your-store.myshopify.com
SHOPIFY_ADMIN_TOKEN=shpat_xxx
SHOPIFY_API_VERSION=2026-01

Alias keys also supported:

• SHOPIFY_STORE_URL -> same as SHOPIFY_SHOP
• SHOPIFY_ACCESS_TOKEN -> same as SHOPIFY_ADMIN_TOKEN

6. Usage

6.1 Base command by OS

Windows (PowerShell):

py -3 scripts/admin_graphql_query.py capabilities

macOS/Linux:

python3 scripts/admin_graphql_query.py capabilities

6.2 Query and analysis commands

python scripts/admin_graphql_query.py query --query "{ shop { name myshopifyDomain } }"
python scripts/admin_graphql_query.py query --query-file query.graphql --variables-file vars.json
python scripts/admin_graphql_query.py capabilities
python scripts/admin_graphql_query.py report-sales --page-size 100 --max-pages 10
python scripts/admin_graphql_query.py top-products --days 30 --limit 20 --by revenue
python scripts/admin_graphql_query.py orders-export --days 30 --page-size 100 --max-pages 10

6.3 Business use-case templates

Use the built-in template library in references/templates/:

python scripts/admin_graphql_query.py query --query-file references/templates/orders_recent.graphql --variables-file references/templates/orders_recent.variables.json
python scripts/admin_graphql_query.py query --query-file references/templates/customers_recent.graphql --variables-file references/templates/customers_recent.variables.json
python scripts/admin_graphql_query.py query --query-file references/templates/blogs_with_articles.graphql --variables-file references/templates/blogs_with_articles.variables.json
python scripts/admin_graphql_query.py query --query-file references/templates/products_performance.graphql --variables-file references/templates/products_performance.variables.json
python scripts/admin_graphql_query.py query --query-file references/templates/sales_shopifyql.graphql --variables-file references/templates/sales_shopifyql.variables.json
python scripts/admin_graphql_query.py query --query-file references/templates/subscription_contracts.graphql --variables-file references/templates/subscription_contracts.variables.json
python scripts/admin_graphql_query.py query --query-file references/templates/app_installation_subscriptions.graphql --variables-file references/templates/app_installation_subscriptions.variables.json

Full matrix (scopes + scenario notes): references/common-templates.md

6.4 Inventory commands

python scripts/admin_graphql_query.py scan-stock --threshold 50 --exclude-product "Shipment Protection+"
python scripts/admin_graphql_query.py inventory-alerts --low-threshold 10 --high-threshold 50

6.5 Safe write flow

1. Dry-run preview:

python scripts/admin_graphql_query.py randomize-stock --threshold 50 --target-min 20 --target-max 35 --exclude-product "Shipment Protection+"

2. Apply with guardrail:

python scripts/admin_graphql_query.py randomize-stock --threshold 50 --target-min 20 --target-max 35 --exclude-product "Shipment Protection+" --apply --max-changes 20

3. Rollback if needed:

python scripts/admin_graphql_query.py rollback-stock --rollback-file shopify-skill-output/<YYYYMMDD>/<HHMMSS>-randomize-stock-<runid>/rollback-plan.json --apply --max-changes 20

7. Audit Outputs

Output root:

shopify-skill-output/<YYYYMMDD>/<HHMMSS>-<operation>-<runid>/

Mandatory files:

• summary.json
• request.json
• result.json

Write operations also emit:

• applied.csv
• failed.csv
• rollback-plan.json

Detailed convention: references/audit-output-convention.md

8. Testing

python -m unittest discover tests -v

9. Changelog

Short changelog summary is kept here. Detailed history is in documentation/CHANGELOG.md.

1.1.0 (2026-03-03)

• Added scenario template packs for orders, customers, blogs/articles, products, sales (ShopifyQL), and subscriptions.
• Added official-source use-case research notes in documentation/use-cases-research-2026-03-03.md.
• Expanded usage docs with copy-paste template commands.

1.0.0 (2026-03-03)

• Added unified CLI with safety controls and audit outputs.
• Added report and inventory workflows.
• Set default mode to read-only.

10. Release

• Release template: .github/release-template.md
• v1.0.0 notes: documentation/RELEASE_NOTES_v1.0.0.md

11. License

MIT. See LICENSE.