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. That one gap lines up almost exactly with the low scores. Every repo in the bottom two grades, all 49 of them, is a repo with zero agent-instruction files. The single most common thing missing from an agent-ready repo is the instructions for the agent.

Where this comes from: crag is a tool I built that audits a repo and scores it for agent readiness, then publishes the result. The numbers on this page were pulled live from the public leaderboard API in July 2026 and recomputed by a script I am linking below. It is a small board and a young tool, so read it as a snapshot, not a census. Every figure here is reproducible from 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, which matters for how you read the tally, and I come back to that at the end.

One honesty note up front. crag measures governance signals, meaning 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 the plain reason that 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. The one thing they all 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 is in the lower bands, here is what actually moves the score, in the order I would do it. First, add the instruction file. A single Markdown file at the root, telling an agent the test command, the commit rules, and the folders it must leave alone. This is the one that flips the bottom half of the board.

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.