Claude Code
Claude Code subagents: what they are and when to use them
A Claude Code subagent is a separate assistant with its own context window, its own system prompt and only the tools you allow it. Claude hands it a task, the subagent works on its own and sends back just a summary, so long logs and search results stay out of your main conversation.
Updated
What is a subagent in Claude Code?
A Markdown file with YAML frontmatter where only name and description are required. The text below the frontmatter becomes its system prompt. The subagent gets that prompt plus a few environment details, without the Claude Code system prompt. You can keep it in the project, in your user folder or in a plugin.
How does Claude pick a subagent?
- Automatically, from your request, each subagent's description field and the current context.
- Explicitly, when you name it in your message.
- Claude Code ships with built-in subagents: Explore and Plan are read-only, General-purpose has every tool.
Which tools and model does a subagent get?
The tools field is an allowlist. Leave it out and the subagent inherits the conversation's tools, while disallowedTools removes the ones you don't want. The model field takes an alias (for example sonnet, opus or haiku), a full model ID, or inherit, which means the main conversation's model.
What does a good subagent look like?
A log-reading subagent gets read-only tools, goes through the long log of a failed build and returns the errors and the files they point to. Your conversation receives a few lines instead of the whole log.
When is a subagent the wrong choice?
- When the work needs a lot of back-and-forth with you.
- When several phases need the same context.
- For a quick, targeted change.
- When latency matters.
Frequently asked questions
Subagent or skill?
A skill brings instructions into the current conversation. A subagent is a separate assistant with its own context. You can combine them: a skill with context: fork runs inside a subagent.
Which model does a subagent use?
The one in its model field. If no model is set anywhere, it uses the main conversation's model.
Does a subagent see my whole conversation?
No. It gets its own system prompt, a few environment details and the delegated task, and its work stays in its own context.
Does a subagent cost more?
Its requests count toward the same usage limits as the main conversation. For simple tasks you can set a smaller model in its configuration.
Can a subagent start other subagents?
Yes by default, down to a limited depth. An environment variable changes the limit or turns nesting off.
Sources
Related articles
Claude Code skills: instructions that load when needed
A Claude Code skill is a folder with a SKILL.md file that holds a name, a description and instructions. The description is always in context, so Claude knows which skills it has. The rest loads only when you run it with /name or when your request matches the description.ReadOrchestrator, workers and evaluator: patterns for AI agents
Orchestrator-workers is a pattern where a central model breaks a task down, hands the pieces to workers and combines their results. In evaluator-optimizer, one model generates and another evaluates, in a loop, until the result meets the criteria. Anthropic recommends the simplest solution that works, with more complexity only when needed.Read
Case studies
Related services
Want your team to work this way?
In the Claude Code workshop, your engineers build a working agent on one of their own projects.
See the workshop