Build Shopify apps and themes with ak:shopify

Use ak:shopify to implement or refine a Shopify app, UI extension, Function, theme, or Admin API integration. The Skill provides patterns for GraphQL, OAuth, session tokens, webhooks, app billing, Liquid, Shopify CLI, and platform-specific testing.

Choose the right Shopify surface

Use ak:shopify when

• You are building an app that integrates services or manages store data.
• You need a checkout, admin, POS, customer-account, or theme app extension.
• You need a Shopify Function for discount, payment, delivery, or validation logic.
• You are changing a Liquid theme, section, snippet, storefront interaction, or theme deployment workflow.

Choose another workflow when

• The task is a generic commerce website without Shopify. Use the appropriate frontend or backend workflow.
• Product, billing, privacy, data-retention, or app-distribution requirements are unsettled. Resolve them before code mutation.
• You only need visual direction for a storefront. Use ak:frontend-design before theme implementation.
• You need an independent review of an existing change. Use ak:code-review, ak:test, or ak:security.

Prepare the store, API version, and tools

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the current runtime and scope.
• Identify whether the target is an app, extension, Function, or theme; do not mix their deployment models implicitly.
• Read the installed Shopify CLI, framework, UI-extension, Liquid, and Admin API versions from the project, then verify current Shopify documentation and deprecations.
• Use a development store, test app, test products/orders, and least-privilege access scopes. Keep API secrets, access tokens, session tokens, webhook secrets, and customer/order data out of prompts, logs, client code, and Git.
• Define allowed files, remote stores, webhook topics, billing behavior, test accounts, and whether CLI login, tunnel creation, store sync, deploy, push, or publish is authorized.

The bundled reference is a January 2025 platform snapshot. Its API versions, extension targets, component APIs, CLI output, and store requirements must be checked against the current project and Shopify’s current contract.

See Runtime adapters for component-level differences.

Run the Skill

The declared argument shape is [extension-type] [feature], but you can name app, function, or theme when those are the actual target.

/ak:shopify "checkout_ui_extension Add an optional gift message to the existing app. Preserve its pinned API version and scopes, validate and store the attribute through current project patterns, add focused tests, use only the development store, and do not deploy or publish."

/ak:shopify "checkout_ui_extension Add an optional gift message to the existing app. Preserve its pinned API version and scopes, validate and store the attribute through current project patterns, add focused tests, use only the development store, and do not deploy or publish."

$ak:shopify "checkout_ui_extension Add an optional gift message to the existing app. Preserve its pinned API version and scopes, validate and store the attribute through current project patterns, add focused tests, use only the development store, and do not deploy or publish."

Observe the Shopify stages

1. The run identifies the exact surface. It maps the current app, extension, Function, or theme layout, generated files, configuration, API version, and store boundary.
2. The run verifies current platform support. Extension targets, GraphQL fields, access scopes, Liquid behavior, CLI commands, and plan restrictions are checked before implementation.
3. The run defines data and security behavior. OAuth state, session tokens, webhook HMAC, customer data, billing confirmation, error states, and cleanup behavior stay explicit.
4. The run implements the smallest local change. It follows existing generated-file rules and project scaffolding rather than replacing the app with a generic reference.
5. The run verifies on the correct boundary. Static checks run locally; development-store, extension, webhook, theme, mobile, and accessibility behavior are checked only with approved test access.
6. The run reports remote effects. Changed files, scopes, generated output, store objects, preview links, CLI sessions, and unperformed deployment or publication steps remain visible.

Keep store mutations and publication under approval

• Request only required access scopes and re-evaluate them when data use changes. Treat customer and order data as sensitive.
• Verify OAuth state and webhook HMAC using the authentic request bytes before processing. Keep webhook handlers idempotent and acknowledge only according to the current Shopify contract.
• GraphQL queries and mutations must handle pagination, user errors, throttling, and versioned schema changes.
• The optional bundled initializer is a lightweight local generator, not official Shopify scaffolding. For app and extension choices it creates or overwrites config, README, and package files inside a same-named directory; for themes it only prints the recommended shopify theme init command.
• shopify app deploy, theme push, live pull, and theme publish are outside a normal local implementation unless separately authorized.

Verify the result

A complete result should provide:

• The chosen Shopify surface, current API/CLI evidence, store identity class without secrets, and user-visible behavior.
• Exact changed and generated files, dependency changes, scopes, webhook topics, GraphQL operations, theme assets, and remote objects.
• Focused typecheck, unit, component, Function, shopify theme check, webhook, development-store, accessibility, and responsive evidence as applicable.
• Evidence for authentication failure, GraphQL user errors, throttling, duplicate webhooks, uninstall/privacy cleanup, billing cancellation, or theme rollback where relevant.
• Confirmation that no live deploy or publish occurred unless explicitly authorized, plus the remaining review and rollout checklist.

Troubleshoot or continue

Continue with ak:frontend-development for embedded React UI, ak:payment-integration for a separately scoped external payment provider, or the Engineer Kit overview for coordinated delivery.

Know the current limits

• The Skill does not grant Partner, Admin, development-store, billing, customer, or App Store access.
• The references do not prove current API fields, plan entitlements, review rules, rate limits, extension availability, or CLI behavior.
• The included examples are partial patterns, not a complete OAuth library, privacy program, billing ledger, webhook queue, theme rollback system, or app review checklist.
• Bundled tests exercise the lightweight initializer, not a real Shopify app, store, extension, Function, theme, webhook, or deployment.
• Stable and beta contain identical Skill content and resources for this release pair. Beta Codex Hook diagnostics do not change this workflow.