Subagents

You inherit a payment system in a codebase you have never seen, and you need one fact: which service handles refunds? You ask Claude Code. It reads fifteen files, runs half a dozen searches, traces three function calls — and by the end, your context window is full of code you will never look at again, to answer one question. You did not want the journey. You wanted the answer. Subagents are how you stop paying for the journey.

The problem subagents solve

You already know the context window is a scarce resource. Every tool call and every file read eats into it. A lot of that exploration work is not relevant to the main feature you are building — it is plumbing for a question you asked ten minutes ago.

A subagent is a delegated task that runs in a completely isolated context window and returns only a summary to the main thread. The subagent reads, searches, runs tools, and works autonomously. None of that activity shows up in your main conversation. When it finishes, you get the finding. The rest is discarded.

The mental model worth keeping: you get the answer without the journey.

Before and after: investigating the payment system

Take the refund question. Without a subagent, Claude Code explores from the main thread: fifteen files read, multiple searches, several traces. Every one of those results lands in your main context window. You asked one question and burned half your working memory on the answer.

With a subagent, Claude spawns a parallel agent with two inputs: a system prompt from your configuration and a task description derived from your request. The subagent does the same exploration — but in its own context window. When it finishes, it hands back a focused summary ("the refund flow is handled by services/payments/refunds.ts"). Your main context stays clean.

The tradeoff worth naming: the main thread loses visibility into how the subagent reached its conclusion. If you want to audit the exploration, subagents are the wrong tool. If you want the answer, they are the right one.

Creating a custom subagent

Subagents are defined in markdown files with YAML frontmatter, but you do not need to write one by hand. Run:

/agents

Then select Create new agent. Claude walks you through the decisions that matter:

• Scope — user-level (across all your projects) or project-level (checked into this repo).
• Purpose — what this agent is for. Claude uses this to decide when to call it.
• Tools — which tools this agent can use. Give reviewers read-only access. Give builders whatever they need.
• Color — visual differentiation in the UI.

Claude then generates a name, description, and system prompt. The description is especially important: it is how Claude decides whether this subagent is the right one to call for a given task, so make it precise.

Built-in subagents

Claude Code ships with several subagents you can use immediately:

• general-purpose — multi-step tasks that require both exploration and action.
• explore — fast searching across your codebase.
• plan — research and analysis during Plan Mode, before presenting a plan.

You have already been using the explore and plan subagents implicitly — they are what powers Plan Mode. Now you can invoke them directly for the same benefit outside of Plan Mode.

Further customisation

Two features worth knowing about as you build more sophisticated subagents:

Persistent memory. A subagent can retain memory across conversations. Useful when you have an agent you reuse on the same project — a reviewer, for instance, that learns your team's standards over time.

Preloaded skills. You can list skills in the subagent's configuration by name. Unlike skills loaded into your main conversation (where only the name and description are in context), preloaded skills in a subagent load the entire skill into its context — the subagent has the full instructions from the start.

Where this sits in the course

Subagents are a direct consequence of context management. You learned in the context lesson that tool call results clutter the main window; subagents are the architectural answer. They also connect back to the workflow lesson's reviewer pattern — the subagent code reviewer you run before committing is the exact same mechanism applied to a different task.

Want to go deeper on when and how to design custom subagents? Check out the dedicated Introduction to Subagents course.