# What goes in an AGENTS.md: 4,687 files counted

By markdownregistry. Published October 7, 2026. Updated October 7, 2026.

About half of the root AGENTS.md files we read list a test or check command for the agent to run. Of 1,559 AGENTS.md files at the root of public GitHub repositories, 68.3% list a command to run and 48.2% list a test or check command, the kind of command the AGENTS.md site says an agent will try to run before it finishes. Only 2.4% have a heading for all six topics the site suggests.

| The root AGENTS.md | Files | Share |
| --- | --- | --- |
| Lists a command to run | 1,065 | 68.3% |
| Lists a test or check command | 751 | 48.2% |
| Has a build or setup heading | 568 | 36.4% |
| Has a testing heading | 492 | 31.6% |
| Has a commit or pull request heading | 450 | 28.9% |
| Has a code style heading | 408 | 26.2% |
| Has an overview heading | 373 | 23.9% |
| Has a security heading | 186 | 11.9% |
| Has a heading for all six | 38 | 2.4% |

1,559 AGENTS.md files at the root of public GitHub repositories, each read at its latest version in the registry on October 7, 2026, one per repository. The six headings are the topics the AGENTS.md site suggests. How each was counted is under How we counted.

Counted from the registry's own crawl of public GitHub, read on October 7, 2026, against [the AGENTS.md site](https://agents.md/) as it read that day.

## What the format asks for

The [AGENTS.md site](https://agents.md/) describes the file as a predictable place for the context and instructions that help coding agents work on a project. It has no required fields: it is plain markdown, with any headings. It suggests what to put in it: a project overview, build and test commands, code style guidelines, testing instructions and security considerations, plus commit or pull request guidelines. And it says that when a file lists programmatic checks, the agent will try to run them and fix failures before finishing the task.

## What 1,559 root files hold

The median root AGENTS.md runs 90 lines, and 201 (12.9%) are under 20. By heading, build or setup instructions are the most common of the six topics, in 36.4% of root files, then testing (31.6%), commit or pull request guidelines (28.9%), code style (26.2%) and an overview (23.9%). Security is the rarest, in 11.9%. Only 38 files have a heading for all six. A file can cover a topic in prose without a heading for it, so read these as how often a project gives the topic a section of its own.

## Commands, and the checks an agent runs

Of the root files, 1,065 (68.3%) list at least one command, in a code block or inline. The tools named most across all files are npm, in 508 files, then node (306), python3 (303), uv (295) and npx (289).

Fewer list a check: 751 root files (48.2%) list a test runner, a linter, a type checker or a validation step, such as `pnpm test`, `cargo clippy` or `npx tsc --noEmit`. That is the line that lets an agent confirm its own change before it hands the work back. Another 314 root files (20.1%) name commands, but none that our match counts as a check; a check described in prose, or under a name we do not match, is not counted.

## Nested files

Only 1,559 of the 4,687 AGENTS.md files counted (33.3%) sit at a repository's root; the rest are inside folders. The AGENTS.md site says agents read the nearest file in the directory tree, so a package's own AGENTS.md takes precedence over the root one. 390 repositories hold more than one, and one holds 188. Nested files are short: the 3,128 nested files run a median of 35 lines, and 32.8% are under 20, against 90 lines and 12.9% for root files.

## Check your own AGENTS.md

This prints each line of an AGENTS.md that names a test runner, linter, type checker or validation step, in code or in prose. It prints every line our count would include, and some it would not, such as a sentence about tests. This is the output on a scratch file whose setup block lists `pnpm install` and `pnpm dev` and whose last section says to run `pnpm lint` and `pnpm test`:

```
$ grep -niE '(^|[^[:alnum:]_])(test|tests|pytest|vitest|jest|unittest|nextest|ctest|rspec|phpunit|tox|nox|lint|eslint|ruff|clippy|vet|mypy|pyright|typecheck|type-check|tsc --noEmit|check|validate|verify)([^[:alnum:]_]|$)' AGENTS.md
10:Run `pnpm lint` and `pnpm test`.
```

Read each line it prints: a line that only talks about tests is not a command the agent can run. If no line gives the exact command that proves a change works, add one, written exactly as it should be typed. Real AGENTS.md files from other projects are on [the AGENTS.md page](https://markdownregistry.com/kind/agents), most starred first, and a starting file with what to change in it is the [AGENTS.md starter on mdpantry](https://mdpantry.com/s/st_zdlp6lbqoiyo3ecb). How AGENTS.md relates to CLAUDE.md is in [AGENTS.md and CLAUDE.md in one repo: what 1,203 folders do](https://markdownregistry.com/blog/agents-md-and-claude-md-in-one-repo).

## How we counted

The registry collects agent markdown from public GitHub repositories and stores every version of each file by the SHA-256 of its content. We took every file named AGENTS.md it holds, read each one's latest stored version, and checked its bytes against its hash. A heading counts when it sits outside fenced code. A topic counts when a heading matches words such as these: an overview (overview, about, introduction, architecture, project structure), build or setup (build, setup, install, getting started, quick start, commands, scripts, running), code style (code style, conventions, formatting, lint, naming), testing (test, testing, QA, quality, verification, checks), security (security, secrets, credentials, permissions, safety) or commits (commit, pull request, PR, git, branch, changelog, contributing, review). The full word lists are in the counting script. A fence counts wherever it is indented, and closes only on a bare fence. A command counts when a line in a fenced code block, or an inline code span, starts with a known build or package tool such as npm, pnpm, uv, make or cargo, and is not an assignment in code or a version such as node 20. It is a test or check command when it names a test runner, a linter, a type checker or a validator: test, tests, pytest, vitest, jest, unittest, nextest, playwright test, ctest, rspec, phpunit, tox, nox, lint, eslint, ruff, clippy, vet, mypy, pyright, typecheck, type-check, tsc --noEmit, check, validate or verify. These are lexical matches, so a file can describe a check in prose and not be counted. Root files are the 1,559 at a repository's root, one per repository. The registry crawls the public repositories it has found that hold agent files, not all of GitHub, so read the shares as describing those repositories.

## Sources

- [AGENTS.md: the open format, what to include and how agents use it](https://agents.md/)

Last checked October 7, 2026. The page: https://markdownregistry.com/blog/what-goes-in-an-agents-md