AGENTS.md
The AGENTS.md File, Explained
A README for coding agents: one plain-Markdown file at your repo root that tells every AI tool how to build, test, and follow the conventions of your project. Here is the format, a copy-ready example, and a free generator.
The big idea
One open Markdown file that every coding agent reads
It is just Markdown
A plain AGENTS.md file at your repo root. No required fields, no schema — use whatever headings make sense for your project.
One file, every agent
Codex, Cursor, Copilot, Jules, Aider, Gemini CLI, Zed, and 40+ tools read the same AGENTS.md. Stop maintaining a different rules file per tool.
A README for agents
READMEs are for humans. AGENTS.md holds the build steps, test commands, and conventions an AI needs — without cluttering the README.
What AGENTS.md Is — and Why It Exists
A README.md is for humans: a quick start, what the project does, how to contribute. But coding agents need a different, often more detailed kind of context — the exact build steps, the test commands, the conventions to follow — that would clutter a README or simply isn't relevant to human contributors.
AGENTS.md gives agents a clear, predictable place to find that guidance. It is plain Markdown, lives at the root of your repository, and has no required fields — you write whatever headings help an agent work effectively. Crucially, it is a single open format: rather than maintain a separate rules file for every tool, you write one AGENTS.md and the whole ecosystem reads it. Over 60,000 public repositories already ship one.
It is one of the core Markdown-for-AI files — alongside llms.txt — and a good example of why Markdown is the format AI tooling keeps reaching for: it is readable, token-efficient, and preserves structure.
A Complete Example
Here is a realistic AGENTS.md. Notice there is nothing special about the syntax — it is just headings, lists, and inline code. Pick the sections that matter for your project and skip the rest.
# My Project
## Project overview
A TypeScript monorepo. Apps live in apps/, shared
code in packages/. Start with apps/web.
## Dev environment tips
- Run `pnpm install` at the root to set up all packages.
- Use `pnpm dev` to start the local server on :3000.
## Build and test commands
- `pnpm build` — production build, must pass clean.
- `pnpm test` — run the full Vitest suite.
- `pnpm lint` — ESLint + TypeScript checks.
## Code style
- TypeScript, 2-space indent, no semicolons.
- Match the style of the surrounding code.
## Testing instructions
- Add or update tests for any code you change.
- Fix all test and type errors before finishing.
## PR instructions
- Title format: [<area>] <Short description>
- Run `pnpm lint` and `pnpm test` before committing.What to Include
There are no required fields, so think of these as a menu, not a checklist. Add what helps an agent ship correct changes; leave out the rest.
| Section | Why it helps |
|---|---|
| Project overview | What the project is and how the code is laid out, so the agent orients itself before editing. |
| Build & test commands | The exact commands to build, test, and lint. Agents will run these and fix failures if you list them. |
| Code style guidelines | Language, formatting, naming, and the patterns you want matched — keeps generated code consistent. |
| Testing instructions | How to run tests, what must pass, and the expectation to add tests for changed code. |
| Security considerations | Secrets handling, what must never be committed, and any sensitive areas to avoid. |
| PR & commit guidelines | Title format, commit message conventions, and pre-commit checks the agent should run. |
Free AGENTS.md Generator
Edit the starter sections below — reorder, rename, or delete them — and the AGENTS.md builds live on the right. Copy it or download it as AGENTS.md. Everything runs in your browser.
# My Project
## Project overview
A short description of what this project is and how the code is organized.
Mention the language, framework, and where the main entry points live.
## Dev environment tips
- Use `pnpm install` to install dependencies.
- Run `pnpm dev` to start the local server.
- Node 20+ is required.
## Build and test commands
- `pnpm build` — production build, must pass with zero errors.
- `pnpm test` — run the full test suite.
- `pnpm lint` — ESLint + TypeScript checks.
## Code style
- TypeScript, 2-space indentation, no semicolons.
- Prefer functional components and named exports.
- Match the style of the surrounding code.
## Testing instructions
- Add or update tests for any code you change.
- Run `pnpm test` and fix failures before finishing.
- Run `pnpm lint` after moving files or changing imports.
## PR instructions
- Title format: [<area>] <Short description>
- Run `pnpm lint` and `pnpm test` before committing.
Generated entirely in your browser — nothing is uploaded. Save the result as AGENTS.md at the root of your repository.
Nested Files & Precedence
For a single project, one root-level AGENTS.md is enough. In a large monorepo, drop a nested AGENTS.md inside each package so every subproject can ship tailored instructions.
my-monorepo/
├─ AGENTS.md ← repo-wide defaults
├─ apps/
│ └─ web/
│ └─ AGENTS.md ← overrides for the web app
└─ packages/
└─ ui/
└─ AGENTS.md ← overrides for the ui packageNearest file wins
Agents read the closest AGENTS.md in the directory tree to the file being edited. A package-level file overrides the root one for files in that package.
Chat overrides everything
An explicit instruction you give in the prompt always takes priority over anything written in an AGENTS.md file.
AGENTS.md vs README.md, CLAUDE.md & .cursorrules
These often sit in the same repo and get confused. AGENTS.md is the vendor-neutral baseline; the others are either for humans or for one specific tool.
| File | Read by | Scope | Note |
|---|---|---|---|
| AGENTS.md | All AI coding agents | Build, test, style & conventions for the whole repo | The open, cross-tool standard. 60k+ repos. |
| README.md | Human contributors | What the project is, install steps, how to contribute | Kept concise; agent-only detail moves to AGENTS.md. |
| CLAUDE.md | Claude Code specifically | Claude-specific guidance & overrides | Claude Code also reads AGENTS.md — use this for overrides. |
| .cursorrules | Cursor (legacy) | Tool-specific rules for one editor | Largely superseded by the shared AGENTS.md format. |
Which Tools Read AGENTS.md
AGENTS.md emerged from collaboration across OpenAI Codex, Amp, Jules (Google), Cursor, and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. It is read by a growing list of agents — here is a sample:
Common Mistakes
The errors that make an AGENTS.md less useful than it should be.
Avoid
Keeping five tool-specific rules files in sync
Do
Write one AGENTS.md and let every agent read it
Avoid
Dumping the whole README into AGENTS.md
Do
Include the agent-relevant build, test, and convention detail
Avoid
Listing test commands you do not want run
Do
Only list commands that are safe to execute
Avoid
One giant AGENTS.md for a large monorepo
Do
Add nested AGENTS.md files inside each package
Frequently Asked Questions
What is AGENTS.md?
AGENTS.md is a simple, open Markdown file placed at the root of a code repository that tells AI coding agents how to work on the project — the build and test commands, code-style conventions, testing rules, and any gotchas. Think of it as a README written for agents instead of humans. It is used by over 60,000 open-source projects and is read by most major coding agents, including OpenAI Codex, Cursor, GitHub Copilot, Jules, Aider, Gemini CLI, and Zed.
Are there any required fields in AGENTS.md?
No. AGENTS.md is just standard Markdown with no required fields or schema. You can use any headings you like — the agent simply parses the text you provide. Common, useful sections include a project overview, build and test commands, code style guidelines, testing instructions, security considerations, and pull-request or commit conventions, but none of them are mandatory.
Where do I put the AGENTS.md file?
Create it as AGENTS.md (all caps) at the root of your repository. For a large monorepo, you can also place additional AGENTS.md files inside individual packages or subprojects. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence — letting each subproject ship tailored instructions. The OpenAI Codex repository, for example, contains 88 AGENTS.md files.
What happens if instructions conflict?
The AGENTS.md closest to the file being edited wins. So a package-level AGENTS.md overrides a root-level one for files inside that package. Above everything, an explicit instruction you give in the chat prompt overrides what is written in any AGENTS.md file.
Will an agent actually run the commands listed in AGENTS.md?
Yes — if you list them. When you include build, test, or lint commands, the agent will attempt to execute the relevant programmatic checks and fix any failures before finishing the task. This is a feature, but it also means you should only list commands that are safe to run automatically.
What is the difference between AGENTS.md and README.md?
README.md is written for humans: what the project is, how to install it, and how to contribute. AGENTS.md is written for coding agents: the exact build commands, test commands, code-style rules, and conventions an AI needs to make correct changes. Keeping them separate lets the README stay concise while giving agents a predictable place to find machine-relevant instructions.
Do I need a CLAUDE.md if I already have an AGENTS.md?
Not necessarily. Claude Code reads AGENTS.md, so a single AGENTS.md covers the most common case. A CLAUDE.md is useful when you want Claude-specific guidance that differs from what other agents should see, or for global instructions in ~/.claude/CLAUDE.md that apply across all your projects. When both exist, treat AGENTS.md as the shared baseline and CLAUDE.md as Claude-specific overrides. The same idea applies to legacy files like .cursorrules, which the shared AGENTS.md format largely replaces.
Which AI coding tools read AGENTS.md?
Support is broad and growing. Tools that read AGENTS.md include OpenAI Codex, Cursor, GitHub Copilot's coding agent, Jules from Google, Gemini CLI, Aider, Zed, Amp, Windsurf, Devin, Warp, RooCode, Junie from JetBrains, Factory, Kilo Code, goose, opencode, and many more. Because it is a vendor-neutral open format, one AGENTS.md keeps all of them in sync.
How do I migrate an existing AGENT.md or rules file to AGENTS.md?
Rename the file to AGENTS.md and, if you want backward compatibility, create a symbolic link from the old name: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md. For tool-specific configs, point the tool at AGENTS.md — for example, set read: AGENTS.md in .aider.conf.yml, or { "context": { "fileName": "AGENTS.md" } } in .gemini/settings.json.
Is AGENTS.md an official standard?
It is an open, community-driven format rather than a formal web standard. It emerged from collaboration across OpenAI Codex, Amp, Jules from Google, Cursor, and Factory, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation. Adoption is wide — over 60,000 public repositories ship one — and because it is plain Markdown with no schema, there is nothing to install or validate.
Related Guides
AGENTS.md is one piece of the bigger Markdown-for-AI picture. Keep going: