What goes in a CLAUDE.md file: data from 42,106 AGENTS.md, CLAUDE.md and SKILL.md files
Data on CLAUDE.md and AGENTS.md files in 38,272 active GitHub repos with 1,000+ stars: length, sections, test commands, and how often CLAUDE.md skips AGENTS.md.
A CLAUDE.md file is a Markdown file in a repo that Claude Code reads at the start of every session; an AGENTS.md file does the same job for Codex, Cursor, Copilot and other coding agents. A coding agent starts every session knowing nothing about your repo. It does not know that the tests run with pnpm test --filter api, that src/legacy/ is frozen, or that you squash-merge. These files hand it that context before it starts.
I wanted counts for how people write these files, so I read all of them in a defined set of popular repos. This post covers the method, the results, and a checker you can run on your own files. The data and the checker are open: github.com/prasadus92/agent-files-index.
The 3 file types
AGENTS.mdis the open format read by Codex, Cursor, GitHub Copilot and the other tools listed on agents.md. It has no required fields. Codex reads 1 per folder, from the repo root down to the folder you run it in, and stops at 32 KiB in total.CLAUDE.mdis what Claude Code reads. It can pull in other files with@pathimports. By default, Claude Code readsAGENTS.mdonly when there is noCLAUDE.md, so a repo with both has to connect them.SKILL.mddescribes 1 skill: a folder of instructions, and sometimes scripts, that the agent loads only when a task needs it. It starts with YAML frontmatter holding aname(up to 64 lowercase characters) and adescription(up to 1,024 characters) that the agent uses to decide when to load it.
The first 2 sit in context on every task, so every line costs tokens every time. Both vendors say to keep them short and specific. Claude Code's docs suggest under 200 lines for a CLAUDE.md file.
How I sampled
GitHub code search is the obvious tool, and it does not work for this. On 15 November 2026 it returned 1,353,728 hits for filename:AGENTS.md and 1,067,008 for filename:CLAUDE.md. It caps every query at 1,000 results, allows 10 queries a minute, and ranks by relevance, so a page of results has no defined population behind it.
So I started from repos instead of files:
- A census. Every public, non-fork, non-archived repo with 1,000 or more stars and a push in the last 12 months: 38,272 repos.
- A sample. The same filters with 100 to 999 stars, limited to repos created on 345 random days since 2008: 7,912 repos, standing for about 158,000. Every repo in that band had the same chance of selection.
For each repo I read the root tree at the head commit, fetched AGENTS.md, CLAUDE.md, .claude/CLAUDE.md and up to 50 SKILL.md files from skills/, .claude/skills/ and .agents/skills/, and recorded the commit SHA. A plain Python extractor then measured each file: size, headings, commands, rule words, links and paths. No model reads the files. The full method is in the repo's docs/method.md.
The crawl took about 2.5 hours on GitHub's GraphQL and REST APIs. It produced 42,106 files: 7,502 AGENTS.md, 5,252 CLAUDE.md and 29,352 SKILL.md. File numbers below are for the census unless they say otherwise.
1 in 5 popular repos has one, and it climbs with stars
21.3% of the 1,000+ star repos have an AGENTS.md or CLAUDE.md. 17.3% have AGENTS.md, 12.0% have CLAUDE.md, and 8.0% have both. In the 100 to 999 star sample it is 15.2%.
The share rises with stars, from 17.8% of repos with 1,000 to 1,999 stars to 47.5% of the 488 repos with 50,000 or more. 38.9% of the 1,000+ star repos created in 2026 have one, against 15% to 17% for repos created between 2013 and 2020.
By language, TypeScript leads at 37.8%, then Rust at 32.2% and Go at 26.6%. Python sits at 21.3%, and Jupyter notebook repos at 8.4%.
AGENTS.md is the common format. The tool-specific files trail it: Copilot instructions in 3.5% of repos, Cursor rules in 1.4%, GEMINI.md in 0.6%.
A typical CLAUDE.md file is under 60 lines
The median CLAUDE.md file is 55 lines, about 670 tokens. The median AGENTS.md is 96 lines, about 1,400 tokens. At the long end:
- 16.5% of
CLAUDE.mdfiles are over Claude Code's 200-line guidance. - 4.0% of
AGENTS.mdfiles are over 32 KiB, which means Codex truncates it and adds noAGENTS.mdfrom subfolders. - The 90th percentile is 316 lines for
AGENTS.mdand 287 forCLAUDE.md.
CLAUDE.md examples: the sections popular repos use
I matched every heading against 17 keyword categories. For AGENTS.md, leaving out agent workflow (75.7%), a category whose keywords also catch title headings like # AGENTS.md, the most common are code style (51.4% of files), testing (51.2%), architecture (50.1%) and git or pull request rules (49.1%). Security headings appear in 12.9%.
Leaving out agent workflow (59.8%) for the same reason, CLAUDE.md files lean on architecture (43.7%) and commands (39.8%). Fewer of them cover testing (33.5%) or git rules (23.8%), and 6.6% have a security heading.
After the file's own title (# AGENTS.md in 17.1%, # CLAUDE.md in 14.1%), the most common single headings across both file types are "project overview" (14.0% of files), "architecture" (13.7%), "testing" (13.5%), "commands" (9.6%) and "code style" (6.9%). If you want CLAUDE.md examples to copy from, the dataset lists every file with its repo and commit, so you can filter for repos in your language and read the originals.
57% of AGENTS.md and 40% of CLAUDE.md files name a test command
A test command lets the agent check its own change. 57.4% of AGENTS.md files have a test command in a code block or inline code. 40.1% of CLAUDE.md files do.
AGENTS.md files are more operational overall: 81.2% contain at least 1 command, against 55.4% of CLAUDE.md files. A third of CLAUDE.md files (34.0%) have only ever had 1 commit, against 20.0% of AGENTS.md files. The obvious guess is /init output committed once and left alone, and the data does not back it. A quarter of CLAUDE.md files (25.4%) contain "This file provides guidance to Claude Code", the sentence Claude Code's /init command opens the file with. Only 22.8% of those have a single commit, against 37.9% of the rest, and only 17.0% of the single-commit files carry the sentence. Files that keep the /init sentence are more likely to have been changed after their first commit, not less.
AGENTS.md and CLAUDE.md in the same repo
2,968 repos in the census ship both AGENTS.md and a root CLAUDE.md. By default, Claude Code reads AGENTS.md only when there is no CLAUDE.md, so the second file needs to point at the first. Here is what those repos do:
- 38.3% import it with an
@AGENTS.mdline. - 24.6% make
CLAUDE.mda symlink to it. - 16.1% mention it in the text, for example "read AGENTS.md first". Claude Code's docs say a file named only in words is read only if Claude decides to open it.
- 20.1% never refer to it. In those 597 repos, Claude Code works from
CLAUDE.mdalone and never sees theAGENTS.mdnext to it.
The fix is 1 line. Put @AGENTS.md at the top of CLAUDE.md, or replace CLAUDE.md with a symlink.
About 1 in 4 name a path the checker cannot find
Agent files name repo paths: "the entry point is src/server/index.ts". I checked each repo path at the recorded commit. If it was not where the file said, I looked for any file in the repo ending with that path, because files can describe paths relative to a package folder.
27.1% of AGENTS.md and 28.6% of CLAUDE.md files that name repo paths name at least 1 that exists nowhere in the repo. That number overstates staleness. When I hand-checked 30 of those paths, 11 were stale: deleted files, moved files and broken links. The other 19 were build output, date placeholders, files in another repo, or files the agent is told to create. So about 1 in 3 flagged paths is stale. Applied to the file shares, that is roughly 1 in 10 files, with a wide margin since the check covered 30 paths. Any single flag is worth a look before you act on it.
Skills: 29,352 files in 4,130 repos
SKILL.md adoption is concentrated. 9.6% of the 1,000+ star repos have at least 1. Repos with skills have a median of 3 skill files and a mean of 7.1; 88 repos reach the crawl's cap of 50. Across all 29,352 skill files from both frames, 98.9% of skill files have frontmatter. 3.5% have a name that breaks the spec, mostly because it does not match the folder the skill lives in. 4.3% have a body over the 500 lines the spec recommends. 8.9% set allowed-tools.
Secrets and risky text: close to none
I scanned all 42,106 files for 11 credential patterns: cloud and API key formats, private key blocks, JWTs, and connection strings with passwords. The raw patterns matched in 119 file and pattern pairs. Nearly all were placeholders, local dev credentials like postgres:password@localhost, or documentation examples. After filtering those, 2 files remain, each with an AWS-format access key ID and no secret key next to it.
Text that tries to override the agent, such as "ignore all previous instructions" outside a quote or code block, appears in 4 files. Absolute home-directory paths such as /Users/<name>/, which work on 1 laptop only, appear in 496 files. 188 files tell the agent to pipe a downloaded script into a shell.
The published tables carry counts only for secrets and override text, with no repo names.
The checker
Each problem above is also a rule in agentfiles, a checker with no dependencies beyond Python 3.11:
uvx --from git+https://github.com/prasadus92/agent-files-index agentfiles lint
It finds the agent files in the current repo and reports problems like these:
CLAUDE.md: warning AF601 CLAUDE.md never mentions AGENTS.md: AGENTS.md sits next to this file and is never mentioned; add @AGENTS.md or symlink CLAUDE.md to it
CLAUDE.md:41: warning AF401 referenced path does not exist: `src/server/routes.ts` not found
.claude/skills/pdf/SKILL.md: error AF502 invalid skill name: name 'PDF Tools' must be 1 to 64 lowercase letters, digits or single hyphens
There are 24 rules. Each one names its source: the Claude Code docs, the Codex docs, the Agent Skills spec, agents.md, or this dataset. It also runs as a GitHub Action and as a pre-commit hook. The README has the snippets.
Limits
- Stars measure attention. This frame leans toward AI tooling repos, which gained stars quickly in 2025 and 2026.
- Version 1 reads root files,
.claude/CLAUDE.mdand 1 level of skill folders. Monorepos withAGENTS.mdin each package count only for the root, so adoption is a lower bound. - Headings and commands are matched by keyword rules. A section titled "How we ship" will not count as git rules.
- Listing the census took about 35 minutes, and stars and pushes moved during it.
Get the data
The repo has CSV and Parquet tables, a data card and every pipeline step, so you can rerun the crawl or extend it:
repos: 46,184 rows, 1 per repo, with a flag per agent file location.files: 42,106 rows with 66 features each, plus the repo, path and commit SHA.headings,commandsandlint_findingsfor finer cuts.
Data is CC BY 4.0, the code is MIT, and CITATION.cff has the citation.
Key takeaways
- 21.3% of active public repos with 1,000+ stars ship an
AGENTS.mdorCLAUDE.md, rising to 47.5% at 50,000+ stars and 38.9% for repos created in 2026. - The median
CLAUDE.mdfile is 55 lines. 16.5% are over the 200 lines Claude Code suggests. - 57.4% of
AGENTS.mdand 40.1% ofCLAUDE.mdfiles give the agent a test command. Put yours near the top. - If you ship both files, check that
CLAUDE.mdimports or symlinksAGENTS.md. 37.1% of repos with both do neither, and 20.1% never mention it. - Run
agentfiles linton your repo to find these issues in your own files.
Common questions
What is a CLAUDE.md file?↓
A CLAUDE.md file is a Markdown file at the root of a repo, or in `.claude/CLAUDE.md`, that Claude Code loads into context at the start of every session. It holds what the agent cannot work out from the code: the exact test and lint commands, conventions, and things to avoid. It can pull in other files with `@path` imports.
Is a CLAUDE.md file needed?↓
No. Claude Code works without one, and if the repo has an AGENTS.md and no CLAUDE.md, Claude Code reads the AGENTS.md. A CLAUDE.md file helps when the agent keeps getting something wrong that the code does not show, such as the right test command or a folder it must not touch. 12.0% of active public repos with 1,000+ stars have one.
What should I put in my CLAUDE.md file?↓
The commands to build, test and lint, with flags; the conventions a new contributor would get wrong; and the things the agent must not do. The most common headings in the files in this dataset are project overview, architecture, testing, commands and code style. Keep it short: Claude Code's docs suggest under 200 lines, and the median file is 55.
Should I use CLAUDE.md or AGENTS.md?↓
Write the instructions once in AGENTS.md, which Codex, Cursor, GitHub Copilot and other tools read, and add a CLAUDE.md that contains `@AGENTS.md` or is a symlink to it. By default, Claude Code reads AGENTS.md only when there is no CLAUDE.md. In this dataset, 20.1% of repos with both files do neither and never mention AGENTS.md.
How long should a CLAUDE.md file be?↓
Claude Code's docs suggest under 200 lines. In this dataset the median CLAUDE.md file is 55 lines and 16.5% are over 200. Codex stops reading AGENTS.md content at 32 KiB in total, and 4.0% of AGENTS.md files are larger than that on their own.
Where can I find CLAUDE.md examples?↓
The dataset lists 5,252 CLAUDE.md and 7,502 AGENTS.md files with their repo, path and commit SHA, so you can filter by language, stars or structure and open the originals on GitHub. It publishes features and common headings, never the file text.