AGENTS.md - Claude Code

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