--- title: "What is AGENTS.md? A plain-English guide" description: What AGENTS.md is, what goes in the file, and why AI coding agents read it — how it differs from README.md, CLAUDE.md and .cursorrules, and how to validate yours. last_updated: 2026-06-20 canonical_url: https://agent-ready.dev/what-is-agents-md --- # What is AGENTS.md? A plain-English guide > AGENTS.md is a plain-Markdown file at a repository's root that gives AI coding agents the project-specific instructions they need to build, test, and work in your codebase. **AGENTS.md** is a plain-Markdown file, conventionally at a repository's root, that tells AI coding agents how 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: a README optimizes for a person understanding the project, while AGENTS.md optimizes for an agent reliably doing the right thing without guessing. It's a vendor-neutral convention specified at [agents.md](https://agents.md), 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. 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. ```markdown # 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. ``` ## How is AGENTS.md different from README.md? 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; 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. ## How does AGENTS.md compare to CLAUDE.md and .cursorrules? CLAUDE.md and `.cursorrules` do the same job 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. Full breakdown: . ## 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](https://agent-ready.dev/what-is-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. ## Do AI coding agents actually read AGENTS.md? Increasingly, yes. AGENTS.md emerged 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 — and because it's plain Markdown, it costs nothing for tools that don't read it yet. ## 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](https://agent-ready.dev/how-to-write-an-effective-agents-md) walks through each. Then run it through the [AGENTS.md validator](https://agent-ready.dev/agents-md-validator) to catch structural gaps an agent would trip on. ## 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. --- Read the full guide on the web: Scan your site: ## Sitemap See the full [sitemap](https://agent-ready.dev/sitemap.md) for all pages on agent-ready.dev.