You'll walk away with
- Why subagents exist and what problem they solve in long Claude Code sessions
- How to invoke a built-in subagent vs spawn a custom one from a config file
- How to write a focused system prompt + tool whitelist that keeps a subagent on-task
- When to use a subagent and when to keep work inline in the main thread
Read these first
Lesson outline
Every lesson from Introduction to Subagents with our one-line simplification. The Skilljar course is the source; we summarize.
| # | Skilljar lesson | Our simplification |
|---|---|---|
| 1 | What are subagents? | Specialized helpers that run in their own context and return only a summary, isolating tool noise from your main thread. |
| 2 | Creating a subagent | Define a markdown config with name, description, tools, and system prompt; place it in .claude/agents/ to make it discoverable. |
| 3 | Designing effective subagents | Scope tightly: focused role, narrow tool whitelist, explicit output format. Broad agents drift; narrow ones land. |
| 4 | Using subagents effectively | Invoke explicitly when you want isolation, accept the visibility tradeoff, and aggregate findings in the parent thread. |
The course in 6 paragraphs
Subagents exist because every Claude Code session has a finite context window, and every tool call, file read, and search result fills that window with noise. After 50 turns of debugging, you might need to scroll past dozens of intermediate tool outputs to find the answer Claude actually gave you. Subagents fix this by running their own conversation in a separate window, doing their work, and returning only a summary to the main thread. The intermediate work is discarded; you keep the answer.
Mechanically, a subagent receives two inputs at spawn: a custom system prompt (defining role and behavior) and a task description (written by the parent agent based on the user's request). It then runs its own loop with whatever tools it has access to, isolated from the parent's context. When it returns, only the summary lands in the main thread. The parent never sees the intermediate steps, which is both the value (cleaner context) and the limitation (less debuggability if the subagent reaches a wrong answer).
Claude Code ships three built-in subagents: General (multi-step tasks needing both exploration and action), Explore (fast search and navigation), and Plan (used during plan mode for research before producing a plan). For most tasks, the built-ins are enough — Claude picks which one to use automatically when you ask the right shape of question. The customization story matters when your team has recurring specialist patterns — a code reviewer, a test writer, a docs generator — that warrant a fixed config.
Custom subagents live as markdown files in .claude/agents/ (or ~/.claude/agents/ for personal). Each file declares: a name, a description (which Claude reads to decide when to invoke), a tool whitelist, and a system prompt. The tool whitelist is load-bearing: a code-reviewer subagent should have [Read, Grep, Glob] only, never [Edit, Write]. Tool overscoping is the canonical anti-pattern. Claude is allowed to call any whitelisted tool but will never call one outside the list, so the whitelist is your safety contract.
Designing effective subagents comes down to three rules: scope tightly (one role, not three), constrain tools (minimum needed for the role), and define output format (so the parent can aggregate cleanly). A subagent without an output schema wanders. A subagent with [Read, Grep, Glob, Bash, Edit, Write] is just another general-purpose agent in disguise. The narrow ones land; the broad ones drift, every time.
When you should *not* use a subagent: short tasks where the noise is minimal, exploratory work where you want to see the journey, or anything where you'll need to debug the path to the answer. The clean-context benefit is also a visibility cost — once the subagent returns, you cannot ask it follow-up questions, and the intermediate state is gone. For inline reasoning that should remain in the parent thread, just stay inline. Subagents are for delegation, not micro-isolation.
3 anti-patterns when designing subagents
Each of these will be a question on the exam in disguise. Watch for the failure mode behind each.
- Tool overscoping
Granting
Concept: tool-calling ↗[Read, Edit, Write, Bash]to a code-reviewer subagent. The reviewer should never edit; the whitelist is the contract. Restrict to[Read, Grep, Glob]so accidents become impossible. - No output format
A subagent without a defined output schema wanders for 30+ turns and returns a wall of prose. Define a structured shape (
Concept: structured-outputs ↗{findings: [], confidence: number}) so the parent can aggregate. - Treating subagents as inheritance
Subagents do NOT inherit the parent's chat history. Pass every fact the subagent needs in the task string. This is the single most-tested distractor pattern.
Concept: subagents ↗
5 takeaways with cross-pillar bridges
Subagents run in their own context window and return only a summary, isolating tool noise from the parent thread.
Claude Code ships three built-in subagents (General, Explore, Plan); custom ones live as markdown files in .claude/agents/.
Tool whitelist is the load-bearing contract for safety — restrict to the minimum needed for the role; never trust prompt-only constraints.
Subagents do NOT inherit the parent's conversation; pass every required fact in the task string explicitly.
Define a structured output format in the subagent's system prompt to bound runtime and enable clean parent-side aggregation.
How this maps to the CCA-F exam
2 hand-picked extras
These amplify the Skilljar course beyond what the course itself covers. Each was picked for a specific reason.
How we built our multi-agent research system
Anthropic's own engineering write-up of the hub-and-spoke pattern Claude Code's subagents are modelled on; deeper context behind the Skilljar lessons.
Read source ↗Subagents — Anthropic Claude Code documentation
Canonical reference for the markdown config schema and tool whitelist mechanics. Pair with the Skilljar lesson when you start authoring custom subagents.
Read source ↗Concepts in this course
Where you'll see this in production
Other course mirrors you may want next
7 questions answered
Phrased as the way real students search. Tagged by intent so you can scan to what you actually need.
DefinitionWhat is a subagent in Claude Code and how is it different from the main agent?
ComparisonWhen should I use a subagent vs keep work inline in the main Claude Code session?
How-toHow do I create a custom subagent in Claude Code?
.claude/agents/<name>.md with frontmatter declaring name, description, tools (the whitelist), and system_prompt. Claude Code auto-discovers files in this directory and uses the description field to decide when to invoke the subagent. Place personal subagents in ~/.claude/agents/ and project ones in .claude/agents/.TroubleshootWhy does my subagent return wrong answers about facts the main conversation already established?
How-toWhat tools should I give a code-review subagent?
[Read, Grep, Glob] — strictly read-only. Reviewers should never edit, write, or run code. Tool overscoping is the canonical anti-pattern: granting Edit or Write to a reviewer means accidents become possible. The whitelist is your safety contract; the prompt alone won't enforce it.ScopeAre subagents and Claude API agents the same thing?
messages.create calls with tool use. The mental model is similar (parent dispatches, child does focused work), but the runtime, tool surface, and configuration are distinct.DefinitionHow many built-in subagents does Claude Code have and what do they do?
General for multi-step tasks needing both exploration and action; Explore for fast search and codebase navigation; Plan for research and analysis during plan mode. Claude picks which built-in to invoke based on the task shape. Custom subagents extend this set with team-specific specialists like reviewers, test writers, or docs generators.