Shopify Agent Skill

Shopify themes, apps & checkout

The single authoritative skill for building and customizing a Shopify store. The mental model:

**a Shopify store is a hosted platform you extend at well-defined seams — never a server you

control.** You render on the storefront with Liquid, you mutate data through the versioned

GraphQL Admin API, and you customize checkout through sandboxed extensions. The platform owns

hosting, the database, PCI scope, and the checkout DOM; you own only the seams. Three surfaces,

three toolchains — name the surface before you write a line of code.

Pinned stack (verify against shopify.dev before pinning in a repo):

• Shopify CLI 4.x — auto-upgrades via the package manager it was installed with; skips CI,

project-local installs, and major bumps. shopify app config push is removed; use shopify app deploy.

• GraphQL Admin API 2026-04 — latest stable; supported window 2026-04 / 2026-01 / 2025-10 /

2025-07†. Each version is supported ~12 months. Pin apiVersion and bump quarterly.

† 2025-07 is at the edge of its window — accessible only until 2026-07-16; treat it as

sunsetting and do not pin it in new work. Re-check the live list at shopify.dev/docs/api/usage/versioning.

• Remix app template (@shopify/shopify-app-remix, App Bridge, Polaris React). GraphQL > REST —

REST Admin API is legacy; Shopify steers all new app work to GraphQL.

• Dawn — Shopify's source-available reference theme; OS 2.0 architecture is the baseline.

Pick your surface first

Most Shopify mistakes are surface confusion — answering with a headless React build when the ask

was a Liquid section, or editing checkout.liquid when the seam is now an extension. Branch here:

| Surface | You're working on… | Tool & entry | Reference |

|---|---|---|---|

| Theme | .liquid files, {% schema %}, JSON templates, storefront rendering, merchant-editable content | shopify theme dev on a Dawn-based theme | references/liquid-themes.md |

| App | embedded admin UI, reading/writing store data, webhooks, automation | shopify app dev on the Remix template + Admin GraphQL | references/apps-graphql.md |

| Checkout | checkout/thank-you/order-status UI or logic, discounts, shipping, tracking | Checkout UI extensions / Functions / Web Pixels | references/checkout-extensibility.md |

If the answer is "the React rendering layer of a headless storefront", that is ../nextjs/SKILL.md,

not this skill — Shopify is only the data seam (Storefront API) there.

Theme surface — Online Store 2.0 architecture

OS 2.0 (GA 2021, sometimes marketed "3.0") is the architecture: JSON templates + sections-

everywhere + theme blocks + @app blocks + dynamic sources. The file map:

layout/theme.liquid            # the HTML shell (one per theme)
templates/product.json         # JSON template: which sections render, in what order
sections/main-product.liquid   # a section: markup + {% schema %} of merchant settings
sections/*.liquid              # section groups (header/footer) live here too
blocks/*.liquid                # theme blocks (reusable, nestable) — OS 2.0
snippets/*.liquid              # partials rendered via {% render %}
config/settings_schema.json    # global theme settings

**Rule: every section carries a {% schema %} with presets so merchants edit content in the

theme editor without a deploy.** The why: content belongs in section.settings and metafields, not

in code — if a merchant has to ask you to change a headline, the section is built wrong.

<!-- Bad: copy hardcoded in Liquid; merchant can't touch it -->
<h2>Summer Sale — 20% off everything</h2>

<!-- Good: editable in the theme editor, with a preset so it appears in "Add section" -->
<h2>{{ section.settings.heading | escape }}</h2>
{% schema %}
{
  "name": "Promo banner",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "Summer Sale" }
  ],
  "blocks": [{ "type": "@app" }],
  "presets": [{ "name": "Promo banner" }]
}
{% endschema %}

The { "type": "@app" } block lets merchant-installed apps drop content into your section. The

Shopify Theme Store requires the main product and featured-product sections to support @app

blocks. See references/liquid-themes.md for setting types, section groups, and dynamic sources.

Liquid rules

• {% render %}, never {% include %}. render is scoped (the snippet only sees what you

pass) and cacheable; include leaks the parent scope and is deprecated.

  {% comment %} Bad {% endcomment %}
  {% include 'price' %}
  {% comment %} Good — explicit, scoped, cacheable {% endcomment %}
  {% render 'price', product: product, variant: variant %}

• Bound every collection loop with limit: and never nest unbounded loops — storefront render

cost is real and slow pages cost conversions. {% for p in collection.products limit: 8 %}.

• Pipe all dynamic output. | money for prices (raw values render cents/locale wrong),

| escape for any user/merchant string (XSS), | json when emitting data into a <script>.

• Push branchy logic into metafields/metaobjects, not conditional chains. A case/if ladder

over product types is data pretending to be code — bind a metafield and let Liquid do a lookup.

CLI workflow

Theme work (hot-reloads against a dev theme; never edits live unprompted):

shopify theme dev                      # local preview + hot reload
shopify theme pull                     # sync live/named theme down
shopify theme push --only templates/*  # push a subset; --ignore excludes paths
shopify theme check                    # Theme Check linter — wire into CI

Multi-environment lives in shopify.theme.toml; --environment is repeatable

(shopify theme push --environment staging --environment prod).

App work:

shopify app dev      # tunnel + env + reload; provisions admin.graphql()
shopify app deploy   # release app + extensions  (NOT `app config push` — removed in 4.x)

CLI 4.x auto-upgrades via your package manager but skips CI and project-local installs — pin the

version in CI so a silent bump never changes a release.

App surface — Remix + GraphQL Admin API

Apps are the Remix template. The shape:

app/shopify.server.js     # shopifyApp({ apiVersion, sessionStorage, webhooks, ... })
app/routes/app.*.jsx      # embedded admin pages (App Bridge + Polaris)
shopify.app.toml          # app config, scopes, webhook subscriptions
extensions/*              # app extensions (theme app ext, UI ext, Functions, Flow)

• Pin apiVersion in shopify.server and bump it quarterly — an unpinned client silently

follows Shopify's default and can break on a version rollover.

• Use the GraphQL Admin API, not REST. REST is legacy; new fields ship to GraphQL only.

  // Bad — legacy REST Admin endpoint
  await fetch(`https://${shop}/admin/api/2026-04/orders.json`);

  // Good — authenticated GraphQL through the template
  const { admin } = await authenticate.admin(request);
  const res = await admin.graphql(
    `#graphql
     query Orders { orders(first: 10) { nodes { id name } } }`
  );

• Verify webhook HMAC before trusting any payload — authenticate.webhook(request) in the

template does this; never parse a raw webhook body without it.

See references/apps-graphql.md for OAuth/session storage, mutations, App Bridge, and extensions.

GraphQL query-cost model

Admin GraphQL meters by calculated query cost (points), not request count. Every response

carries extensions.cost:

{ "extensions": { "cost": {
  "requestedQueryCost": 92, "actualQueryCost": 30,
  "throttleStatus": { "maximumAvailable": 2000, "currentlyAvailable": 1970, "restoreRate": 100 }
}}}

• Over-budget returns HTTP 200 with a MAX_COST_EXCEEDED error — you must handle it in code; it

is not an HTTP-level failure your client will throw on.

• Read throttleStatus and back off on restoreRate (points restored per second) rather than

blindly retrying.

• Large reads use bulk operations, not paginated loops. A 10k-product export through first:

pagination will throttle; bulkOperationRunQuery runs async and returns a JSONL file.

Checkout surface — the post-checkout.liquid model

checkout.liquid and additional scripts are deprecated and being removed. Dated facts:

• 2024-08-13 — Information/Shipping/Payment steps lost checkout.liquid support.
• 2025-08-28 — Plus self-migrate deadline for Thank-you & Order-status customizations (additional

scripts, script tags, checkout.liquid). This was the *deadline to act*, not the auto-upgrade date.

• 2026-01 — automatic upgrades of Thank-you & Order-status pages begin (30-day email notice);

any remaining additional-scripts / script-tag / checkout.liquid customizations stop running.

• 2026-04-15 — legacy Shopify Scripts can no longer be edited or published (existing scripts still run).
• 2026-06-30 — legacy Shopify Scripts (Script Editor discount/shipping/payment scripts) stop executing entirely.

Migrate by surface — match the old mechanism to its new seam:

| Old (deprecated) | New seam | Notes |

|---|---|---|

| checkout.liquid UI tweaks | Checkout UI extensions | sandboxed React/JS targets, not DOM access |

| Script Editor / additional-script discounts, shipping, payment logic | Functions (Rust or JS → Wasm) | deterministic, run server-side |

| <script> tracking / analytics in checkout | Web Pixels + server-side events | sandboxed; no arbitrary DOM scripts |

| custom checkout colors/fonts/CSS | Checkout Branding API | GraphQL, not CSS injection |

Several checkout surfaces (full checkout UI customization, some Functions) are Shopify Plus-only.

The full migration map, extension targets, and Functions structure are in

references/checkout-extensibility.md.

App extensions catalog

• Theme app extension — your app injects an @app block / blocks into themes (no theme edit).
• Admin UI extension — surfaces inside admin pages (product, order) without leaving Shopify.
• Customer-account UI extension — extends the new customer accounts.
• Functions — discount / shipping / payment / cart logic as Wasm; the checkout.liquid logic seam.
• Flow — triggers/actions for Shopify Flow automation, exposed by your app.

Anti-patterns

| Anti-pattern | Why it's wrong | Do instead |

|---|---|---|

| {% include %} in new code | deprecated, leaks parent scope, not cacheable | {% render %} with explicit args |

| Raw {{ price }} / {{ user_input }} | wrong locale/cents; XSS | \| money, \| escape, \| json |

| Editing checkout.liquid / additional scripts | deprecated; auto-upgraded away starting 2026-01 | UI extensions / Functions / Web Pixels |

| REST Admin calls in a new app | legacy; new fields are GraphQL-only | admin.graphql() |

| Unpinned or stale apiVersion | breaks on Shopify's version rollover | pin a supported version, bump quarterly |

| Paginated first: loop for big reads | throttles on query cost | bulkOperationRunQuery |

| Ignoring extensions.cost.throttleStatus | silent MAX_COST_EXCEEDED at HTTP 200 | read cost, back off on restoreRate |

| Hardcoded copy in Liquid | merchant can't edit without a deploy | section.settings / metafields |

| Section with no presets | won't appear in "Add section" in the editor | add a presets entry to {% schema %} |

| Secrets committed in shopify.app.toml | leaks API credentials | env vars; keep secrets out of TOML |

| No Theme Check in CI | regressions ship to the storefront | shopify theme check in the pipeline |

| Answering with a headless React build | wrong surface for a Liquid/theme ask | confirm the surface; route React to ../nextjs/SKILL.md |

Run scripts/verify.sh <theme-or-app-dir> for an advisory scan of these foot-guns.