The State of AI Instruction Quality: Q3 2026

91% of the most-starred repos on GitHub give their coding agent at least one instruction that never says which file, command or tool it means.

In April we measured 28,721 repos, and our own limitations section admitted that a 10-star side project counted the same as a 50,000-star production repo. This time we started from the other end: the 10,000 most-starred English-language repos that ship instructions for a coding agent. If you've ever opened a well-known repo to see how they wrote their AGENTS.md, these are the files you were looking at.

10,000 repos. 15,237 agent setups. Read in September 2026 and scored with the same ails check you can run on your own repo.

The short version

• 91.1% of repos have at least one vague instruction. Among the lines that tell the agent what to do, about 1 in 3 is vague.
• Vague is the most common finding of several: 96.6% of repos have at least one finding, 38 in the median repo.
• Star count doesn't predict the score (Spearman's rho -0.028 across 9,674 repos).
• Sub-agent files score lowest: 19.6% of them score below 5, against 6.8% of main files.
• Only 7.6% of repos back their instructions with an agent hook.

91% of repos carry at least one vague instruction

One AGENTS.md from a popular Python project runs to 386 lines, and most of it is careful work. It names requirements.txt, torch.inference_mode and dozens of the project's own modules the agent can look up. It also has two rules about dependencies:

Both are sensible. The second one gives the agent a file to open and a condition to test. The first leaves "absolutely necessary" for the agent to decide on its own, mid-task, with nothing in the file to check its call against.

ails check flags the first one as CORE:C:0042, a vague instruction: a directive or constraint that names no file, command or tool, in a section where other lines do. The second one passes.

Another popular repo's Copilot instructions ask for the same kind of judgment call:

When there is an option, opt for more performant solutions and trade RAM usage for less CPU cycles

Which option? Measured how? The agent decides, and you find out what it decided when you read the diff.

Across the 9,776 repos with a setup we could check, 8,910 carry at least one CORE:C:0042 (91.1%).

The checker raised that finding 655,791 times. Two-thirds of what sits in these files describes, explains or shows; a third tells the agent what to do. Count only those directives and constraints and about one in three is vague.

Vague instructions are the most common finding, and far from the only one. 96.6% of repos have at least one finding of some kind, 38 in the median repo, and four other checks fire in more than 60% of repos.

Stars don't predict the score

Every file and every setup ails check reads gets a score from 0 to 10, built from all of its findings (how the score works). If popularity bought better instructions, scores would climb with stars. From 493 stars to 454,882, the line stays flat.

Spearman's rho between stars and score is -0.028 across 9,674 repos: stars account for less than 0.1% of the variation. Split the repos into ten equal groups by stars and every group lands in the same place, with 63% to 66% of repos scoring 7 or above. The most-starred tenth, 12,849 stars and up, averages a touch lower than the least-starred tenth.

A famous repo's AGENTS.md scores like anyone else's. If you copy one, read it line by line first.

Next: does the agent you write for change the picture?

Who writes for which agent

Two setups dominate: AGENTS.md in 62.6% of repos and Claude Code in 61.6%. Copilot follows at 17.9%, then Cursor, Gemini and Codex. 4,213 repos (43.1%) write for more than one agent, most often the pair of Claude Code and AGENTS.md (2,399 repos).

The formats differ in what they're made of. Skills are the largest share of files for every agent except Gemini, and Cursor is the only one where rule files outnumber main files.

The quality of what's in them barely moves between agents. The vague rate sits between 32 and 36 of every 100 instructions, whichever agent the file was written for.

Codex counts repos with a .codex/ folder; a plain AGENTS.md setup sits in the shared row.

The one column that does move is the last: Cursor and Gemini setups land below 5 about twice as often as the rest.

Where the numbers do move is between the files inside a setup.

Sub-agent files score lowest

A sub-agent file defines a specialist the main agent hands work to: a reviewer, a debugger, a test writer. Those files are where the low scores pile up. 19.6% of sub-agent files score below 5, against 6.8% of main files like CLAUDE.md and AGENTS.md, nearly three times the rate. Commands and prompts (13.9%), rules (13.6%) and skills (12.1%) sit in between.

The three biggest sub-agent folders all sit above the main-file rate, and Claude Code's is the worst: nearly one in four of its sub-agent files scores below 5.

Sub-agent files are also the busiest. The median one carries 19 directives, against 12 in a main file.

One Copilot bug-fixing sub-agent, in a large TypeScript monorepo, scores 3.9. Its quality gates:

Four gates, and nowhere in the file's 212 lines is the command for any of them. The agent has to work out how this monorepo tests, lints, type-checks and builds before it can obey a single one.

A Claude Code debugging sub-agent in another well-known repo scores 3.6. It opens:

You are an expert software debugger who treats debugging as a scientific process, not guesswork.

In 41 lines, the only file it names is CODE_DEBUGGING_SESSION.md, the report it's told to write. Nothing in it is about the project it lives in; it would read the same in any repo. It also carries the line most sub-agents do: 57.4% of sub-agent files have a line that starts with "You are a", "You are an" or "You are the".

To check yours, run npx @reporails/cli check and read the per-file scores for your .claude/agents/, .github/agents/ or .codex/agents/ folder.

7.6% of repos back their instructions with a hook

Everything above is about instructions, which the agent can follow or not. A hook is different: a script the agent's harness runs at a set moment, such as before a tool call, that can block what an instruction only asks for. (Prompts steer, hooks enforce is the long version.)

746 of the 9,784 repos (7.6%) ship an agent hook of any kind. Claude Code is where they live: 591 of its 6,030 setups (9.8%) have one. Cursor follows at 4.9%, Copilot at 1.3% and Gemini at 0.9%.

For the other 92%, nothing at the agent's own level checks whether the instructions were followed.

What held from April

April's 28,721 repos came from GitHub search. This quarter's 10,000 are the most-starred, read with a newer version of the checker, so the comparison is about direction, not size.

How we measured

• The sample. 10,000 English-language GitHub repos, taken top-down by stars from repos that ship an instruction file for Claude Code, Codex, Copilot, Cursor or Gemini. Stars run from 493 to 454,882, with a median of 1,551. Files are the September 2026 snapshot.
• What we read. We read every repository the way its coding agent does: the instruction files each agent loads by default, at the exact names and paths its documentation specifies. That is CLAUDE.md, AGENTS.md, rules, skills, sub-agents and commands, across 15,237 agent setups in 9,784 repos.
• Imports. The text of a Claude Code @path import whose target is in the snapshot is read as part of the importing file. Imports written with a leading dot directory (@.github/…) are not recognized and stay literal.
• Out of scope. Repo code, and docs an agent opens only when something links to them.
• The scorer. Every score comes from the same ails check pipeline you can run on your own repo.
• Denominators. Shares of repos, like the 91%, count the 9,776 repos with a checked setup. The vague rate, about 1 in 3, counts against the directives and constraints in those setups: 655,791 findings over 1,894,268 instructions. Score figures count the 9,674 repos with a score.
• Not in the figures.
  • 158 of the largest agent setups (more than 90 instruction files each, about 1% of setups) are not in these figures. 77 are larger than the 10,000 instruction units ails check currently scores, and 2 exceed its time limit; they are skill and rule libraries, with a median of 15,027 units across 192 files. The other 79 were scored after these figures were frozen and will be added in a dataset update.
  • 258 setups contain no directive or constraint (every line is descriptive, or the file is empty), so the scorer returns no score for them.
  • 18 setups couldn't be checked: 8 are larger than the same 10,000-unit limit and 10 hit an error during scoring.
  • For 76 repos we couldn't pin the files in sub-folders (sub-agents, commands, hooks) to the September snapshot, so they're measured on the files we already had.
• What it measures. How the instructions are written, not what any agent did with them.

Check your own files

If you came here to find out whose AGENTS.md to copy: the star count won't tell you, so read the lines instead, or let the checker read them. To run the same check we ran on all 10,000:

npx @reporails/cli check

It lists the findings file by file, with line numbers, and a 0 to 10 score for each file. Start with the three findings most repos carry: instructions that name no file, command or tool (CORE:C:0042), instructions too short to register (CORE:E:0004), and hedged ones, the "should" and "try to" kind (CORE:C:0043).

The data behind these figures is published in the 2026-Q3 folder of reporails/reports. If you disagree with a finding, count the rows.

Next in this series

Four shorter posts follow over the next days, each on one habit from the same 10,000 repos:

• The /init header. 1,604 repos (16.4%) still open with the line Claude Code's /init writes, and they score higher than the repos without it.
• "You are…" 285 main files tell the agent who it is with a "You are a…" line. They score lower at every file size.
• The habits. ALL-CAPS in a third of repos, emoji, "please", TODOs, and a 129,121-word main file.
• Hidden attribution. About 400 repos tell the agent not to take credit for its work.