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