Shopify Developer
Use this skill as the coordination hub. Keep implementation details in references/ files and load only the file(s) needed for the task.
Authentication
Use quarterly API versions in all endpoints, for example 2026-01.
Admin GraphQL endpoint:
https://${SHOP}.myshopify.com/admin/api/${API_VERSION}/graphql.json
Admin API headers:
X-Shopify-Access-Token: ${SHOPIFY_ACCESS_TOKEN}
Content-Type: application/json
Storefront GraphQL endpoint:
https://${SHOP}.myshopify.com/api/${API_VERSION}/graphql.json
Storefront API headers:
X-Shopify-Storefront-Access-Token: ${SHOPIFY_STOREFRONT_TOKEN}
Content-Type: application/json
Source environment variables from ~/.agents/.env before running commands.
API Conventions
- Prefer GraphQL over REST for new work.
- Include API version in the URL; update quarterly.
- Paginate with cursors (
first/after) rather than page numbers.
- Handle both top-level
errors and mutation userErrors.
- Budget GraphQL query cost and throttle based on available points.
- Use bulk operations for large export/import workloads.
- Prefer idempotent mutation patterns for retry-safe writes.
Core Workflows
Theme development pipeline:
- Pull current theme state, iterate in local dev, push to draft first.
- Validate theme editor behavior (sections, blocks, settings) before live publish.
- Reference:
references/theme-architecture.md, references/liquid.md.
Product and metafield management:
- Define metafield/metaobject schemas first, then write values through Admin API.
- Access values in Liquid and Storefront API using type-safe patterns.
- Reference:
references/admin-api.md, references/metafields-metaobjects.md.
Checkout customization:
- Use Checkout UI Extensions and Shopify Functions; avoid legacy checkout patterns.
- Separate UI concerns (extensions) from pricing/fulfillment logic (functions).
- Reference:
references/checkout-extensibility.md, references/shopify-functions.md.
Reference Files
| File |
When to read |
references/admin-api.md |
Product/order/customer/inventory GraphQL workflows; bulk operations. Grep hint: bulkOperation. |
references/storefront-api.md |
Headless storefront queries, cart operations, customer account flows, localization. Grep hint: cart. |
references/metafields-metaobjects.md |
Metafield types, definitions, Liquid access, metaobject CRUD. Grep hint: metafieldsSet. |
references/liquid.md |
Liquid objects, filters, tags, render patterns, metafield rendering, performance tuning. |
references/theme-architecture.md |
OS 2.0 structure, section schema, templates, app blocks, CLI deployment flow. |
references/checkout-extensibility.md |
Checkout UI extensions, web pixels, migration timelines, post-purchase extensions. |
references/shopify-functions.md |
Function types, WASM constraints, implementation/testing, Scripts migration path. |
references/webhooks-events.md |
Webhook topics, compliance webhooks, HMAC verification, retries/idempotency. |
references/platform-limits.md |
API versioning, limits, deprecation timelines, plan-specific capabilities. |
Gotchas
- Use
.value when rendering metafields in Liquid.
- Use
metafieldsDelete (plural), not singular deletion mutation names.
- Do not rely on
checkout.liquid; migrate to checkout extensibility.
- Plan Scripts migration before June 30, 2026 sunset.
- Treat REST Admin API as maintenance-only for new implementation.
- Rotate to supported API versions before the 12-month support window ends.
- Implement idempotency keys for retry-safe writes before April 1, 2026 enforcement.
- Remove deprecated Storefront tax fields during API upgrades.
- Do not hand-edit
config/settings_data.json; use Theme Editor.
- Keep Shopify Functions logic minimal to stay inside strict runtime limits.
1---2name: shopify-developer3description: Comprehensive Shopify development skill for theme architecture, Liquid, Admin API, Storefront API, metafields/metaobjects, checkout extensibility, Shopify Functions, webhooks, and platform limits. Use when implementing or debugging Shopify app/theme work, API integrations, checkout customizations, or data modeling. For Hydrogen/headless framework specifics, use Context7 MCP for current framework docs.4---56# Shopify Developer78Use this skill as the coordination hub. Keep implementation details in `references/` files and load only the file(s) needed for the task.910## Authentication1112Use quarterly API versions in all endpoints, for example `2026-01`.1314Admin GraphQL endpoint:1516```bash17https://${SHOP}.myshopify.com/admin/api/${API_VERSION}/graphql.json18```1920Admin API headers:2122```bash23X-Shopify-Access-Token: ${SHOPIFY_ACCESS_TOKEN}24Content-Type: application/json25```2627Storefront GraphQL endpoint:2829```bash30https://${SHOP}.myshopify.com/api/${API_VERSION}/graphql.json31```3233Storefront API headers:3435```bash36X-Shopify-Storefront-Access-Token: ${SHOPIFY_STOREFRONT_TOKEN}37Content-Type: application/json38```3940Source environment variables from `~/.agents/.env` before running commands.4142## API Conventions4344- Prefer GraphQL over REST for new work.45- Include API version in the URL; update quarterly.46- Paginate with cursors (`first/after`) rather than page numbers.47- Handle both top-level `errors` and mutation `userErrors`.48- Budget GraphQL query cost and throttle based on available points.49- Use bulk operations for large export/import workloads.50- Prefer idempotent mutation patterns for retry-safe writes.5152## Core Workflows5354Theme development pipeline:55- Pull current theme state, iterate in local dev, push to draft first.56- Validate theme editor behavior (sections, blocks, settings) before live publish.57- Reference: `references/theme-architecture.md`, `references/liquid.md`.5859Product and metafield management:60- Define metafield/metaobject schemas first, then write values through Admin API.61- Access values in Liquid and Storefront API using type-safe patterns.62- Reference: `references/admin-api.md`, `references/metafields-metaobjects.md`.6364Checkout customization:65- Use Checkout UI Extensions and Shopify Functions; avoid legacy checkout patterns.66- Separate UI concerns (extensions) from pricing/fulfillment logic (functions).67- Reference: `references/checkout-extensibility.md`, `references/shopify-functions.md`.6869## Reference Files7071| File | When to read |72|---|---|73| `references/admin-api.md` | Product/order/customer/inventory GraphQL workflows; bulk operations. Grep hint: `bulkOperation`. |74| `references/storefront-api.md` | Headless storefront queries, cart operations, customer account flows, localization. Grep hint: `cart`. |75| `references/metafields-metaobjects.md` | Metafield types, definitions, Liquid access, metaobject CRUD. Grep hint: `metafieldsSet`. |76| `references/liquid.md` | Liquid objects, filters, tags, render patterns, metafield rendering, performance tuning. |77| `references/theme-architecture.md` | OS 2.0 structure, section schema, templates, app blocks, CLI deployment flow. |78| `references/checkout-extensibility.md` | Checkout UI extensions, web pixels, migration timelines, post-purchase extensions. |79| `references/shopify-functions.md` | Function types, WASM constraints, implementation/testing, Scripts migration path. |80| `references/webhooks-events.md` | Webhook topics, compliance webhooks, HMAC verification, retries/idempotency. |81| `references/platform-limits.md` | API versioning, limits, deprecation timelines, plan-specific capabilities. |8283## Gotchas84851. Use `.value` when rendering metafields in Liquid.862. Use `metafieldsDelete` (plural), not singular deletion mutation names.873. Do not rely on `checkout.liquid`; migrate to checkout extensibility.884. Plan Scripts migration before June 30, 2026 sunset.895. Treat REST Admin API as maintenance-only for new implementation.906. Rotate to supported API versions before the 12-month support window ends.917. Implement idempotency keys for retry-safe writes before April 1, 2026 enforcement.928. Remove deprecated Storefront tax fields during API upgrades.939. Do not hand-edit `config/settings_data.json`; use Theme Editor.9410. Keep Shopify Functions logic minimal to stay inside strict runtime limits.
cathrynlavery