The complete guide to AGENTS.md

AGENTS.md is an open convention: a plain-Markdown file, placed at your repository root, that gives coding agents the operating instructions they need before they touch your code. Think of it as a README written for the machine instead of the newcomer - build and test commands, code style, project layout, and the rules that are obvious to your team but invisible to an agent.

There is no required schema and no special syntax. It is standard Markdown with headings, so anything you would explain to a new engineer in their first hour belongs in it. The value is that you write it once and many different agents read the same file.

Keep it scannable - agents, like people, skim. A useful AGENTS.md usually covers a handful of concrete, verifiable things:

The primary file sits at the repository root, where agents look first. For a monorepo, you can also place additional AGENTS.md files inside individual packages or directories - the agent uses the closest file to the code it is editing, so a package can override or extend the root instructions with its own commands and rules.

Because it is committed to the repo, AGENTS.md travels with the code and applies to every developer and every agent working in that tree - unlike an IDE setting that lives only on one machine.

The point of AGENTS.md is cross-tool reach. It started across agents like OpenAI Codex, Cursor, and Jules, and is now stewarded by the Agentic AI Foundation under the Linux Foundation, with a broad and growing set of tools that read it. Write it once, and many agents pick it up.

The notable exception is Claude Code, which reads CLAUDE.md and does not fall back to AGENTS.md automatically. The common fix is a CLAUDE.md that imports AGENTS.md (via an @AGENTS.md import or a symlink), so both share one source of truth. See our AGENTS.md vs CLAUDE.md vs llms.txt comparison for the full picture.

An AGENTS.md file is only useful while it is true. The moment someone changes the test runner, renames a package, or swaps a build step without updating the file, the agent starts running the wrong commands - confidently, and at scale.

This is the same documentation drift that hits any README or wiki, except the reader is a machine that will not sense something is off. The durable fix is to treat AGENTS.md as living documentation: tie it to the source of truth, check it when code merges, and correct it through normal review rather than a quarterly cleanup.