Skip to content
Chen FeldmanLEAD BY NATURE
All posts
· Claude Code

How to hire your first sub-agent, and why "the model is good enough" is only half the answer

I help organizations and companies adopt AI - from strategy to hands-on implementation.

Intro Call
Claude in a black coat and sunglasses on a rooftop at night, with five copies of itself behind, each doing a different job

"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 teamIn the agentWhat you get
Job descriptiondescriptionClaude knows when to turn to it
Access permissionstoolsA reviewer that can't edit code. The tool enforces it, it isn't a request in a prompt
What the task calls formodelSorting a thousand log lines calls for speed and volume. A design decision calls for depth and judgment
OnboardingskillsYour procedures are loaded from the start
ExperiencememoryIt remembers what it learned in earlier runs
Knowledge that belongs to the team, not one personA 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.

SkillSub-agent
What it isInstructions and knowledge loaded into your conversationA separate worker with its own working window
Where the work happensWith you, in front of your eyesIn another room. Only a summary comes back
Best forA process you want to watch and steer at every stepWork 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:

  1. Long output you won't come back to. A full test run, a broad search, logs.
  2. 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.
  3. The task needs fewer permissions than you have. Someone who only checks doesn't need to edit.
  4. 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.

prompt
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:

markdown
---
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: haiku is 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:

  1. The loop waits for the reviewer before it continues.
  2. "Done" is a literal line that only the reviewer prints: VERDICT: NO WEAK TESTS.
  3. 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: haiku for simple roles, like collecting files or running tests.
  • Ask for a short summary back. Twenty long reports will fill your conversation anyway.
  • /usage shows 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. tools is 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 /usage to 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:

prompt
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:

  1. Pick one. The one that used the most and returned the least text. It's almost always the logs.
  2. Write the expected answer before the first run. Otherwise you won't know if it's any good.
  3. Fix one thing at a time.
  4. 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.

Hiring your first sub-agent: the job description card and the four steps to the first hire

Sources and further reading

Anthropic's docs and blog

Other writers

More from Lead By Nature

Explore all workshops, courses, and personal coaching for managers and dev teams

Home
WhatsAppBook a call