Shopify theme workflow and validation

Use this guide before editing and again before returning theme code. Better Design serves the implementation knowledge through get-shopify-guide; no separate agent skill is required.

Inspect before changing files

1. Confirm the theme root and its package or build commands.
2. Read the relevant layout, template, section, block, snippet, locale, and asset files before deciding ownership.
3. Check whether the task affects an unpublished duplicate. Never push or publish to the live theme without explicit approval.
4. Call get-shopify-guide with the exact task or unfamiliar API. Use a topic for a complete guide and a query for focused retrieval.
5. Preserve merchant settings, app blocks, app embeds, analytics hooks, locale keys, and existing template assignments unless the request changes them.

Use Shopify CLI for local theme work

Shopify CLI is the supported local interface for authentication, development previews, theme downloads, pushes, listing themes, opening the editor, packaging, and Theme Check. Confirm the installed version with shopify version and read command help before any state-changing operation.

Common read or local-development commands include:

shopify theme dev --store <store>
shopify theme list --store <store>
shopify theme check --path <absolute-theme-path>
shopify theme package --path <absolute-theme-path>

The theme command surface includes theme init, dev, push, pull, list, info, publish, delete, rename, duplicate, check, console, profile, open, share, package, language-server, and metafields pull. Use shopify help <command> for the installed version's flags instead of relying on memorized options.

General CLI utilities include auth logout, commands, config autocorrect on|off|status, help, search, upgrade, and version. Common flags include --path, --verbose, --no-color, and --reset, but support varies by command.

Shopify CLI may collect anonymous usage statistics. If the user wants to opt out, confirm the current Shopify CLI privacy setting or environment variable in the installed version's documentation before changing their environment.

Commands such as theme push, theme publish, theme delete, sharing a development theme, or changing store state require explicit user approval and a resolved target. Do not infer the store or theme ID.

Validate every changed surface

Run the repository's own checks first, then run Shopify Theme Check at the theme root:

shopify theme check --path <absolute-theme-path>

If the project config enables stricter checks, keep them. Do not disable a rule merely to make the run green. Fix the Liquid, schema, translation, performance, accessibility, or deprecation issue at its source.

Also verify these deterministic conditions:

• Every JSON and {% schema %} body parses.
• Liquid tags and output delimiters are balanced.
• Every render, section, asset, and locale reference resolves to a real file or key.
• Every template section type exists, and each order entry names a section instance.
• New snippets include LiquidDoc contracts.
• Product forms submit variant IDs and prices use money filters.
• Images use current image filters, dimensions, and alt text.
• Customer-facing fixed copy uses locale keys.
• The theme works without JavaScript for essential navigation, product selection, add to cart, cart editing, and checkout handoff.

Preview the unpublished theme on mobile and desktop. Test at least home, product, collection, cart, search, page, and 404 templates, plus empty, loading, unavailable, sold-out, and long-content states relevant to the change.

Resolve failures with documentation

When Theme Check names an unfamiliar object, tag, filter, schema property, or deprecation:

1. Call get-shopify-guide({ query: "<exact error and API name>" }).
2. Open the linked Shopify primary reference when the returned guide says the API is version-sensitive.
3. Fix the smallest cause.
4. Rerun Theme Check.
5. Report any remaining warning and why it cannot be resolved safely.

Do not guess at valid Liquid and do not claim validation when Theme Check did not run.

Primary Shopify sources

• Shopify CLI for themes
• Theme Check
• Theme Check performance checks
• Tools for building themes