AGENTS.md vs llms.txt
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) | 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 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 — 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 and OpenAPI spec.
- 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 (an access-policy proposal) or 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.