AI Guides › Step-by-step guides
By Nigel Guy · 7 min read
The usual mistake is treating a subagent like a colleague who was in the room. You type "have a subagent check the other modules too", it goes off, and it comes back with a confident summary of the wrong thing, because it never saw the forty messages that explained what "the other modules" meant. It feels like delegation. It's a sticky note handed to a stranger.
The rule: a subagent knows only what you put in its brief. Write every hand-off as if the reader has never seen your conversation, and say exactly what shape you want the answer back in.
| You need | Notes |
|---|---|
| Claude Code, installed and signed in | Subagents are part of Claude Code itself. Nothing extra to install. Some behaviour below changed in recent versions, so update first and check with claude --version. |
| A paid plan or API access | Claude Code is included with Pro and Max, not Free. Anthropic lists Pro at US$20 a month, or US$17 a month billed annually, and Max from US$100 a month. UK buyers pay a local amount; the pricing page didn't show a £ figure at time of writing, so check yours at checkout. Each subagent's requests also count against your plan's usage limits. |
| A project folder you're happy to experiment in | Ideally a git repository, so you can see and undo what changed. |
A subagent is a helper Claude Code starts inside your session, with its own fresh context window, system prompt, tools and permissions. It works, then hands back one summary; everything it read stays out of your main thread. Three things get called "agents":
| Subagent | Fork | Agent team | |
|---|---|---|---|
| What it sees at the start | Its own prompt, your brief, your CLAUDE.md files. Not your conversation. | Your entire conversation so far | Its own context, as a separate Claude Code instance |
| Who it reports to | Back to the main conversation | Back to the main conversation | Shares a task list and messages teammates directly |
| Status | Standard | Standard (start one with /subtask) |
Experimental, off by default |
| Cost | Lowest | Reuses the main session's prompt cache | Highest; each teammate is a full instance |
The main conversation is the agent you talk to; subagents are its helpers. Agent teams are experimental, switched on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Leave it off: with teams enabled, a subagent Claude names can launch as a teammate instead.
Claude Code ships with built-in subagents, and Claude uses them on its own:
If an older guide sends you to the /agents wizard: since v2.1.198, /agents only prints a reminder to ask Claude or edit the agent folders directly.
You only need a custom subagent when you keep briefing the same kind of helper the same way. Ask Claude to write the file:
Create a project subagent in .claude/agents/ called link-checker. It should
read Markdown files I point it at, list every outbound link, and flag any that
look broken or point to an old domain. It must not edit anything. Use Haiku.
Then open .claude/agents/link-checker.md and check it reads something like this:
---
name: link-checker
description: Audits outbound links in Markdown files and reports suspect ones. Use when asked to check links in content.
tools: Read, Grep, Glob
model: haiku
---
You audit links. For each file, list every outbound link, then mark each as
OK, SUSPECT or BROKEN with a one-line reason. Never change files.
Where beginners trip:
| Detail | What to know |
|---|---|
| Where it lives | .claude/agents/ is this project only; commit it so others get it. ~/.claude/agents/ is every project on your machine. If both define the same name, the project version wins. |
| Required fields | Only name and description. The Markdown body is the system prompt. |
| Typos | Field names are camelCase (disallowedTools, maxTurns). Claude Code silently ignores a field it doesn't recognise. If a restriction "isn't working", check the spelling first. |
tools vs disallowedTools |
tools is an allowlist; leave it out and the subagent inherits everything. disallowedTools removes items from what it would otherwise get. |
model |
sonnet, opus, haiku, fable, a full model ID, or inherit. A cheaper model is the easiest saving for simple, repetitive checks. |
| New folder not noticed | Edits are picked up within seconds. But if the agents folder didn't exist when the session started, restart Claude Code. |
| Descriptions | Keep them short. Claude reads them all to decide when to delegate, and warns at startup past 15,000 tokens combined. |
This decides whether the subagent is useful. Put these five lines in any substantial request. Claude writes the subagent's task message from what you say, so what you leave out, it never gets.
| Line | What goes in it | Example |
|---|---|---|
| Goal | The one outcome, in one sentence | "Find every page in content/guides/ that still quotes a 2025 price." |
| Scope | Exact folders, files or sources, and what's out of bounds | "Only content/guides/. Ignore drafts/ and archive/." |
| What you already know | Decisions from your conversation the subagent can't see | "We've agreed prices must say 'at time of writing'. Don't flag ones that already do." |
| Hands off | What it must not do | "Read only. Don't edit, don't commit." |
| Return shape | The format and length of the answer | "A table: file, line, quoted text. Nothing else. Under 40 rows." |
The fourth line is the one people skip. A subagent can't ask you a follow-up question (the tool for asking is removed from every subagent), so anything ambiguous gets guessed.
| Shape | Use it when | How to ask |
|---|---|---|
| Fan-out | Several independent investigations that don't touch each other | "Using three separate subagents in parallel, audit guides/, reviews/ and news/ with the same Hand-Off Card. Then merge the tables." |
| Relay | Step two depends on step one's output | "Use link-checker to list broken links, then use a general-purpose subagent to propose fixes for the BROKEN ones only." |
| Specialist | One noisy job you want kept out of your main thread | "Use a subagent to run the test suite and report only the failures with their error messages." |
| Fork | The helper would need most of your conversation to be useful | /subtask draft three alternative intros for the guide we've been editing |
To force a particular subagent, type @ and pick it, or type @agent-link-checker. Claude still writes the brief from your message, so the card still matters.
In an interactive session, subagents run in the background by default, in a panel below the prompt: arrow keys to move, Enter to open a transcript, x to stop one. /tasks lists them. Permission requests appear in your main session, labelled with the subagent's name.
Background subagents get a narrower set of built-in tools, which explains most "missing tool" surprises.
link-checker(Audit links in guides).reviews/". Claude resumes the same subagent with its history intact. Explore and Plan are one-off and can't be resumed, so use a custom or general-purpose subagent for anything you'll pick up again.isolation: worktree so each helper gets its own copy of the repository./agents have all changed in recent versions. Check the official page against your claude --version.