Only 5% of mature open-source repos have a file written for AI agents

From READMEs written for people to documentation written for machines. A look at how developers write instructions for AI agents in open-source repositories.

Since GitHub Copilot and ChatGPT, plenty of teams have gotten used to handing an LLM chunks of code and tests to write. The next wave is agentic tooling that acts far more autonomously: it reads the repository itself, runs commands, edits files and assembles a PR. That brings up a practical problem — a couple of sentences in a prompt is not enough for an agent. It needs to understand how the project is built and how work gets done in it, from architecture and interfaces to code-style rules, build commands and security requirements.

The authors of Context Engineering for AI Agents in Open-Source Software look at how developers are solving this in the wild — directly in public repositories. One-off prompts are giving way to version-controlled files of instructions for the AI agent: what not to touch, how to run the tests, which patterns to use, how to format changes. That is context engineering: less about how to phrase a request, more about what context to put underneath the task so the agent isn't working blind.

From READMEs for people to documentation for machines

The idea is simple: drop a dedicated Markdown file into the repository that the agent will automatically mix into every request. Different tools expect different names (for example, CLAUDE.md, copilot-instructions.md), while AGENTS.md is being discussed as a possible universal standard. It is meant to be a tool-agnostic format: the same file works for any agent.

But how widespread has the practice actually become? And what goes into these files — a dry description of the project, or hard prohibitions? The authors pose three questions: how widely such files have been adopted in open source, what structure they have, and how they change over time.

How they picked repositories, and what counted as a real project

Collecting the data turned out to be less trivial than "take the top of GitHub." By 2025, the most-starred repositories are not necessarily about software at all. So the authors apply maturity and activity filters: not a fork, at least two contributors, a license, created before 2024 and updated recently. They then cut out odd licenses and unsuitable repositories and focus on 10 popular programming languages. That leaves 10,000 repositories for the initial screening, each checked for files in the default branch matching the formats that common tools support.

For closer reading they pick AGENTS.md specifically, as the most universal candidate.

How common this actually is

The number is sobering: only 466 repositories out of 10,000, roughly 5%, contained at least one AI configuration file in any of the four formats checked. That doesn't mean the phenomenon is rare overall — GitHub search suggests there may be tens of thousands of such files — but among mature, visible projects it is not mainstream yet.

There are language skews too: TypeScript repositories more often carry files for Claude Code, while C# leans toward Copilot instructions. AGENTS.md is shorter on average but the most variable: from terse notes to sprawling mini-manuals.

What goes into AGENTS.md, and how developers talk to an agent

The interesting part starts when the authors look inside. They take the section headings, group them by meaning, and arrive at the set of topics developers most often consider important for an agent. At the top: programming practices, contribution rules, architecture and project structure, build and test commands. Rarer: troubleshooting and security — even though prohibitions and boundaries would seem especially useful for an autonomous agent.

The authors note separately that there is no single AGENTS.md template. One project writes a reference (here is how things are done), another a set of orders (do it this way), a third a list of prohibitions (never do this), a fourth adds explanations of why, and occasionally you find conditional instructions for rare situations. That is an important observation: unlike the README, whose structure has more or less settled, documentation for machines is still looking for its canon.

How these files live over time

The commit history is telling as well. In half the cases, AGENTS.md was never touched after the first commit — as if it had been added because it seemed obligatory and then never folded into regular maintenance. Roughly a quarter of the files changed once, and only a fraction evolved actively.

What follows from this

The paper doesn't try to prove that AGENTS.md has already won, or that a best structure exists. It records a moment instead: developers have started version-controlling context for LLMs and agents — and that opens a rare chance to study context engineering from real traces in repositories rather than from posts and demos.

The main takeaway is pragmatic: if agentic tools keep getting more autonomous, these files deserve to be treated as part of engineering discipline. They need review, maintenance, checks that they are still accurate and, perhaps, even tests — measuring how changes to the instructions affect the agent's behavior.