AGENTS.md
One instruction file that every coding agent agrees to read
AGENTS.md is a convention rather than a tool: a single markdown file at the root of a repository holding the instructions a coding agent needs. A growing number of agents read it, which means one file instead of one per vendor.
Why a convention beats a feature
Every coding tool invented its own instruction file, so a repository accumulated several copies of the same rules that then drifted apart. A shared filename fixes that with no code at all.
The practical benefit is that the rules stay true. One file gets updated when a convention changes; four files get updated once and then quietly rot.
What belongs in it
Commands, the architecture in one paragraph per area, and the rules that are not discoverable from the code. Which command verifies a change is the single most valuable line in the file.
What does not belong is anything the agent can read for itself. Describing the folder structure wastes context that the file listing already provides.
Reach for it when
- more than one coding agent touches the repository
- there are conventions an agent cannot infer from the code
- you are tired of maintaining several instruction files
Watch out for
- adoption is a convention, not a guarantee, so check what your tool reads
- a long file eats the context your task needs
- instructions that contradict the code get followed, which is worse than no instructions
Compare with these
- SkillsFree
Anthropic Skills
The reference implementation of what a skill should look like
- skills
- claude
- documents
No licence file in the repositoryRead - SkillsFree
Superpowers
A process framework that makes an agent plan before it builds
- skills
- process
- planning
MITRead - SkillsFree
Awesome Claude Code
A community index of commands, hooks and configurations
- skills
- claude-code
- hooks
CC0-1.0Read