---
title: AGENTS.md
description: >-
  Learn how to use a theme-root AGENTS.md file to give AI agents the context
  they need to build with your theme.
source_url:
  html: 'https://shopify.dev/docs/storefronts/themes/agentic-workflows/agents-md'
  md: 'https://shopify.dev/docs/storefronts/themes/agentic-workflows/agents-md.md'
api_name: liquid
---

# AGENTS.​md

`AGENTS.md` is a Markdown file at the root of a theme that tells AI agents like [Sidekick](https://help.shopify.com/en/manual/shopify-admin/productivity-tools/sidekick) how the theme is built. It gives an agent the context that it needs to make the most of your theme when it builds: how the theme's pieces fit together, which conventions to follow, and which common patterns the theme deliberately avoids.

Without this context, an agent falls back on general knowledge of Shopify themes. That's often enough to write working Liquid, but it isn't enough to follow the patterns that make your theme consistent and maintainable. `AGENTS.md` closes that gap.

**Note:**

`AGENTS.md` isn't the same as the [`agents.md.liquid`](https://shopify.dev/docs/storefronts/themes/architecture/templates/agents-md-liquid) template. The template renders the public `/agents.md` page for shopping agents. The theme-root `AGENTS.md` file is theme source for coding agents, and it isn't served on the storefront.

***

## Location

`AGENTS.md` lives at the root of the theme, outside the theme's directories:

## Theme directory structure

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

The file name is case-sensitive, so name the file exactly `AGENTS.md`. The file can be up to 50 KB. Every theme supports `AGENTS.md`, and the file is optional.

***

## Content

`AGENTS.md` is free-form Markdown. There's no required format or outline, so structure the file in whatever way works best for your theme. Focus on what an agent can't easily work out by reading a few files, and on the mistakes that you want it to avoid.

For example, the base theme that Canvas uses to create new themes includes an `AGENTS.md` that covers the following topics:

* **Non-negotiables**: The short list of rules that every change must follow, such as which theme features the theme doesn't use.
* **Composition model**: How templates, blocks, and snippets fit together, and which file owns each part of a page.
* **Block and snippet contracts**: The shape that every block follows, how blocks expose settings, and when to use a snippet instead.
* **Styling and tokens**: Where styles live, which design tokens to use, and where to find the theme's design intent in `DESIGN.md`.
* **JavaScript**: How the theme structures custom elements and handles events.
* **Translations**: How to add user-facing strings.
* **Decision guide**: Quick answers to common questions, such as whether a new element should be a block or a snippet.

Themes created with Canvas include the base theme's `AGENTS.md`, so you can [pull](https://shopify.dev/docs/api/shopify-cli/theme/theme-pull) one of these themes to see a complete example.

When you write the file, keep the following in mind:

* **Write rules, not tutorials**: Agents already know Liquid and HTML. Spend the file on what's specific to your theme.
* **Explain why**: A rule with a reason helps an agent handle cases that the rule doesn't cover.
* **Keep it current**: Update `AGENTS.md` when your theme's architecture changes, in the same change that introduces the new pattern.

***

## Usage

Agents read `AGENTS.md` before they change the theme:

* **Sidekick in Canvas**: Sidekick reads the theme's `AGENTS.md` and follows it when it makes changes that a merchant asks for.
* **Your local agent**: Coding agents that support the [`AGENTS.md` format](https://agents.md) read the file from your local theme directory as project instructions.

**Note:**

AI agents are non-deterministic. Agents follow the rules in `AGENTS.md` most of the time, but they might sometimes take a different approach. Use the file to shape and guide an agent's reasoning, not as a guarantee that every rule is followed.

Shopify CLI 4.8.4 and higher includes `AGENTS.md` when you run `shopify theme pull`, `shopify theme push`, and `shopify theme package`. The file also syncs through the [GitHub integration](https://shopify.dev/docs/storefronts/themes/tools/github), and you can edit it in the [code editor](https://shopify.dev/docs/storefronts/themes/tools/code-editor). To learn about all the ways to work with theme context files, refer to [Agentic workflows](https://shopify.dev/docs/storefronts/themes/agentic-workflows#developer-tools-and-resources).

***