AGENTS.md files: the open convention for coding agents

AGENTS.md is a plain-Markdown file you put at the root of a repository to tell coding agents how this project works — how to install it, build it, test it, and what conventions to follow. The tagline the project uses is exactly right: “a README for agents.” A human-facing README explains the project to people; AGENTS.md holds the extra, sometimes-tedious operational detail an agent needs but that would clutter a README — the exact test command, the lint rule, the PR title format.

Crucially, it’s an open format, not tied to one vendor. For the “when do I use this vs. a skill?” framing, see the overview; this page is the practical reference for the file itself.

It’s just Markdown — there is no schema

This is the most important thing to internalize: AGENTS.md has no required schema, no required fields, and no required headings. It is ordinary Markdown. You use whatever H2 sections make sense for your project. There’s nothing to validate and no frontmatter to get wrong — if a human can read it, an agent can use it.

That freedom is deliberate. The format’s only real guidance is “use whatever headings make sense,” which is why in practice teams converge on a handful of recurring, useful sections rather than a mandated structure.

The sections teams commonly include

Across thousands of real AGENTS.md files, a common shape has emerged. None are required, but these are the ones that pull their weight:

Section	What goes in it
Project overview / setup	One or two lines on what the repo is, plus how to install dependencies and get a dev environment running.
Dev environment tips	Shortcuts for navigating the codebase, spinning up packages, running the dev server.
Build & test instructions	The exact commands to build, lint, and run the test suite — the single highest-value section.
Code style / conventions	Formatting, naming, patterns to follow or avoid, files the agent must not touch.
PR / commit instructions	Commit message format, PR title format, checks that must pass before committing.
Security / gotchas	Anything dangerous: secrets handling, migrations, “never run X against prod.”

The build-and-test section is the one to get right first. An agent that knows the one true command to run your tests is dramatically more useful than one guessing between npm test, make test, and pnpm turbo run test.

A complete example

Here’s the canonical example from the agents.md project — a realistic AGENTS.md for a pnpm/Turbo/Vite monorepo. Notice it’s just headings and bullets, and every instruction is concrete and copy-pasteable:

# 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.

And a smaller one for a plain Python project, to show it scales down:

# AGENTS.md

## Setup
- Create a virtualenv and install: `python -m venv .venv && . .venv/bin/activate && pip install -e ".[dev]"`

## Testing
- Run the full suite with `pytest`.
- Run a single test with `pytest tests/test_api.py::test_login`.
- Type-check with `mypy src/` and lint with `ruff check .` before committing.

## Conventions
- Format with `ruff format` — do not hand-format.
- Public functions need type hints and a docstring.
- Never edit files under `src/generated/`; they come from `make codegen`.

## Commits
- Use Conventional Commit prefixes (`feat:`, `fix:`, `docs:`, `chore:`).
- Keep commits focused; one logical change per commit.

Monorepos: nesting and “nearest wins”

AGENTS.md really shines in monorepos, thanks to one simple rule: agents read the nearest AGENTS.md in the directory tree, and the closest one wins.

You can place an AGENTS.md at the repo root and additional ones deeper in the tree. When the agent works on a file, it walks up from that file and uses the closest AGENTS.md it finds. That lets each subproject ship instructions tailored to itself while a thin root file carries the repo-wide basics.

my-monorepo/
├── AGENTS.md                 # repo-wide basics (tooling, PR rules)
├── apps/
│   ├── web/
│   │   └── AGENTS.md         # wins for work under apps/web/
│   └── api/
│       └── AGENTS.md         # wins for work under apps/api/
└── packages/
    └── ui/
        └── AGENTS.md         # wins for work under packages/ui/

The pattern that scales best is a thin root AGENTS.md plus rich per-package files — not one giant root file trying to describe everything. This isn’t theoretical: OpenAI’s own Codex repository is reported to use 88 AGENTS.md files across its tree. An explicit instruction you give the agent in chat still overrides whatever the file says.

Because the nearest file wins, a nested AGENTS.md can specialize rather than repeat: the root sets the defaults, and a package-level file only needs to note what’s different about that package.

Which tools read it

The whole point of an open format is portability. AGENTS.md came out of collaboration across the AI-tooling ecosystem — OpenAI Codex, Amp, Google’s Jules, Cursor, and Factory among them — and is now stewarded by the Agentic AI Foundation under the Linux Foundation.

It’s read natively by a long and growing list of tools — reported to include Codex, Cursor, GitHub Copilot’s coding agent, Gemini CLI, Aider, goose, opencode, Zed, Warp, VS Code, Devin, JetBrains Junie, Amp, Jules, Factory, Windsurf, and more — with adoption across tens of thousands of repositories. Because it’s plain Markdown, a tool that doesn’t “officially” support it can still be pointed at the file, and it degrades gracefully: worst case, it’s a document a human can read too.

One file, many agents. Instead of maintaining separate instruction files per tool, a single AGENTS.md serves whichever agent a contributor happens to use. Some tools also read their own dedicated file (e.g. Claude Code reads CLAUDE.md); a common approach is to keep the shared operational detail in AGENTS.md and let tool-specific files reference or supplement it.

Writing a good one: practical tips

• Be concrete, not aspirational. “Run pnpm test” beats “make sure tests pass.” Give the literal command.
• Front-load the build/test commands. They’re what an agent needs most and what it’s most likely to get wrong on its own.
• State the “don’t”s explicitly. Files not to touch, commands not to run, branches not to push to. Agents follow negative rules well when they’re clear.
• Keep it current. A stale AGENTS.md is worse than none — if the test command changes, update the file in the same PR.
• Scope with nesting instead of length. If the root file is getting long, that’s a signal to push package-specific detail into nested AGENTS.md files.
• Remember it’s for agents and humans. New contributors benefit from the same build/test/convention notes.

AGENTS.md vs. skills, one more time

AGENTS.md describes a repository; a skill packages a capability. Put repo-specific build/test/convention facts in AGENTS.md, where every tool working in that repo will read them. Put reusable, on-demand procedures — the ones you’d want across projects, or that are too long to keep always-loaded — into skills. They’re complementary: the agent reads AGENTS.md to understand where it’s working, and loads skills to extend what it can do.

References

Verified July 2026 against official sources:

• AGENTS.md — the standard’s site (the canonical example above is reproduced from it)
• agentsmd/agents.md on GitHub
• How to write a great AGENTS.md: lessons from over 2,500 repositories — GitHub Blog

Note: the agents.md homepage returned HTTP 403 to automated fetching during research, so its example and claims were cross-checked against the project’s GitHub repository and the GitHub Engineering blog rather than fetched directly. The specific tool list and adoption counts come from secondary summaries of the standard and may shift as the ecosystem grows.