AI glossary · Agents and tools
What is AGENTS.md?
Also called: AGENTS.md file, README for agents, agent instructions file
Definition
AGENTS.md is a plain Markdown file in a repository that tells AI coding agents how to work on the project, such as setup and test commands, code style and rules, in an open format that many different agents read.
Explained
How does AGENTS.md work?
Its site calls it “a README for agents”: README.md is for people, and AGENTS.md holds the build steps, tests and conventions an agent needs but a human reader doesn’t. There are no required fields or schema. It is ordinary Markdown, and the agent reads whatever headings you write.
OpenAI released it in August 2025, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation. Tools that read it include OpenAI Codex, Cursor, GitHub Copilot’s cloud agent, Google’s Jules, Devin, Zed, Warp and VS Code. Gemini CLI reads it once you name it in its context.fileName setting.
In a monorepo you can add one per package. The site’s rule is that the closest AGENTS.md to the edited file wins, and an explicit instruction in chat overrides it. Tools apply this differently: Codex joins the files from the repository root down to your folder, up to 32 KiB by default.
Example
A short AGENTS.md
This file follows the sections the AGENTS.md site suggests: setup, testing, conventions and security. It is 111 tokens on OpenAI’s o200k_base tokenizer. Agents load it into context, so like a CLAUDE.md it is paid for on every request; list only what the agent can’t work out from the code.
The site says an agent will try to run the test commands you list and fix failures before finishing, which is why the commands come first.
# Acme API
## Setup
- `pnpm install`, then `pnpm dev` starts the API on http://localhost:4000
## Testing
- Run `pnpm test` before every commit and fix any failures.
- Add or update tests for the code you change.
## Conventions
- TypeScript strict mode; avoid `any`.
- Database changes go in a new file in `db/migrations/`; never edit an old one.
## Security
- Never commit `.env` files or print secrets in logs.Cost and quality
Why use AGENTS.md instead of a file per tool?
One file serves every agent on a team, instead of a separate rules file per tool. Claude Code reads it from v2.1.277 when a project has no CLAUDE.md; to use both, put an @AGENTS.md import at the top of a short CLAUDE.md, so shared rules live in one place and Claude-only rules go below.
Don’t mix up
How is AGENTS.md different from README.md and CLAUDE.md?
- AGENTS.md vs README.md
- A README explains the project to people: what it is, how to install it, how to contribute. AGENTS.md adds the detail agents need, such as exact commands and rules, that would clutter a README. Keep both.
- AGENTS.md vs CLAUDE.md
- CLAUDE.md is Claude Code’s own instructions file and can import other files with
@path. AGENTS.md is the tool-neutral one. Claude Code reads AGENTS.md only when there’s no CLAUDE.md or CLAUDE.local.md in your folder or above it, unless you import it.
FAQ
Questions people ask
Which coding agents support AGENTS.md?
The AGENTS.md site lists, among others, OpenAI Codex, Cursor, GitHub Copilot’s coding agent, Google’s Jules and Gemini CLI, Devin, Windsurf, Zed, Warp, VS Code, Aider, goose, opencode, Amp and Junie. Claude Code reads it from v2.1.277 when there’s no CLAUDE.md. Some need a setting: Gemini CLI uses context.fileName and Aider a read: AGENTS.md line.
Where do you put an AGENTS.md file?
At the root of the repository, next to the README. In a monorepo, add another inside each package that needs its own rules: agents read the nearest one to the files they edit. Codex also reads a personal file from its home folder (~/.codex/AGENTS.md), which applies to all your projects.
Can I rename my existing agent rules file to AGENTS.md?
Yes. The AGENTS.md site suggests renaming the old file and leaving a symbolic link with the old name so tools that expect it still work, for example mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md. On Windows, symlinks can check out as plain text files, so for Claude Code use an @AGENTS.md import in CLAUDE.md instead.
Go deeper
Try it and read more
- Free toolCLAUDE.md GeneratorGenerate a CLAUDE.md and AGENTS.md for your project.
- Free toolAI Rules ConverterConvert Cursor rules, Copilot instructions, Devin Desktop rules and CLAUDE.md.
- Free toolAI Token CounterCount tokens for GPT, Claude, Gemini, DeepSeek, Qwen and more.
- Guide · 13 min readHow to write a good CLAUDE.md, with a complete exampleHow to write a good CLAUDE.md: what to include, what to leave out, how long it should be, where Claude Code loads it from, and a complete annotated example.
Related
Related terms
- CLAUDE.mdCLAUDE.md is a Markdown file of project instructions that Claude Code loads into context at the start of every session, and AGENTS.md is the open, tool-neutral equivalent read by many coding agents.
- AI agentAn AI agent is a program in which a language model works towards a goal by repeatedly choosing a tool to call, reading the result and deciding the next step, until the task is done or a stop condition is reached.
- System promptA system prompt is the set of standing instructions a developer sends with every request to set a model’s role, rules and output format, kept separate from what the user types.
- Context windowA context window is the maximum number of tokens a language model can work with in one request, counting the system prompt, tool definitions, conversation history, documents and the reply it writes.