Claude Code Subagents: How I Actually Use Them (With Examples)

Claude Code shipped subagents a while back, and most people I talk to still use them wrong. They either ignore them completely, or they spin up ten of them and wonder why their context is a mess.

The official docs tell you what a subagent is. They do not tell you when to reach for one, how it is different from a skill or a slash command, or what actually breaks when you scale them. That is the part I learned the hard way, building more than 100 agents over the last two years.

So here is the practical version. What subagents are, how they differ from the other tools, how to make your own, and the real workflows I run them in.

What is a Claude Code subagent?

A subagent is a separate Claude instance that your main agent can spawn to handle a focused task. It has its own context window, its own system prompt, and its own tools. When it finishes, it hands one clean result back to the main agent and disappears.

That last part is the whole point. The subagent reads ten files, runs five searches, burns through a pile of tokens, and the main thread never sees any of that mess. It only sees the answer.

Think of it like delegating to a junior who does the digging and comes back with a one paragraph summary, instead of cc-ing you on every email along the way.

Subagents vs skills vs commands (the part everyone confuses)

This is the question I get most, so let me make it simple.

• A slash command is a saved prompt. You type it, it expands into instructions, and it runs in your current context. No isolation. Good for repeatable prompts you fire often.

• A skill is packaged knowledge and instructions that Claude pulls in when a task matches. It teaches the agent how to do something. It does not run in its own context.

• A subagent is a separate worker with its own context. It is about isolation and parallelism, not knowledge.

The rule I use: reach for a skill when you want Claude to know something. Reach for a subagent when you want Claude to offload something. And yes, a subagent can use your skills while it works, so they stack.

How to create a custom subagent

You do not need anything fancy. A subagent is defined by three things: a name, a description of when to use it, and a system prompt telling it how to behave. You can scope which tools it gets, which is where a lot of the safety comes from.

My advice: keep the description sharp. Claude decides when to delegate based on that description, so a vague one means it never gets used, and an overeager one means it gets used for everything. Write it like you are briefing a contractor on exactly which jobs are theirs.

And give it the smallest set of tools it needs. A research subagent gets read and search, nothing that can write. You would not hand a new hire production access on day one. Same logic.

The workflows I actually run subagents in

Here is where it stops being theory.

Parallel research. When I need to understand a codebase or a topic fast, I fan out several read-only subagents at once, each on a different corner. One reads the auth flow, one maps the database, one checks the tests. They run at the same time, and I get four summaries back instead of one slow crawl. This is the single biggest time saver.

Keeping the main thread clean. Anything that involves reading a lot to produce a little goes to a subagent. Digging through logs. Searching twenty files for one pattern. The main agent stays focused on the actual decision instead of drowning in raw output.

Adversarial checking. For anything important, I spawn a subagent whose only job is to try to prove the first answer wrong. A second pair of eyes that does not share the original context, so it is not anchored to the same mistake.

Best practices, and how many to run at once

A few things I learned by getting them wrong first.

• One job per subagent. The moment a subagent has two responsibilities, its output gets vague. Split it.

• Do not over-parallelize. Running a handful at once is great. Running twenty means you are now managing twenty summaries, which is its own kind of overwhelm. Match the count to the work, not to the thrill of watching them go.

• Be explicit about the return. Tell the subagent exactly what shape you want back. The cleaner the handoff, the more useful it is.

• Read-only by default. Give write access only when the task genuinely needs it.

The bottom line

Subagents are not about making Claude smarter. They are about protecting your main context and doing several things at once. Use a skill when you want the agent to know something. Use a subagent when you want it to go do something and come back with just the answer.

Get that distinction right and your agents stop choking on their own output. That is the difference between a setup that works on a demo and one that survives a real day of work.

Robin

P.S. I build AI agents for companies for a living, and most of what I learn ends up in this newsletter first. If you are putting agents into a real workflow and want a second opinion on the architecture, book a free AI agent audit here.