## Two files, two jobs

Both live at your root, both address agents, and they answer different questions:

| | llms.txt | AGENTS.md |
|---|---|---|
| Answers | "What is here?" | "How should you behave here?" |
| Shape | Markdown link index with one-line summaries | Freeform markdown instructions |
| Born in | Documentation sites ([llmstxt.org](https://llmstxt.org)) | Code repositories, for coding agents |
| Read by | Agents orienting on a site | Agents about to *do work* in a context |
| Analogy | A site map for machines | A README addressed to the machine |

[llms.txt](/kb/llms-txt) is a curated index: key URLs with one-line descriptions, so an agent learns your surface in one fetch. **AGENTS.md** is prose instructions: conventions, do's and don'ts, how to run things — the file coding agents look for in a repository before touching it, now spreading beyond repos.

## Why storefronts suddenly have AGENTS.md

Shopify made the convention mainstream on the storefront web: every Shopify store now serves a default `/agents.md`, and — per [Shopify's own theme docs](https://shopify.dev/docs/storefronts/themes/architecture/templates/llms-txt-liquid) — **Shopify manages /llms.txt by mirroring the content of /agents.md**, with `/llms-full.txt` pointing the same way. Merchants override any of the three with Liquid templates (`templates/agents.md.liquid`, `templates/llms.txt.liquid`, `templates/llms-full.txt.liquid`). One instruction file, three doors.

That design choice is telling: when forced to pick a single source of truth, Shopify picked the *instructions* file and generated the *index* from it.

## Which should you ship?

- **You have documentation or an API** → llms.txt first. Index your key pages and cross-reference your [MCP endpoint](/kb/mcp) and [OpenAPI spec](/kb/openapi).
- **Agents transact or operate on your site** (checkout, booking, support flows) → add AGENTS.md with behavioral instructions: what agents may do, rate expectations, where the machine-readable paths are.
- **Both is the safe default.** They cross-reference cleanly: llms.txt links AGENTS.md as "operating instructions," AGENTS.md links llms.txt as "the index."

Don't confuse either with [agents.txt](/kb/agents-txt) (an access-policy proposal) or [robots.txt](/kb/robots-txt) (crawl permissions). Four root files, four jobs: permission, policy, index, instructions.

## FAQ

### Is AGENTS.md a standard?

It's a convention, not a specification — there is no formal spec body behind it. Its strength is adoption: coding agents look for it in repositories, and Shopify serves it by default for every storefront.

### Does AGENTS.md replace llms.txt?

No — they answer different questions, and Shopify's mirror design shows how they coexist: instructions as the source, index as a view. A site with only AGENTS.md loses the one-fetch link index; a site with only llms.txt gives agents no behavioral guidance.

### Does AgentGrade check AGENTS.md?

The scanner's discovery checks center on llms.txt, which remains the wider convention for the "what is here" job — and on whether it cross-references your other machine files. [Scan your site](/) to see what your root files currently tell an agent.

## Related

- [llms.txt — the full guide](/kb/llms-txt)
- [Does llms.txt actually work?](/kb/does-llms-txt-work)
- [agents.txt](/kb/agents-txt)