How do you write an AGENTS.md file?#
Start with the things an AI coding agent would otherwise have to guess. In most projects, that means build and test commands, code style, testing instructions, security constraints, pull request conventions, and any repository-specific rules that are easy to miss. The file does not need to document the whole codebase. In fact, it is usually better when it does not. If a rule is already obvious from the code, scripts, or configuration, repeating it in AGENTS.md adds context without necessarily helping the agent.
Larger repositories can use nested files. A root AGENTS.md might contain instructions that apply everywhere, while a package deeper in the repository can have a second file for its own build process, tests, or conventions. The general convention is that the nearest file to the code being edited carries the most specific instructions, but tools do not all implement that in exactly the same way. Codex, for example, concatenates instruction files from the root down so that the closer files appear later and can take precedence. GitHub Copilot has its own behaviour in the IDE, including a default restriction on files outside the workspace root.
An explicit instruction in chat can also override repository guidance, depending on the tool. That is why it is worth checking the documentation for the coding agents your team actually uses rather than assuming every implementation follows the same precedence rules.
Which AI coding tools read AGENTS.md?#
Support is now broad enough that AGENTS.md works as a shared starting point across several coding tools, but native support and manual opt-in are not the same thing. The table below shows the main differences.
| Tool | Reads it | What to know |
|---|---|---|
| OpenAI Codex | Yes, natively | Where the file originated. Reads global and project scopes, concatenated root-down. |
| Cursor | Yes, natively | Root and subdirectories; nested instructions combine, with the more specific winning. |
| GitHub Copilot | Yes | Coding agent support since August 2025. In the IDE, files outside the workspace root are off by default. |
| Gemini CLI | Only if configured | Defaults to GEMINI.md; AGENTS.md has to be added to the context filename setting. |
| Claude Code | No | Reads CLAUDE.md. Anthropic documents importing AGENTS.md from it, which is the usual way to share instructions. |
The project site lists 23 compatible tools, but that number includes both native support and tools that need configuration changes. Aider and Gemini CLI, for example, need manual setup.
Where did AGENTS.md come from?#
OpenAI released AGENTS.md in August 2025 as a simple convention for giving coding agents repository-specific instructions. Four months later, the format was contributed to the Agentic AI Foundation at the Linux Foundation alongside Anthropic's Model Context Protocol and Block's goose. Its technical charter was adopted on 8 December 2025, with governance handled by individual maintainers rather than reserved company seats.
The project site says the format is used across 'over 60k open-source projects'. That number has not changed since 8 December 2025, the same day the Linux Foundation used it in its own announcement, so it is best treated as a floor rather than a current count.
What doesn't AGENTS.md fix?#
An AGENTS.md file can make a repository easier for AI coding agents to work in, but simply having one does not guarantee better output. The instructions still have to be accurate, specific, and worth loading into context. A long file full of vague guidance or outdated rules can make things worse by burying the few lines the agent actually needs.
This is where teams often need more discipline than they expect. Every instruction should earn its place. If the agent keeps making a certain mistake, the file may need to change. If a rule no longer affects behaviour, it may be better to remove it. And if the repository itself can be made clearer so that the agent no longer needs a special instruction, that is usually a better fix than adding another paragraph to AGENTS.md.
The same point applies to context size. Every instruction takes up tokens whenever the file is loaded. More context is not automatically better context, especially when important rules are mixed with material the agent could have discovered on its own. AGENTS.md works best when it contains a small set of instructions that genuinely change how the agent works.