AGENTS.md: The One File That Rules Your AI Agent
AGENTS.md is the instruction file 60,000+ repos use to tell agents how to work. What goes in it, what to leave out, and how to write your first one.
AGENTS.md is a plain Markdown file that sits in your project and tells an AI agent how to work on it — build commands, test commands, conventions, and the traps that waste its time. One file, read automatically, at a path the agent already knows to look for.
It has become the closest thing the industry has to a standard for this job: adopted across tens of thousands of open-source repositories, read by most major coding agents, and now stewarded by the Agentic AI Foundation under the Linux Foundation. If you run an agent against anything you care about, this is the cheapest quality upgrade available to you.
Why not just put it in the README
A README is written for humans arriving cold. An AGENTS.md is written for a machine that will run commands and then live with the consequences.
The split matters because the two documents want opposite things. A README should stay short and welcoming. An agent file should be dense and specific — the exact test invocation for one package, the fact that the dev server needs a migration first, the one directory that must never be edited by hand. Putting that in a README buries the human quick-start under machine plumbing.
The official project puts it well: AGENTS.md gives agents "a clear, predictable place for instructions" so READMEs can stay focused on human contributors.
What actually goes in the file
The format is deliberately unopinionated — there are no required fields, no schema, no validator. That freedom is why the file works and also why most first drafts are useless. A few sections carry almost all the value:
| Section | What to write | Why it pays off |
|---|---|---|
| Project overview | One short paragraph: what this is, what it is not | Stops the agent inferring architecture from filenames |
| Build and test commands | The literal command, per package if needed | Removes the trial-and-error phase entirely |
| Code style | Only the rules a linter does not already enforce | Linters cover formatting; you cover judgement |
| Testing expectations | "Add or update tests for the code you change" | The single highest-value line in most files |
| Security and caution | Paths, secrets or operations that are off-limits | Turns a silent mistake into a non-event |
Notice what is missing: a personality brief, a list of everything the project does, a restatement of the framework's docs. An AGENTS.md is not a knowledge dump. It is the set of things a competent contractor would need on day one that they cannot get from reading the code.
A worked example
The official sample is a good template because it is unexciting:
# AGENTS.md
## Dev environment
- Use `pnpm dlx turbo run where <project>` to jump to a package.
- Run `pnpm install --filter <project>` before touching its deps.
## Testing
- Find the CI plan in `.github/workflows`.
- Run `pnpm turbo run test --filter <project>` for every check.
- After moving files, run `pnpm lint --filter <project>`.
## PR instructions
- Title format: `[<project>] <Title>`
- Always run `pnpm lint` and `pnpm test` before committing.
Every line is a command or a rule with a command behind it. Nothing is aspirational. That is the bar.
How to write your first one
- Start from a failing session. The next time an agent fumbles something — wrong test command, edits the wrong file, misses a migration — write down that exact correction. Three or four of those are your first draft.
- Write commands, not descriptions. "Run the tests with
pnpm test" beats "the project has a comprehensive test suite". The agent can run the first one. - Put it at the repository root. Root is the predictable location every tool checks.
- Add nesting only where it earns its keep. Large monorepos use nested AGENTS.md files, so a package's own rules are read when working inside it. OpenAI's Codex repository reportedly ships dozens of them. Start with one.
- Revisit it after big changes. A stale instruction file is worse than none, because the agent will confidently follow it.
The portability trick, and its limits
The reason AGENTS.md spread is that it is not proprietary. One file works across a growing ecosystem — Codex, Cursor, Amp, Jules, Copilot, Aider and others.
That was not always true of Claude Code, which reads its own CLAUDE.md. That gap closed on 18 September 2026, when Anthropic added AGENTS.md support: with no CLAUDE.md present, Claude Code now falls back to AGENTS.md.
Practical advice for the two-file world: keep the substance identical and let each file carry only the tool-specific extras. If you already have AGENT.md in the singular, the official FAQ suggests renaming and symlinking for backward compatibility:
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
One caveat worth knowing: a file that tells the agent how to run tests does not make the agent run them. Whether test commands execute automatically is a setting in the tool, not a property of the Markdown.
This is not only for code
The pattern generalises further than its origin. Any agent you give work to benefits from a small, inspectable file of standing instructions sitting next to the work.
Wolffish takes this literally: the agent's behaviour, preferences and accumulated knowledge live as plain Markdown you can open and edit, so "why did it do that" is answered by reading a file rather than by guessing at a prompt. The repository this post is published from carries its own AGENTS.md for exactly this reason — the same document pattern, pointed at a website instead of a service.
If you want the personal-agent version of the idea, start with how to prompt an agent properly, then move the standing parts into a file. That is the whole trick: prompts are what you say once, instructions are what you should only have to say once.
Takeaway
AGENTS.md is a Markdown file at a predictable path that tells an agent how to work: literal commands, real conventions, and the traps you already fell into. There are no required fields, so quality comes entirely from specificity — write commands rather than descriptions, start from your own agent's mistakes, and trim anything that is not a command or a rule. One good file beats any amount of re-prompting.
