AGENTS.md - Claude Code
Define custom subagent types within your project's memory layer.
AGENTS.md is where you define custom subagent types so they're available to every session in the repo.
What it does
You list subagent definitions - name, description, model, tools, and system prompt - and Claude Code picks them up automatically. When the main agent decides to delegate, these custom types are candidates alongside the built-ins. It's the project-level version of personal subagent definitions.
When to use it
- Standardizing a "reviewer" or "researcher" agent across the team.
- Locking specific subagents to a narrow toolset for safety.
- Encoding repo-specific workflows as reusable agents.
- Sharing good subagent patterns with every contributor.
Gotchas
- AGENTS.md is committed. Don't put secrets, API keys, or personal prompts there.
- Changes take effect on session restart, not live.
- Overly custom agents can be worse than the defaults - start with built-ins and specialize only when needed.
Official docs: https://code.claude.com/docs/en/memory.md#agents-md
Technical content at the intersection of AI and development. Building with AI agents, Claude Code, and modern dev tools - then showing you exactly how it works.
Get the weekly deep dive
Tutorials on Claude Code, AI agents, and dev tools - delivered free every week.
Was this helpful?
