
"The new models already send out sub-agents on their own. Why build our own? The model is good enough."
I hear this sentence a lot. And whoever says it is half right.
This post is about the other half: what Claude already does by itself, what only you can define for it, and how to build your first sub-agent in one conversation.
Along the way I'll use a comparison you already know from work. Even a very talented engineer needs a job description.
This post is based on Anthropic's official documentation, as of November 2026. Claude Code changes fast, and the full sources are at the end.
"The model already does this on its own, right?"
Yes. Anthropic says so itself: Claude hands work to sub-agents when it sees a reason to, and you rarely need to ask. A broad code search goes to a built-in agent called Explore. Side tasks run in the background while your conversation keeps moving.
If you work with Claude Code, this is already running for you.
So what is a sub-agent? A worker that gets a task, goes off to another room with its own working window, and comes back with a summary. The dozens of files it read along the way stay with it.
A developer on one of the teams I work with built a discovery process on top of this, for an old legacy monolith. Before anyone starts on a ticket, a separate sub-agent goes into each area of the code: the entry points, the business logic, the data layer. Each one returns a summary, and the developer decides what to do with it. By his own measurement, about 3 hours of investigation dropped to about 20 minutes. Along the way it surfaced a security bug and dependencies between tables, before a single line of code was written.
Two more things from the docs, where the skeptics are right:
- Delegating doesn't get you a smarter answer. It's the same model on the same task. This is where the team comparison breaks: a new hire brings another brain, a sub-agent doesn't.
- "Delegate so you don't run out of context" is outdated advice. Most current models have a one-million-token window, and running out is rare. What still holds: long output that sits in your main session rides along until the session ends, and you pay for it on every turn.
So if it isn't smarter, why build your own?
"So what can't the model do on its own?"
The model knows when to delegate. It doesn't know what isn't written in the repo, and it can't enforce limits on itself.
The built-in agents are like a talented engineer from another team who comes to write code in your repo. They know how to work. They have no defined role on your team, and they haven't built up experience with you. Explore and Plan don't even read your CLAUDE.md.
A custom agent is that same engineer, after you gave them a role:
| On a team | In the agent | What you get |
|---|---|---|
| Job description | description | Claude knows when to turn to it |
| Access permissions | tools | A reviewer that can't edit code. The tool enforces it, it isn't a request in a prompt |
| What the task calls for | model | Sorting a thousand log lines calls for speed and volume. A design decision calls for depth and judgment |
| Onboarding | skills | Your procedures are loaded from the start |
| Experience | memory | It remembers what it learned in earlier runs |
| Knowledge that belongs to the team, not one person | A file in .claude/agents/ | It goes into git, and the whole team works with the same agent |
Nothing in this table depends on how smart the model is. These are your decisions.
"I already have skills. What's the difference?"
A skill is a procedure. A sub-agent is a worker.
| Skill | Sub-agent | |
|---|---|---|
| What it is | Instructions and knowledge loaded into your conversation | A separate worker with its own working window |
| Where the work happens | With you, in front of your eyes | In another room. Only a summary comes back |
| Best for | A process you want to watch and steer at every step | Work whose intermediate output would only get in the way |
They also work together. An agent can get skills as part of its onboarding, and a skill can run inside a sub-agent, with context: fork.
"When is it worth hiring?"
The rule: hire for a role that repeats, not for a one-off task. Claude handles one-off tasks by itself.
Four signs that you have a role:
- Long output you won't come back to. A full test run, a broad search, logs.
- You need eyes that weren't in the room. A reviewer that didn't see how the code was written isn't swayed by the reasoning that led to it.
- The task needs fewer permissions than you have. Someone who only checks doesn't need to edit.
- Work you can split. Parts that don't depend on each other can run in parallel, each with its own sub-agent, while your conversation keeps moving. Claude runs up to 20 of them at once by default. The price: each one uses its own tokens, so ask for short summaries.
When not to: a small fix, work with a lot of back-and-forth, or a task that depends on what was already said in the conversation. A new agent starts from zero and has to gather context you already have.
And don't hire for everything. Anthropic warns that too many custom agents flood Claude with options, and automatic delegation gets less reliable. Like a team with five overlapping roles, where nobody knows who to go to.
"Is it complicated to build?"
No. It's a conversation with Claude, like almost everything else.
Create a sub-agent named reviewer in this project's .claude/agents/ folder.
Role: review changed code against the spec it was built from, before a PR is opened.
Permissions: read-only (Read, Grep, Glob). It judges, it doesn't fix.
Output: only gaps that affect correctness, up to 30 lines. No style comments.
Show me the file before you save it.What you get is one markdown file. It's worth knowing, because this is what you'll edit later:
---
name: reviewer
description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening a PR.
tools: Read, Grep, Glob
---
You are reviewing code you did not write.
Compare the changed files to the spec you are given.
Report only gaps that affect correctness, in 30 lines or less. Skip style.Only name and description are required. The text below them is the agent's system prompt. There's no model line here, so it uses the session's model.
Three first roles worth considering:
- reviewer - read-only, checks against a spec.
- test-runner - runs the tests and returns only what failed.
model: haikuis enough here. - log-investigator - read-only, a short report, and at the end a list of "open threads". Every "one more thing worth checking" comes back as a candidate for a separate run, instead of dragging the main session along.
Check that it worked: type "use the reviewer agent on the last change", and make sure a short summary comes back, not everything it read.
Note: if this is the first time a .claude/agents/ folder is created for you, start a new session. After that, changes to the files are picked up within seconds.
"I built one, and it doesn't work the way I expected"
Two failures keep coming back.
Claude doesn't turn to it. Usually the job description is vague. "Helps with code" tells Claude nothing. Write in the description when to use the agent. And when it matters, don't rely on automatic delegation: call it by name, in a plain sentence or with @agent-reviewer.
It works, but the result arrives too late. I learned this one myself.
While preparing a workshop, I built a loop that raises test coverage, with a reviewer sub-agent that checks the tests are real and not just inflating the number. In the first version the reviewer ran in the background. Its report arrived one turn too late, and the loop had already declared "done" by itself.
It wasn't a bug. Sub-agents run in the background by default, and their result arrives in a later turn.
Three fixes closed it:
- The loop waits for the reviewer before it continues.
- "Done" is a literal line that only the reviewer prints:
VERDICT: NO WEAK TESTS. - The loop is not allowed to declare done itself, and there's a cap of 10 turns.
A loop can't check its own homework. I wrote about the loops themselves in the post on loops.
"Won't this cost me more?"
It will. Every sub-agent sends its own requests, and they count against the same usage as your main conversation. Sometimes it's slower too, because a new agent first has to work out where it is.
What you get in return: a main session without the noise, parallel work, and a reviewer that doesn't depend on whoever wrote the code. Saving tokens isn't on the list.
How to spend less:
model: haikufor simple roles, like collecting files or running tests.- Ask for a short summary back. Twenty long reports will fill your conversation anyway.
/usageshows how much each agent type uses (on Pro, Max, Team and Enterprise plans). That's where you see which ones earn their cost.
"And what does this look like for a team or an organization?"
If you lead a group, there are three levers here:
- Risk.
toolsis a limit the tool enforces. A read-only agent won't edit code, even if the prompt went wrong. I wrote about the difference between asking and enforcing in the post on guardrails. - Cost. A model per role, and
/usageto see where it goes. - Scale. A file in
.claude/agents/goes into git and serves the whole team. At the organization level you can distribute agents through managed settings, or package them as a plugin for several repos. Why it's worth starting at the team level is in the post on team harness.
A question worth bringing to your next team meeting: which role comes back every week, and yet everyone explains it to Claude from scratch?
Where to start: the most painful session you already had
You don't need to imagine an agent. Its spec already exists, in your last long session.
Open a long session that ended, a production investigation for example, and ask it:
If you had split the work in this session into sub-agents, which two or three would have helped the most, and in which part?Then:
- Pick one. The one that used the most and returned the least text. It's almost always the logs.
- Write the expected answer before the first run. Otherwise you won't know if it's any good.
- Fix one thing at a time.
- Share it with the team only after two real cases.
Run /context before and after. The difference is what stayed out of your main session. And if you want to get more out of your old sessions, that's what the post on session mining is about.
And the next time someone on the team says the model is good enough, agree with them. Then ask which role you're giving it.

Sources and further reading
Anthropic's docs and blog
- Create custom subagents - every field, the built-in agents, background and foreground
- Best practices for Claude Code - what sub-agents give you, what they cost, and which advice is outdated
- Extend Claude Code - skill and sub-agent compared
- How and when to use subagents in Claude Code - when to, and when not to
- Steering Claude Code - skills, hooks, rules and sub-agents side by side
Other writers
- Leland - Claude Code Subagents - on how reliable automatic delegation to custom agents is