I audited 119 repos for AI-agent readiness.

The short version

The missing file is the agent's instructions

An AI coding agent walks into your repo knowing nothing about it. It does not know your test command, your branch rules, or which folders it must never touch. Some repos hand it that on a plate, in a plain file at the root. Most do not.

I counted. Of the 119 repos on my leaderboard, 49 have no agent-instruction file at all. That is 41 percent of the board with nothing at the front door for an agent to read.

Here is the part I did not expect. The missing-file gap lines up almost exactly with the low scores. Every repo in the bottom two grades, all 49 of them, has zero agent-instruction files.

crag audits a repo and scores it for agent readiness, then publishes the result to a public board. Every number on this page comes from the public leaderboard API in July 2026. The board is small and young, so read it as a snapshot, not a census, and every figure traces back to that one fetch.

The method

How the audits run

crag reads a repo the way an agent would, then checks it against a set of governance signals. It looks for the instruction file. It counts the quality gates the repo defines, the commands an agent is told to run before it commits. It checks whether those gates match what the config actually declares, so the guidance cannot quietly drift from reality.

The scoring is automated, and it runs on demand. Anyone can point crag at a public repo and get a graded page. Each result lands on the leaderboard with a letter grade and the raw counts behind it. The 119 repos on the board today are the ones people chose to run. That matters for how you read the tally, and I come back to it at the end.

crag measures governance signals: the scaffolding that makes a repo legible to an agent. It says nothing about whether the code is any good. A beautifully engineered library can score low here for one plain reason: nobody wrote down how an agent should behave in it.

The distribution

119 repos, graded

Grades and counts pulled live from the crag leaderboard API in July 2026, recomputed from the raw payload by the linked script.

The shape

Grade C is the biggest band, and it is the config gap

Finding one

The top of the board already did the work

Thirty of the 119 repos score a perfect 100. They are names you know: linters, package managers, runtimes, the tools that other tools are built on. Size and star count varied wildly across them. What they shared was simpler: every one carries at least one agent-instruction file, and most carry two or three.

That is the quiet lesson of the top band. The repos an agent finds easiest to work in are the ones whose maintainers already write things down for humans. For those teams the instruction file is the same discipline they always had, pointed now at a new kind of contributor.

The gap between the top and the bottom is small to close and large in effect. A grade-C repo is rarely one big rewrite away from a grade A. It is usually one file away.

What to add

Three things that move a repo up

If your repo sits in the lower bands, here is what actually moves the score. First: add the instruction file, a single Markdown file at the root that tells an agent the test command, the commit rules, and the folders it must leave alone. Nothing else on this list moves the bottom half of the board as far.

Second, write your quality gates down as commands. The median repo on the board defines 38 of these: the checks an agent runs before it commits, spelled out so it can run them itself. An agent that can verify its own work is an agent you can trust with a pull request.

Third, keep the written guidance and the real config in sync. crag flags drift, where the instructions claim one thing and the build does another. Only 10 of the 119 repos carry any such mismatch, which tells you the discipline is achievable. A stale instruction is worse than none, because the agent believes it.