Subagents: Outsource the Work, Don't Carry Everything Yourself

📚 Series Navigation: The previous post 22 MCP taught you how to connect external tools to Claude so it can query databases and connect to GitHub. This post shifts the mindset—instead of "adding tools" to it, we'll teach you to outsource the work: Subagent, a specialized assistant with independent context, independent permissions, and an independent persona, which only returns the conclusion when the work is done.

Everyone says subagents are powerful, the "advanced gameplay" of Claude Code. When many people first learned about this feature, they were so excited they wanted to split one task into five or six subagents to run simultaneously, thinking this was "more professional and efficient".

But to tell the truth: It's a mistake for most people to just start splitting right away.

This takes a while of using to figure out. I will explain exactly why later—but let's put the conclusion here first: Subagents are not "the more tasks, the more you should split them." It is a tool with clear applicable scenarios; it saves you worry when used correctly, but makes things slower and more expensive when used wrong. Thinking clearly about "whether to split" is much more important than learning "how to split".

In this post, I won't just teach you how to create and trigger subagents. More importantly, I'll help you establish that baseline of judgment: when to outsource, and when doing it yourself is faster.

After reading this post, you will get:

• What a subagent actually is—independent context, independent tools, independent persona. Explain the difference between it and the main conversation in one sentence.
• The three real problems it solves (isolating context, specializing tasks, and parallelism), and the counter-intuitive trap: when you should not split.
• Using /agents to create interactively, or manually writing .claude/agents/name.md configuration files, and what each field is for.
• Two trigger methods: automatic delegation relying on description vs your direct callout.
• A practical exercise you can follow and run, with expected output provided: manually create a minimal subagent and let it work.

---

01 Understand First: What Exactly is a Subagent

Let's give the conclusion first: A subagent is just a specialized minion temporarily hired by Claude—it works in its own room, only hands the conclusion to you when done, and the pile of materials it flips through in the process doesn't occupy your desk.

Analogy: Outsourcing a job to a specialized minion. You have a bunch of things on your hands, among which a dirty and space-occupying job like "flip through this thousand-line log and pick out the few error lines" is something you don't want to spread out and do yourself on the main workbench—that would clutter your desk. So you outsource it to a minion who specializes in this: he is in his own room, on his own desk, flipping through that thousand-line log; when done, he won't carry a thousand lines of raw logs back to you, he just hands you a piece of paper: "There are just these three errors, on lines 207, 589, and 903 respectively". Your desk is always clean.

This minion has three things that are "his own", completely separated from you (the main conversation). The official documentation states this sentence very firmly, and it's worth remembering:

Each subagent runs in its own context window, with a custom system prompt, specific tool access permissions, and independent permissions.

Breaking it down, there are three "independences":

Dimension	Main Conversation (You)	Subagent (Outsourced Minion)
Context	The entire history you and Claude chatted along the way	Completely blank, only receives a "task assignment", cannot see what you chatted about before
System Prompt (Persona)	Default setting of Claude Code	The exclusive persona you write for it, like "You are a code reviewer who only picks faults"
Tools / Permissions	All tools you authorized	Can be stripped down individually, like "read-only, no writing"

The most crucial and easiest to ignore is the first row: A subagent starts from a blank slate. The official wording is very direct—it "does not see your conversation history, the skills you have invoked, or the files Claude has already read". Claude will write a "task assignment" and throw it to it, and it will start working from this sentence.

This point determines what a subagent "is good at and what it is not good at", which we will rely on for judgment in the next section.

💡 One-sentence summary: Subagent = Outsourced minion with independent context + independent persona + independent tools, works in its own room, only returns the conclusion; remember it starts from a blank slate and cannot see your previous conversations.

---

02 What It Solves—And That Counter-intuitive Trap

Knowing "what it is", we must clarify "why have it". Subagents really solve three problems, I'll explain them one by one, and for the third point, I will also dig out that counter-intuitive trap from the beginning.

Problem 1: Isolate Context, Don't Pollute the Main Thread

This is the most core and valuable use of subagents.

Context—Claude's "workbench" is limited. The longer you chat with it and the more files it reads, the more crowded the desk gets, and once full, it starts forgetting things and becoming clumsy. Some jobs will crazily occupy the desk, but you won't take a second look at the intermediate garbage produced.

For example, "run the entire test suite and tell me which ones failed". Running tests will spit out hundreds or thousands of lines of output, but what you really want is just one sentence: "These three tests failed, the error is XXX". If you run it directly in the main conversation, those hundreds of lines will be smeared all over your desk.

At this time, outsource it to a subagent: it handles these hundreds of lines in its own room, and only returns the single sentence "which ones failed". Your main conversation desk is as clean as before. The official docs list this use as one of the "most effective uses" for subagents:

Running tests, fetching documentation, or processing log files can consume a lot of context. By delegating these to a subagent, detailed output stays in the subagent's context, while only the relevant summary returns to your main conversation.

Real Scenario: When debugging a third-party SDK, you have to repeatedly curl its API to see the response, brushing a screen of JSON each time. By the dozen-th round, the main conversation is so stuffed with JSON that it starts to forget the initial requirement. Use a different approach—let a subagent specifically "debug this interface, only tell me what the fields look like", the main conversation is instantly refreshing, and your own train of thought won't break.

Problem 2: Specialize in a Certain Type of Task

The second use: for a certain type of recurring job, designate a "person dedicated to doing this".

If you find yourself repeatedly issuing the same kind of instruction—every time you finish writing code, you ask Claude to "pick faults from a senior reviewer's perspective, focusing on security and naming"—then you might as well solidify this set of instructions into a subagent called code-reviewer, which can be summoned with one sentence later. Official quote: "Define a custom subagent when you keep spawning the same type of worker and using the same instructions."

It is "specialized" in two places: one is exclusive persona (hardcode "you are a reviewer who only picks faults" in the system prompt), and the other is exclusive tools (a reviewer should only read and not write, so cut off Write and Edit, and it couldn't change it even if it wanted to).

Problem 3: Parallelizable

The third use: several unrelated jobs can be thrown to several subagents to run together at the same time.

For example, "investigate the authentication, database, and API modules separately"—these three parts are independent of each other, so open three subagents to explore simultaneously, and finally Claude summarizes the three conclusions for you. Serial would wait for three trips, parallel gets it done in one.

The Counter-intuitive Trap: Not the More the Merrier

Alright, having laid the groundwork for the three uses, let's return to that sentence at the beginning—why is it wrong to "just start splitting right away"?

Because beginners generally have a misunderstanding: "The finer the split = the more professional = the faster". It's completely reversed. Subagents have three hidden costs, and when you split simple tasks, all the costs pop up:

Comparison Item	Simple task done directly in main conversation	Simple task forcefully split to subagent
Startup Overhead	None, open mouth and do it	Subagents start from a blank slate, must first take time to "gather context" and figure out the situation
Back-and-forth Communication	You say a sentence, it says a sentence, modify anytime	Rework if not explained clearly, the subagent can't see your previous conversation
Cost	One share of token	Opening an extra context = burning more token, the more you open, the more you burn
Result Backfill	Doesn't exist	Every subagent stuffs detailed results back to the main conversation, opening too many instead clutters the desk again

The official docs specifically provide a checklist of "whether to use the main conversation or a subagent", which I refine into one sentence: Tasks with frequent back-and-forth, shared context, rapid small changes, and where speed matters, stay in the main conversation; only jobs that produce a pile of intermediate garbage you don't want to look at, need to lock down tool permissions, and can be self-contained returning just a single conclusion, are outsourced.

The official docs also pointed out a counter-intuitive detail—subagents are actually at a disadvantage in scenarios where "latency" matters:

Latency matters. Subagents start from scratch and may take time to gather context.

Real Scenario: If you are stubborn and even open a subagent to "change a variable name" just to "appear professional". The result? It has to re-read the file first (because it doesn't have your context from just now), slowly finish the change and then backfill the result, which is much slower than directly saying "change this variable name" in the main conversation, and also burned more token. So there is an iron rule worth remembering: A job that can be explained in one sentence, with changes right in front of your eyes, is never outsourced.

💡 One-sentence summary: Subagents solve the three things of "isolating context, specializing tasks, and parallelism"; but simple tasks are faster and more economical done directly—splitting more ≠ professional, over-splitting will only be slower, more expensive, and pile up the desk again.

This picture illustrates the act of "outsourcing" clearly: the main conversation is your workbench; throw a dirty job that will spit out a massive intermediate output (running tests / flipping through logs) to a subagent; the subagent shoulders all the details in its own independent context room, and finally only a line of "conclusion summary" returns to the main thread, leaving your desk always clean.

---

03 How to Create: Interactive Creation with /agents

After talking about "whether to use", let's build one hands-on. The most hassle-free way is to use the /agents command, which is interactive the whole way, without manually writing a single word of configuration.

Type in the Claude Code session:

/agents

A management interface will pop up. To create a new one, the official recommended flow is these few steps (I am restating according to the official drill, you just follow along):

1. Choose location: Switch to the Library tab → Create new agent → choose Personal. Choosing Personal will save it to ~/.claude/agents/, available for all projects; choosing Project will only use it in the current project, and it can also be committed via git to the team (the difference between these two is detailed in the next section).
2. Let Claude generate for you: Choose Generate with Claude, then use plain language to describe what kind of assistant you want. For example: "A code review assistant, scans files, gives improvement suggestions from three angles: readability, performance, best practices. For each item, clearly state the problem, paste the current code, and give an improved version." Claude will automatically write the name, description, and that persona system prompt for you.
3. Select tools: A reviewer should only read, not write, so only check Read-only tools, and uncheck all others. The official docs remind us of a crucial point: "If you leave all tools checked, the subagent inherits all tools available to the main conversation." — If you don't actively cut them, it can do anything.
4. Select model: Pick a model specifically for it. For review work like this, the official example chose Sonnet (a balance of analytical capability and speed).
5. Save: Take a look at the configuration summary, press s or Enter to save, and it's ready to use immediately. (The actual interface will also ask you to choose a background color and memory scope; color is up to you, memory defaults to None, beginners can skip it.)

Analogy: Filling out an "outsourcing job application form". You don't need to know how to write a contract. The front desk (/agents interface) takes a form and asks you item by item: What is this job called, what work does it do, what tools can it touch, what grade of person to use—you finish filling it out, and it builds this "job" for you. Generate with Claude is like having an HR next to you filling out the form beautifully for you.

Real Scenario: A very worthwhile permanent subagent is built just like this—a test-runner, specifically for "running tests, only reporting which ones failed + error message". When creating it, intentionally only give it Read and Bash, not Write, precisely for fear that its hands get itchy and it goes to modify your code while running. Build it once, use it every day thereafter.

💡 One-sentence summary: /agents is the recommended way to create subagents, interactive form-filling the whole way, and you can let Claude generate the persona for you; remember to actively cut tools, if not cut it inherits all permissions of the main conversation.

---

04 How to Create: Manually Write a Configuration File

After creating interactively, what lands on the disk is actually a Markdown file. Once you understand this file, you can also write it manually yourself, or modify someone else's.

The subagent file looks like this—a YAML header (frontmatter) at the top manages the configuration, and the body text below is its persona (system prompt):

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Analogy: A badge + a job description given to an outsourced minion. The YAML header is the hard info on the badge—what name, what it does, what tools it can touch, what grade (name/description/tools/model); the body text below the line is the job description stuffed to him, "who you are, what to do first when you arrive, by what standard". He only looks at these two things when taking the post, and cannot see the other messy affairs of your company.

The official docs clarify that only name and description are required, the rest can be omitted. Let's pull out the common fields and explain them clearly:

Field	Required	What it does	Points for Beginners
name	Yes	Unique identifier, lowercase letters plus hyphens (like code-reviewer)	Don't duplicate names across the whole project, if duplicated one will be quietly dropped
description	Yes	Tells Claude "what tasks should be dispatched to it"	The clearer it's written, the more accurate the automatic delegation, this is the key to triggering
tools	No	What tools it can use	Omitted = inherits all tools of the main conversation; if you want to limit permissions, list the allowlist here
model	No	Which model to use	sonnet/opus/haiku/inherit, default is inherit (same model as the main conversation)
permissionMode	No	Its permission mode	Optional: default/acceptEdits/auto/dontAsk/bypassPermissions/plan

Where to put the file matters, the location determines "who can use it". The official docs list several tiers, beginners only need to remember the two most common ones:

Put Where	Who Can Use	Suitable for
~/.claude/agents/	All your projects	Personal general assistant, like a code reviewer you want to use everywhere you go
.claude/agents/	Current project only	Project-exclusive assistant; can be committed with git, shared with the team

The official advice on the project-level tier is very practical:

Project subagents (.claude/agents/) are great for codebase-specific subagents. Check them into version control so your team can collaborate on using and improving them.

The last pitfall beginners must step into, the official docs used a Note to specifically remind—after manually writing or directly modifying the file on disk, you must restart the session for it to load; but those built through the /agents interface do not need a restart and take effect immediately. After manually writing a subagent for the first time, it's very easy to run into a situation where you call it for a long time with no response, thinking you wrote it wrong, when in fact you just forgot to restart.

💡 One-sentence summary: A subagent is just a Markdown file, the YAML header manages configuration (only name/description are required), the body is the persona; putting it in ~/.claude/agents/ makes it globally available, putting it in .claude/agents/ shares it within the project; remember to restart the session after manually modifying the file.

---

05 How to Trigger: Automatic Delegation vs Direct Callout

Now that the subagent is built, how do we make it work? Two ways: Claude looks at the "job description" and dispatches automatically, or you directly call its name.

Way 1: description-driven automatic delegation

You state your requirement normally, Claude will take your sentence to match against the description of each subagent, and if it feels like a match, it automatically dispatches the job over. You don't even have to know such a subagent exists.

This is why the previous section repeatedly emphasized that description must be written clearly—it is Claude's only basis for dispatching. The official docs gave a small tip to improve "proactivity": add words like "use proactively" in the description, and Claude will be more willing to delegate proactively. For example, if the reviewer's description is written as "proactively review immediately after writing or modifying code", once you finish modifying the code it might summon the reviewer itself.

Analogy: Whether the job description is written well determines whether HR will dispatch the right job to him. description is the "recruitment notice" for this outsourced position. If the notice is written vaguely ("handles some tasks"), HR (Claude) simply doesn't know what kind of job to find him for; if written precisely ("specializes in reviewing code security and naming, comes up proactively after code is written"), when a matching job comes, HR naturally thinks of him.

Way 2: You direct callout

When automatic delegation is unreliable, or you just want to specify a certain subagent, call its name yourself. The official docs give several ways from light to heavy, beginners remembering the first two is enough:

Natural language callout—just call its name directly in the sentence, no special syntax:

Use the code-reviewer subagent to look at my recent changes

@ callout—type @ and select from the popped-up list (after selection it inserts a format like @"code-reviewer (agent)"), or skip the list and manually type @agent- plus the name. This kind "guarantees" using it, not leaving the choice to Claude:

@agent-code-reviewer Look at the authentication-related changes this time

The difference between the two is stated very clearly officially: natural language is "Claude will usually delegate", while @ is "ensures the specific subagent runs". A safe habit—for newly built subagents whose temper you haven't figured out yet, uniformly use @ to callout, to avoid Claude acting on its own and not dispatching to it, making you think the subagent is broken.

How the conclusion is handed back

No matter which way triggers it, when the subagent finishes, it only hands the "conclusion" back to the main conversation, keeping all processes in its own room. This is exactly the fulfillment of the metaphor in section 01: the minion flips through a thousand lines of logs, and only hands back a piece of paper saying "the error is on these three lines". Official quote: it "works independently and returns results", and "detailed output stays in the subagent's context, while only the relevant summary returns to your main conversation".

⚠️ But there is a trap of quantity here, the official docs specifically warned: Opening too many subagents, each backfilling a massive detailed result, will still clutter your main conversation's desk. So don't be greedy with parallelism either—return to the baseline in section 02: only self-contained jobs that return a single sentence conclusion are worth outsourcing.

💡 One-sentence summary: Triggering splits into two paths—relying on description to let Claude automatically dispatch (description must be precise), or using natural language / @ direct callout (@ guarantees its use); subagents only hand conclusions back to the main thread, but backfilling too much still clutters the desk.

---

06 Hands-on: Build a Minimal Subagent and Let It Work in 5 Minutes

Just reading without practicing is an empty exercise. Below I'll take you to manually write a minimal subagent, then actually let it run, to see with your own eyes the chain of "outsource → return only conclusion". The whole process relies on no complex environments.

We'll build the simplest one: a read-only "code critic", specializing in reading files and giving improvement suggestions, but not allowed to change a single word (only given Read, not given Write/Edit).

Step 1: Build a toy project and subagent directory (Mac / Linux)

mkdir sub-demo
cd sub-demo
mkdir -p .claude/agents

Expectation: Inside the sub-demo folder, there is the .claude/agents/ directory layer. Typing ls .claude will show agents is there.

Step 2: Manually write the subagent configuration file

Using an editor you are comfortable with, create sub-demo/.claude/agents/code-reviewer.md, and paste:

---
name: code-reviewer
description: Read-only code critic, reads specified files and gives improvement suggestions from the angles of readability, naming, and potential bugs. Use proactively when reviewing any code.
tools: Read, Grep, Glob
---

You are a senior code reviewer who only picks faults and does not modify code.
When invoked:
1. Read the file specified by the user
2. List problems categorized by readability, naming, and potential bugs
3. Give specific improvement suggestions for each problem, but do not directly modify the file

Group by severity: must change, suggest changing, can consider.

Notice here the model field is not given—according to the official default, it will inherit (use the same model as your main conversation). tools only listed three read-only tools, it couldn't write even if it wanted to.

Step 3: Create a piece of code "with room for improvement" for it to critique

echo 'def f(a, b):
    return a / b' > calc.py

This function name f, parameter names a/b are all terrible, and it doesn't handle division by 0—perfect for the critic to catch.

Expectation: sub-demo has calc.py, the content is those two lines above.

Step 4: Start Claude, callout to let the subagent work

claude

After going in, use @ to directly callout (guarantee using it, don't let Claude act on its own). Manually type @agent-code-reviewer, or type @ then select code-reviewer from the popped-up list:

@agent-code-reviewer critique calc.py

Expectation: You will see Claude delegate to the code-reviewer subagent (the interface will mark that this subagent is running, possibly with a color block). It finishes reading calc.py in its own context, and then only hands a "critique conclusion" back to the main conversation—roughly pointing out: function name f and parameters a/b are unexpressive, missing handling for divisor being 0, suggesting changing to clearer naming and adding bounds checking. Notice it only gives suggestions, and didn't touch your file (because you didn't give it the Write tool).

Step 5: Verify it really didn't modify the file

Exit Claude (type exit or press Ctrl+D), go back to the terminal and see:

cat calc.py

(Windows PowerShell uses type calc.py)

Expectation: calc.py remains intact, still those two lines—this is the power of "limiting permissions": you only gave read-only tools, even if it wants to help you modify it is powerless, it can only move its mouth.

Running through these five steps, you have personally verified the complete chain of "write config → load → callout trigger → subagent works in independent context → returns only conclusion, no overstepping". Any future subagent is essentially changing the persona and adjusting tools on this mechanism.

⚠️ If it's not in the list when typing @agent-code-reviewer, mostly it's the subagent file load didn't take effect—manually written files need the session restarted (that pitfall in section 04). Exit and re-enter, or simply use the /agents interface to create (no restart needed).

💡 One-sentence summary: Manually write a critic that only gives Read, use @ callout to make it run, then cat to confirm the file wasn't touched—personally running through the chain of "working independently + limiting permissions without overstepping" is more effective than memorizing ten fields.

---

07 Summary

In this post, we talked about "subagents" all the way from "whether to use it" to "how to create, how to trigger, how to verify"—the core is not teaching you to split them up fancily, but helping you establish that baseline of "whether to outsource or do it yourself".

Stringing the key points together for a review:

What you want to figure out	Answer	Key point
What is a subagent	Outsourced minion with independent context + persona + tools	Starts from a blank slate, can't see your previous conversations
What it solves	Isolating context, specializing tasks, parallelism	The most valuable is "dirty work stays in its room, returns only conclusion"
When not to use	Simple jobs, requires frequent back-and-forth, cares about speed	Splitting more ≠ professional, over-splitting is slow and expensive
How to create	/agents interactive, or manually write .claude/agents/name.md	Only name/description are required; manual changes require restart
How to trigger	description auto-dispatch / natural language / @ callout	@ guarantees use; description must be clear to dispatch accurately

You should now be able to: Judge whether a task should be outsourced to a subagent (rather than excitedly splitting right away), use /agents or manually write files to create a subagent with an exclusive persona and limited tools, and use automatic delegation or @ callout to make it work, cleanly handing the conclusion back to the main thread. This sense of proportion—"outsource when you should, do it yourself when you should"—is the real threshold for subagents; the features can be learned in ten minutes, but the sense of proportion must be applied.

Remember that counter-intuitive sentence at the beginning: Subagents are powerful, but powerful in "using the right scenario", not in "splitting a lot".

💡 One-sentence summary: The threshold for subagents is not "knowing how to create", but "knowing when to create"—dirty work, self-containable, needing permission lock-down, outsource it; simple, fast, frequent back-and-forth, do it yourself.

---

Next post 24 "Plugins"—At this point, you have more and more "accessories" in your hands: CLAUDE.md, slash commands, Skill, and now Subagent is added. Configuring them one by one, isn't it a bit fragmented? The next post will teach you how to package these into a plugin, one-click install, one-click share, and even grab ready-made ones directly from the "plugin market". Think about it: Can subagents and commands tuned by others be moved to your place with one click?

---

Recommended Reading

• CLI Reference Manual: Commands and All Flags
• Making Videos (Remotion) [Optional]
• Installation and Usage