llms.txt vs AGENTS.md
Published:
This question gets asked as if it were a choice between two formats. It isn't. They have different readers, describe different things, and are read at different moments — most projects that need one will eventually want both, for unrelated reasons.
The one-sentence difference
- AGENTS.md tells a coding agent how to work inside your repository — build commands, tests, conventions.
- llms.txt tells a model which pages on your website are worth reading when it answers someone's question.
A codebase and a website. An agent writing code and a model answering a user. The only thing the two files share is being plain Markdown at a predictable path.
Side by side
| AGENTS.md | llms.txt | |
|---|---|---|
| Reader | Coding agents | Models answering a user |
| Subject | One codebase | One website |
| Read when | The agent starts work | A question needs your site |
| Lives at | Repo root, and per package | Site root, or a path it covers |
| Contains | Build steps, tests, conventions | Curated links with descriptions |
| Structure | Free-form Markdown | Specified: H1, summary, sections |
| Versioned spec | None published | Yes — v2, August 2026 |
What AGENTS.md actually is
Its own description is "a simple, open format for guiding coding agents", and the site offers a useful analogy: "Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project."
It goes at the root of a repository. In a monorepo you put one in each package, and the agent reads the nearest file in the directory tree — the closest one wins. There is no schema and there are no required fields; the project's own FAQ says it is "just standard Markdown. Use any headings you like." The sections it suggests are project overview, build and test commands, code style, testing instructions and security considerations.
It emerged, per the project, "from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory", and is now stewarded by the Agentic AI Foundation under the Linux Foundation.
What llms.txt actually is
A Markdown file at your site's root — an H1 title, a blockquote summary, then H2 sections of annotated links to the pages that best help a model understand and use your site. It is curation, not coverage: the opposite of a sitemap. It is read at inference time, when someone asks an assistant a question your site can answer. See what is llms.txt for the full picture and how to create one for the format.
So which do you need?
- You maintain a codebase people (or agents) work in. AGENTS.md. llms.txt does nothing for you here — there is no website for a model to navigate.
- You run a site with content worth citing — docs, a product, a blog. llms.txt. AGENTS.md would be describing a repository nobody is asking your site about.
- You are an open-source project with both a repo and a docs site. Both, and they will not overlap: AGENTS.md in the repo for contributors' agents, llms.txt on the docs domain for everyone else's.
Does AGENTS.md replace CLAUDE.md or .cursorrules?
Not according to its own sources. The project says it chose a shared name "rather than introducing another proprietary file", and the only migration it documents is the rename from the singular AGENT.md. In practice the tools coexist: Claude Code still treats CLAUDE.md as primary and falls back to AGENTS.md only when none is present, and Gemini CLI lists AGENTS.md alongside its own file. Expect coexistence, not consolidation.
A note on the adoption numbers
The AGENTS.md site says the format is "used by over 60k open-source projects", linked to a GitHub code search. That is their figure with no published method, so quote it as theirs. Tool support is easier to check, and it is real: OpenAI Codex "reads AGENTS.md files before doing any work"; GitHub's coding agent announced support in August 2025 for a root file and nested ones; Cursor documents it as "a simple alternative to .cursor/rules"; Google Jules "automatically looks for a file named AGENTS.md in the root of your repository"; Claude Code reads it as a fallback when no CLAUDE.md is present, from v2.1.277. One caveat on the compatibility list: Gemini CLI reads it only if you add it to context.fileName yourself — the list means "can be made to read it", not "does by default".
We are no more precious about our own side. We logged every AI crawler reaching this site for 89 days and published the result: 33 fetches of llms.txt against 1,365 of robots.txt. Both of these conventions are young, and anyone telling you either one is already load-bearing is selling something.
If you do publish an llms.txt
Check it before you rely on it — structure against the spec, and whether every link you listed actually resolves. Paste a domain into the validator and it will tell you in a few seconds.