What the 100 biggest GitHub repos put in their AGENTS.md files

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 I suppose 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 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. Redirected content not taken into consideration

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.

testing²²commands¹⁴project overview¹³architecture¹¹development workflow¹⁰project structure⁸code style⁸tests⁷common commands⁷code quality⁶overview⁶environment variables⁶pull request guidelines⁶build⁶monorepo structure⁵documentation⁵running tests⁵setup commands⁵type checking⁴conventions⁴

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.

Whether or not we agree this is what 'perfect' looks like, is a different conversation. It's however a great starting point you can refine to suit your specific project needs.

Who writes these files

TypeScript, Python, Go, JavaScript, and Rust cover four fifths of the sample. vscode, ollama, pytorch, bun, zed, n8n, AutoGPT, and webpack all ship an AGENTS.md. We may be past early-adopter habit now.

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.

Watch the whole study move

The census as one animated field of dots: 1,000 repos sweep down to the 100 we read, then pile up by word count until the axis has to stretch for OpenHands.

Filmed from the interactive census, where every dot is a real repository you can tap to open its actual AGENTS.md.

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 empty, so content statistics cover 99 files. Classification is regex-based, so individual percentages carry a few points of noise; the ordering is robust.