Custom Subagent Types - Claude Code

Custom subagents let you define your own roles - "migration agent", "doc writer", "test generator" - and invoke them anywhere in the session.

What it does

Create a markdown file with a name, description, system prompt, tool allowlist, and model preference. Drop it in the project's AGENTS.md or your user-level agents directory. Claude treats it as a first-class delegation target from that point on.

When to use it

• Encoding repeatable roles your team uses often.
• Locking down tool access per role for safety.
• Building specialized agents for domain work (security review, migration, copyediting).
• Reducing the cognitive load of "how do I prompt this kind of task?"

Gotchas

• Keep descriptions crisp - that's what Claude matches against to pick the right agent.
• Overlapping descriptions cause wrong picks. Test with explicit invocation first.
• Agents live on disk. Updates need a reload on older Claude Code builds.

Official docs: https://code.claude.com/docs/en/sub-agents.md#quickstart-create-your-first-subagent