What Is AGENTS.md? A Guide for AI Coding Agents
If you've let an AI coding agent like Cursor, GitHub Copilot, or OpenAI's Codex work in your repository, you've probably watched it guess. It runs the wrong test command, misses the lint step, invents a build script, or writes code in a style your project doesn't use. The agent isn't reading your mind, and it isn't reading your CONTRIBUTING.md either. AGENTS.md is the file that tells it what to do instead.
What is AGENTS.md?
AGENTS.md is a plain Markdown file you place at the root of your repository that gives AI coding agents the project-specific instructions they need to work on your code: how to build it, how to run the tests, what code style to follow, and any conventions a new contributor would have to learn. Its own maintainers describe it as "a README for agents."
The idea is a clean separation of audiences. Your README.md is written for humans who want to use your project; AGENTS.md is written for the agents that need to work in it — the exact build/test/style detail that clutters a human README but is precisely what an agent needs to avoid guessing.
You can place one AGENTS.md at the repo root and add more in subdirectories for monorepos or packages with their own rules; when files are nested, the one closest to the code being edited takes precedence.
What goes in an AGENTS.md file?
There's no rigid schema, but the widely-used sections are practical and predictable:
- Project overview — what the project is, in a sentence or two.
- Build and test commands — the exact commands to install, build, and run tests.
- Code style — formatting, linting, language conventions the agent should match.
- Testing instructions — how to run and add tests, what must pass before a change is done.
- Security considerations — anything an agent must not touch or must handle carefully.
- Commit and PR guidelines — message format, branching, review expectations.
A short example:
# AGENTS.md
## Project overview
A Nuxt 3 marketing site with a Firebase backend.
## Build & test
- Install: `npm install`
- Dev server: `npm run dev`
- Run tests: `npm test` — all tests must pass before a change is complete.
## Code style
- TypeScript, 2-space indent. Run `npm run lint` and fix warnings.
- Prefer composables over mixins.
## Commits
- Conventional Commits (`feat:`, `fix:`, `chore:`).
The value is simple: the agent stops guessing at the things your team already knows.
Who created AGENTS.md, and is it an official standard?
AGENTS.md came out of OpenAI's Codex team in 2025 and was built with collaborators across the coding-agent ecosystem. In December 2025 it was donated to the Agentic AI Foundation (AAIF), a new body under the Linux Foundation, as one of three anchor projects — alongside Anthropic's Model Context Protocol (MCP) and Block's goose agent. Members of the foundation include AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, and OpenAI.
One point of precision: AGENTS.md is an open format now stewarded by that foundation. OpenAI and the Linux Foundation sometimes call it a "standard," but there's no ratified, versioned specification behind it yet. Adopting the format and joining the foundation are also separate things. Cursor, for example, reads AGENTS.md but isn't a foundation member. The direction of travel is real, though it's still a converging convention.
Which tools read AGENTS.md?
Adoption is the reason the format matters, and it's broad. The tools that read AGENTS.md include OpenAI Codex, Cursor, GitHub Copilot, Google's Jules and Gemini CLI, Devin, Zed, Warp, VS Code, Aider, goose, opencode, and others. The project's own site reports the format is used across more than 60,000 open-source repositories as of mid-2026. That figure is self-reported, from a live GitHub code search, but it's large and consistent with how quickly the tool list has grown.
One useful data point on how to write a good file: when GitHub studied the practice, it analyzed more than 2,500 repositories with AGENTS.md files to draw out what works. The recurring lesson was that specific, runnable commands beat vague prose — an agent can execute npm test, it can't act on "make sure things work."
AGENTS.md vs llms.txt
This is the comparison people ask about most, and the short answer is that they solve different problems at different layers, so most projects that care about AI will eventually want both.
| AGENTS.md | llms.txt | |
|---|---|---|
| Lives at | your repository root | your website root |
| Read by | AI coding agents working in your code | AI assistants reading your docs at inference time |
| Contains | build/test commands, code style, conventions | a curated, link-first index of your documentation |
| Job | help an agent work in your project | help an assistant use your content |
AGENTS.md is about the code: it helps an agent contribute to your repository correctly. llms.txt is about the content: it gives an AI assistant a clean, structured map of your documentation instead of making it scrape your HTML. Neither replaces the other, and neither replaces your robots.txt or sitemap.xml.
One caution, because it's a common source of confusion: some marketing and SEO articles use the name "AGENTS.md" for a different file — a website-root file meant to tell AI shopping agents how to represent a business — and claim it's "replacing llms.txt." Shopify, for example, now points to a website-root /agents.md for agentic commerce. That's a reuse of the name, not the repo-level coding-agent format described here. When someone tells you AGENTS.md is replacing llms.txt, they're almost always talking about that separate ecommerce idea, and conflating two things that don't compete.
AGENTS.md vs CLAUDE.md
If you use Anthropic's Claude Code, you've met its own instructions file, CLAUDE.md. Per Anthropic's own docs, Claude Code reads CLAUDE.md by default and does not natively read AGENTS.md. If you keep both — say, AGENTS.md for Codex and Cursor, CLAUDE.md for Claude Code — you can avoid maintaining two copies by importing one into the other (an @AGENTS.md line inside CLAUDE.md) or pointing one at the other with a symlink. It's a minor bit of housekeeping, and the ecosystem is still settling on the cleanest convention, so check your tool's current docs.
Do you actually need AGENTS.md?
If AI coding agents touch your repository — and for most active projects they now do — an AGENTS.md earns its keep the first time it stops an agent from running the wrong command. The cost is low: it's a Markdown file you write once and update when your build or conventions change.
It also fits a bigger shift worth naming plainly. AI agents are becoming a real audience for your project, and different files serve different parts of that audience: AGENTS.md for the agents working in your code, llms.txt for the assistants reading your docs. Getting both right is what "agent-ready" actually means in practice — not a ranking trick, just clean, machine-readable context in the places agents look for it.
The honest caveat: this is a young, fast-moving area. AGENTS.md adoption among coding-agent tools is genuine and growing, but the conventions are still converging, and a file only helps the agents that actually read it. Treat it as a low-cost, high-clarity improvement for the tools your team actually uses, not a guarantee.
If you want to start with the documentation side, our free tool generates a spec-compliant llms.txt for your site, and validates one you already have.
Frequently asked questions
Where do I put an AGENTS.md file? At the root of your repository. For a monorepo, add extra AGENTS.md files in subdirectories; the one closest to the code being edited wins.
Is AGENTS.md the same as llms.txt? No. AGENTS.md lives in your repo and tells AI coding agents how to build, test, and contribute to your code. llms.txt lives at your website root and gives AI assistants a clean index of your documentation. They serve different audiences and don't compete.
Do Cursor and GitHub Copilot read AGENTS.md? Yes. Both are among the tools that read AGENTS.md, along with OpenAI Codex, Google's Jules, Devin, Zed, and others.
Is AGENTS.md an official standard? It's an open format stewarded by the Agentic AI Foundation under the Linux Foundation, to which it was donated in December 2025. That's a strong signal of direction, but the format is still a converging convention, not yet a finished, versioned spec.
Does Claude Code use AGENTS.md? Claude Code reads its own CLAUDE.md by default and doesn't natively read AGENTS.md. You can bridge them by importing AGENTS.md into CLAUDE.md or using a symlink.