AGENTS.md started as a simple convention — drop a markdown file in your repo to tell AI agents how the project works. In 2026, it has become a foundational file for multi-agent Claude Code setups, used in over 60,000 open-source repositories and formally adopted as an open standard by the Agentic AI Foundation.
If you are using Claude Code subagents, AGENTS.md is where you configure them. This guide covers what actually works: the file format, how to write agent entries that produce consistent results, how scope hierarchies behave, and what patterns the community has converged on.
What AGENTS.md Does
AGENTS.md has two distinct jobs depending on context.
As an ecosystem standard, AGENTS.md is a project-level file that tells AI agents about your codebase: how to build it, how to run tests, what conventions to follow, which directories to avoid. Any agent supporting the AGENTS.md standard reads this file and adapts its behavior accordingly. It is the multi-agent equivalent of CLAUDE.md.
Within Claude Code, AGENTS.md also defines named subagents — specialized Claude instances with their own system prompts, tool permissions, and model configurations. When you write a ## code-reviewer entry in AGENTS.md, you are creating a subagent that Claude can delegate to.
Both jobs coexist in the same file. The top-level markdown describes the project; the agent sections define delegatable workers.
File Format
AGENTS.md is plain Markdown. No YAML schema, no JSON configuration, no special syntax. This is intentional — it needs to be readable by humans, parseable by any model, and writable without tooling.
A complete AGENTS.md looks like this:
# Project Overview
This is a TypeScript monorepo with three packages: API, web client, and CLI.
## Build
```bash
pnpm install
pnpm buildTesting
pnpm test # unit tests
pnpm test:e2e # end-to-end tests (requires running API)Conventions
- All API routes are in
packages/api/src/routes/ - Database models are in
packages/api/src/models/ - Tests live adjacent to source files as
*.test.ts - No
anytypes except in test files
Agents
code-reviewer
description: Reviews code for correctness, security issues, and TypeScript best practices. Use before committing or opening a pull request. tools: read, bash model: claude-sonnet-4-6
test-generator
description: Generates unit tests for existing TypeScript code. Use after implementing new features or when test coverage is below 80%. tools: read, write model: claude-sonnet-4-6
migration-writer
description: Writes database migrations for schema changes. Checks for backward compatibility and reversibility. Use when modifying database models. tools: read, write, bash model: claude-sonnet-4-6
The `## Agents` section is where Claude Code subagent definitions live. Each `###` heading is an agent name; the indented key-value pairs are its configuration.
## Scope Hierarchy
AGENTS.md files, like CLAUDE.md files, follow a hierarchical scope model. You can have multiple AGENTS.md files in a single project, and Claude merges them based on the file's location:
/ ← global (~/.claude/AGENTS.md) project-root/ AGENTS.md ← project-wide agents packages/ api/ AGENTS.md ← API-specific agents web/ AGENTS.md ← web-specific agents
When Claude is working in `packages/api/`, it has access to agents defined in all three files. When working at the project root, it only sees the top two.
This means you can define specialized agents at the package level without polluting the global namespace. A `database-migrator` agent that only makes sense in the `api` package belongs in `packages/api/AGENTS.md`, not at the project root.
**Conflict resolution**: If two AGENTS.md files at different levels define an agent with the same name, the more specific one (deeper in the directory tree) wins. This lets you override or specialize a global agent for a specific package.
## Writing Effective Agent Entries
The description field is the most important part of an agent entry. It controls two things: how the agent appears in Claude's decision-making and whether Claude invokes the agent autonomously.
**Weak description:**description: Reviews code
**Strong description:**description: Reviews TypeScript code for null pointer dereferences, missing error handling, and violations of the API conventions in this project. Use before committing any changes to packages/api/.
The weak version tells Claude almost nothing. The strong version gives Claude three pieces of information: what the agent checks for, which codebase conventions it knows about, and when to invoke it.
For autonomous invocation — where Claude calls the agent without you asking — the description needs to match the context clearly. If Claude is writing API code and sees an agent described as "use before committing any changes to packages/api/", it will invoke that agent at the right moment without being prompted.
For agents you always invoke manually, the description matters less for routing but still helps with discoverability.
## Tool Permissions
The `tools` field in an agent entry is a security boundary. Subagents only have access to the tools you grant them.
Common tool sets:
| Tools | Use case |
|---|---|
| `read` | Read-only analysis: code review, documentation review, audit |
| `read, write` | Content generation: test writing, documentation writing |
| `read, bash` | Analysis with execution: running tests, checking compilation |
| `read, write, bash` | Full development tasks: implementing features, running migrations |
| `read, write, bash, web_search` | Research-intensive tasks |
The principle of least privilege applies here. A code reviewer does not need write access. A documentation writer does not need bash. Tighter permissions reduce the blast radius of an agent going wrong and make the agent's behavior more predictable.
## Model Selection
Most agent entries should use `model: claude-sonnet-4-6`. It is faster and cheaper than Opus while being capable enough for the majority of subagent tasks.
Reserve `model: claude-opus-4-6` for agents that do genuinely hard reasoning:
- Architecture decision review
- Security audit with complex vulnerability analysis
- Agents that need to reason across large, complex codebases
For simple, mechanical tasks — formatting checks, boilerplate generation, straightforward documentation — `claude-haiku-3-6` reduces latency and cost significantly.
## Patterns That Work
**The specialist pool.** Define a set of agents that each cover one domain: testing, security, documentation, performance. Rather than asking your main Claude session to do everything, delegate to the specialist. This keeps context clean and lets each agent focus.
```markdown
### security-auditor
description: Audits code for security vulnerabilities including injection, broken auth,
sensitive data exposure, and insecure dependencies. Use before production deployments.
tools: read, bash
model: claude-opus-4-6
### performance-reviewer
description: Identifies performance bottlenecks: N+1 queries, unnecessary re-renders,
blocking operations, and memory leaks. Use when profiling indicates slow paths.
tools: read, bash
model: claude-sonnet-4-6
### docs-writer
description: Writes and updates technical documentation: README files, inline comments,
API reference, and architecture notes. Use when code changes are complete.
tools: read, write
model: claude-sonnet-4-6The gatekeeper pattern. One agent checks pre-conditions before another agent acts. For deployment workflows, a pre-deploy-checker agent runs first and blocks if anything is wrong.
### pre-deploy-checker
description: Verifies deployment readiness: all tests pass, no TODO comments in new code,
environment variables are set, dependencies are pinned. Use before any deployment.
tools: read, bash
model: claude-sonnet-4-6
### deployer
description: Executes the deployment workflow. Always invoke pre-deploy-checker first.
tools: read, bash
model: claude-sonnet-4-6The scoped specialist. For monorepos, define agents scoped to specific packages. A database-expert agent that knows the ORM conventions and migration patterns for your API package is more useful than a general database agent.
What Not to Do
Do not define agents you never use. An AGENTS.md with 20 agent definitions sounds comprehensive but adds noise. Claude reads all the descriptions and factors them into its reasoning. Irrelevant agents dilute the signal. Start with three or four and add more when you have a clear need.
Do not write vague descriptions. “Use when needed” is not a description. If you cannot articulate specifically when an agent should run, you probably do not need the agent yet.
Do not give every agent full tool access. Over-permissioning is a code smell. It signals that you have not thought carefully about what the agent actually needs.
Do not skip the project context section. The top of AGENTS.md, before any agent definitions, should describe the project. This context is read by Claude as part of the session initialization. A minimal project description — language, structure, build commands, conventions — makes every agent more effective because they start with an accurate mental model of the codebase.
Integration with CLAUDE.md
AGENTS.md and CLAUDE.md are complementary, not competing.
CLAUDE.md is for your main session: coding standards, file structure, workflow rules, things you want Claude to remember every time.
AGENTS.md is for agents: project context that helps both the main Claude session and subagents understand the codebase, plus the subagent definitions themselves.
In practice, the top section of AGENTS.md often repeats some of CLAUDE.md — build commands, directory structure, testing conventions. This redundancy is intentional: agents need their own copy of the context they require, rather than depending on the main session’s memory.
If maintaining both files feels like duplication, consider keeping project context in CLAUDE.md and only using AGENTS.md for the ## Agents section. Claude Code reads both and merges the context. Just make sure that any agent with restricted tool access still has access to the files it needs to read.
Getting Started
If you are adding AGENTS.md to an existing project, start small. Write the project context section (build commands, directory layout, testing instructions) and define one agent. Run it a few times. Refine the description based on what Claude calls it for versus what you intended.
The file will grow naturally as you discover workflows worth delegating. The best AGENTS.md files in production codebases did not start comprehensive — they started with one or two entries and evolved over months of use.