AGENTS.md in the wild

An AGENTS.md is a Markdown file at the root of a repository that tells a coding agent how the project works: how to build it, how to run the tests, what not to touch. OpenAI's Codex CLI switched to the name in May 2025, a group of agent makers put it on agents.md that August, and the Linux Foundation took it in that December. Claude Code, which had kept its own CLAUDE.md, began reading it on 18 September 2026, in projects with no CLAUDE.md, after the most-upvoted feature request in its repository.

We wanted to know what developers actually put in these files, so we counted. We checked the root of every one of the 5,710 public GitHub repositories with at least 10,000 stars, dated each file from its git history, and drew a random sample of 2,230 AGENTS.md, 1,232 CLAUDE.md and 751 .cursorrules files from all of GitHub that ranking couldn't bias. Then we read them with scripts and by hand, and set that next to every controlled study we could find on whether the files help. The methodology explains how, and where the counts fall short.

How AGENTS.md took the popular repos#

The most-starred repositories on GitHub are a good place to watch a convention spread, because they're maintained, public and few enough to check one by one. We listed all 5,710 non-fork repositories with at least 10,000 stars and looked at the root of each default branch on 31 October 2026, then dated each file by the first commit that added it.

The first root AGENTS.md among these repositories appeared on 11 May 2025, in Open Interpreter's, the day after Codex CLI migrated from codex.md to AGENTS.md. Chatwoot, trigger.dev, Bun, FastMCP, Langfuse and OpenAI's Agents SDK followed within a week. CLAUDE.md had a head start of about two and a half months, since it shipped with Claude Code in February 2025, and led until November 2025. Today 25.0% of these repositories have one file or the other, 10.2% have both, and 27.5% have at least one of the instruction files we checked.

By October 2026 the list included torvalds/linux (an AGENTS.md added on 14 October that is a symlink to the kernel's README), Kubernetes, VS Code, Next.js, React Native, Hugging Face Transformers, LangChain, llama.cpp and Bootstrap. React itself, Electron and Anthropic's own claude-code repository have a CLAUDE.md and no AGENTS.md.

Language matters too. 42.1% of the popular Rust repositories and 40.8% of the TypeScript ones have an AGENTS.md, against 22.5% in Python and 9.9% in JavaScript. A separate census of 22,854 "popular, active" repositories in 13 languages, posted to arXiv in October, found agent instructions in 26.3% of them, close to our 25.0%, though the two populations are drawn differently (theirs is filtered for activity and language, ours is a hard star cut).

A year of standards, and who reads them#

None of these files is new as an idea. .cursorrules shipped in Cursor 0.32 in April 2024, GitHub added copilot-instructions.md that October, and every agent since has had its own file. AGENTS.md is the attempt to make one name work for all of them.

We re-read the instruction-file docs of 15 agents on 31 October. Twelve read AGENTS.md on their own. Three don't, quite.

Of the agents that came around, Claude Code took the longest. Issue #6235, "Support AGENTS.md", was opened the day after agents.md went live and collected 5,190 👍, 2.5 times the next most-upvoted issue in the repository. GitHub shows it closed on 17 August 2026, but the feature shipped a month later, in v2.1.277 on 18 September. "If there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md," Anthropic's Thariq Shihipar told The Register. Claude Code's logo has never appeared on the agents.md site, which lists 23 agents.

The switch shows up in commit messages. GitHub's commit search counts every public commit whose message names the file ("Update AGENTS.md", "add CLAUDE.md"), which measures activity rather than adoption, and agents write some of those commits themselves.

The agents.md site says AGENTS.md is "used by over 60k open-source projects". That's the site's claim, and by our Wayback check it hasn't changed since 9 December 2025, the day the foundation was announced; it said 20k before that. It's about a tenth of the repositories GitHub search finds, so the site is probably counting something else.

About a million files, mostly in new repos#

GitHub's code search reports about 1.1 million hits for filename:AGENTS.md. That total is an estimate, and about 9% of the hits are other files (ADDING_AGENTS.md, agents.mdx, templates), so the honest number is about a million. CLAUDE.md is the same size, within our error. The two tie on repositories too: about 0.6–0.8 million each, and about 35% of repositories with an AGENTS.md also have a CLAUDE.md.

Almost none of these files are in projects anyone has heard of. In our random sample, 55.5% of AGENTS.md files sit in repositories with no stars at all and 87% in repositories with fewer than 10. 76.5% are in repositories created in 2026, and nearly half (45.8%) of the AGENTS.md files on GitHub today were first committed between August and October 2026. "AGENTS.md on GitHub" is mostly new personal projects, many of them started by an agent, and the most-starred repositories are 0.3% of it. Whenever a number below is about all of GitHub, that's the population. Private repositories, where most team work probably happens, aren't visible to anyone.

What's in an AGENTS.md#

The median AGENTS.md in our sample is 437 words, 56 lines and about 880 tokens, with seven headings. A quarter are under 165 words; one in ten runs past 1,953. CLAUDE.md files run a little longer (515 words at the median), .cursorrules shorter (320). In repositories with 10,000+ stars, a real AGENTS.md (not a symlink or a stub) is twice as long, at 890 words.

What they say is fairly uniform. Nearly three in four tell the agent what it must or must never do. Fewer than half give it a command it can run. A fifth set a rule about secrets. The headings we matched by keyword (so the shares are approximate) are mostly commands, architecture and code style.

The tools they name are the ones you'd expect: npm in 15.5% of AGENTS.md files, pytest in 8.0%, pnpm in 7.7%, then git, npx, tsc, uv and make. 7.8% aren't in English. The commands are usually right: of the 80 npm scripts named in our 100-file staleness sample, all 80 exist in the repository's package.json.

Boilerplate, pointers and files nobody touches#

Many of these files weren't written so much as generated. Claude Code's /init command opens every CLAUDE.md it writes with "This file provides guidance to Claude Code", and 26.6% of the CLAUDE.md files on GitHub still say it. Code search, counting differently, finds the phrase in about a fifth of them. AGENTS.md carries fewer fingerprints: Codex's /init heading "Repository Guidelines" in 2.7%, and the block that create-next-app writes in 1.7%.

Then there are the pointers. Since Claude Code didn't read AGENTS.md until September, the common fix was a CLAUDE.md that only says @AGENTS.md, Claude Code's import syntax. 35,712 CLAUDE.md files are exactly 11 bytes, which is that line plus a newline. Counting every tiny file and sampling the slightly bigger ones, about 126,000 CLAUDE.md files, roughly 13%, do nothing but point elsewhere. In the repositories with 10,000+ stars it's most of them: 419 of 780 CLAUDE.md files (54%) are a symlink or a pointer stub, and 164 are a symlink straight to AGENTS.md.

And most files are written once. We traced each sampled file's history on its default branch.

Some go stale. We pulled 100 random AGENTS.md files, extracted every path they mention and checked each one against the repository tree at that commit. After removing false positives by hand, 15 files referred to at least one file or folder in their own repository that no longer exists, with 8 more uncertain: a contributing guide renamed from 04- to 05-, a module moved into crates/, a tailwind.config.js in a project on a Tailwind version that doesn't use one. About one in six, give or take, is enough to matter, as the next section shows.

Do these files help#

The research is young — we found 32 arXiv papers centrally about agent instruction files, most of them from 2026, and that's a floor — but the controlled results point the same way. Files that tell an agent something it can't work out (a new API, a local rule) can help a lot. Files that describe what the code already shows help little and cost tokens.

The sharpest result is about the stale files. In a study posted on 22 October, researchers built 40 Python projects whose instruction file and code disagreed on a convention, then asked Claude Code and Codex CLI to add a feature, 320 runs in all.

So a file that's one in six wrong is not harmless. The vendors' advice has moved the same way. In April 2025 Anthropic suggested adding emphasis like "IMPORTANT" to improve adherence; its current docs say to target "under 200 lines per CLAUDE.md file", and OpenAI's Codex guide says "a short, accurate AGENTS.md is more useful than a long file full of vague rules."

The security question#

An instruction file is text an agent obeys, shipped by whoever wrote the repository. That makes it a prompt-injection channel, and researchers have shown it: Pillar Security hid instructions in rule files with invisible Unicode in March 2025, and Gemini CLI fixed an injection through README.md and GEMINI.md that July. But the bugs that got CVE numbers were somewhere else.

When Pillar reported its attack, Cursor said it was "not a vulnerability on their side" and GitHub said users are responsible for reviewing Copilot's suggestions; GitHub later added a warning for hidden Unicode. The fixes go to the config files that execute, and the prose is left to you. Claude Code asks before loading imports that resolve outside the project, a dialog it shows, its docs say, "to protect you from files other people commit". And Copilot code review now reads custom instructions from a pull request's head branch, so a pull request can change what its reviewer is told. Of the files we sampled, 19.6% set a rule about secrets ("never commit secrets", ".env is gitignored"); GitHub's November 2025 review of more than 2,500 agent files called "Never commit secrets" the most common helpful constraint.

What this means if you build with AI#

1. Write one file and point the rest at it. Put your instructions in AGENTS.md. If you use Claude Code, a one-line CLAUDE.md with @AGENTS.md (or no CLAUDE.md at all, since September) keeps them in one place. A CLAUDE.md that says something different will silently win.
2. Lead with commands that run. The exact install, build, test and lint commands, with flags. It's the part agents can't guess and the part that's usually right: every npm script named in our staleness sample existed.
3. Write down what the code can't tell the agent. Local conventions, the deploy step, the API that changed after the model's training. Skip the architecture tour; the agent can read the tree, and the studies found overviews don't help.
4. Prefer "don't" to "do". Negative constraints ("don't edit generated files", "never commit .env") were the rules that helped in isolation. Shouting doesn't make up for it: Claude Code's best-practices page now says adding IMPORTANT to an ignored line "probably won't fix it".
5. Keep it short. A few hundred words covers what most files say. Codex stops at 32 KiB in total and Devin reads 16 KiB per file; past that, split per folder or into linked docs that load when needed.
6. Update it when the code changes. In one study agents followed a stale file over the code nine times in ten. When you rename a folder or change a convention, change the file in the same commit, and add a line to your own user-level file saying the code wins when the two disagree.
7. Don't treat it as a security boundary. Keep secrets out of the file and the repo, and enforce anything that must always happen with hooks, permissions or CI. Claude Code's docs say the same: anything that must happen every time belongs in a hook, a deny rule or a managed setting.
8. Read other people's files before your agent does. An AGENTS.md in a repo you cloned is instructions from a stranger. Skim it, and its config folders, before you let an agent loose in auto-approve mode.

If you want a starting point, our CLAUDE.md generator helps you draft a short one. We build host0 for what comes after: whatever your agent builds goes live at a private link you can share.

Methodology#

We used public data only, collected on 31 October 2026, and re-read the primary pages behind the main studies, docs and quotes that day.

• The popular repos. GitHub's repository search, split into star ranges small enough to return complete lists, gave all 5,710 public non-fork repositories with at least 10,000 stars (305 of them archived). For each we listed the root of the default branch and eight config folders through the GraphQL API, case-insensitive, and recorded symlinks. A file's date is the oldest commit touching that exact path, so renames reset it and deleted files are not counted. Nested files weren't checked, so these shares are floors.
• File counts. GitHub code search totals for each file name, read three times, corrected by the share of hits that really are that file (from fully enumerated random windows). Code search covers default branches of non-fork repositories and files under 384 KB. Its totals are estimates, so we give rounded figures and ranges, and we make no claim about which of AGENTS.md and CLAUDE.md is in more repositories overall.
• The random sample. Code search returns at most 1,000 ranked results per query, so we split each file type into byte-size bins and enumerated every hit in random narrow size windows inside each bin, keeping at most 40 files per window and weighting each by its bin's total. That gave 2,230 AGENTS.md files from 2,096 repositories, 1,232 CLAUDE.md files and 751 .cursorrules. Texts were fetched at the exact indexed commit. Tokens are bytes divided by four, not a tokenizer.
• Content. Regular expressions for each signal, with hand checks of precision where noted. "A rule about secrets" was right about 16 times in 20; a looser "mentions secrets" (34.2%) also catches auth features, so we don't use it. Heading shares are keyword matches and approximate. Generator shares are floors.
• Pointers and edits. Every CLAUDE.md of 1 to 60 bytes and AGENTS.md of 1 to 40 bytes was enumerated and classified; files of 61 to 400 bytes were sampled. Edit counts are commits touching the file's path on the default branch.
• Staleness. 100 random AGENTS.md files; every path in backticks or links checked against the repository tree at the indexed commit, false positives (import paths, build output, gitignored files, placeholders) removed by hand.
• Commit mentions. GitHub commit search totals for messages containing each file name, two readings per window. This counts activity, including commits written by agents, not adoption.
• Support and history. Each agent's own docs, read on 31 October 2026; dates from changelogs, commits, npm publish times and Wayback Machine captures.
• CVEs. NVD's CVE API searched for 17 file and agent names; 25 machine hits plus 4 known CVEs, coded by hand to 20 where a repository file was the vector. NVD descriptions are terse, so the coding is ours and could miss an instruction-file vector the text doesn't name.
• Studies. We cite each paper's own numbers; for the ETH Zurich paper, its §4.2 results. The agents.md "60k projects" and Vercel's eval are the publishers' own claims.

The data pack, with every source, tier, a reconciliation with arXiv 2610.31715 and a do-not-cite list, is in our repository at docs/research/2026-10-31-agents-md.md. The scripts and the series behind every chart are in docs/research/2026-10-31-agents-md-data/.

Open questions#

• What happens in private repositories? Team use is probably concentrated there, and nobody outside GitHub can count it.
• How often do agents actually read nested files? No tool publishes it, and most files we found are at the root.
• Will the spec grow? Proposals for a global file, directories and imports have been open on the spec's repository since 2025; it has had 38 commits in total.
• Does a maintained file beat no file? The studies compare files to no files, not fresh files to stale ones in real repositories. That's the comparison most teams need.
• When does a prose instruction file become a CVE? So far the answer has been never, and it isn't clear whether that's policy or a gap.