AGENTS.md is a convention rather than a tool: a Markdown file at the root of a repository holding the instructions a coding agent needs. The site’s framing is the clearest summary available — it is “a README for agents.”
The distinction it draws is the point. “README.md files are for humans,” the site states, and AGENTS.md exists so that build quirks, test invocations and house conventions have somewhere to live without cluttering the file a new human contributor reads first.
There is no schema
The most common question has a short answer. Asked whether any fields are required, the site says: “No. AGENTS.md is just standard Markdown.”
Suggested sections are a project overview, build and test commands, code style, testing instructions and security considerations, with commit or pull request guidelines, security gotchas, large datasets and deployment steps all named as reasonable inclusions. But nothing is mandatory, and there is no parser to satisfy.
That is a deliberate design choice, and it is why adoption has been fast: the file costs nothing to add and degrades gracefully. An agent that does not understand it ignores it.
The precedence rule is the part worth memorising
For monorepos, one line in the documentation settles the behaviour that otherwise causes confusion:
“The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.”
Nested files are supported, so a subproject can carry its own conventions, and agents read the nearest file up the directory tree. Two consequences follow. First, a root file should hold only what is true everywhere — anything stack-specific belongs next to the code it describes, or it will be overridden unpredictably. Second, nothing in the file outranks what you type in the session; the file sets defaults, not constraints.
Who is behind it
This matters more than it might appear for a convention whose whole value is that multiple tools honour it. The site says AGENTS.md emerged from collaboration across the ecosystem — OpenAI Codex, Amp, Jules from Google, Cursor and Factory among the contributors — and that it is now stewarded by the Agentic AI Foundation under the Linux Foundation.
Neutral stewardship is the difference between a shared standard and one vendor’s file format that others tolerate. It is the strongest signal that writing one is not wasted effort.
Adoption figures on the site: “used by over 60k open-source projects,” with 23 named tools reading it, including Codex, Jules, Aider, Cursor, GitHub Copilot’s coding agent, VS Code and Gemini CLI. Note that Gemini CLI and Aider need configuration to pick it up — the FAQ shows how — so “supported” does not always mean automatic.
What to actually put in it
The suggested section list is sound, but the useful filter is narrower: write down what an agent cannot infer from the repository and will otherwise get wrong.
That means the test command when it is not the obvious one, the reason a lint rule exists, the directory that looks dead but is generated, the deploy step that must run in order, the file nobody should edit by hand. It does not mean restating your stack — the agent can read package.json.
The failure mode is a file that grows into documentation nobody maintains. Every line is context that will be loaded on every task, so a short accurate file beats a long aspirational one.
Worth adopting
Yes, with very little hesitation. The cost is one file of standard Markdown, the format has neutral governance, and more than twenty tools already read it. If you currently maintain tool-specific instruction files, AGENTS.md is the version that survives switching agents — which, given how fast this tooling moves, is the practical argument.
Start with your build and test commands and the two conventions a newcomer always breaks. Add the precedence rule to your mental model if you work in a monorepo, and keep the root file to what is genuinely universal.
