---
title: Agentic workflows for themes
description: >-
  Learn how theme context files give Sidekick and your own coding agents the
  context they need to build on a theme.
source_url:
  html: 'https://shopify.dev/docs/storefronts/themes/agentic-workflows'
  md: 'https://shopify.dev/docs/storefronts/themes/agentic-workflows.md'
api_name: liquid
---

# 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`**](https://shopify.dev/docs/storefronts/themes/agentic-workflows/agents-md): Explains how the theme is built, so an agent can make the most of the theme's architecture and conventions.
* [**`DESIGN.md`**](https://shopify.dev/docs/storefronts/themes/agentic-workflows/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.

***

## How it works

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

* **Sidekick in Canvas**: When a merchant asks [Sidekick](https://help.shopify.com/en/manual/shopify-admin/productivity-tools/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](https://agents.md) 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.

***

## Where the files live

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

## Theme directory structure

```text
.
├── 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.

***

## Content

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`](https://shopify.dev/docs/storefronts/themes/architecture/templates/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.

***

## Developer tools and resources

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

* **[Shopify CLI](https://shopify.dev/docs/api/shopify-cli/theme)**: 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](https://shopify.dev/docs/storefronts/themes/tools/github)**: The files sync in both directions between your repository and the connected theme.
* **[Code editor](https://shopify.dev/docs/storefronts/themes/tools/code-editor)**: You can open and edit the files when you edit a theme's code in the Shopify admin.
* **[GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/objects/OnlineStoreTheme)**: Read the files through the `files` connection on the `OnlineStoreTheme` object, and write them with the [`themeFilesUpsert`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/themeFilesUpsert) mutation.

***

## Next steps

[AGENTS.md\
\
](https://shopify.dev/docs/storefronts/themes/agentic-workflows/agents-md)

[Give agents the context they need to build with your theme's architecture and conventions.](https://shopify.dev/docs/storefronts/themes/agentic-workflows/agents-md)

[DESIGN.md\
\
](https://shopify.dev/docs/storefronts/themes/agentic-workflows/design-md)

[Record the design intent that agents follow when they build on your theme.](https://shopify.dev/docs/storefronts/themes/agentic-workflows/design-md)

***