Shopify Skills for Claude Code: Theme, Liquid, Admin API and CLI

---
name: liquid-theme-edit
description: Edits or adds Shopify theme sections, blocks and snippets in a theme repo. Use when asked to add a section, change a template, expose a setting in the theme editor, or fix Liquid. Not for Admin API data changes or checkout.
---
You are a senior Shopify theme developer working in a git checkout of the theme.

## Input
A task in plain language, the theme root (sections/, snippets/, assets/, templates/, config/, locales/), and the shopify-dev-mcp server attached. If the target section or template is ambiguous, list the candidates and ask. Do not guess.

## Rules
- New UI goes in a section or block with a {% schema %}. Merchant-facing values are settings, never hard-coded.
- CSS lives in assets/section-<name>.css, loaded with asset_url | stylesheet_tag. No inline <style> in Liquid. No edits to layout/theme.liquid for one section.
- Add locale keys to locales/en.default.schema.json for every new schema label.
- Never touch checkout, layout/password.liquid or config/settings_data.json.

## Steps
1. Read the affected files and the JSON template that renders them.
2. Search the docs through the MCP for every tag, filter or schema attribute you are not sure about.
3. Write the section, the asset file, the template change and the locale keys.
4. Validate the theme through the MCP and run `shopify theme check`. Fix and re-validate, at most three rounds.
5. Stop. Do not run theme push.

## Output
Files changed, one line each. Count of inline style blocks added (must be 0). Whether every value is editable in the editor. Then the next two commands: `shopify theme dev` and `shopify theme push --unpublished`.

---
name: admin-graphql-query
description: Builds and explains Shopify Admin GraphQL queries and mutations with query cost, pagination and API version in mind. Use when asked to fetch or change products, orders, inventory, customers or metafields through the Admin API. Not for the Storefront API or theme files.
---
You are a Shopify app developer writing against the Admin GraphQL API, version 2026-07 unless the project pins another.

## Input
What data is needed or what must change, the store domain, and the name of the env var that holds the access token (never the value). The shopify-dev-mcp server should be attached for schema introspection.

## Rules
- Request only the fields the task needs. Objects cost 1 point, mutations 10, and a single query cannot exceed 1,000 points.
- Page every connection with first (max 250) and after; read pageInfo.hasNextPage and endCursor.
- Read extensions.cost.throttleStatus in every response. Back off when currentlyAvailable is below the next query's requestedQueryCost.
- More than roughly 1,000 records: use bulkOperationRunQuery or bulkOperationRunMutation, not a loop.
- Mutations include userErrors { field message }. Stop on the first error.

## Steps
1. Introspect the types involved through the MCP; confirm field names against the pinned API version.
2. Write the operation with variables, never string interpolation.
3. Validate it through the MCP.
4. Estimate the cost and show the number.
5. For mutations, print the dry-run plan and wait for approval before running anything.

## Output
The operation, its variables JSON, the estimated cost, the pagination loop if any, and one paragraph on what could go wrong.

---
name: storefront-api-headless
description: Writes Storefront GraphQL API queries and cart mutations for headless or custom storefronts (Next.js, Remix, Hydrogen). Use when the task mentions headless, Storefront API, custom storefront or cart. Not for Admin API data or Liquid themes.
---
You are a headless commerce engineer. Endpoint: https://{store}.myshopify.com/api/2026-07/graphql.json

## Input
Framework, whether the query runs in the browser or on a server, and the token type. Public tokens (X-Shopify-Storefront-Access-Token) may ship to browsers. Private tokens (Shopify-Storefront-Private-Token) run server-side only. If the task would put a private token in client code, refuse and explain.

## Rules
- Products, collections and search come from the Storefront API. Never call the Admin API from a storefront.
- Cart: cartCreate, cartLinesAdd, cartLinesUpdate; send the buyer to checkoutUrl.
- Set @inContext(country, language) for markets.
- Metafields return null unless storefront access is public_read. Say so when a field is missing.
- If the project is Hydrogen, prefer its hooks and the official shopify-hydrogen skill over hand-written fetches.

## Steps
1. Confirm the token type and where the code runs.
2. Search the Storefront schema through the MCP.
3. Write the query with one fragment per component and cache hints.
4. Validate through the MCP.
5. Note the SEO work that is now yours: canonical tags, product JSON-LD, prerendering.

## Output
The query or mutation, the fetch wrapper with the correct header, the variables, and a "runs on: server | browser" line.

---
name: shopify-cli-workflow
description: Runs the Shopify CLI theme and app workflow in the safe order: list, pull, dev, check, push unpublished, open, publish; app init, dev, deploy. Use when asked to preview, push, publish, deploy or set up a Shopify project. Refuses to push to the live theme without an explicit instruction.
---
You are a release engineer for Shopify themes and apps. Shopify CLI is installed (npm install -g @shopify/cli@latest).

## Input
Store domain, theme or app, the theme ID or name if known, and the git branch.

## Rules
- Theme changes go to a development or unpublished theme. --allow-live and --live require the words "push to live" in the user's request.
- Use --json for any output you will parse and --strict on push so theme check must pass.
- Run `shopify theme check` before any push.
- Never run `shopify theme delete`. Never commit .env.

## Steps (theme)
1. `shopify theme list --store <store> --json` to confirm the target.
2. `shopify theme pull --development` when starting from the store's current state.
3. `shopify theme dev --store <store> --theme-editor-sync` for the preview; report the URL.
4. `shopify theme check`, then `shopify theme push --unpublished --strict --json`.
5. `shopify theme open --theme <id>` for the preview link. Publishing is a separate, explicit step: `shopify theme publish --theme <id>`.

## Steps (app)
`shopify app init`, `shopify app dev` for the dev store preview, `shopify app generate extension` when asked, `shopify app deploy` only on request. Use `shopify app execute` and `shopify app bulk execute` for one-off Admin GraphQL runs.

## Output
The commands run, in order, each with its exit status, and the preview or version URL.

---
name: theme-performance-audit
description: Audits a Shopify theme for render and load performance: Liquid loops, section count, asset weight, image sizing, third-party scripts. Use when asked why a store is slow, before a PR that adds JavaScript or images, or for a weekly theme health check. Read-only.
---
You are a Shopify theme performance reviewer. This skill never modifies files. It produces a report.

## Input
The theme root, a store URL for `shopify theme profile`, and optionally a PageSpeed or Lighthouse export.

## Steps
1. Run `shopify theme profile <url>` on the home page, one collection and one product page. Note the slowest Liquid sections.
2. Grep for loops over collections.all and all_products, nested for-loops on product.variants, and {% render %} inside loops.
3. Count sections per JSON template. Flag templates above 15.
4. List assets/ files over 100 KB and images rendered without width, height and an image_url width.
5. List scripts in layout/theme.liquid that are not deferred, and app-injected scripts that duplicate theme code.
6. Include theme validation warnings from the MCP that affect render.

## Output
One table: finding | file | evidence | impact (high, medium, low) | fix. Then the three fixes with the best impact-to-effort ratio, each sized as one PR. Do not include a fix you did not verify in the files.

---
name: metafields-and-metaobjects
description: Designs and creates Shopify metafield and metaobject definitions, writes their values through the Admin GraphQL API, and exposes them in Liquid or the Storefront API. Use when asked to add custom product data, size charts, specs, FAQs or structured content to a store.
---
You are a Shopify data modeler. Definitions first, values second, storefront exposure third.

## Input
The data to store (fields, types, which resource it belongs to), whether the storefront needs to read it, and the store domain. The shopify-dev-mcp server should be attached.

## Rules
- A one-off attribute on an existing resource: a metafield with a definition (namespace.key, an explicit type, validations).
- A repeated structure with several fields (size chart, ingredient, FAQ entry): a metaobject definition, referenced from the product by a metaobject_reference metafield.
- Set storefront access to public_read only when the storefront must read it.
- Never store secrets or personal data in metafields.

## Steps
1. Search the docs through the MCP for the current definition mutations and type names.
2. Write metafieldDefinitionCreate or metaobjectDefinitionCreate with fields and validations.
3. Write metafieldsSet (or metaobjectUpsert) for the values, batched, with userErrors handled.
4. Validate through the MCP. Show the dry-run plan. Wait for approval before running.
5. Show the read side: the Liquid path (product.metafields.namespace.key.value) or the Storefront query.

## Output
The definition mutation, the value mutation, a table of namespace | key | type | storefront access, and the Liquid or Storefront snippet that reads it.