Subagents for Beginners: When to Hand Work to a Second Claude

You asked Claude a question that needed a look across the whole codebase. It read a file, then another, then a stack of others, and by the time the answer arrived your session felt slower, vaguer, and full of material you never wanted to see. That is the problem subagents solve, and it is close to the only problem you should reach for one to solve.

A subagent is a second Claude with a clean desk

A subagent is a separate Claude with its own context window, its own system prompt, and its own tool permissions. You hand it a task. It works on that task in isolation, spending its own context rather than yours, and when it finishes, only its summary comes back into your session. Everything it read along the way stays on its side of the wall.

The isolation is the whole feature. A subagent is not a smarter Claude, a faster Claude, or a Claude with abilities yours lacks. It is the same model doing the same kind of work somewhere else, so the mess it makes stays somewhere else. Read that sentence twice, because almost every wrong reason to use a subagent comes from expecting it to be a power-up instead of a container.

One naming trap before we go further. A Claude Code subagent is not the same thing as a standalone personal agent: the always-on assistant you build yourself, run on your own machine, and talk to over something like Telegram. That is a separate program you own end to end, and a different kind of project entirely. A subagent has no life of its own. It exists inside a Claude Code session, only for as long as that session has work for it.

Why a beginner should care: context is finite

Every session has a context window, and everything in it competes for the model’s attention: your instructions, the project files that have been read, tool output, and the whole conversation so far. Size is only half the problem. A window packed with search noise makes the model worse at the thing you actually asked about, because your real question is now a small fraction of what it is looking at.

So the question behind every delegation decision is simple: do I need the intermediate output, or do I only need the conclusion? A repo-wide search produces an enormous amount of intermediate output and a two-line conclusion. That ratio, mountains of working material to a small answer, is what a subagent is for.

The situation that calls for one

Reach for a subagent when a task will generate a lot of material you do not need to see, and the useful part is a short answer at the end. Concretely:

• Broad searches. “Where do we do X across this codebase” gets answered by opening many files and writing one paragraph.
• Research sweeps. Reading documentation, comparing options, or checking a list of sources when all you want is the recommendation.
• Independent work you want running in parallel while you keep going in the main session.
• Anything whose working notes you would immediately clear if there were a button for it.

What came back is a few lines. What did not come back is the pile of files the subagent read to produce them. You keep the answer and you keep your room.

The situations that do not

This is the half most explanations skip, and it is the more useful half. Delegation has a cost. You write a brief, the subagent starts cold with no memory of your conversation, and you wait for a result you cannot steer. For most requests that cost is larger than the benefit.

• A quick edit. One file, one change, no research: the handoff is more typing than the fix.
• Anything that needs back and forth. Assume a subagent will not stop to ask you a clarifying question, so ambiguity becomes a guess you only find out about at the end.
• Anything where you need to see the working. If the reasoning is the deliverable, do not put it behind a wall.
• Small tasks in general. If a task would add ten lines to your context, delegating it saves ten lines and costs a round trip.

How a skill and a subagent relate

Since this is a skills site, here is the comparison worth internalizing: a skill is a procedure, a subagent is a worker. A skill is a folder of instructions Claude loads when a task matches its description, so it changes how the work gets done. A subagent is a separate context the work gets done in, so it changes where. Neither one replaces the other, and confusing them is why people reach for a subagent when they wanted a skill.

They compose, too. A skill can tell the main session to delegate one of its steps, which is exactly right when a procedure has one expensive research step and several cheap ones. Both are configured as files on disk, and both can be scoped to you personally or committed with a project, the same split covered in the guide on where skills live. The wider comparison, with CLAUDE.md and hooks alongside them, is its own guide linked at the end.

Claude Code also lets a skill declare that it should run as an isolated subagent rather than inline in your conversation, using a frontmatter field (the small settings block at the top of a skill’s file) called context: fork. It is worth recognizing the phrase when you meet it in someone else’s skill. It is not where a beginner should start. Build the manual delegation habit first, then automate it.

How you actually invoke one

Two things to know, and the second matters more. First, /agents is the command for the agents themselves: it is where you look at what a session can delegate to, and where you create or edit one. What that panel offers has changed across Claude Code versions, so treat your own screen as the current truth.

Second: you do not have to configure anything to start. Delegation is a request. Ask for the work to be handed off, in plain language, and describe the task the way you would describe it to a competent stranger, because that is precisely what the subagent is. Configured agents are the optimization you reach for after you know which handoffs you keep repeating.

When you do get there, configured agents live as files in two familiar places: a personal directory that follows you across projects, and a project directory you commit so your team gets the same ones.

# personal: follows you across every project on this machine
~/.claude/agents/

# project: committed with the repo, so the team gets the same ones
<repo>/.claude/agents/

The file format for a configured agent is documented in Claude Code’s own sub-agents reference. Do not copy an agent schema out of a blog post, including this one. That is the detail most likely to have changed since whatever you are reading was written.

The limits, stated plainly

• Plan on getting the summary rather than the path it took. If you need to catch a wrong turn mid-flight, stay in the main session.
• A vague brief buys you a confident, useless summary. The subagent cannot check what you meant, so it decides for itself, and you find out at the end. Write the task as if the reader has never seen your project, because it has not.
• Expect parallel subagents to duplicate work. Each one can be individually correct and the set collectively redundant, because none of them sees what the others found. Split tasks so they do not overlap, or accept the overlap on purpose.
• Limits exist and they move. How deeply subagents can nest and how many can run at once are governed by settings that have changed across Claude Code versions. If a delegation fails for no obvious reason, check the current documentation for your version before assuming your request was wrong.