Claude Code subagents: when to use them and how to build one

I see people get Claude Code subagents wrong in two opposite ways. Some never touch them. Others launch ten in one go, then scroll through ten reports their main session had no use for.

Neither works. The official documentation covers what a subagent is. It says much less about when one is the right tool, how it stacks up against skills and slash commands, and what goes wrong once you run a lot of them. I picked those lessons up while building agents for companies over the past two years, usually by making the mistake first.

This guide is the hands-on version. The concept, the comparison, how to write your own, the three setups I rely on, and what they cost you.

So what is a subagent, really?

Picture a second Claude that your main session can hand one task to. It gets a fresh context window, a system prompt written for that role, a set of tools, and permissions that can be tighter than yours. It works through the task, sends a single result back, and is gone.

The value sits in what you don't see. Say the job needs ten files opened and five searches run. All of that reading, and all the tokens it eats, happens on the subagent's side. Your conversation receives the conclusion and nothing else.

It's how you'd brief a good junior colleague. You don't want to be copied on every message they send while they figure it out. You want a short note at the end that says what they found.

Chances are you've already used a few. Claude Code comes with built-in subagents:

• Explore: quick and read-only. Claude sends it off to search a codebase and make sense of it.
• Plan: gathers context for Claude while you're in plan mode.
• General-purpose: for multi-step work that involves both reading and making changes.

Whenever Claude hands work to one of them, the raw search output stays out of your conversation.

Subagent, skill or slash command: which one fits?

People ask me this more than anything else about Claude Code. Here's the side-by-side.

A detail that trips people up: recent Claude Code versions folded custom slash commands into skills. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both give you a /deploy command. So the useful distinction isn't command versus skill anymore. It's whether the work happens inside your conversation or somewhere else.

My shorthand: skill = know, subagent = offload. If Claude needs to know your way of doing something, write a skill. If Claude needs to offload a chunk of work, make a subagent.

You don't have to pick one. A subagent can call your skills mid-task, and you can preload particular skills into it. Knowledge and isolation get along fine.

When should work leave your main session?

Hand a task to a subagent when it looks like one of these:

• Lots of input, small output. Combing through log files. Hunting for one pattern across twenty files. Running the full test suite when the failures are all you care about.
• You need guardrails. Lock a subagent to read-only tools and it can't change anything, even when it loses the plot.
• It's self-contained. You can explain the task in a paragraph, and the answer fits in a short report.

Keep it in the main conversation when:

• the task needs a lot of back-and-forth with you
• planning, building and testing all lean on the same context
• it's a small, targeted edit

Every subagent boots up knowing nothing. On a two-line fix, that startup time is wasted.

How do you build your own subagent?

Nothing special required. A subagent is a Markdown file that opens with YAML frontmatter. The frontmatter covers identity and permissions. Everything underneath becomes the system prompt.

The folder you save it in decides who can use it:

name and description are the only required fields. Two more show up in nearly all of mine: tools, which lists what it may use, and model, which takes sonnet, opus, haiku, or inherit to match whatever your main session runs. Skip tools and the subagent inherits every tool available to subagents. Handy, sure. For most jobs it's also the opposite of what I want.

You can create one in two ways. Ask Claude to write it for you ("Create a read-only research subagent in ~/.claude/agents/ that..."), or write the file by hand. In older versions, /agents opened an interactive wizard. Newer versions just point you to those two routes. The file format didn't change.

This is the read-only researcher I reach for more than any other:

---
name: research-scout
description: Read-only investigator. Call it when a question requires going through many files or docs but the answer itself is short. It never modifies anything.
tools: Read, Grep, Glob, WebFetch, WebSearch
model: sonnet
---

You investigate a single question and report what you find.

Rules:
- Read only. Do not create, change or remove any file.
- Answer the question as asked. Ignore tangents, however tempting.
- Reply with no more than 10 bullet points. Cite the file path or URL behind each one.
- Close with one line naming anything you were unable to confirm.

Drop it into .claude/agents/research-scout.md and Claude can start delegating to it. One gotcha: if there was no agents folder when your session began, restart Claude Code once so it notices the new folder. Want quick, inexpensive digging? Change the model to haiku.

The description decides when it gets called

Claude picks a subagent by reading its description. Make it fuzzy and the subagent sits unused. Make it too eager and it grabs every task in sight. Write it the way you'd brief a contractor: these jobs are yours, those aren't.

Keep it brief as well. Every description stays loaded in your context so Claude knows what's on offer. The long instructions go in the body, which only loads when the subagent actually runs.

Don't want to depend on Claude choosing? Name the subagent in your prompt ("Use the research-scout subagent to map the auth flow"). Or @-mention it, which makes sure that exact subagent runs.

Hand out as few tools as possible

tools works as an allowlist. My research subagent gets reading and searching, and nothing that writes. If it's easier to start from the full set and strip a few out, disallowedTools does the reverse and acts as a denylist.

Nobody gives a new hire the keys to production in their first week. Subagents get the same treatment.

Where do subagents actually pay off?

Enough concepts. These are the three setups I use most.

1. Research in parallel. When I have to get up to speed on a codebase or a subject quickly, I launch a few read-only subagents side by side, each with its own slice. One traces how login works. Another sketches the database. A third goes through the tests. They all run simultaneously, and a few tight summaries come back in place of one long crawl. Nothing else saves me as much time.

2. A tidy main thread. Any job that means reading a mountain to produce a paragraph gets delegated. That keeps the main session on the decision in front of it, not wading through raw output. The longer a session runs, the more this counts, since every log dump you keep out leaves room for the real work.

3. Checking the work adversarially. When something matters, I start a subagent with a single brief: find what's wrong with the first answer. It never saw the original context, so it can't inherit the same blind spot. A second opinion doesn't come cheaper.

What's the catch?

Subagents cost something. Know the trade-offs before you design a workflow around them.

None of this argues against subagents. It argues for giving them only the jobs where working in isolation earns back what it costs.

How many subagents should run at once?

Fewer than you'd guess. These are the rules I ended up with after breaking each of them:

• Each subagent gets one job. Give it two and the output turns mushy. Make it two subagents instead.
• Hold back on parallel runs. A handful at the same time works well. By default Claude Code lets 20 run at once, but reading twenty summaries is a mess of its own. Treat that number as a ceiling, never a goal. Size the batch to the task, not to how fun it is to watch them all spin up.
• Spell out the return format. Say exactly what you expect: bullets, a table, a yes or no with the evidence. A tighter handoff gives you a more usable result.
• Write access is opt-in. Every subagent starts read-only. Add write tools only for tasks that really have to change files.

What should you remember?

A subagent won't make Claude any smarter. It keeps your main context clean and lets you run several pieces of work side by side. That's it, and that's plenty.

So keep the split in mind. Skills hold what Claude should know. Subagents take the work Claude should send away and get a short answer back on. Get that right and your sessions stop collapsing under their own output. That's what turns a setup that impresses in a demo into one that holds up on a normal Tuesday.