The AGENTS.md Standard Explained

TL;DR: AGENTS.md is an open format, not a specification. It has no required fields, no schema and no version. Around a dozen coding agents document support on their own pages, several combine nested files differently, and Claude Code does not read it at all without an import or a symlink.

If you have opened a repository lately and found an AGENTS.md sitting next to the README, the reasonable first question is whether it is a real convention or a logo wall. The honest answer is: a bit of both, and the difference matters more than the name suggests.

Everything below was verified against primary sources on 28 August 2026. Every tool listed as reading AGENTS.md was confirmed on that vendor's own documentation, at the URL given. Tools that appear on the format's compatibility list but that I could not confirm on their own docs are labelled as claimed rather than verified.

Is AGENTS.md actually a standard?

Not in the sense that word usually carries. It is a format convention, and its own publishers describe it that way.

The site at agents.md calls it "A simple, open format for guiding coding agents". Its FAQ answers the question directly: asked whether there are required fields, it says "No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide."

That is the entire content specification. A Markdown file, at your repository root, containing whatever you want.

Compare that to what a specification normally ships:

The stewardship is real and checkable: the Agentic AI Foundation lists AGENTS.md among its projects at aaif.io, described in the same words, alongside goose and Agent2Agent.

So the accurate framing is that AGENTS.md standardises a filename and a location, not a format. That is a much smaller promise than "standard" implies, and it is also, in practice, most of the value. The hard problem was never Markdown syntax. It was that every tool invented its own filename.

Which tools actually read AGENTS.md?

This is the question the compatibility wall on agents.md answers badly, because a list published by a format's own site is a claim, not a confirmation. So I checked each vendor's own documentation. Here is what held up on 28 August 2026.

The wording is worth quoting in a few places, because it is more specific than a checkmark on a compatibility wall.

OpenAI is the most emphatic: "Codex reads AGENTS.md files before doing any work." Cursor's help documentation is equally plain: "Create an AGENTS.md file in your project root. Write instructions in plain markdown. Cursor picks it up automatically." Zed says it "supports AGENTS.md as the primary instruction file for personal and project-level agent guidance". Amp "looks in AGENTS.md files for guidance on codebase structure, build/test commands, and conventions". opencode: "You can provide custom instructions to opencode by creating an AGENTS.md file." Jules, in its environment-setup docs, says it "will also refer to agents.md or your readme.md file for hints to setup an environment on the fly".

Two entries on the compatibility wall deserve an asterisk. Gemini CLI's own configuration reference never mentions AGENTS.md. Its context file is documented as "defaulting to GEMINI.md but configurable via the context.fileName setting". You can point it at AGENTS.md, and the agents.md FAQ tells you exactly how, but that is you configuring your tool, not your tool honouring the convention. Aider is the same class: its conventions page documents loading a file with --read or a read: key in .aider.conf.yml, and its worked example is CONVENTIONS.md. The string "AGENTS.md" does not appear on that page.

And support is not even uniform inside one vendor. GitHub's own reference table shows agent instructions supported by the Copilot cloud agent in every environment where the table lists one, and by Copilot code review on GitHub.com, but not by Copilot Chat in Visual Studio, Eclipse or Xcode. GitHub says so itself: agent instructions are "currently not supported by all Copilot features".

Why doesn't Claude Code read AGENTS.md?

Because Anthropic ships its own equivalent and says so without hedging. From Anthropic's memory documentation: "Claude Code reads CLAUDE.md, not AGENTS.md."

This is the part of the AGENTS.md story that most write-ups skip, and skipping it is a disservice. The entire pitch of the format is write it once, every agent reads it. One of the most widely used coding agents does not, out of the box. Pretending otherwise sends people to debug a file that was never loaded.

The resolution is documented and takes one line. Anthropic's own page gives two options. Create a CLAUDE.md whose first line imports the shared file, then add anything Claude-specific below it:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Or, if you have nothing Claude-specific to add, symlink it:

ln -s AGENTS.md CLAUDE.md

On Windows a symlink needs Administrator privileges or Developer Mode, so Anthropic recommends the @AGENTS.md import there. Anthropic also documents a /import command that copies a supported agent's configuration, including AGENTS.md, into the matching CLAUDE.md, and an /init that can read AGENTS.md behind an environment flag. The import is the version to reach for: it keeps one file authoritative instead of duplicating it.

Two files, one of which is two lines long, is a small tax. Silently assuming Claude read your AGENTS.md is not. If you are writing that bridging file, the companion post on what belongs in a CLAUDE.md covers the economics of what earns a line, and CLAUDE.md templates for Claude Code has paste-ready starting points.

What happens with nested AGENTS.md files?

Every major implementation supports subdirectory files. None of them combine those files the same way, and the format's own site describes only one of the behaviours.

The agents.md FAQ says: "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything." That is a clean rule. It is also not what several tools document.

The difference is not cosmetic. Codex's chain is anchored to where you launched it and stops there, so a rule in services/payments/AGENTS.md does nothing if you started Codex at the repo root and never cd'd down. Amp and Warp key off files the agent actually touches. Those two models produce different behaviour for the same file tree.

There is one more portability trap, and it is a genuine contradiction between two vendors' docs. Warp: "The filename must be in all caps for Warp to recognize it". Factory, meanwhile, lists agents.md and Agents.md in its own table of accepted filenames, because "Droid also reads compatible filenames so existing instruction files from other coding tools keep working." Both cannot be a shared rule. All-caps AGENTS.md is the spelling that works in both, so use it.

What does a good AGENTS.md look like?

Here is a complete file for a small TypeScript web app. It is short on purpose. Annotations follow.

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 3000)
- Test one file: `pnpm vitest run src/lib/pricing.test.ts`
- Full check before you say you are done: `pnpm typecheck && pnpm test`

## Boundaries
- Never edit `src/generated/` — it is rebuilt by `pnpm codegen`.
- Never run migrations against anything but the local database.
- `main` auto-deploys on merge. Ask before merging.

## Conventions
- Data fetching goes in `src/server/`, never in a client component.
- We use `zod` for validation. Do not add a second validation library.
- Two patterns exist for forms. `react-hook-form` is correct; the older
  uncontrolled pattern in `src/legacy/` is not. Do not copy it.

## Traps
- Do not upgrade `sharp` past 0.33: CI has no prebuilt Linux binary for it.
- `pnpm test` needs Postgres running. `docker compose up -d db` first.

## Pull requests
- Title format: `[area] what changed`
- Run `pnpm lint` before committing.

Why each block earns its place:

Commands come first because getting them wrong costs a full round trip every single time, and because they are the one thing agents will otherwise guess from a stale README. The "test one file" line matters more than it looks: without it, an agent runs the whole suite to check a one-line change.

Boundaries are the entries that pay for themselves the first time they fire. Each one names a specific irreversible action. "Be careful" is not a boundary; "never run migrations against anything but the local database" is.

Conventions exist only for things the code cannot reveal. The two-forms-patterns entry is the archetype: a repository that contains both an old pattern and a new one cannot tell an agent which one is current. That is exactly the information worth writing down.

Traps carry their reason. A trap without a reason gets rationalised away by a model looking for a way forward; "no prebuilt Linux binary in CI" survives an argument, "don't touch sharp" does not.

Pull requests is here because several tools, Codex among them, document using AGENTS.md for PR titles and pre-commit checks. If your agent opens PRs, this section is load-bearing. If it never does, delete it.

What does not belong in an AGENTS.md?

The file is loaded into the model's context window, so every line in it competes with your actual task for attention. That argument is developed properly in the CLAUDE.md best-practices piece; the short version is that this file is not free, so anything an agent can read for itself is a net loss.

Cut these:

• Directory listings. The agent can run ls. A tree in the file is stale within a month.
• Dependency inventories. package.json is right there and is never wrong.
• Architecture essays. If it is longer than a paragraph, it belongs in docs/ with a one-line pointer.
• Anything the README already says. The format exists to complement the README, not mirror it.
• Secrets, tokens, internal URLs. This file is committed and is read by third-party services.
• Aspirations. "We are migrating to X" without a rule attached produces half-migrated code.
• Politeness. "Please be careful and write high-quality code" consumes tokens and changes nothing.

What AGENTS.md cannot do

Two limits, both worth internalising before you write anything into it.

It is context, not enforcement. No vendor claims otherwise, and Anthropic's parallel documentation is the most explicit: instructions are treated as "context, not enforced configuration", with "no guarantee of strict compliance". A rule in an AGENTS.md is a strong hint. If a rule must hold every time, it belongs in CI, a pre-commit hook, or your agent's hook system, and the file should explain why the rule exists so the agent stops fighting it.

Size is capped, and the useful ceiling is lower than the cap. Codex documents a real limit: it "skips empty files and stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default)". Past that, your instructions are simply truncated. No vendor publishes a recommended length, and any token budget you see quoted for these files is not coming from a primary source. Treat 32 KiB as a hard ceiling and aim nowhere near it.

How do you set this up today?

Five steps, in order:

1. Write one AGENTS.md at the repository root. All caps. Commands first.
2. Add nested files only where a package genuinely differs, and keep the root file correct on its own.
3. Add a CLAUDE.md containing @AGENTS.md if anyone on the team uses Claude Code.
4. Check the docs for the specific tools your team runs. The table above is accurate as of 28 August 2026, and these pages change.
5. Commit it, then edit it when it is wrong. A file that has not changed in six months is describing a repository that no longer exists.

If your team also keeps reusable prompts rather than just repository rules, that is a separate problem with a separate answer: treat prompts like code and version them, rather than letting them accumulate inside the instruction file.

One note on where we fit, since it is the obvious question on a post like this. Prompt Architects does not generate or manage AGENTS.md files, and nothing on our roadmap says otherwise. What we do run is an MCP server at mcp.prompt-architects.com/mcp with documented setup for Claude Desktop, Claude.ai, Cursor, Claude Code, Codex and Codex CLI, exposing improve, refine, shorten and enhance as tools inside those clients. That is a different layer: your AGENTS.md tells the agent how your repository works, and the MCP tools improve the prompts you type at it. If that is useful, using MCP inside Claude Code walks through the setup, and Cursor rules and prompt templates covers the Cursor-specific rule mechanisms that sit alongside AGENTS.md.

The short version

AGENTS.md is a good convention with an overstated name. It fixed the filename problem, which was the actual problem, and it fixed nothing else, because there was nothing else to specify. Around a dozen tools document reading it. One major one does not, and says so clearly enough that there is no excuse for being surprised. The behaviours diverge most where files nest.

Write the root file, keep it short, bridge it to Claude Code with two lines, and check your own tools' documentation rather than a logo wall. That is the whole practice.