What GitHub's biggest repos tell their agents
We read the AGENTS.md files of the 100 most-starred repos on GitHub that have one. What the giants write for their coding agents, what they ban, and a copy-paste template distilled from all of it.
We walked GitHub's most-starred repositories in order and kept the first
hundred with an AGENTS.md at the root. Together they hold 11.4 million stars:
vscode, ollama, n8n, pytorch, and 96 more. We read every file to find out what
the biggest projects on GitHub tell their coding agents.
They're operating manuals, not rulebooks
Split every file into sections, classify each section by theme, and count the words: even at the very top, the AGENTS.md is an operating manual first. Orientation (what this project is, how the code is laid out) and verification (how to build it, test it, and prove a change didn't break anything) together take roughly half of everything written.
But the biggest projects are also the bossiest.
Dedicated rules-and-boundaries sections take 11% of the word count here, nearly double what we measured in a broader sample of smaller repos. The corpus carries 784 explicit "don't" bullets, and 56 of the 99 non-empty files stack three or more. 90% write in must, always, never.
Each of the 100 files was split at its headings; every section was assigned one theme by heading and content keywords, and word counts were summed across the corpus. "Unclassified" covers sections with no dominant theme. Hover a segment or legend row to focus it.
What the majority have in common
Measured as presence (does the file address the topic at all) the ranking
reshuffles from what you may expect. If there is a canonical AGENTS.md, it
says: here's what you must never do, here's how a PR should look, here's how
you test, and here's the code style.
Compared with smaller projects, the giants care visibly more about PR etiquette, CI gates, security, and monorepo structure: the things that hurt at scale.
Detected by pattern-matching headings and body text: named test runners for testing, formatter and linter names for style, negative imperatives for guardrails. Teal bars mark majority topics; grey bars fall below 50%.
The shape of a typical file
The median file runs 1,198 words under roughly 14 headings, but the distribution is a barbell: 37% are constitutions past 1,500 words while one file in ten is under 150.
The extremes get funny.
OpenHands writes 13,718 words. microsoft/vscode writes 33, a polite redirect to its separate 1,600-word Copilot instructions. The entire huggingface/transformers file is the path .ai/AGENTS.md, pointing at a 570-word version that lives there. And one top-100 repo ships an AGENTS.md
that is literally empty.
The shortest real manual belongs to neovim: 35 words, one rule, disclose AI use in your commits. Here it is in full:
AI Disclosure
If AI was used in any way for a commit, add an
AI-assisted: <tool name>trailer to the commit message. If the user commits manually, remind them to add it.
File length in words · n = 99 non-empty files · median 1,198 · range 1 to 13,718
The headings everyone reaches for
Across the corpus, section names converge hard. Counting normalized headings, the same vocabulary tops the list, sized here by how many of the 100 files use it.
Dear agent, never do that again
Whatever the section, most entries are commands, not commentary.
We counted 784 explicit negative-rule bullets across the sample, and they're wonderfully specific. They feel like someone logged exact mistakes an agent already made in their repo once.
Once bitten, twice shy, eh?
There are 784 of these. The roulette below deals from a pool of 24, all verbatim, all real instructions one of GitHub's biggest repositories gives its agents, and most of them load-bearing.
The perfect AGENTS.md
Judging solely by these top repositories, this is supposedly the perfect AGENTS.md file i.e., everything the hundred agree on, folded into one file.
The section order follows the corpus; the rules are drawn from its most repeated instructions.
Swap the placeholders, delete what doesn't apply, and keep it under two pages: the median file is around 1,200 words, and neovim gets by on one rule.
# AGENTS.md ## Project overview One short paragraph: what this project does and the parts an agent will touch most. Link deeper docs instead of repeating them. ## Project structure - `src/` - core application code - `tests/` - test suites, mirrors `src/` - `docs/` - contributor documentation ## Setup & build ```bash <install command> # e.g. pnpm install <build command> # e.g. pnpm build ``` ## Testing ```bash <full test suite> # e.g. pnpm test <single test> # e.g. pnpm vitest run path/to/file.test.ts <lint + typecheck> # e.g. pnpm lint && pnpm typecheck ``` - Run the full suite before committing. All tests must pass. - While iterating, run the single test closest to your change. - Never delete, weaken, or rewrite a test to make a change pass. - Do not claim that an interrupted or timed-out run passed. ## Code style - Formatter: <tool>. Linter: <tool>. Run them; do not hand-format. - Follow the patterns already in neighboring files. - Do not add comments that restate the code. - Do not reformat code you are not otherwise changing. ## Git workflow - Branch from <branch>; PRs target <branch>. - Commit format: <convention, e.g. Conventional Commits>. - Never commit, push, or open a PR unless asked. - All CI checks must pass before merge. ## Boundaries - Do not modify unrelated files or widen scope beyond the request. - Do not add dependencies without asking. - Never commit secrets, API keys, or .env files. - If a command fails, report the failure. Do not guess or present assumptions as confirmed results.
Sections are ordered by how often the corpus writes them; every rule paraphrases instructions that appear repeatedly across the 100 files.
Who writes these files
TypeScript, Python, Go, JavaScript, and Rust cover four fifths of the sample,
but the roster is the point: vscode, ollama, pytorch, bun, zed, n8n, AutoGPT,
and webpack all ship an AGENTS.md. This stopped being an early-adopter habit.
Regardless, I'm personally surprised that only 27% of the top repos have an AGENTS.md file.
Primary repository language per the GitHub API · the top five languages cover 80 of the 100 repos
Score your own AGENTS.md
Eight things the sample writes down most. Tick what your file already covers and see how you compare with the hundred.
Method
We enumerated GitHub's 1,000 most-starred public repositories and checked each for a root AGENTS.md: 273 have one (27%). The 100 most-starred of those form the sample: 64k to 387k stars each, 11.4M combined. Files were fetched at HEAD on August 21, 2026; one is literally empty, so content statistics cover 99 files. Classification is regex-based, so individual percentages carry a few points of noise; the ordering is robust.