AGENTS.md, project instructions for the coding agent

Inside a repository, a coding agent still needs a predictable place for build steps, tests and conventions. That is the cut where AGENTS.md belongs, and where it also appears in the protocols index.

What the format describes

The official homepage presents AGENTS.md as a simple, open format for guiding coding agents, and suggests thinking of it as a README for the agent: a dedicated, predictable place for the context and instructions that help the agent work on the project. The AAIF project page summarizes the same cut: a simple, open format for guiding coding agents.

The homepage explains the split from the human README. README.md files are for people: quick starts, project descriptions and contribution guidelines. AGENTS.md complements that file with the extra, sometimes detailed context coding agents need: build steps, tests and conventions that might clutter a README or that are not relevant to human contributors.

The official FAQ, on the same homepage, states that there are no required fields. AGENTS.md is just standard Markdown. Any headings are fine; the agent simply parses the text in the file. The official pages reopened for this text do not publish a specification number. I treat the artifact as that open format, without inventing a version.

The For agents page explains what an agent can read on this site. AGENTS.md, in this text, is the instruction format inside a project's repository.

History and stewardship

The About section of the homepage says AGENTS.md emerged from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor and Factory, and that the commitment is to maintain and evolve this as an open format, regardless of which coding agent you use. The same section states that AGENTS.md is now stewarded by the Agentic AI Foundation under the Linux Foundation.

The Linux Foundation's note attributes the release to OpenAI, as a founding contribution to the AAIF, alongside Anthropic's MCP and Block's goose. The Foundation describes the format as a Markdown-based convention that gives coding agents a consistent source of project-specific guidance, so they can operate more predictably across repositories and toolchains. The steward repository pointed to by the AAIF is https://github.com/agentsmd/agents.md.

How to use it in a repository

The homepage, in «How to use AGENTS.md?», describes the flow as follows. You add an AGENTS.md file at the root of the repository. The text should cover what matters, with suggested sections: project overview, build and test commands, code style guidelines, testing instructions and security considerations. Commit messages or pull request guidelines, security gotchas, large datasets and deployment steps can go in as well: anything you would tell a new teammate.

In monorepos, the official guidance is to place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, and the closest one takes precedence. The FAQ states the conflict rule this way: the closest AGENTS.md to the edited file wins, and explicit user chat prompts override everything. I record that only as the precedence rule documented on the homepage.

The same FAQ states that if testing commands are listed, the agent will attempt to execute relevant programmatic checks and fix failures before finishing the task. There is, on this page, no discovery protocol of the /.well-known/ kind and no JSON manifesto for agent-to-agent traffic. The artifact is a Markdown file in the repository.

An official example

The example below is the «Sample AGENTS.md file» from the official documentation, in the README of the steward repository, at https://raw.githubusercontent.com/agentsmd/agents.md/main/README.md, the same long example the homepage points to in its Examples section.

# Sample AGENTS.md file

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

Relation to MCP and A2A

On the official pages of AGENTS.md itself, the relation to MCP and A2A is not described as an on-the-wire integration. What the sources support is shared governance: AGENTS.md, MCP and goose are founding contributions of the AAIF, and the official A2A blog calls them, together with A2A, sibling projects. The cut of AGENTS.md remains project instructions in the repository.

I treat AGENTS.md as project guidance sitting in the tree, stewarded with MCP and A2A at the AAIF. The rest of the map is in the index.

Sources