Skip to main content

Agentic workflows for themes

AI agents can build on a theme faster and more consistently when they know how the theme works and the design intent behind it. Themes carry that context in two Markdown files at the root of the theme:

  • AGENTS.md: Explains how the theme is built, so an agent can make the most of the theme's architecture and conventions.
  • DESIGN.md: Records the theme's design intent, so an agent can extend the design consistently when it builds something new on the theme.

These files are context for agents. They aren't templates, Shopify doesn't render them, and buyers never see them.

Anchor to How it worksHow it works

The same files guide every agent that works on the theme:

  • Sidekick in Canvas: When a merchant asks Sidekick to change their theme in Canvas, Sidekick reads the theme's context files before it makes changes. When a merchant asks for stylistic changes, Sidekick can update DESIGN.md so later changes follow the new direction.
  • Your local agent: When you develop a theme locally, the files are part of your theme directory. Coding agents that support the AGENTS.md format can read them as project instructions. AGENTS.md can point your agent to DESIGN.md before design work.

Because the files travel with the theme, the context that you write locally is the same context that Sidekick reads in the Shopify admin, and the design decisions that Sidekick records come back to you the next time you pull the theme.

Anchor to Where the files liveWhere the files live

Theme context files live at the root of the theme, next to the theme's directories:

Theme directory structure

.
├── AGENTS.md
├── DESIGN.md
├── assets
├── blocks
├── config
├── layout
├── locales
├── sections
├── snippets
└── templates

Every theme supports both files, and both are optional. A theme can include either file, both, or neither.

Anchor to ContentContent

Theme context files are free-form Markdown. There's no required format, outline, or set of headings. Write whatever helps an agent work on your theme. For example, describe the patterns that your theme uses, the rules that an agent might otherwise miss, and the choices that you've already made.

The files have the following requirements:

  • File names: File names are case-sensitive. Name the files exactly AGENTS.md and DESIGN.md. Shopify doesn't save other casings, such as agents.md or Design.md.
  • Location: Shopify supports the files only at the theme root. Files with these names in other theme directories aren't supported.
  • Size: Each file can be up to 50 KB.
Note

The theme-root AGENTS.md file isn't the same as the agents.md.liquid template. The template lives in the templates directory and renders the public /agents.md page that shopping agents read to learn how to transact with a store. The theme-root AGENTS.md file is theme source for coding agents, and it isn't served on the storefront.

Anchor to Developer tools and resourcesDeveloper tools and resources

You can work with theme context files in the same ways that you work with other theme files:

  • Shopify CLI: Version 4.8.4 and higher includes AGENTS.md and DESIGN.md when you run shopify theme pull, shopify theme push, and shopify theme package.
  • GitHub integration: The files sync in both directions between your repository and the connected theme.
  • Code editor: You can open and edit the files when you edit a theme's code in the Shopify admin.
  • GraphQL Admin API: Read the files through the files connection on the OnlineStoreTheme object, and write them with the themeFilesUpsert mutation.

Anchor to Next stepsNext steps

AGENTS.md

Give agents the context they need to build with your theme's architecture and conventions.

DESIGN.md

Record the design intent that agents follow when they build on your theme.

Was this page helpful?