How to Use Subagents in Claude Code

#claude #ai #tutorial #automation

This is a cross-post — the original (and any updates) live at broke2builtai.com.

Long Claude Code sessions die the same way every time: the context window fills up with search results, file dumps, and dead-end exploration, and the model gets dumber right when you need it sharp. Subagents are the built-in fix — separate workers that do the messy digging in their own context and hand back only the conclusion. Here's how to actually use them.

What a subagent actually is

A subagent is a separate agent instance that Claude Code spins up with its own context window. It gets a task, works it — reading files, grepping, reasoning — and returns a single result message to the main conversation. All the intermediate noise stays in the subagent's context and dies with it.

That buys you three things:

A clean main context. The subagent burns its own tokens exploring; your main conversation only receives the conclusion. Fifty file reads on its side show up as one summary on yours.
Parallel work. Multiple subagents can run at once. Three independent questions, three workers, answered simultaneously instead of serially.
Specialization. A custom subagent carries its own system prompt and its own tool restrictions, so it behaves like a focused specialist instead of a generalist with your whole session on its mind.

Triggering one: automatic vs explicit

You don't have to configure anything to start. Claude decides to delegate on its own when a task looks like broad search or research — "find everywhere we handle auth" is the kind of thing it will hand to a subagent without being asked.

When you want control, ask explicitly:

use a subagent to find every place we construct SQL queries by hand

spawn an agent to research how the payment webhook flow works, then summarize it

Plain language is the interface. Say "subagent" or "spawn an agent" and describe the task; Claude handles the rest.

One thing to know about the plumbing: subagent results come back to the main agent, not directly to you. The main agent reads the result and summarizes it in its reply. You're always talking to the coordinator, never the worker.

Building a custom subagent

The real power move is defining your own. A custom subagent is one Markdown file with YAML frontmatter, and it lives in one of two places:

.claude/agents/ in your repo — project-level. Commit it and your whole team gets the same specialist.
~/.claude/agents/ — personal, available in every project you open.

Here's a read-only code reviewer:

---
name: code-reviewer
description: "Use this agent when code has just been written or modified and needs review. Checks for bugs, security issues, and convention violations before anything ships."
tools: Read, Grep, Glob
---

You are a senior code reviewer. Review the changes you're pointed at
for correctness bugs first, then security issues, then convention
violations. Be specific: file and line, what's wrong, why it matters.
Do not suggest rewrites of code that works. Report findings ranked
by severity, worst first.

Four frontmatter fields matter:

name — kebab-case identifier.
description — when Claude should use it. This is the routing signal; more on it below, because it's where most subagents fail.
tools — optional allowlist. Everything not listed is off the table.
model — optional; pin the model this subagent runs on.

Everything below the frontmatter is the subagent's system prompt. If you've read how to write a system prompt for an AI agent, all of it applies here — concrete rules, explicit output shape, no vibes.

Don't want to hand-write the file? Run /agents inside Claude Code — it opens an interactive manager for creating and editing subagents.

The description is the routing signal — write it like a trigger

Claude reads the description field to decide when to delegate. That makes it the single most important line in the file. Write it as a trigger condition:

# Weak — Claude has no idea when to reach for this
description: A helpful agent for code quality.

# Strong — reads like a rule Claude can match against
description: Use this agent when code has just been written or modified and needs review.

"Use this agent when…" followed by concrete situations is the pattern that works. If your subagent never fires automatically, fix the description before you touch anything else.

Restrict tools — it's a safety feature, not a nicety

The tools allowlist is what makes specialists trustworthy. A reviewer with only Read, Grep, Glob cannot accidentally edit a file, no matter how confused it gets. That's a guarantee, not a hope.

Good candidates for the specialist treatment, each with tools scoped to the job:

Code reviewer — read-only.
Test runner/fixer — needs to run commands and edit test files.
Docs writer — read plus write, no shell.
Security auditor — read-only, again.
Read-only explorer — for "map this codebase" jobs where you want zero chance of side effects.

One structural limit to design around: a subagent cannot spawn further subagents. Delegation goes one level deep, so the main agent is always the coordinator fanning work out — build your workflows with that shape in mind.

The honest trade-off

Subagents are not free. Each one spins up its own instance, which means added latency before you see anything, and its exploration burns tokens even though they never land in your context. For a single quick file lookup, direct search is flat-out better — don't spawn a worker to answer a one-line grep.

The rule of thumb: delegate when the search is broad or the task is self-contained. Keep it direct when the answer is one known location away.

The token side is worth planning around too, since subagents burn tokens even though those tokens never land in your context. If cost is a concern, one option is pointing Claude Code at a cheaper backend — the GLM Coding Plan is one, and I walk through that setup in how to set up Claude Code with the GLM API. When the exploring is cheap, "spawn three workers" feels like a shrug instead of a bill.

Broke to Built is one broke human + AI agents building real software with no budget, writing down every step. This site's tools run on free GLM — z.ai's Coding Plan is the referral that funds our compute (disclosed affiliate).