What Is AGENTS.md?

AGENTS.md is a plain markdown file in your repository that tells coding agents how to work on your project. The official format describes it as:

A README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project.

By its maintainers' count it is used by over 60,000 open-source projects and supported by more than 25 tools, including offerings from OpenAI, Google, Cognition, JetBrains and GitHub. It is the closest thing this space has to a cross-vendor convention.

Why it exists separately from the README

The obvious objection is that a README already explains the project. The distinction the format's authors draw is about audience:

READMEs are for humans: quick starts, project descriptions, and contribution guidelines. AGENTS.md complements this by containing the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README or aren't relevant to human contributors.

That is a genuine split. Your README should not contain the exact incantation to run one test file, which formatter runs on commit, or the reason a particular directory must never be edited by hand. A human contributor asks; an agent guesses. The guess is usually plausible and wrong, and you find out after it has rewritten forty files.

What to actually put in it

The failure mode is a wall of aspirational prose that describes the project's philosophy. Agents follow concrete, checkable instructions and drift away from vague ones.

Commands, verbatim. How to install, build, run one test file, run the whole suite, lint, and typecheck. Exact command lines, copy-pasteable. This is the single highest-value section and the one most often missing.

Project layout, but only where it is non-obvious. Which directory holds what, and specifically which paths are generated and must not be hand-edited — a migrations directory, a compiled schema, a vendored dependency.

Conventions that are enforced. If commits must be conventional, say so. If the codebase uses one test framework and a legacy corner uses another, say which is which. Write the rules a reviewer would actually reject a PR over — not stylistic preferences nobody enforces.

Boundaries. Files never to touch, secrets never to read, commands never to run, external services that must not be called from tests. This is the section people skip and later wish they had written.

How to verify work. What the agent should run before claiming it is done. An agent given a verification command will use it; one without will tell you the change looks correct.

Keep it short and keep it true. A stale AGENTS.md is worse than none, because the agent trusts it. If a documented command has not worked since March, the agent will run it, watch it fail, and start inventing alternatives.

The nesting behaviour worth knowing

In a monorepo, place an AGENTS.md in each package as well as at the root. Agents generally read the nearest one to the files they are editing, so a package can override root conventions with its own — the same inheritance model as configuration files. This handles the common case where one repository contains a Python service and a TypeScript frontend with entirely different tooling.

AGENTS.md and CLAUDE.md

These serve the same purpose and the ecosystem is mid-consolidation. CLAUDE.md is Claude Code's project instruction file; AGENTS.md is the vendor-neutral format that grew up alongside it and has since been adopted broadly.

The practical approach is to keep one source of truth rather than maintaining two files that drift apart within a month. Which one is canonical depends on the tools your team uses — check your tool's current documentation, since support here changes faster than articles about it do. What matters is that the content lives in exactly one place.

Why it works

An AGENTS.md is a prompt. It is loaded into the model's context before the agent starts, and it is subject to every property that governs prompts generally.

Which means the anatomy of a great prompt applies directly: specific beats general, imperative beats descriptive, and an instruction with a checkable outcome beats an aspiration. It also means it consumes context window on every request, so a 2,000-line file is a real cost paid continuously — another argument for keeping it tight.

And it means it inherits a security property. Instructions in a file are instructions the model follows. Content pulled into an agent's context from an untrusted repository is a prompt injection vector: if you point an agent with tool access at a stranger's codebase, you have let that stranger write part of your prompt. Review the AGENTS.md of any repository you would not review the code of.

Getting one written

The fastest way to a good file is to write down what you had to explain the last three times an agent got something wrong in your repo. Those corrections are the content.

Beyond that, how to write your first agent skill covers packaging reusable instructions more formally, what is context engineering covers the broader discipline of deciding what an agent sees, and the AI development pack collects the rest.

The short version

A small markdown file with exact commands, real conventions, hard boundaries, and a way to verify work. Nested per package in a monorepo. Kept short, kept current, kept in one place. It is the cheapest improvement available to anyone using coding agents on a non-trivial codebase, and most repositories still do not have one.

Sources

• AGENTS.md — the open format specification; the README for agents framing, the rationale for keeping it separate from README.md, and the maintainers' figures of 60,000+ projects and 25+ supporting tools