feat: add 7 agent skills for Shopify app development

Skills focused on mental models, gotchas, and decision trees:
- shopify-functions: Wasm compilation, declarative I/O, execution order
- shopify-graphql-admin: Cost-based rate limiting, GIDs, userErrors, bulk ops
- shopify-app-extensions: Sandbox model, web components not React, 64KB limit
- shopify-checkout-ui: Preact Signals, static vs block targets, no CSS/DOM
- shopify-webhooks: TOML vs API subscriptions, GDPR compliance, idempotency
- shopify-app-auth: Token exchange vs OAuth, session vs access tokens
- shopify-hydrogen: React Router not Next.js, Storefront API, Oxygen hosting

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tizmagik

skills/shopify-app-auth/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: shopify-app-auth
+description: "Decision guide for Shopify app authentication: token exchange, OAuth, credentials, and token types"
+metadata:
+  author: shopify
+  version: "1.0"
+---
+
+# Shopify App Authentication
+
+## Decision Tree: Which Auth Flow?
+
+```
+Is your app embedded in Shopify Admin?
+├─ YES → Token Exchange (recommended)
+│   App Bridge session token → exchange for access token
+│   No redirects. Seamless UX.
+│
+├─ NO (standalone web app) → Authorization Code Grant (OAuth)
+│   Standard OAuth 2.0 redirect flow.
+│   Merchant sees consent screen → redirect back with code → exchange for token.
+│
+└─ Backend-only service (no user interaction) → Client Credentials Grant
+    App acts on its own behalf. No merchant/user context.
+    Limited to app-level permissions only.
+```
+
+## Critical Confusion: Session Tokens vs Access Tokens
+
+These are NOT the same thing. Mixing them up is the #1 auth mistake.
+
+| | Session Token | Access Token |
+|---|---|---|
+| **What** | Short-lived JWT from App Bridge | Credential for calling Shopify APIs |
+| **Issued by** | App Bridge (frontend) | Shopify OAuth endpoint (backend) |
+| **Lifetime** | ~1 minute | Hours (online) or indefinite (offline) |
+| **Used for** | Proving the request comes from an embedded app | `X-Shopify-Access-Token` header on API calls |
+| **Alone?** | Cannot call APIs directly | Yes, this is what calls APIs |
+
+Flow: App Bridge issues session token → your backend receives it → exchanges it for an access token → uses access token to call Admin API.
+
+## Online vs Offline Access Tokens
+
+| | Online | Offline |
+|---|---|---|
+| **Scope** | Per-user (merchant staff) | Per-store |
+| **Lifetime** | Expires within 24 hours | Non-expiring (default) or expiring w/ refresh token |
+| **Use when** | You need user-specific permissions or audit trails | Background jobs, webhooks, most common case |
+| **Token exchange param** | `requested_token_type: urn:ietf:params:oauth:token-type:access_token` | `requested_token_type: urn:shopify:params:oauth:token-type:offline-access-token` |
+
+**Most apps need offline tokens.** Use online only when you need to scope actions to a specific staff member.
+
+## Embedded App Auth (Token Exchange)
+
+1. Frontend: App Bridge automatically provides a session token
+2. Backend: Validate the session token on every incoming request
+3. Backend: POST to `https://{shop}.myshopify.com/admin/oauth/access_token` with:
+   - `client_id`, `client_secret`
+   - `grant_type: urn:ietf:params:oauth:grant-type:token-exchange`
+   - `subject_token: <session_token>`
+   - `subject_token_type: urn:ietf:params:oauth:token-type:id_token`
+4. Use returned access token in `X-Shopify-Access-Token` header
+
+Shopify CLI templates (`shopify app generate`) handle this automatically.
+
+## Scopes
+
+- Declared in `shopify.app.toml` under `[access_scopes]`
+- Requested at install time; merchant grants consent
+- Changing scopes requires re-authorization (merchant sees consent screen again)
+- Example: `scopes = "read_products,write_orders"`
+
+## HMAC Verification
+
+Two contexts where you verify HMAC signatures:
+
+- **Webhooks**: Verify `X-Shopify-Hmac-Sha256` header against raw request body using app client secret (HMAC-SHA256, base64-encoded). The `shopify-app-react-router` library's `authenticate.webhook()` handles this.
+- **OAuth install requests**: Verify `hmac` query parameter by sorting remaining params, computing HMAC-SHA256 with client secret.
+
+Pitfall: You must use the **raw request body** for webhook HMAC. If middleware (e.g., `express.json()`) parses the body first, verification will fail.
+
+## CLI Auth Note
+
+`shopify auth login` opens a browser for human interaction. It cannot be automated or scripted in CI. For CI/CD, use environment variables (`SHOPIFY_CLI_PARTNERS_TOKEN`) or app-level client credentials.
+
+## Documentation
+
+- Overview: https://shopify.dev/docs/apps/build/authentication-authorization
+- Access tokens: https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens
+- Token exchange: https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/token-exchange
+- OAuth code grant: https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/authorization-code-grant
+- Session tokens: https://shopify.dev/docs/apps/build/authentication-authorization/session-tokens
+- Scopes: https://shopify.dev/docs/api/usage/access-scopes

skills/shopify-app-extensions/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: shopify-app-extensions
+description: "Mental models and gotchas for building Shopify app extensions across admin, checkout, POS, and customer account surfaces"
+metadata:
+  author: shopify
+  version: "1.0"
+---
+
+# Shopify App Extensions
+
+## The #1 Mistake: This Is NOT React DOM
+
+Extensions render in an **isolated sandbox** via Remote DOM. There is no `document`, no `window`, no CSS, no arbitrary HTML. You cannot use `<div>`, `<span>`, `<iframe>`, or `<script>` tags.
+
+**What you write** looks like JSX (Preact by default), but **what renders** are Shopify web components (`<s-button>`, `<s-banner>`, `<s-stack>`, etc.). These components inherit merchant brand settings. You cannot override or inject CSS.
+
+```tsx
+// WRONG - agents generate this constantly
+import React from 'react';
+export default function MyExtension() {
+  return <div className="my-class"><button onClick={handleClick}>Click</button></div>;
+}
+
+// RIGHT - Shopify UI components only
+import { AdminAction, Button, Text } from '@shopify/ui-extensions-react/admin';
+export default function MyExtension() {
+  return (
+    <AdminAction title="My Action">
+      <Text>Hello</Text>
+      <Button onPress={handlePress}>Click</Button>
+    </AdminAction>
+  );
+}
+```
+
+Key corrections:
+- `onClick` -> `onPress` (Shopify component API)
+- No `className`, no `style` props
+- No HTML elements — only Shopify components from `@shopify/ui-extensions-react/{surface}`
+- Preact is the default scaffolding, not React. The React-like API is a compatibility layer.
+
+## Extension Surfaces — Decision Guide
+
+| Surface | Use When | Target Prefix |
+|---------|----------|---------------|
+| **Admin** | CRUD workflows, resource management, merchant tools | `admin.` |
+| **Checkout** | Cart modifications, upsells, custom fields, payment logic | `purchase.checkout.` |
+| **Customer Accounts** | Post-purchase, order management, account self-service | `customer-account.` |
+| **POS** | In-store workflows, receipt customization | `pos.` |
+| **Online Store** | Theme app extensions (different model — Liquid blocks, not JS sandbox) | N/A (app blocks) |
+
+Admin sub-types:
+- **Admin Action**: Modal triggered from resource pages (orders, products, customers). Use for transactional workflows.
+- **Admin Block**: Persistent card on resource pages. Use for contextual info display.
+- **Admin Print Action**: Document generation with preview/print APIs.
+
+> Full target catalog: https://shopify.dev/docs/api/admin-extensions
+> Checkout targets: https://shopify.dev/docs/api/checkout-ui-extensions
+
+## Hard Limits & Gotchas
+
+### Bundle Size: 64KB Compressed
+The compiled extension bundle must be under **64KB compressed**. The CLI generates `.metafile.json` (esbuild) to help analyze what's eating your budget. Heavy libraries will blow this limit instantly.
+
+### All Extensions Deploy Together
+`shopify app deploy` creates a single app version containing ALL extensions. You cannot deploy one extension independently. Removing an extension from the codebase does NOT auto-remove it from the app — explicit removal is required.
+
+### Extension-Only Apps Use Custom Distribution Only
+Apps with no web server (extension-only) cannot be listed on the Shopify App Store. They must use custom distribution (direct install links).
+
+### Some Extensions Require Review
+Certain extension types require Shopify review before release. You cannot deploy an app version containing reviewable extensions until approved.
+
+### No Direct Network Access in Some Surfaces
+Checkout extensions cannot make arbitrary fetch calls. Use the `fetch` API provided by the extension API, which is proxied and restricted.
+
+## Configuration: shopify.extension.toml
+
+Every extension has a `shopify.extension.toml` in its directory. This defines the extension type, targets, metafields access, and capabilities.
+
+```toml
+# Example: extensions/my-action/shopify.extension.toml
+api_version = "2025-01"
+[[targeting]]
+  module = "./src/ActionExtension.tsx"
+  target = "admin.product-details.action.render"
+```
+
+> Per-type TOML schemas: https://shopify.dev/docs/apps/build/app-extensions
+
+## CLI Workflow
+
+```bash
+# Scaffold a new extension (interactive — picks type and surface)
+shopify app generate extension
+
+# Start dev server with hot reload
+shopify app dev
+
+# Deploy all extensions as a new app version
+shopify app deploy
+```
+
+The CLI knows about these extension types (from source `specifications/`):
+`ui_extension`, `checkout_ui_extension`, `checkout_post_purchase`, `pos_ui_extension`, `function`, `theme`, `web_pixel_extension`, `flow_action`, `flow_trigger`, `flow_template`, `payments_app_extension`, `product_subscription`, `tax_calculation`, `editor_extension_collection`
+
+## Documentation Pointers
+
+- Extensions overview: https://shopify.dev/docs/apps/build/app-extensions
+- Admin extensions: https://shopify.dev/docs/apps/build/admin
+- Admin components API: https://shopify.dev/docs/api/admin-extensions/components
+- Checkout extensions: https://shopify.dev/docs/api/checkout-ui-extensions
+- Functions (backend logic): https://shopify.dev/docs/apps/build/functions
+- Extension TOML config: https://shopify.dev/docs/apps/build/app-extensions/configuration

skills/shopify-checkout-ui/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: shopify-checkout-ui
+description: "Constraints, gotchas, and mental model for building Shopify Checkout UI Extensions"
+metadata:
+  author: shopify
+  version: "1.0"
+---
+
+# Shopify Checkout UI Extensions
+
+## Mental Model
+
+Checkout is the highest-stakes surface in commerce. Bugs here lose revenue. Extensions run in a **sandboxed Web Worker** -- there is no DOM, no `window`, no `document`, no `<script>` tags, no arbitrary HTML. Only Shopify-provided components render. The platform controls layout, accessibility, and branding. You write logic and declare UI; Shopify renders it natively.
+
+## Components Are Web Components (`<s-*>`), Not React DOM
+
+- All UI uses custom HTML elements: `<s-text>`, `<s-button>`, `<s-stack>`, `<s-grid>`, `<s-box>`, etc.
+- These are **not** React components. They follow standard web component property/attribute patterns.
+- Preact is the default framework. Use Preact hooks (`useState`, `useEffect`) and JSX with `<s-*>` elements.
+- In JSX, props that match an element property are set as properties; otherwise as attributes.
+- Event handlers use camelCase in JSX (`onClick`, `onInput`, `onChange`). Under the hood they become `addEventListener` calls.
+- Form inputs return **string** values, even for numeric fields. Multi-selects use a `values` prop (string array).
+- `<s-clickable>` is an escape hatch; prefer `<s-button>` and `<s-link>` first.
+
+## Data Access: Preact Signals, Not Hooks
+
+- The global `shopify` object exposes all checkout APIs.
+- APIs with a `value` property are **Preact Signals** (e.g., `shopify.shippingAddress.value`). Preact auto-re-renders when signals change.
+- Do NOT use React-style hooks for checkout data. Read from `shopify.*` signals directly.
+
+## Static vs Block Targets
+
+| Type | Behavior | Use When |
+|------|----------|----------|
+| **Static** | Tied to a core checkout feature (e.g., before/after shipping methods). Disappears when that feature is hidden. | Content is tightly coupled to a checkout step. |
+| **Block** | Merchant-positionable in the checkout editor. Always renders regardless of which features are active. | Content is independent (e.g., order notes, banners, loyalty points). |
+
+- Register targets in `shopify.extension.toml` via `[[extensions.targeting]]`.
+- Block targets support multiple placements with placement references (`INFORMATION1`, `DELIVERY1`, `PAYMENT1`, etc.).
+- One extension can support multiple targets, but each target needs its own `module` file with a `default export`.
+
+## 64 KB Compressed Bundle Limit
+
+- Hard limit enforced at **deploy time** -- `shopify app deploy` will fail if exceeded.
+- This means: no large libraries, no bundled CSS frameworks, no heavy GraphQL clients with DOM dependencies.
+- Analyze with `shopify app build` and check output size. Keep dependencies minimal.
+
+## Network Constraints
+
+- **No arbitrary `fetch`** by default. Extensions run in a Web Worker with restricted network access.
+- **Storefront API**: Enable `api_access` capability in TOML. Use the `query()` helper or the global `fetch` (auto-authenticated). Available scopes are unauthenticated read-only (products, collections, metaobjects, selling plans).
+- **External network calls**: Require `network_access` capability AND Partner Dashboard approval. Your server **must** respond with `Access-Control-Allow-Origin: *` (CORS for any origin). The worker origin may change without notice.
+- **Prefer metafields over network calls**: Use Admin API to write metafields ahead of checkout, then read them via `appMetafields` in the extension. Faster, no external call needed.
+- Session tokens prove claim integrity but do NOT prove the request came from Shopify. Never expose sensitive endpoints that trust only a session token.
+
+## No CSS Overrides
+
+- Components inherit the merchant's brand settings automatically.
+- You **cannot** override or inject CSS. There is no style API.
+- Layout control is through component props only: `<s-stack>`, `<s-grid>`, `<s-box>` with `gap`, `padding`, `direction` props.
+- Scale uses middle-out naming: `small-300 < small-100 < base < large-100 < large-300`.
+- Responsive values use container query syntax: `@container (inline-size > 500px) large, small`.
+
+## Other Critical Gotchas
+
+- **Shopify Plus only**: Extensions in the information, shipping, and payment steps require Shopify Plus.
+- **`block_progress` capability**: Must be declared in TOML for validation that blocks checkout. Merchants can disable it -- check `extension.capabilities` at runtime and show a warning fallback.
+- **Settings**: Up to 20 fields per extension, configured in TOML. All settings are optional from the merchant's perspective -- code defensively.
+- **Metafields**: Declare needed metafields in TOML. Use `$app` prefix for app-owned metafields. Only specific resources supported: cart, customer, product, variant, shop, company, companyLocation, shopUser.
+- **No DOM APIs**: GraphQL clients like Apollo that use DOM APIs will not work. Use lightweight alternatives or the built-in `query()` helper.
+
+## Documentation Pointers
+
+| Topic | URL |
+|-------|-----|
+| Overview & getting started | https://shopify.dev/docs/api/checkout-ui-extensions |
+| Extension targets reference | https://shopify.dev/docs/api/checkout-ui-extensions/extension-targets-overview |
+| Web components (UI library) | https://shopify.dev/docs/api/checkout-ui-extensions/using-polaris-components |
+| Configuration (TOML) | https://shopify.dev/docs/api/checkout-ui-extensions/configuration |
+| Checkout APIs | https://shopify.dev/docs/api/checkout-ui-extensions/apis |
+| Tutorials & use cases | https://shopify.dev/docs/apps/build/checkout |
+| Bundle size analysis | https://shopify.dev/docs/apps/build/app-extensions#analyzing-bundle-size |
+| Figma UI kit | https://www.figma.com/community/file/1554582792754361051 |