Explainer · updated Oct 10, 2026

What is AGENTS.md and how coding agents use it

AGENTS.md is a plain Markdown file in a repository that gives coding agents build steps, tests and conventions. It has no required fields, and agents read the nearest file in the directory tree.

AGENTS.md →

What AGENTS.md is

AGENTS.md is a plain Markdown file that you place in a repository to give coding agents the project instructions they need, such as build steps, tests and conventions. The AGENTS.md site describes it as a README for agents. Humans keep reading the regular README, while agents get a predictable place for the detail that would clutter it. The site says the format is stewarded by the Agentic AI Foundation under the Linux Foundation. The agents that read it include Claude Code, OpenAI Codex, Gemini CLI, Cursor and GitHub Copilot.

There are no required fields and no schema. It is standard Markdown, so you can use any headings you like. How an agent treats the contents depends on that agent, which is the main thing to know before relying on it. Because the format sets no rules for content, two agents can read the same file and act on it differently, so it is worth checking how each tool you use handles it.

A README for humans, an AGENTS.md for agents: build steps, tests and conventions

How AGENTS.md works

An agent reads the AGENTS.md closest to the file it is editing. In a monorepo you can therefore keep one file at the repository root and add another inside each package, so each subproject gets its own instructions. When two files conflict, the closest one wins. Explicit prompts from the user in chat override everything, including the file. That makes AGENTS.md guidance for the agent, not a hard rule. Tool-specific layers sit on top: Cursor rules, Claude Code skills and MCP servers for external tools.

Nested AGENTS.md files: the closest one wins, and your chat prompt overrides them all

Gives agents a predictable place for setup, test and code-style instructions
Keeps agent-focused detail out of the human README
Supports nested AGENTS.md files; the closest one to the edited file wins
Works across many agents with one file instead of per-tool formats

What AGENTS.md costs

AGENTS.md is a file format rather than a paid product, so there are no plans or prices to compare. Our profile lists no license and no release date, and the public source repository was not verified, so we do not state them. The only requirement is an agent that reads AGENTS.md. Everything else is the time it takes you to write and maintain the file. If you are still choosing an agent, start with Codex vs Claude Code, Cursor vs GitHub Copilot or the Best AI agents list; the AI coding tools guide covers the wider field, and prompt engineering explains how to phrase the file.

Who AGENTS.md is for, and who it is not for

It fits teams that use more than one coding agent on the same repository, because one file replaces a separate format for each tool. It also fits monorepos that need per-package instructions, and anyone who wants agents to run the listed test commands before finishing. Keeping this detail out of the human README keeps both documents shorter and easier to read.

It is not a way to enforce policy. The file is guidance text, and explicit user prompts in chat override it. If a rule must always hold, it needs a mechanism outside the file, since the format does not require any agent to follow particular content. Treat it as a shared set of instructions that many agents read, and check each agent's behavior yourself.

Which agents read AGENTS.md

The site lists Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Copilot coding agent, Windsurf and others. Our catalog links related profiles for OpenAI Codex, Cursor, Gemini CLI and Windsurf Editor. Some tools need a setting: Gemini CLI reads the file once context.fileName is set to AGENTS.md in .gemini/settings.json, and Aider needs read: AGENTS.md in .aider.conf.yml.

Agents the site lists, and the two settings Gemini CLI and Aider need

Getting started with AGENTS.md

Create an AGENTS.md at the repository root and add sections such as project overview, build and test commands, code style, testing and PR instructions. For a monorepo, add another file inside each package. If you already have an AGENT.md file, the migration command is listed below as well. Then configure any agent that does not pick up the file by default.

Create the file at the root, add sections, then add one per package

Create an AGENTS.md file at the repository root
Add sections such as project overview, build and test commands, code style, testing and PR instructions
For monorepos add another AGENTS.md inside each package
To migrate: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
Gemini CLI: set context.fileName to AGENTS.md in .gemini/settings.json; Aider: add read: AGENTS.md to .aider.conf.yml

Frequently asked questions

What is AGENTS.md?

AGENTS.md is a plain Markdown file placed in a repository to give coding agents build steps, tests and conventions. The site calls it a README for agents.

What should I put in AGENTS.md?

Put what an agent needs to work in your repo: a project overview, build and test commands, code style, testing rules and PR instructions. Keep human-facing detail in the README, and add a nested AGENTS.md per package in a monorepo.

What happens when AGENTS.md files conflict?

The closest AGENTS.md to the edited file wins, and explicit user chat prompts override everything.

Which agents support AGENTS.md?

The site lists Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Copilot coding agent, Windsurf and others.

How do I make Gemini CLI read AGENTS.md?

Set context.fileName to AGENTS.md in .gemini/settings.json.