What Is AGENTS.md? How to Write One Your Coding Agent Follows

AGENTS.md is a plain Markdown file, usually at the root of a repository, that tells AI coding agents how to work on the project: which commands build and test it, which conventions to follow and what not to touch. It has no required fields and no special syntax. Codex, GitHub Copilot, Cursor and many other agents read it at the start of a task, and Claude Code reads it when the project has no CLAUDE.md of its own. The official site calls it "a README for agents" and counts over 60,000 open-source projects using it.

The format came from OpenAI. Since December 2025 it has been looked after by the Agentic AI Foundation, a fund under the Linux Foundation that also holds Anthropic's Model Context Protocol and Block's goose.

Which agents read AGENTS.md

Most agents read AGENTS.md as it is; a few prefer their own file and read AGENTS.md as a fallback or once configured. As of November 2026, from each tool's docs:

Agent	Reads AGENTS.md?	Its own file
OpenAI Codex	Yes, plus a personal one in ~/.codex	AGENTS.override.md
GitHub Copilot	Yes; the nearest one wins	copilot-instructions.md in .github/
Cursor	Yes, root and subfolders	.mdc rules in .cursor/rules/
Claude Code	When there's no CLAUDE.md (v2.1.277 or later)	CLAUDE.md
Gemini CLI	Once you add it to context.fileName	GEMINI.md
Aider	Once you list it under read in .aider.conf.yml	None by default

The agents.md site lists many more, including Jules, Zed, Warp, Windsurf, Devin, Junie, Amp, opencode and goose.

AGENTS.md vs CLAUDE.md

Both are Markdown instructions loaded at the start of every session. AGENTS.md is the shared format; CLAUDE.md is Claude Code's own, and its docs add a few things AGENTS.md doesn't have: @path imports (resolved from the importing file, at most four hops deep), path-scoped rules in .claude/rules/ that load only for matching files, a personal CLAUDE.local.md you keep out of git, and HTML comments that are stripped before loading, so notes to maintainers cost no tokens.

With the default setting, Claude Code decides which file to read like this:

In your folder or any folder above it	Claude Code reads
An AGENTS.md and no CLAUDE.md	The AGENTS.md
An AGENTS.md and a CLAUDE.md (or CLAUDE.local.md)	The CLAUDE.md files only
A CLAUDE.md that contains @AGENTS.md	Both, through the import

Your personal ~/.claude/CLAUDE.md doesn't count for that check, and loads either way.

So if your team uses more than one agent, keep one AGENTS.md as the shared file. If you also want lines only Claude should read, start a CLAUDE.md with an import:

@AGENTS.md

## Claude Code

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

Three things catch people out. A CLAUDE.md that says "read AGENTS.md" in words doesn't load it; Claude sees the file only if it decides to open it. Adding a CLAUDE.local.md for your own notes stops Claude Code reading AGENTS.md, unless you set Project instructions to claude-md-and-agents-md in /config. And @ imports are a Claude Code feature: Codex, Copilot and Cursor read @path in an AGENTS.md as plain text, so keep imports in CLAUDE.md. A symlink (ln -s AGENTS.md CLAUDE.md) also works, though not reliably for teammates on Windows.

Where the files go, and which one wins

Put one AGENTS.md at the root. In a monorepo, add one to each package that has its own commands or rules (OpenAI's main repository has 88). The agents.md FAQ gives the rule: the closest AGENTS.md to the edited file wins, and explicit chat prompts override everything.

Most agents load the parent files too, rather than swapping them out. Codex walks from the project root to your working directory, takes at most one file per folder (AGENTS.override.md before AGENTS.md) and joins them root first, so closer files come later and override earlier ones. It stops at 32 KiB combined, so the deepest file is the one that gets cut. Claude Code loads your folder and every folder above it at launch, and a subfolder's file once it opens a file there. Cursor merges nested files with their parents, the more specific one winning.

So a nested file should hold only what's different about its package. Repeating the root's commands costs tokens twice.

What a good AGENTS.md contains

Two 2026 studies have tested whether these files help. Researchers at ETH Zurich (Gloaguen et al.) ran agents on SWE-bench Lite (300 tasks) and 138 tasks from 12 repositories with their own context files. Files written by an LLM lowered the share of tasks solved by 0.5 and 2 points and raised cost by 20% and 23%. Files written by developers did a little better, 2.4 points on average (not statistically significant), at up to 19% more cost. Repository overviews didn't get agents to the right files any sooner. But agents did follow concrete instructions: when a file named the uv tool, they used it 1.6 times per task, against under 0.01 times when it didn't.

A second study (Lulla et al.) of 124 pull requests in 10 repositories found that with an AGENTS.md, median runtime was 28.64% lower and agents used 16.58% fewer output tokens, with a similar share of tasks completed.

Agents do what the file says, so use it for what they can't work out from the code:

1. Exact commands. Install, build, test everything, test one file, lint, type-check. Put each in backticks. The agents.md site says agents will try to run the checks you list and fix failures before they finish.
2. How to test. Which command to run for a quick check, what must pass before a commit, and anything unusual (a database to start, a flag the test runner needs).
3. Conventions the code doesn't show. "Money is integer cents, never floats" is worth a line. "We use React" isn't; the agent can see package.json.
4. Boundaries. Generated folders not to edit, files never to open, and when to ask first (a new dependency, a migration).
5. Pull request and commit rules, if you have them: title format, what to say in the description.

What to leave out

• Secrets. The file is committed and loaded into every prompt, so a key in it is in your git history and every session. Name the environment variable instead.
• A project overview and a folder tree. The part the ETH Zurich study found didn't help. The agent can read your README and list folders itself.
• Rules your tools already enforce. If a formatter or linter fixes it, give the agent the lint command, not the rule. Claude Code's docs are blunt that instruction files are context, not enforced configuration: something that must never happen belongs in a hook or a permission setting.
• Vague advice. "Write clean code" can't be checked. Claude Code's docs suggest "Use 2-space indentation" instead of "Format code properly", and "Run npm test before committing" instead of "Test your changes".
• Contradictions. Two rules that disagree (single and double quotes, say) may be followed either way.
• Shouting. Anthropic's prompting guide notes that newer models follow instructions closely, and lines like "CRITICAL: You MUST" can make them overreact. Plain wording works.

Then keep it short. Claude Code's docs target under 200 lines per CLAUDE.md, Cursor's under 500 lines per rule, and Codex stops reading at 32 KiB. Every line is part of every prompt. If you let a command like /init draft the file, cut it down afterwards: in the ETH Zurich study, generated files cost more and helped less.

A copyable example

This one is 26 lines for an invented TypeScript invoicing app. Swap in your own commands and rules:

# AGENTS.md

## Commands

- Install: `pnpm install` (pnpm only; the lockfile is pnpm-lock.yaml)
- Test everything: `pnpm test`
- Test one file: `pnpm vitest run src/lib/money.test.ts`
- Lint and types: `pnpm lint && pnpm typecheck` (both must pass before a commit)
- Database: `pnpm db:migrate` after changing `prisma/schema.prisma`

## Conventions

- Money is integer cents (`number`), never floats; format it with `formatCents()` from `src/lib/money.ts`.
- Dates are stored in UTC and shown in the team's time zone (`team.tz`).
- New API routes go in `src/api/routes/` and need a test in `src/api/__tests__/`.

## Boundaries

- Don't edit `src/generated/`: run `pnpm codegen` instead.
- Ask before adding a dependency.
- Never open `.env*` files or print their values.

## Pull requests

- Title: `area: short summary`, for example `invoices: fix rounding on partial refunds`.
- Run the lint, type and test commands first and say in the PR that they passed.

Notice what isn't there: no description of the product, no list of folders, no "write good code".

SKILL.md: instructions that load only when needed

Everything in AGENTS.md costs tokens on every task. An Agent Skill holds instructions an agent loads only when a task calls for them. It's a folder with a SKILL.md file (YAML front matter, then Markdown instructions) and, optionally, scripts/, references/ and assets/ folders. Anthropic developed the format and released it as an open standard. Claude Code reads skills from .claude/skills/ and Codex from .agents/skills/.

The specification requires two fields:

• name: up to 64 characters of lowercase letters, digits and hyphens, with no hyphen at either end or two in a row, and the same as the folder's name.
• description: up to 1,024 characters, saying what the skill does and when to use it. The agent matches tasks against it, so "Helps with PDFs" is too thin.

license, compatibility, metadata and allowed-tools (experimental) are optional. Claude Code reads extra fields of its own, which its skills docs say don't work in other agents.

---
name: release-notes
description: Drafts release notes from merged pull requests. Use when the user asks for release notes or a changelog.
---

# Release notes

1. Run `scripts/list_prs.sh` to list the pull requests merged since the last tag.
2. Group them as `references/style.md` describes.
3. Fill in `assets/template.md`, newest change first.

This is progressive disclosure. At startup the agent loads only each skill's name and description, about 100 tokens a skill. When a task matches, it reads the body of SKILL.md, which the spec suggests keeping under 5,000 tokens and 500 lines, with file references one level deep. Bundled files load only when the instructions point to them, and a script is run rather than read, so only its output enters the context (Anthropic's overview).

The rule of thumb: if every task needs it, it goes in AGENTS.md. If only some tasks do, make it a skill.

Skills carry a risk AGENTS.md mostly doesn't: they ship scripts, and the agent runs them with your permissions. Anthropic advises using skills only from sources you trust and auditing every bundled file first. When Snyk scanned 3,984 skills from ClawHub and skills.sh in February 2026, 13.4% (534) had at least one critical issue, and it confirmed 76 malicious payloads.

Checking your files

We built two free checkers for these files. Both run in your browser and upload nothing.

The AGENTS.md Checker reads AGENTS.md, CLAUDE.md, GEMINI.md, Copilot instructions and Cursor rules. Paste a file, open several, or drop a whole repository folder. It runs 48 checks covering build and test commands, vague and contradicting rules, README-style overviews, the size limits above, links and @ imports, secrets, hidden Unicode text, headings and file names (it warns, for example, when a CLAUDE.md beside your AGENTS.md means Claude Code won't read the AGENTS.md). Each finding points at a line and names the doc or study behind it; checks no source covers are labelled style suggestions.

The score starts at 100 and loses 12, 5 or 2 points per finding by severity (each check counts at most three times); a secret or hidden text caps it at 40. Those weights are our judgement, not a standard, and tokens are estimated at four characters each. It can also convert between the five formats, write a starter file for nine common stacks, and copy its findings as a prompt for your agent to fix.

It doesn't run your commands, so it can't tell you whether pnpm test works or whether a rule is right for your project. Links and imports are checked against real files only when you drop the folder.

The Agent Skill Checker takes a skill folder, a .zip or a single SKILL.md. It checks the front matter against the specification and its reference validator, skills-ref, with Anthropic's extra rules and Claude Code-only fields as warnings. Then it reads every text file line by line with 70 safety checks: code fetched from the internet, reads of keys, data sent elsewhere, obfuscation, deletions, persistence, hidden text, prompt injection and broad grants such as allowed-tools: Bash. It never runs anything, so "No red flags found" means none of the checks matched, not that a skill is safe.

The short version

• AGENTS.md is Markdown instructions for coding agents at the repository root, plus nested files where a package needs its own. The closest one to the edited file wins.
• Codex, Copilot and Cursor read it directly. Claude Code reads it when there's no CLAUDE.md; if you have both, put @AGENTS.md in the CLAUDE.md.
• Fill it with exact commands, test steps, unwritten conventions and boundaries. Leave out secrets, overviews, folder trees and anything a linter enforces. Aim for under 200 lines.
• Put what only some tasks need in a skill, and read a skill's scripts before you install it.

Sources

• AGENTS.md. agents.md. The format, recommended sections, nested files and precedence, supported agents, Aider and Gemini CLI setup, 60,000+ projects, 88 files in OpenAI's repository.
• Linux Foundation. Linux Foundation announces the formation of the Agentic AI Foundation (December 2025). AGENTS.md, MCP and goose as founding projects.
• OpenAI. Custom instructions with AGENTS.md and Build skills. Codex's discovery order, AGENTS.override.md, the 32 KiB project_doc_max_bytes default, .agents/skills.
• Anthropic. How Claude remembers your project. CLAUDE.md locations, loading order, imports, .claude/rules/, the 200-line target, when Claude Code reads AGENTS.md, the import and symlink setups.
• Anthropic. Extend Claude with skills and Agent Skills overview. Skill locations, the three loading levels and their token costs, security advice.
• Anthropic. Prompting best practices. Softening "CRITICAL" and "MUST" for newer models.
• GitHub Docs. Adding repository custom instructions for GitHub Copilot. AGENTS.md anywhere in the repo, the nearest one wins.
• Cursor Docs. Rules. AGENTS.md at the root and in subfolders, the 500-line guidance.
• Google. Provide context with GEMINI.md files. context.fileName.
• Agent Skills. Specification. SKILL.md fields and limits, progressive disclosure, the 500-line and 5,000-token guidance.
• Gloaguen, Mündler-Sasahara, Müller, Raychev and Vechev. Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? arXiv:2602.11988 (2026).
• Lulla, Mohsenimofidi, Galster, Zhang, Baltes and Treude. On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents. arXiv:2601.20404 (2026).
• Snyk. ToxicSkills: malicious AI agent skills on ClawHub (February 2026).