Drop an AI coding agent into a repo with no guidance and it does what a new hire would: guesses your build command, invents a code style, and occasionally edits the one file it should never touch. AGENTS.md fixes that by writing the rules down where the agent looks first. It is a small file with an outsized effect on how reliable an agent feels.
What Is AGENTS.md?
Short answer. AGENTS.md is a markdown file in your repository root that tells AI coding agents how to work there: how to build and test, which conventions to follow, and what never to touch. It is a README written for an agent rather than a human, and it gets read into the model’s context before it starts a task.
The idea spread because it solves a concrete pain: agents are capable but context-blind. They cannot infer that you use pnpm not npm, that /generated is off-limits, or that tests sit beside source. Put those facts in one predictable place and the same model behaves markedly better. No new runtime, no SDK, just markdown an agent reads.
What to Put in an AGENTS.md
The rule of thumb: write down the things an agent gets wrong without being told.
- Commands. Exact build, test, lint, and run commands. Copy-pasteable, not described.
- Structure. Where things live and what each area is for.
- Conventions. Language, formatting, naming, how to write tests.
- Guardrails. Files and folders never to edit, secrets never to touch, patterns to avoid.
pnpm test before claiming done; never edit files in /generated” changes behavior.AGENTS.md vs CLAUDE.md vs README
| AGENTS.md | CLAUDE.md | README | |
|---|---|---|---|
| Audience | AI agents | AI agents (Claude tools) | Humans |
| Tone | Imperative rules | Imperative rules | Explanatory |
| Includes | Commands + guardrails | Commands + guardrails | Overview + setup |
| Scope | Vendor-neutral | Tool-specific origin | Universal |
They are not mutually exclusive. CLAUDE.md was an early, tool-specific version of the same idea; AGENTS.md is the vendor-neutral name the ecosystem is settling on. Plenty of repos keep a human README and an agent-facing AGENTS.md side by side, and some symlink CLAUDE.md to it so every tool finds the same instructions.
Which Agents Read It?
Coding agents and agentic IDEs increasingly look for a root instruction file by convention and load it before they act. Exact filename support still varies and is consolidating, which is the whole reason the community pushed for one shared name. The safe move: keep the file, check your tool’s docs for the name it expects, and symlink alternates so nothing misses it.
How AGENTS.md Connects to OKF
AGENTS.md is the single-file, single-repo version of a much bigger pattern: give an agent curated markdown to read before it works. Google’s Open Knowledge Formatgeneralizes that into a portable, multi-file format for any kind of knowledge, from “how to work in this repo” to “what this metric means” or “how these systems connect.” Google explicitly lists the AGENTS.md family as part of the pattern OKF formalizes. Same instinct, wider scope.
AGENTS.md is for agents that write code. If you want an agent that does business work (answering customers, enriching records, following up), TinyAgents gives you one with knowledge and tools built in. No repo, no code. Free to start.
Build an agent without the repoFrequently Asked Questions
What is AGENTS.md?
AGENTS.md is a plain markdown file in the root of a code repository that tells AI coding agents how to work there: how to build and test, the conventions to follow, and what never to touch. It is sometimes called a README for agents. The point is to put the instructions a model needs in one predictable place instead of scattering them across docs and tribal knowledge.
What is the difference between AGENTS.md, CLAUDE.md, and README?
A README is written for humans onboarding to a project. AGENTS.md is written for AI agents doing work. It is more imperative and includes exact commands and guardrails. CLAUDE.md is the same idea, originally specific to Claude-based tools; AGENTS.md is the vendor-neutral name the ecosystem is converging on. Many repos keep a short README for people and an AGENTS.md for agents.
What should I put in an AGENTS.md file?
The things an agent gets wrong without being told: the exact build, test, and lint commands; project structure and where things live; code style and naming conventions; and hard rules: files or directories never to edit, secrets never to touch, patterns to avoid. Keep it concrete and imperative. Vague guidance produces vague behavior.
Which AI agents read AGENTS.md?
Coding agents and agentic IDEs increasingly look for it by convention, reading the file into context before the agent starts work. Support for the exact filename varies by tool and is still consolidating, which is why the community has rallied around one name. Check your specific tool's docs, but the pattern of a root-level markdown instruction file is now near-universal.
Is AGENTS.md the same as the Open Knowledge Format?
No, but they are relatives. AGENTS.md is one file telling an agent how to work in one repo. OKF generalizes the same instinct (knowledge as markdown an agent reads first) into a portable, multi-file format for any domain, with a required type field and a link graph. Google explicitly names the AGENTS.md family as part of the pattern OKF formalizes.