AGENTS.md
What is AGENTS.md?
AGENTS.md is a plain Markdown file at the root of a repository that AI coding agents read into context before they work. It's not a config file. There is no schema, no validation, and no required fields. The spec is maintained at agents.md and the supporting community lives at github.com/agentsmd/agents.md.
The standard is present in tens of thousands of public GitHub repositories. Adoption signals matter for agent interoperability: a single AGENTS.md file works across every tool that reads the spec, instead of one rules file per IDE.
Use AGENTS.md as your source of truth. Tool-specific files such as CLAUDE.md or .cursorrules can point at AGENTS.md rather than duplicate its content.
Which AI coding agents support AGENTS.md?
Around 20 coding-agent tools read the AGENTS.md spec today. Supporters include OpenAI Codex, Cursor, GitHub Copilot, Google Jules, Aider, Windsurf, Zed, Sourcegraph Amp, RooCode, Factory, and Phoenix, among others.
Why AGENTS.md needs to stay short
AGENTS.md is a context file, not a config file. When a coding agent opens your repository, the agent runtime adds AGENTS.md to its system context before reading any code. There is no parser. There is no JSON schema. Every line you write costs tokens, and tokens compete with the actual code the agent needs to reason about. Short, specific files outperform exhaustive ones.
Empirical research cited by the GitHub Blog found that autogenerated AGENTS.md files can hurt agent performance and inflate token cost. The lesson: write less, write specific, and skip the autogenerators.
The "nearest file wins" rule in monorepos exists for the same reason. A subproject team knows its own conventions better than a global file can express them, so the spec lets local files replace the root without inheritance complexity.
How does AGENTS.md compare to related files?
| File | Who reads it | When to use |
|---|---|---|
AGENTS.md | Codex, Cursor, Copilot, Jules, Aider, Windsurf, Zed, and others | Default (open standard, broad support) |
README.md | Humans, and agents as a fallback | Human-facing project description, not agent-instructional |
CLAUDE.md | Anthropic's Claude Code | When you need Claude Code's memory model on top of AGENTS.md |
llms.txt | Web crawlers and LLM retrieval pipelines | Public-site discovery, a different audience from repo agents |
CONTRIBUTING.md | Human contributors | Human contribution workflow, not agent context |
Keep AGENTS.md as the source of truth for agent behavior. Tool-specific files such as CLAUDE.md or .cursorrules must reference AGENTS.md rather than duplicate it.
See also
- Write AGENTS.md file
- agents.md: canonical AGENTS.md specification