Ten of the highest scoring AGENTS.md files in the corpus, all of them in repositories you have probably installed.
Every one is a real file at a real path, linked to the commit you can read right now; the numbers beside each are counted from the corpus, not estimated. If you only open one, open mui/material-ui. It is the most complete file this index holds.
Ranked by score, then edited so no language appears three times
Counted 13 September 2026The score rewards runnable commands, explicit prohibitions, architecture context and section coverage, and penalises length. A 500 star floor was applied, then the list was cut for language spread. Length and command counts are measured from the file itself on the last corpus run.
What each one does that the others do not
mui/material-ui
AGENTS.mdThe most complete file in the corpus, and the one to copy first. Every command is written for the exact package manager and workspace filter the repo uses, `pnpm -F @mui/material build`, not `build the package`, so an agent never has to guess a workspace flag. It also does the thing most files forget: a pre-PR checklist and a PR title format, at the bottom, where an agent reaches for them last.
vllm-project/vllm
AGENTS.mdOpens with a mandatory contribution policy before a single build command: check for duplicate work with `gh issue view`, no low-value busywork PRs, fail closed when unsure. Most AGENTS.md files tell an agent how to build. This one tells it when not to open the pull request at all, which is the rule a maintainer actually needs enforced.
caddyserver/caddy
AGENTS.mdNotice what the test commands carry in their comments: `go test -race -short ./...` is labelled as matching CI, and so is the lint command. An agent that runs the documented command gets the same verdict the pipeline will give it, so it stops guessing at a green build.
rails/rails
AGENTS.mdThe clearest worked example of a convention with a right and a wrong shape: it shows `Object#with` for temporary config changes next to the manual set/restore pattern it replaces, labelled Correct and Avoid. Prose telling an agent to 'follow existing patterns' does nothing; two code blocks side by side do.
mozilla/pdf.js
AGENTS.mdThe best architecture section here: the worker/main-thread split is explained before any instruction depends on it, so a rule about where code may live has a reason attached. Its one gap is measured and shown below: the corpus flags it for having no explicit prohibitions.
ethereum/go-ethereum
AGENTS.mdThe shortest file on this list and still a perfect score: a numbered six-step pre-commit checklist, commit message format, PR title format, nothing else. Proof that the quality score is not rewarding length. This is well under half the corpus median and beats almost everything.
duckdb/duckdb
AGENTS.mdThe one to study for navigation rather than rules. It spends whole sections on how to find a component and how to search the codebase, which is the work an agent does before it can follow any instruction. Long enough that the corpus flags the context cost, so read it for the pattern, not the page count.
strapi/strapi
AGENTS.mdThe monorepo reference. More distinct commands than any other file here, and they are separated by the situation that calls for them: unit tests marked as fastest and to be run first, then admin-panel tests, type checking, API integration, CLI, Playwright E2E. An agent picks the cheapest check that could fail.
elastic/elasticsearch
AGENTS.mdWritten for a codebase where the obvious command is wrong. It carries a debugging section for a specific Gradle error an agent will otherwise hit and misdiagnose, plus which Javadoc must be read before touching certain methods. Institutional knowledge, not a README rewrite.
n8n-io/n8n
AGENTS.mdThe longest file on this list, from the highest-starred repository in the corpus, and worth seeing precisely because the length is a real trade. It ships a `pnpm agent:setup` command built for agents specifically, and a security section that survives contact with an agent trying to be helpful. The corpus still flags it for context cost.
Browse the rest at every indexed AGENTS.md, ranked by score, or narrow to your own stack from the stack index.
One question, one answer, nothing collapsed
Read 7 August 2026How long should an AGENTS.md be?
Shorter than most people write it: the median AGENTS.md across 617 repositories in the corpus is 857 words, and the 90th percentile is 3,018. The evidence that length is not the point is in the table above. ethereum/go-ethereum scores 100 on 436 words, while n8n-io/n8n takes 3,124 and is flagged by the corpus for context cost. Every word in an AGENTS.md is loaded on every request the agent makes, so length is a recurring bill, not a one-off. Write the commands and the prohibitions; leave out anything the agent can read off the codebase itself.
Does Claude Code read AGENTS.md?
No. Anthropic’s documentation is explicit: Claude Code reads CLAUDE.md, not AGENTS.md.
The documented fix is not to duplicate the file. It is to create a CLAUDE.md whose first line is @AGENTS.md, which imports the shared instructions, and then add any Claude-specific rules underneath. A symlink works too if you have nothing Claude-specific to add. This is the single most common wrong assumption about AGENTS.md, and it is why 207 repositories in the corpus carry both files. Read the Claude Code memory documentation for the import rules.Read 7 August 2026
Do I need both AGENTS.md and CLAUDE.md?
Only if your team actually uses Claude Code, and then the second file should be one line long. Of the 617 repositories shipping AGENTS.md, 207 also ship CLAUDE.md, 33.5% of them, counted 13 September 2026. That is the number to weigh against the maintenance cost, and no capability table can produce it. The failure mode is not having two files; it is having two files that disagree, which happens the first time someone edits one and forgets the other. Import instead of copying. Full breakdown on AGENTS.md against CLAUDE.md, where CLAUDE.md’s own adoption sits at 359 repositories.
Does Cursor read AGENTS.md, or do I need .cursor/rules?
Cursor reads both. Its documentation describes AGENTS.md as a simple alternative to .cursor/rules
and supports it in the project root and in subdirectories. Reach for .cursor/rules only when you need a rule to load conditionally: that is the one thing AGENTS.md cannot express, and Cursor offers four activation modes for it, Always Apply, Apply Intelligently, Apply to Specific Files, and Apply Manually. One trap worth knowing before you start: Project rules must use the .mdc extension. A plain .md file in .cursor/rules is ignored.
A rule that silently never applies looks exactly like a rule the model chose to ignore. See Cursor’s rules documentation and our ten best Cursor rules, annotated, which counts how many real .mdc files get that frontmatter wrong.Read 7 August 2026
Where does AGENTS.md go in a monorepo?
One at the repository root, then another inside each package that needs different instructions. The specification states that agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions
. In practice that means the root file should carry only what is true everywhere, the package manager, the commit convention, the prohibitions, and per-package files carry the build and test commands for that package. Strapi is the worked example in this list. Checked against agents.md.Read 7 August 2026
What does a good AGENTS.md actually contain?
Runnable commands first, prohibitions second, architecture third. Reading across the ten files above, the sections that recur are: exact build and test commands including the package-manager flags, the lint and format command with a note on whether it matches CI, an explicit list of what not to do, a short architecture orientation, and a pre-PR checklist. The sections that recur in low-scoring files and add nothing are a restated project description, a dependency list, and a directory tree, all three of which the agent can read off the repository for free. AGENTS.md has no schema to help you here: AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.
That freedom is why the median file is mediocre and why the ten above are worth reading before you write yours.
Three primary sources, and the corpus
Read 7 August 2026Adoption, length and command counts on this page are measured from the corpus, not asserted, and were counted 13 September 2026. The method and the raw figures are on the AGENTS.md format page.