How do you write an AGENTS.md file?#
The file sits at the root of the repository, and large codebases add more of them further down: a monorepo can ship one per package, and the project's own site notes that OpenAI's main repository had 88 of them at the time of writing. There are no required fields. The site's answer to that question is that the file "is just standard Markdown", so headings are a convention rather than a contract. What most teams put in one is the same handful of things: build and test commands, code style, testing instructions, security constraints and pull request conventions.
Precedence is where the convention and the implementations come apart. The site's rule is that the nearest file to the edited code wins and an explicit instruction in chat overrides everything. Codex does something different in practice, concatenating files from the root down so that closer files win by appearing later in the prompt, and GitHub Copilot turns support for files outside the workspace root off by default in the IDE. Nesting works, and it does not work identically everywhere.
Which AI coding tools read AGENTS.md?#
| 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 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 fix |
Verified against each vendor's own documentation, 16 September 2026. The project site lists 23 compatible tools, which counts native support and manual opt-in together; Aider and Gemini CLI both need a configuration change.
Where did AGENTS.md come from?#
OpenAI released the format in August 2025 and gave it away four months later. It was one of three anchor contributions to the Agentic AI Foundation at the Linux Foundation in December 2025, alongside Anthropic's Model Context Protocol and Block's goose, and its technical charter was adopted on 8 December 2025. Governance sits with individual maintainers rather than reserved company seats.
The site says "over 60k open-source projects", and that string has not changed since 8 December 2025, which is the same day the Linux Foundation used the same number in its announcement. Treat it as a floor observed nine months ago rather than a current count.
Where does AGENTS.md sit in context engineering?#
It is one channel among several. Context engineering covers everything an agent sees — what it retrieves, which rules and prior decisions reach it, how history is summarised, and what it is deliberately not shown. AGENTS.md carries the part that should be read every time: the conventions of this repository. Material that varies per task belongs in retrieval, and material that is only true today belongs nowhere near a file that is committed.
What doesn't AGENTS.md fix?#
A good file is also not a guarantee of good output. Josh Mock argues that the file's presence now reads to some engineers as a signal that "the agents have been here", before concluding it is still the best defence a maintainer has. Tessl's Simon Maple makes the sharper point: research showing context files do not reliably help is evidence that "unvalidated context is useless, and often harmful", rather than evidence against the format. Nobody tests whether the instructions in these files earn their place, and until a team does, an AGENTS.md is a hypothesis.