AGENTS.md and DESIGN.md at the root of your Shopify theme. Use AGENTS.md for architecture, implementation rules, and things a coding agent must not accidentally break. Use DESIGN.md for the visual decisions that should survive future changes. Shopify supports both files on themes, and Sidekick in Canvas can read them. Neither file renders on the storefront, replaces your Liquid code, or guarantees that an AI agent will obey every instruction.On this page
Why a theme needs more than code comments
A Shopify theme rarely explains itself in one file. A product template might depend on a custom block, a shared JavaScript controller, a metafield, a checkout-adjacent app, and a styling convention that only the original developer knows. An AI assistant can edit the visible component and miss the contract around it.
Shopify’s Fall ’26 Edition formalizes a better handoff. Two optional Markdown files can travel with the theme and tell Sidekick and compatible local coding agents how to work on it. This is not a new storefront content system. It is project context for the people and agents editing theme source.
Use AGENTS.md for implementation rules
AGENTS.md should answer the questions a new developer would ask before changing code: where product state is managed, which components are shared, which integrations are sensitive, and how changes are tested.
For example, a theme with a custom variant selector might use a short file like this:
# Theme development rules
- Product option changes are handled by assets/product-controller.js.
- Keep variant IDs and selling-plan IDs in sync before cart submission.
- Reuse the existing cart drawer refresh event; do not add a second cart implementation.
- Never hardcode a market currency or customer-specific price.
- Test product forms with one-time and subscription purchases.
- Run Shopify Theme Check and inspect the theme preview before release.
These are example project rules, not Shopify-required headings. The useful part is specificity: a new contributor knows where the behavior lives and what regressions matter.
Use DESIGN.md for the design contract
DESIGN.md should describe visual intent rather than repeat every CSS declaration. Record typography hierarchy, spacing rhythm, responsive behavior, component shapes, image treatment, and deliberate exceptions.
# Design direction
- Product pages are editorial and restrained, not card-heavy.
- Keep primary calls to action visually dominant.
- Use existing design tokens before introducing a new color or spacing value.
- Mobile product controls must remain readable without horizontal scrolling.
- New components should match existing buttons, inputs, and disclosure patterns.
Shopify describes DESIGN.md as the explanation of why a theme looks the way it does. The actual rendered styles still come from theme code and settings. Sidekick may update the design file when a merchant requests a new visual direction, so treat changes to it as source changes worth reviewing.
Where the files live and how they move
Both filenames are case-sensitive. They must be named exactly AGENTS.md and DESIGN.md, placed at the theme root alongside assets, sections, blocks, and templates. Each file can be up to 50 KB. You may include either one, both, or neither.
Shopify CLI version 4.8.4 and later includes these files in shopify theme pull, shopify theme push, and shopify theme package. Shopify’s GitHub theme integration also syncs them, and the Shopify code editor can edit them.
For an existing theme, start with a development copy, add the files, and commit them. Do not rewrite the theme’s JSON templates or Liquid sections merely to adopt the context files. The new Liquid-first architecture announced in Fall ’26 is a separate architectural change.
AGENTS.md is not the public /agents.md page
This naming collision is easy to miss. The root-level uppercase AGENTS.md file is private theme-source context for coding agents. A templates/agents.md.liquid template serves a public /agents.md page intended for shopping agents. They have different audiences and purposes.
Do not put credentials, internal endpoints, or sensitive operational information in either file. A theme’s source can be copied or shared, and the public template is designed to be read by outside agents.
Make the instructions maintainable
Write down durable decisions, not a diary of every edit. Link architectural rules to actual file paths. Remove obsolete instructions when a feature is replaced. When a merchant changes a design in Canvas, pull the theme before beginning local work so your local agent sees the latest DESIGN.md.
These files improve the odds of consistent work, but they are not enforcement. Review diffs and test storefront behavior just as you would for human-authored changes. For a broader handoff process, see moving a Shopify feature between themes without copying unrelated code.
AGENTS.md upgrades my Dawn or Horizon theme to Shopify’s new architecture.” It doesn’t. The files document how an existing theme should be edited. They do not convert JSON templates to Liquid-first templates, change merchant settings, or render new storefront components.How to test this
- Duplicate the theme and add both files at the root with the exact capitalization.
- Use Shopify CLI
4.8.4or newer; pull the theme and confirm both files arrive intact. - Push a harmless wording change to the development theme and pull it again to confirm round-trip syncing.
- If the theme uses GitHub integration, confirm the Markdown diff appears in the repository and does not alter unrelated theme files.
- Ask a compatible coding agent to explain the product-form architecture before making a change; confirm it references the actual rules.
- Make a small visual change in a safe preview and inspect whether the result follows the documented design direction.
- Check product, collection, and mobile storefront previews for unintended changes. The Markdown files alone should not alter rendered output.
- Review any Sidekick-updated
DESIGN.mddiff before the next local theme pull or deployment.
Sources and further reading
- Shopify developer docs: Agentic workflows for themes
- Shopify developer docs: DESIGN.md
- Shopify developer docs: Theme architecture
- Shopify Fall ’26 Edition developer announcement, October 28, 2026
Documentation reviewed October 28, 2026.

