Key Takeaways
- AGENTS.md is an open standard for instructing AI coding agents — a "README for machines" that sits next to README.md rather than replacing it. It was formalised in August 2025 by OpenAI, Google, Cursor, Factory and Sourcegraph.
- Adoption moved fast: by December 2025 more than 60,000 open-source projects had adopted it and 20+ AI coding tools supported it, including GitHub Copilot (native support from August 2025), OpenAI Codex, Cursor, Google Jules and Gemini, Factory, Amp, Windsurf, Zed and RooCode.
- In December 2025 the specification was donated to the Linux Foundation's Agentic AI Foundation, which moved it from a vendor convention to neutral governance.
- It is not an SEO or AI-visibility file. AGENTS.md instructs agents working inside your repository. It does nothing for ChatGPT citing your website. That is
llms.txtterritory, and conflating the two is a common and costly mistake. - The transferable lesson matters more than the file: machine readers now outnumber human readers for some of your content, and they perform better when you write explicit instructions instead of expecting inference.
What AGENTS.md is
AGENTS.md is a Markdown file at the root of a repository that tells AI coding agents how to work in that codebase. It complements README.md rather than replacing it: README targets human developers with an overview and quick start; AGENTS.md carries the detailed technical instructions an agent needs — build commands, test commands, code conventions, directory meanings, things not to touch.
The format was formalised in August 2025 through collaboration between OpenAI, Google, Cursor, Factory and Sourcegraph — notably a cross-vendor effort rather than one company's convention. Before it, every coding assistant wanted its own instruction file, and a repository supporting three agents carried three near-duplicate files that drifted apart.
Adoption followed quickly. GitHub Copilot added native support in August 2025. By December 2025 more than 60,000 open-source projects had adopted the format and more than twenty AI coding tools read it. That month the specification was donated to the Linux Foundation's Agentic AI Foundation, placing it under neutral governance.
The reported practical effect is consistent: agents skip the discovery phase, generated code follows team standards from the first attempt, and review cycles shorten.
What goes in it
There is no rigid schema, which is both the strength and the weakness of the format. What experienced repositories converge on:
- Commands that actually work. The exact build, test, lint and dev commands, including which package manager. Agents guess wrong constantly, and a wrong guess burns a whole turn.
- Conventions. Naming, formatting, file layout, which patterns are house style and which are legacy to avoid copying.
- Directory semantics. What lives where and why. "Generated — do not edit" is one of the highest-value lines you can write.
- Hard constraints. What must never be changed, which files are vendored, which directories are excluded from linting, what requires a migration rather than an edit.
- Verification steps. How an agent should confirm its change worked, especially when there is no test runner.
Two failure modes recur. The first is writing it for humans — prose about project philosophy that an agent cannot act on. The second is letting it rot: an AGENTS.md that describes a build command removed six months ago is worse than no file, because the agent will trust it.
The confusion worth clearing up
A lot of marketing content in 2026 treats AGENTS.md as the next llms.txt. It is not, and the distinction is simple once stated:
AGENTS.md | llms.txt | |
|---|---|---|
Reader | AI coding agents working in your repo | AI crawlers and assistants reading your website |
Location | Repository root | Site root ( |
Purpose | How to build, test and modify this code | What this site contains and where the canonical content is |
Affects AI citations of your site? | No | Possibly — see below |
Governance | Linux Foundation Agentic AI Foundation | Community proposal, no formal standards body |
Adoption | 60,000+ repos, 20+ tools (Dec 2025) | Widely published, inconsistently consumed |
If your goal is for ChatGPT or Perplexity to cite your website, AGENTS.md is irrelevant. Publishing one will not improve your AI visibility by a single citation. If someone sells you AGENTS.md as a GEO tactic, that is a red flag about everything else they are selling.
And to be straight about the comparison: llms.txt is a proposal that many sites publish and few engines demonstrably consume. We have written about whether llms.txt actually works rather than assuming it does. AGENTS.md, by contrast, has verified consumption — twenty-plus named tools read it — because the agents reading it are ones you invited into your repository.
That is the structural difference. AGENTS.md works because the reader is cooperative and you control the context. Web-facing files depend on engines choosing to honour them.
Why a marketing team should still care
Not to publish the file. To notice what it proves.
Machine readers respond to explicit instruction, not inference. The entire reason AGENTS.md works is that stating the build command beats hoping the agent deduces it from package.json. The same holds for your product pages. A model will not infer that your product suits small apartments from a dimensions table — and our grounding-query data shows 58.4% of ChatGPT's self-generated searches contain "best" and 26.9% contain "review", meaning the engine is looking for explicit, pre-digested judgements, not raw specs to reason over.
A canonical source beats scattered truth. AGENTS.md exists because three near-duplicate instruction files drifted apart and agents followed the wrong one. Your price exists in your product page, your feed, your schema markup and three retailer listings. When those disagree, a model's safest move is to drop you. Pick one authoritative source and reconcile to it.
Stale machine instructions are worse than none. An agent trusts AGENTS.md. An assistant trusts your structured data. Wrong-but-confident is the costliest state in both cases — undated and outdated evergreen pages are penalised in retrieval, and 18.2% of ChatGPT's grounding queries explicitly contain a year.
Standards consolidate. Five vendors agreed on one file in under a year and handed it to a foundation. Expect the same compression in the commerce and content layers. Build on the parts that have cross-vendor agreement and verified consumption; treat single-vendor conventions as temporary.
FAQ
Is AGENTS.md an official standard? It is an open specification under the Linux Foundation's Agentic AI Foundation since December 2025, originally formalised in August 2025 by OpenAI, Google, Cursor, Factory and Sourcegraph. That is real neutral governance, though it is not an IETF or W3C standard.
Does AGENTS.md replace README.md? No. README is for humans, AGENTS.md is for agents. Keep both; do not duplicate content between them.
Which tools read it? More than twenty as of December 2025, including GitHub Copilot, OpenAI Codex, Cursor, Google Jules and Gemini, Factory, Amp, Windsurf, Zed and RooCode.
Will AGENTS.md help my AI search visibility? No. It is read by agents inside your repository, not by web crawlers indexing your site. For site-level machine instruction, look at robots.txt (access), structured data (facts) and llms.txt (content map).
Should I publish both AGENTS.md and llms.txt? AGENTS.md if you maintain a codebase that AI agents work in — it has clear, verified value. llms.txt if you want to publish a content map, with realistic expectations about how inconsistently it is consumed.
Where to go next
For the website-facing equivalent, read how to create an llms.txt file for GEO and the more sceptical does llms.txt work. To check whether AI crawlers can reach your pages in the first place — the prerequisite for any of this — use the AI bot access checker.