Eighteen months into the agent-shaped pull request era, the maintainers I trust have stopped arguing about whether to accept the work. The argument that now actually matters is whether the repo is set up to handle it. Most of the projects shipping into the agent PR firehose are not. The reason is uncomfortable, and the fix is one file at the root of the repo plus a discipline around skills.
I want to share what I learned from a recent conversation with Nicholas Tindle, founding AI engineer at AutoGPT. AutoGPT sits at 180,000 stars on GitHub and had roughly 150 open pull requests at the time. A meaningful chunk of those came from agents, and the team decided to treat them as a new contributor class instead of a nuisance. The result is the cleanest explanation I have seen of how to structure a repo for agents that actually works.
The free-compute framing is the cleanest reason to say yes
The argument that flipped me was free option theory. If a contributor wants to spend their own tokens improving your project, let them. You are not paying for the inference. They are. The work still has to pass your review, it still has to match your standards, but the cost of generation lands on the contributor. That is a free option in the truest sense. You only exercise it if the PR is good.
The instinct to close the door is emotional. We hear “AI PR” and we picture a wall of low-quality spam that has to be triaged by a tired maintainer at 11pm. Sometimes that is exactly what shows up. But the average quality of agent-generated PRs has climbed faster than most maintainers realize. The bottleneck is no longer whether agents can write code. The bottleneck is whether your repo tells them what good code looks like in your context.
Closing the door is a choice, not a default. The repos that are winning are the ones that treat agents as a new contributor class and adjust the documentation to match. The repos that are losing are the ones that threw their hands up and slammed the door, only to find that the work has to happen anyway and somebody else is going to do it on their own terms.
Why AGENTS.md beats a better CONTRIBUTING doc
The first thing most projects try is the obvious fix. Better contributor guidelines. A more thorough CONTRIBUTING.md. A whole wiki dedicated to working with the repo. None of it moves the needle. The reason is uncomfortable. Agents do not browse your wiki. They do not read your docs unless they are told to. They read what is in front of them, scoped to the directory they are working in.
AutoGPT tried the obvious fix first. The team wrote a more thorough contributor guide. They expanded the wiki. They added a thousand words on how to format a PR. The agent pull requests kept coming in malformed. The team at AutoGPT started putting instructions where agents actually look, and the result was a file called AGENTS.md. The first round was CLAUDE.md files placed at the directory level. The idea was solid. The coverage was not. Copilot and Codex ignore Claude files. They are not Claude. So the team centralized on AGENTS.md and pointed the Claude files at it.
The pattern that works is to make AGENTS.md the lowest common denominator that most agents respect, and use agent-specific files for agent-specific quirks. Directory-scoped instructions beat repo-scoped instructions for agent attention. If the instructions live in the wrong place, the agent will not find them, and the PR will reflect the gap.
Skills are the part most projects are missing. An AGENTS.md is scoped to a directory. A skill is an instruction file with a description that tells the agent when to load it. The agent scans descriptions up front and pulls in the full instructions when the task matches. The practical difference is that AGENTS.md gets opened because the agent is in the directory. A skill gets opened because the agent recognizes the task. That is the lever most projects skip.
AutoGPT’s front end engineer got tired of the same class of broken pull request. Components without Storybook tests were landing in the queue with broken visual snapshots. The fix was a skill file called “storybook-required” that any agent working in the components directory would pick up before opening the PR. The skill said, in plain English, write a Storybook test for any new component, and run the visual snapshot before declaring the work done. The pattern of broken PRs disappeared within a week.
The four things a repo needs to ship into the agent era
The minimum viable setup is not complicated. The four things that actually move the needle are these:
- An AGENTS.md at the repo root with three sections: what this project is, how to run the tests, what a good PR looks like here.
- A directory-scoped AGENTS.md in any subdirectory where the conventions differ from the root.
- A skill file for each pattern of broken PR that shows up more than twice in the queue.
- A clear commit convention that makes agent-authored PRs easy to spot in the log without needing to label them differently.
The first three are discipline. The fourth is bookkeeping. Both are cheap. The hard part is keeping the skills alive, which is the trade-off the next section covers.
What it costs to maintain the system
There is a catch worth naming. If you invest in AGENTS.md and skills, you are betting that agents will keep reading these files. Tooling changes. The AGENTS.md standard is not a formal RFC. If a vendor decides to ship a competing file with a different name and reward behavior in their agent, you may end up writing two parallel docs. That is real, and it is the cost of living in fast-moving territory.
Skills are the bigger maintenance cost. They reference file paths that move. They encode patterns that shift as the codebase evolves. Someone has to keep them alive. Bad skills are worse than no skills, because they sound right and point the agent in the wrong direction. AutoGPT treats this as a real cost line, not a “we will get to it.” Budget the time or the files will get stale and start sending agents in the wrong direction.
The review burden does not disappear. It shifts from PR triage to docs maintenance. The agents still produce work that needs review. The work just gets better, faster, and easier to evaluate. That is a real win, but it is a win you have to pay for in upkeep.
Trade-offs
AGENTS.md and skills are not a magic trick. They are documentation that happens to get read by tools. The cost is the same as good documentation anywhere. Someone has to write it. Someone has to keep it accurate. The standards behind it can shift, and the work you put in can land in a deprecated file format. None of those are reasons not to do it. They are the price of doing it.
For a small repo with a low PR volume, the upside is real but the cost-benefit is borderline. A one-line AGENTS.md at the root is enough. For a repo with a high PR volume and a queue that gets a steady stream of agent submissions, the structure pays for itself inside a month. The calculus is simple. The cost of writing the docs is fixed. The cost of the broken PRs is ongoing. The breakeven is somewhere around the third or fourth rejected agent PR.
If you are running an open source repo with more than a handful of contributors and you have not yet opened an AGENTS.md, the cheapest win available is to write one today. Three sections. What this project is. How to run the tests. What a good PR looks like here. That is the floor. The skill layer comes after.
What I would tell a past version of me
If I could send a message back to the version of me that ran a small open source project and spent eighteen months copy-pasting the same review comment about test coverage onto every contributor PR, here is what I would say.
- The agent PR firehose is coming whether you want it or not. The question is whether your repo is set up to handle it cleanly or whether you will be the one triaging badly-formatted agent submissions at 11pm.
- Skills beat AGENTS.md for the recurring patterns. If the same comment shows up on three PRs in a row, that is a skill file, not a wiki page.
- The work of maintaining the docs is real, but it is cheaper than the work of maintaining the queue. Treat the docs as the first line of triage, not the third.