Subagents are purpose-built AI assistants you define for Claude Code. Each one runs with its own separate context window, a custom system prompt that shapes its behavior, and an optional restricted set of tools. This lets the main agent hand off a well-scoped task (like reviewing code or hunting down a bug) to a specialist without cluttering the primary conversation.
You define a subagent as a Markdown file with YAML frontmatter. Project-level subagents live in .claude/agents/ and user-level ones in ~/.claude/agents/, with project subagents taking precedence on a name conflict. The frontmatter requires a name and a description (used for delegation), and optionally a tools list and a model (for example sonnet, opus, haiku, or inherit); the body is the subagent's system prompt. You can create and manage them interactively with the slash command /agents. See the official docs for exact frontmatter syntax.
Claude Code can invoke a subagent automatically, delegating to it when a task matches its description, or you can request one explicitly by name. Because each subagent works in an isolated context and reports a result back, complex workflows can chain several subagents together while the main session stays focused on the higher-level goal. Subagents differ from Agent Skills, which package reusable instructions and files that any agent can load on demand.
Why it matters
Subagents keep your main context window clean by offloading focused work to specialists, so long sessions stay coherent and less likely to need compaction — and a well-tuned subagent (with a tight system prompt, limited tools, and the right model) often produces better, more consistent results on its specialty than ad-hoc prompting.
Deep dive: Claude Code Subagents Explained
Related terms
See Subagents in action across releases — browse the Claude Code changelog.
Get release alerts