Calling in a Specialist: Sub-Agents

You hand Claude a big one. "Go read every file in this folder and tell me what's going on in here." Off it goes — opening this, scanning that, ten files deep, then thirty. And when it finally surfaces with an answer, something feels off. The nice, focused conversation you had going is buried under a mountain of side-quest: file after file it pulled in, most of which you never needed to lay eyes on. You got your answer. But the thread you were actually on is a mess.

There's a tidier way to hand off a big chunk of work like that — and it turns out you've already met the idea, just under a different name.

What a sub-agent actually is

Think about how you'd handle this with people. For a big, self-contained task, you don't dump your entire week onto a colleague — you call in a specialist for that one job. They don't need your whole backstory. They go off, do the focused work, and come back with the result.

A sub-agent is exactly that, inside Claude Code. It's a separate helper Claude with its own clean workspace, a focused job, and only the tools it needs for that job. The "own workspace" is the part that matters most: the helper doesn't carry your whole conversation around. It starts fresh, does its task off to the side, and hands back just the result.

Picture a researcher you send to the library. They read forty books in the back room and walk out with a single tidy page of findings. The forty books never pile up on your desk — only the page does. That's a sub-agent: the messy middle happens in the helper's space, and only the final answer comes back to your main conversation.

When you'd actually reach for one

You don't need a sub-agent for everyday back-and-forth. You reach for one when a job is big, or messy, or off to the side of what you're really doing. A few honest examples, staying with the recipe site you've been building:

• A big read-and-understand job: "Go through all my recipe files and tell me if any are duplicates or nearly the same."
• A focused review or audit: "Check my whole site for broken links and anything that looks inconsistent."
• Any chunky side-task you'd rather not have cluttering the main thread while you stay focused on the thing you actually care about.

There's a second reason too, and it's an old friend. Remember the permission dial from a few lessons back — how you decide how much Claude can do on its own? A sub-agent can be handed only certain tools. You might send out a helper that's allowed to read your files but not change a single one — perfect for a "just look it over and report back" job. Same trust idea as the dial, scoped down to one helper.

You don't have to set anything up

Here's the reassurance, because this is exactly where it sounds like homework is coming: you do not have to create any "agent" files to use this. Claude Code already comes with capable helpers built in, and when a job clearly suits one, Claude will quietly bring one in on its own. Or you can simply ask — "send a helper off to read all my recipe files and summarize them" — and it does.

So when would you make your own? Only when you've got a repeatable specialist you want to name and reuse — say, a "recipe-site reviewer" you'll call on again and again. That's a defined sub-agent, and like the skills from last lesson, it lives in that .claude folder tucked inside your project (or in your personal one, if you want it everywhere).

And even then, you don't hand-write it — you ask Claude to set one up, the same way you made a skill. So hold two simple options in your head: just ask for a helper in the moment, or, for something you'll want over and over, have Claude set up a named specialist you can call by name later.

Skill or sub-agent — which do I make?

If last lesson's skills and this lesson's helpers are starting to blur, here's the line that keeps them straight. A skill is a method — it teaches Claude how to do a particular kind of job your way. A sub-agent is a worker — a separate someone you send off to go do a big or self-contained job in its own space.

How versus who.

And the happy part: they're not rivals you have to choose between. They work together. A sub-agent you send out can lean on the very skills you've taught Claude — so your specialist does the job and does it your way. You don't wire any of this up in advance; you describe what you want in plain English, and Claude combines the method and the worker for you.

If you'd like the fuller, more technical picture of all this, Claude Code's official sub-agents documentation at code.claude.com/docs/en/sub-agents lays it out — entirely optional, there if you're curious.

Sending a helper off in the background

One more genuinely handy move. Because a helper works in its own space, you can send it off to work while you carry on with something else — no need to sit and watch. It beavers away on its own and surfaces its results when it's done, and you can peek at how it's getting on in the meantime. One helper, working quietly in the background while you keep your momentum.

This same idea scales up — several helpers working at once, as a kind of team, with a lead one coordinating them — and that can be powerful for really big jobs. But it's firmly advanced territory: it's an experimental feature that's switched off unless you deliberately turn it on, and running a whole crew at once burns through a lot more behind the scenes. You absolutely don't need it to be productive — file it away as a "someday, for a really big job" horizon, not a thing to set up now.

So that's a sub-agent: an extra pair of focused hands for the big or messy jobs, working in its own space so your main conversation stays clear — and no setup required to start. You've now taught Claude how you like jobs done, and met the helpers who can take the heavy ones off your plate. The next question is about reach: all of this still happens inside your folder. What if Claude — and its helpers — could also reach your other tools and the information living elsewhere? That's the connection we open up next.