What is an AGENTS.md file?
An open convention, not one tool's feature
AGENTS.md is a plain markdown file, usually sitting at the root of a repository, that gives an AI coding agent the context it needs before it starts making changes. It started as a convention rather than a single vendor's feature, and it has since been adopted across a wide range of coding agents, including OpenAI's Codex, Cursor, and a growing list of others. The idea is simple: instead of every tool inventing its own config format, agents look for one shared, human-readable file and read whatever they find there.
That shared-file idea matters more than any single tool's implementation. A repository maintainer writes one AGENTS.md, and any agent that follows the convention picks it up, without the maintainer having to keep several tool-specific files in sync.
What actually goes in one
An AGENTS.md is essentially a briefing for whichever agent opens the repo next. Common contents include the exact commands to build and test the project, since guessing wrong wastes a run and can leave a half-built tree behind. Coding conventions the agent should follow, like formatting rules, naming patterns, or which directories are generated and should never be hand-edited. And warnings or gotchas: a flaky test to ignore, a migration step that must run before the app boots, a file that looks safe to delete but isn't. None of this is exotic. It's the same context a careful human contributor would want on their first day, written down once so an agent doesn't have to rediscover it by trial and error.
Why markdown, specifically
Markdown is plain text with a handful of formatting marks, like # for headings and - for list items, so it is readable two ways at once. A person can open it in any editor and understand it immediately. An agent can parse it without special tooling, since it's just text. Being plain text also means it lives comfortably in version control: changes to AGENTS.md show up as a normal, readable diff in a pull request, the same as a change to source code. A rich document format, or a proprietary config file, wouldn't offer either of those properties as cleanly.
Who actually writes it
Usually a human, typically whoever set up the project or has the clearest picture of its quirks, writes the first version of AGENTS.md. But it's not necessarily static after that. Because it's just a file in the repo, an agent working in that codebase can update it too, for example adding a note about a command it discovered, or a mistake it made that the next run should avoid. Over time, an AGENTS.md in an actively worked repository can end up being a mix of human-written ground rules and agent-added notes, which is part of why it's worth checking in on periodically rather than treating it as fixed once and forgotten.
How to read one comfortably
Because AGENTS.md is plain markdown, reading it doesn't require anything special. Any text editor opens it fine, you'll just see the raw # and ** marks alongside the words. If the repo is on GitHub, its file browser renders AGENTS.md formatted automatically, headings, code blocks, and lists included, no extra step needed. For a quick formatted look outside GitHub, our own free online viewer renders any markdown file you drag onto it, nothing uploaded. And if you're using Skim to browse the repo locally, it renders AGENTS.md like any other markdown file, with the added benefit of live reload: since agents sometimes edit this file mid-session, as described above, watching it update on screen as the agent works is a genuinely convenient way to follow along.
You don't actually need a special tool
Worth saying plainly: none of this is required. AGENTS.md is plain text, and a plain text editor is a perfectly good way to read it. GitHub's renderer, our viewer, and Skim's live reload are conveniences that make a markdown file easier on the eyes, not prerequisites for understanding one. If Notepad or TextEdit is what you have open, that works too.
For more on reading markdown files that AI tools hand you day to day, see our guide to opening a .md file from Claude or ChatGPT. If your project uses Claude Code specifically, there's a related file worth knowing, CLAUDE.md, which often sits alongside AGENTS.md in the same repo.
FAQ
Is AGENTS.md required?
No. It's an optional convention. A repository without one works fine; an agent just starts with less context and may ask more questions or make more assumptions along the way.
AGENTS.md vs README.md, what's the difference?
A README is written for human contributors and users: what the project does, how to install it, how to use it. AGENTS.md is written for coding agents specifically: build and test commands, conventions, and gotchas an agent needs before editing code. Some projects overlap the two; many keep them separate so the README stays focused on people.
Can I have both AGENTS.md and CLAUDE.md in the same repo?
Yes, and it's common. The two files coexist without conflict: AGENTS.md holds the shared instructions any agent should see, while CLAUDE.md holds notes specific to Claude Code. Many teams have CLAUDE.md import AGENTS.md, with a one-line @AGENTS.md reference, so both stay in sync without duplicating content.