AGENTS.mdis a plain-Markdown file, conventionally placed at a repository’s root, that gives AI coding agents the project-specific instructions they need to work in your codebase — how to set up, build, test, and follow your conventions. Think of it as a README written for agents instead of humans: where a README optimizes for a person understanding the project, AGENTS.md optimizes for an agent reliably doing the right thing without guessing. It’s a vendor-neutral convention specified at agents.md and adopted across coding agents — so you write one file instead of one per tool.
What goes in an AGENTS.md file?
There’s no required schema — it’s just Markdown headings an agent can read. In practice you cover the commands and rules an agent needs to act: how to install dependencies and run the project, how to run tests and what must pass before committing, your code conventions, and any rules for pull requests. Keep it specific and command-level — an agent benefits far more from npm test and “run lint before pushing” than from prose about your philosophy.
# AGENTS.md
## Setup
- Install dependencies: `npm install`
- Start the dev server: `npm run dev`
## Testing
- Run the test suite: `npm test`
- All tests must pass before committing.
## Conventions
- TypeScript strict mode — no `any`.
- Prefer named exports over default exports.
## Pull requests
- Title format: `type(scope): summary`
- Run `npm run lint` before pushing.For a section-by-section walkthrough with real examples, see the guide to writing an effective AGENTS.md.
How is AGENTS.md different from README.md?
They overlap, but the audience is different. README.md is written for humans evaluating or onboarding to a project; AGENTS.md is written for AI coding agents executing work in it. A README optimizes for understanding — what the project is, how to get started, how to contribute. AGENTS.md optimizes for execution: the exact commands to build and test, the conventions to follow, and the gates that must pass before code lands. Ship both — they serve different readers.
How does AGENTS.md compare to CLAUDE.md and .cursorrules?
CLAUDE.md and .cursorrules do the same job as AGENTS.md but are tool-specific — one for Claude, one for Cursor. AGENTS.md is the vendor-neutral convention that emerged to replace that fragmentation: one file every coding agent can read, instead of a separate instruction file per tool.
| AGENTS.md | CLAUDE.md | .cursorrules | |
|---|---|---|---|
| Scope | Vendor-neutral | Claude only | Cursor only |
| Format | Markdown | Markdown | Plain text |
| Read by | Most coding agents | Claude tools | Cursor |
For the full breakdown, see AGENTS.md vs CLAUDE.md vs .cursorrules.
Is AGENTS.md the same as llms.txt?
No — and the two get confused often. They serve different agents. AGENTS.md is repo-facing: it tells coding agents how to build, test, and work inside your codebase. llms.txt is web-facing: it gives retrieval and answer-engine agents a curated map of your website’s most important content. One is for agents writing code in your repo; the other is for agents reading your site. Many projects ship both, and they don’t compete.
Do AI coding agents actually read AGENTS.md?
Increasingly, yes. AGENTS.md emerged specifically to replace the fragmented set of tool-specific files — CLAUDE.md, .cursorrules, .github/copilot-instructions.md — with one convention, and agents such as OpenAI Codex, Cursor, and Jules look for it. Support isn’t universal, but it’s the closest thing to a cross-tool standard for agent instructions — and because it’s plain Markdown, it costs nothing for the tools that don’t read it yet. Omitting it is a common readability gap for code repositories.
How do I write and validate an AGENTS.md?
Create an AGENTS.md at your repository root with command-level sections for setup, testing, conventions, and PRs — the step-by-step guide walks through each one. Then run it through the AGENTS.md validator to catch structural gaps an agent would trip on — a missing setup or test section, vague instructions, or no commands at all.
Frequently asked questions
- What is AGENTS.md?
- AGENTS.md is a plain-Markdown file, conventionally at a repository's root, that gives AI coding agents the project-specific instructions they need to work in your codebase — how to set up, build, test, and follow your conventions. Think of it as a README written for agents instead of humans. It's a vendor-neutral convention specified at agents.md and adopted across coding agents like OpenAI Codex, Cursor, and Jules, so you write one file instead of one per tool.
- What goes in an AGENTS.md file?
- There's no required schema — it's just Markdown headings an agent can read. In practice you cover setup commands (how to install dependencies and run the project), how to run tests and what must pass before committing, code conventions (language, style, export patterns), and any rules for pull requests or commits. Keep it specific and command-level: an agent benefits far more from `npm test` and `run lint before pushing` than from prose about your philosophy.
- How is AGENTS.md different from README.md?
- README.md is written for humans evaluating or onboarding to a project — what it does, how to get started, how to contribute. AGENTS.md is written for AI coding agents executing work in the repo: the exact commands to build and test, the conventions to follow, and the gates that must pass. They overlap, but a README optimizes for understanding while AGENTS.md optimizes for an agent reliably doing the right thing without guessing. Ship both.
- Is AGENTS.md the same as llms.txt?
- No — they serve different agents. AGENTS.md is repo-facing: it tells coding agents how to build, test, and work inside your codebase. llms.txt is web-facing: it gives retrieval and answer-engine agents a curated map of your website's most important content. One is for agents writing code in your repo; the other is for agents reading your site. Many projects ship both, and they don't compete.
- Do AI coding agents actually read AGENTS.md?
- Increasingly, yes. AGENTS.md emerged specifically to replace the fragmented set of tool-specific files (CLAUDE.md, .cursorrules, .github/copilot-instructions.md) with one convention, and agents such as OpenAI Codex, Cursor, and Jules look for it. Support isn't universal, but it's the closest thing to a cross-tool standard for agent instructions — and because it's plain Markdown, it costs nothing for tools that don't yet read it.
- How do I write and validate an AGENTS.md?
- Create an AGENTS.md at your repository root with command-level sections for setup, testing, conventions, and PRs, then keep it short and specific. Run it through a validator to catch structural gaps an agent would trip on — a missing setup or test section, vague instructions, or no commands at all. The Agent Ready AGENTS.md validator checks your file against the conventions that make it actually useful to a coding agent.