AGENTS.md: What 1,000 Top Repos Put in It, and CLAUDE.md
On this page
A new contributor opens your repository. A person reads the README, asks in chat how to run the tests, and learns over a week which folder never to touch. A coding agent reads whatever file it was built to read first, and starts.
AGENTS.md is that file. It is now in more than a third of the most popular repositories on GitHub. We read the file trees of the 1,000 most-starred repositories on 18 November 2026 to see who has one, what is in it, and how it lives next to Claude Code’s CLAUDE.md, which is where most repositories trip.
Short answer: AGENTS.md is a Markdown file at the root of a repository with instructions for AI
coding agents: how to build and test, the rules, the traps. Codex, GitHub Copilot, Cursor and many
others read it; Claude Code reads it too since version 2.1.277, but only when there is no
CLAUDE.md. Of the 1,000 most-starred GitHub repositories, 348 have one at the root and 193 have
a CLAUDE.md. 159 have both: 65 link them with an @AGENTS.md line in CLAUDE.md, the way Claude Code’s
docs recommend, 39 with a symlink, and 12 only tell the agent in words to read AGENTS.md, which Claude
may never do.
What AGENTS.md is, and who reads it
The AGENTS.md site calls it “a simple, open format for guiding coding agents”, “a README for agents”, and says it is used by over 60,000 open-source projects. The format is just Markdown with no required fields. It is now stewarded by the Agentic AI Foundation under the Linux Foundation.
What differs is how each agent finds it:
- Codex builds “an instruction chain” at start: your global
~/.codex/AGENTS.md, then every AGENTS.md from the repository root down to the working folder, joined so that “files closer to your current directory override earlier guidance”. It stops at 32 KiB by default. AnAGENTS.override.mdin a folder wins over the AGENTS.md beside it. - The open format says the same in one line: “The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.”
- Claude Code reads CLAUDE.md first. AGENTS.md is read “only when you have no CLAUDE.md in your working directory or above it”. More on that below, because it is the most common mistake.
Nested files are normal in big repositories. Of the 1,000 we read, 151 have more than one AGENTS.md; one has 150. The AGENTS.md site notes that OpenAI’s main repository had 88 when it wrote its guide.
How many top repositories have one
How we counted. The list is the 1,000 most-starred repositories we used for our Definition of Done study, taken from GitHub’s search on 13 November 2026. For each we read the default branch’s full file tree through GitHub’s API on 18 November 2026 and downloaded the root AGENTS.md and CLAUDE.md. 16 trees were too big for GitHub to return whole, so counts for those could be slightly low.
What we found:
- 495 of 1,000 have at least one agent instruction file of any kind.
- AGENTS.md: 348 at the root, 379 anywhere. Five days earlier, for our AI contribution policy study, the same list had 346 at the root.
- CLAUDE.md: 193 at the root, 229 anywhere. GEMINI.md 33,
.github/copilot-instructions.md70,.cursor/rules25, the old.cursorrules10. - Skills are already here: 319 repositories contain a SKILL.md somewhere, 114 under
.agents/skillsand 81 under.claude/skills. (Our SKILL.md format study checks 1,792 of them against the spec.)
One file per tool is the old way. AGENTS.md is winning the “one shared file” role, and CLAUDE.md is where the friction is.
AGENTS.md and CLAUDE.md: the rule that bites
Claude Code’s memory docs give the rule in a table. With an AGENTS.md and no CLAUDE.md, Claude reads your AGENTS.md. With both, it reads “your CLAUDE.md files only”. With a CLAUDE.md that imports AGENTS.md, it reads both, once. Reading AGENTS.md at all “requires Claude Code v2.1.277 or later”.
So the CLAUDE.md in a repository that also has an AGENTS.md decides what Claude sees. Here is what the 159 top repositories with both at the root do:
| What CLAUDE.md does | Repos | What Claude Code reads |
|---|---|---|
@AGENTS.md and nothing else | 48 | AGENTS.md, through the import |
@AGENTS.md plus Claude-only notes | 17 | both, AGENTS.md first |
| Symlink to AGENTS.md | 39 | AGENTS.md through the link; on Windows, often one line |
| Its own text that mentions AGENTS.md | 17 | CLAUDE.md; AGENTS.md only if Claude opens it |
| Its own text, no mention | 26 | CLAUDE.md only; the two files drift apart |
| “Read AGENTS.md” in words, nothing else | 12 | CLAUDE.md; AGENTS.md “only if it decides to open the file” |
The last row is the quiet failure. Claude Code’s docs say of a CLAUDE.md “that tells Claude in words
to read AGENTS.md”: “Claude sees AGENTS.md only if it decides to open the file.” Among the twelve are
ollama, Hugging Face transformers, llama.cpp and Material UI. The fix is one line: replace the sentence
with @AGENTS.md.
Symlinks work on macOS and Linux. The docs warn about Windows: Git “checks a committed symlink out as a plain text file unless core.symlinks is enabled, which leaves that clone with a one-line CLAUDE.md in place of your instructions.” If anyone on the team uses Windows, use the import.
The pattern that works everywhere:
@AGENTS.md
## Claude Code only
- Use the /release skill for releases; never edit CHANGELOG.md by hand.
What the top repositories put in theirs
We read the 328 root AGENTS.md files with real content (20 were a line or two). The median is 110 lines and about 990 words; the longest tenth run past 350 lines. What they cover:
| What the file contains | Share of 328 |
|---|---|
| “Do not”, “never” or “must not” rules | 88% |
| Code style, formatting or lint rules | 77% |
| Links to CONTRIBUTING, the README or docs | 77% |
| How to run the tests | 61% |
| Commit message, pull request or changelog rules | 58% |
| Security, secrets or credentials | 48% |
| A project structure or architecture overview | 44% |
| Build or test commands in a code block | 42% |
Skills (SKILL.md, .claude/skills, .agents/skills) | 29% |
| AI disclosure or an AI policy | 27% |
| An issue tracker (Jira, GitHub issues, Linear) | 14% |
The most common section headings were Commands, Testing, Architecture, Project overview and Code style. These are text matches on the files, so read them as “mentions”, not “has a section on”.
Is AGENTS.md worth it? What the research says
In February 2026 a team at ETH Zurich and LogicStar.ai published the first careful test, Evaluating AGENTS.md, on SWE-bench tasks and on issues from repositories that had their own context files. Their abstract: providing context files “does not generally improve task success rates, while increasing inference cost by over 20% on average.” And the useful part: “instructions in the context files are well followed by coding agents, repository overviews, although popular and recommended by model providers, are not helpful.”
Put that next to the table above. 44% of top repositories spend part of their AGENTS.md on a tour of the code, the part the study found does not help, and every line of it is paid for on every task. The parts that do work are the ones an agent cannot find on its own: the exact test command, the folder that is generated, the rule that differs from the language’s default. The study’s own conclusion is that context files “are useful for specifying non-standard coding practices”.
A template to copy
# AGENTS.md
## Commands
- Install: `pnpm install`
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Full check before a PR: `pnpm check` (types, lint, tests)
## Rules that differ from the defaults
- Dates are UTC in the API and local only in the UI.
- No new dependencies without asking.
## Do not touch
- `src/generated/` (rebuilt by `pnpm codegen`)
- `migrations/` that are already released
## Pull requests
- Title: `PAY-123: what changed`. Link the work item.
- Say if an AI agent wrote or changed the code, and which one.
## Traps
- The e2e tests need `docker compose up db` first.
Keep the parts you cannot see in the code. Cut what the agent can read from the code itself.
What AGENTS.md cannot hold
An AGENTS.md is the same for every task in the repository. It cannot say what this task is, what “done” means for it, which repository a ticket belongs to when you have twenty, or the rules of the team that owns it. Those live in the work item.
That is the job of Agent Ready, our Jira app: an agent brief, “AGENTS.md for your Jira project”, that goes to the agent with each work item. It holds the company’s rules, the project’s, each issue type’s and each role’s, plus the skills that come with them, and the first line names the repository and base branch from the project’s map. Before the work item reaches the agent, Agent Ready checks it has acceptance criteria and no keys or hidden instructions. The setup page has a Copy the rule button with a few lines for your repository’s AGENTS.md, so agents start each Jira work item through its tools. How that brief is built from skills: agent skills for teams.
Sources
- AGENTS.md and agentsmd/agents.md, read 18 November 2026.
- OpenAI: Custom instructions with AGENTS.md (Codex).
- Claude Code: How Claude remembers your project, sections AGENTS.md, “Where AGENTS.md differs from CLAUDE.md”, “My AGENTS.md isn’t loading”.
- Gloaguen et al., ETH Zurich and LogicStar.ai: Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, arXiv 2602.11988, 2026.
- Our data: default-branch trees of the 1,000 most-starred GitHub repositories and their root AGENTS.md and CLAUDE.md files, 18 November 2026.
Frequently asked questions
Is AGENTS.md the same as CLAUDE.md?
They do the same job for different tools. AGENTS.md is the open format that Codex, Copilot, Cursor and others read. CLAUDE.md is Claude Code's file. Since version 2.1.277 Claude Code also reads AGENTS.md, but only when there is no CLAUDE.md in the working folder or above it. If you have both, put an @AGENTS.md line in CLAUDE.md so Claude reads the shared file too.
Is an AGENTS.md worth it?
For rules an agent cannot guess, yes. A 2026 study by ETH Zurich found that context files did not generally raise task success and raised inference cost by over 20%, but also that agents follow the instructions in them well, and that repository overviews did not help. Keep the file to commands, rules and traps; leave the tour of the code to the code.
What should I put in an AGENTS.md?
The commands to build, test and lint, in a code block; the rules that differ from the defaults (style, naming, what not to touch); how to write commits and pull requests; and the traps: generated files, slow tests, secrets. In the 1,000 most-starred repositories, 88% of AGENTS.md files have "do not" rules and 61% say how to run the tests.
Where does AGENTS.md go?
At the repository root. In a monorepo, add more in subfolders: agents read the nearest one, so the closest file wins. Codex joins every AGENTS.md from the root down to the working folder, up to 32 KiB by default. Of the top 1,000 repositories, 151 have more than one AGENTS.md, and one has 150.
How long should AGENTS.md be?
Short enough that every line earns its tokens, because it is read at the start of every task. The median in the top 1,000 repositories is 110 lines and about 990 words; the longest tenth run past 350 lines. Codex stops reading at 32 KiB by default.
Keep reading
- Jira, JSM and the Marketplace · 6 minSkills vs MCP vs AGENTS.md: Which to Use, and When
- Jira, JSM and the Marketplace · 9 minClaude Code Skills, Tested: What Makes Claude Use One
- Jira, JSM and the Marketplace · 7 minAcceptance Criteria for AI Agents: 3,375 Criteria Checked
- Free toolSKILL.md validator