Subagent Definitions as Teammates - Claude Code

Custom subagent definitions plug directly into Agent Teams. Your "reviewer", "migrator", or "doc writer" subagents become teammates without rewriting them.

What it does

When a team spins up, you can pass a list of subagent definitions for the lead to use as teammates. The lead picks the right agent for each task based on descriptions and tool allowlists. This gives you specialized team compositions - e.g. one coder, one reviewer, one tester - without custom team wiring.

When to use it

• Composing teams of roles you already use as subagents.
• Enforcing tool boundaries within a team (reviewer has no write access).
• Consistency - the same agent definition behaves the same as a teammate or a standalone delegation.
• Sharing team compositions across projects via repo-level definitions.

Gotchas

• A poor mix of roles produces poor team results. Think about coverage.
• Subagents designed for single-task isolation may not fit team workflows that need messaging.
• Frontmatter changes to the subagent definition apply to the team on next spawn.

Official docs: https://code.claude.com/docs/en/agent-teams.md#use-subagent-definitions-for-teammates