Claude Code Subagents Examples: When to Delegate a Task
Claude Code subagents examples from a real repo: what a subagent sees, the name, description and tools fields, when to delegate, and safe parallel fan-out.
By Matthews WongReviewed on Checked against Claude Code v2.1.296
Key takeaway
A Claude Code subagent is a helper that runs a side task in its own context window and hands back only a summary. You define one as a Markdown file in .claude/agents/ with a name, a description that tells Claude when to delegate, and an optional tools list. Delegate noisy, self-contained work; keep back-and-forth and shared files in the main session.
You will be able to
- Write a subagent file with name, description and tools, and predict what it sees when it starts.
- Decide when a task belongs in a subagent and when it belongs in the main conversation.
- Fan work out to parallel subagents without two of them writing the same file.
Step through the diagram
Press Play, or step with the arrows. Every step is written out below the diagram.
How a subagent takes a task and hands back a summary
Claude matches a request to a subagent's description, the subagent works in its own context window, only its report returns to your context, parallel subagents fan out, and one writer merges the shared files.
Reviewed on 13 October 2026 · Claude Code v2.1.296
Keys: ← → step · Home / End · K play or pause
The main session is you and Claude. A Markdown file in .claude/agents/ defines a subagent; every copy Claude spawns works in a fresh context window of its own.
Claude sees each subagent's name and description, not its body. When your request matches a description, Claude hands the work to that subagent.
name: blog-post-author description: Use this agent to research and draft ONE complete bilingual blog post …Predict the next step Claude spawns the subagent. Does it see your conversation? (Yes, the whole conversation so far · No, only its prompt, CLAUDE.md and the task)Claude writes a task message and spawns the subagent. It starts with its own prompt, the CLAUDE.md files and a git snapshot, but none of your conversation.
Every file read, search and draft lands in the subagent's window, not yours. Its tools line is an allowlist: it can use those tools and nothing else.
tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetchWhen it finishes, only its final report comes back. Your context grows by one summary, not by every file the subagent opened along the way.
Return a compact report, not the article textIndependent tasks fan out to parallel subagents. Each one sends its own requests against the same usage limits, so this repo works in batches of five.
Predict the next step Three subagents need keys in messages/en.json. Who writes the file? (Only the main session, one at a time · Each subagent, as soon as it finishes)Each subagent writes only its own staging folder. The main session alone merges those folders into the shared message files, one at a time, then validates.
node scripts/merge-blog-staging.mjs
What does a Claude Code subagent actually see?
A subagent is a separate worker inside your session. It gets its own context window, its own system prompt and its own tool list, and when it finishes only its final report comes back to the main conversation. That is the whole point: a side task that would flood your context with search results, logs or file contents runs somewhere else.
Read more (2)Show less
It starts nearly blank. A custom subagent receives the body of its file as its system prompt, the task message Claude writes when it delegates, every CLAUDE.md file your session loads, a git status snapshot and any skills its definition preloads. It does not see your conversation, the skills you already invoked, the files Claude already read or your auto memory. This repo writes its hard boundaries into the agent file for exactly that reason: the subagent never saw the chat where you explained them.
The one exception is a fork. /subtask starts a subagent that inherits the whole conversation, which saves re-explaining but gives up the clean start. Its own tool calls still stay out of your context, and only its result comes back.
How do you write a subagent file with name, description and tools?
A subagent is one Markdown file: YAML frontmatter, then the system prompt. Put it in .claude/agents/ to share it with your team through git, or in ~/.claude/agents/ to use it in every project. Only name and description are required. Claude decides when to delegate by reading the description, so write it as a trigger: what the agent does and when to use it. Descriptions take up context, so keep them short and put the detail in the body, which loads only when the subagent runs.
Read more (2)Show less
tools is an allowlist. Leave it out and the subagent inherits every tool available to subagents; list a few and it gets those and nothing else, while disallowedTools removes tools instead. model accepts sonnet, opus, haiku, fable, a full model ID or inherit. When Claude passes a model for one call, that wins; then the frontmatter; then the CLAUDE_CODE_SUBAGENT_MODEL variable; then the main conversation's model.
Creating one is now a conversation or a file edit. Since v2.1.198, /agents only prints a reminder to ask Claude or to edit .claude/agents/ directly, so tutorials that show a creation wizard describe an older release. Claude Code watches the agents folders and picks up a new or changed file within seconds, unless that folder did not exist when the session started.
When should you delegate a task to a subagent?
Delegate when the work is noisy, self-contained and can end in a summary: running a test suite, digging through logs, researching several modules, drafting one complete document. Delegate when you want hard limits on what the worker may touch. In this repo, drafting a blog post has exactly that shape: lots of reading and source checking, one bundle of files out, one short report back.
Read more (1)Show less
Keep the work in the main conversation when it needs back-and-forth, when planning, building and testing share a lot of context, when the change is small and targeted, or when latency matters, because a fresh subagent has to gather its own context first. For a question about something already in the session, /btw answers from the current context with no tools and adds nothing to history. And a reusable procedure that should run in your main context is a skill, not a subagent.
How do you run Claude Code subagents in parallel without collisions?
Claude can run several subagents at once, and in an interactive session they run in the background while you keep working; /tasks lists them. The hard ceiling is generous: by default, spawning a 21st concurrent subagent fails with Concurrent subagent limit reached, and nesting stops three layers down. The real limit is usage. Every subagent sends its own requests against the same usage limits as your main session, and every report it returns lands in your context.
Read more (2)Show less
Collisions come from shared files, not from the number of agents. This repo settled on four rules. Give each agent its own output folder, which the per-post validator enforces by rejecting a folder with more than one entry. Let only the main session write shared files such as messages/en.json and messages/id.json. Merge when the completion notification arrives, not when files first appear. And when an agent stops early, resume it instead of starting over, because a resumed subagent keeps its full history.
Isolation has edges too. isolation: worktree gives a subagent its own checkout of the repository, but a temp folder outside the repo is still shared. And /rewind usually does not restore a subagent's edits, so commit before a fan-out and let git be the undo.
The real config behind this lesson
Excerpts from the repository that builds and deploys this website, quoted as they are.
---
name: blog-post-author
description: Use this agent to research and draft ONE complete bilingual blog post for this repository as a staged, validated bundle — the article component plus the EN and ID fragments, the registry entry with SEO meta, and five bilingual FAQs. Dispatch it when the user asks for a new post, a batch of posts (one agent per post, run them in parallel), or a rewrite of an existing post's content. It stages and self-validates but deliberately does NOT merge, generate covers, or commit — the main session owns those steps. Examples: "write a post about Postgres advisory locks", "draft five posts on Bluetooth printing", "rewrite the ERP approval post with real numbers".
tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
model: inherit
---This repo's only custom subagent. The description reads as a trigger list and states the boundary up front: it stages and validates, the main session merges and commits. The tools line has no Agent entry, so it cannot spawn subagents of its own, and model: inherit keeps it on whatever model the main session runs.
# Boundaries
- **Do not** run `merge-blog-staging.mjs`, `merge-blog-faqs.mjs`, or any git
command. The main session merges, generates covers, builds and commits.
- **Do not** edit `messages/en.json`, `messages/id.json`, `lib/blog-*.ts` or
`[slug]/page.tsx` — the merge script owns those six files.
- **Do not** fetch or add images. Report what figure would help and where; the
main session sources or draws it.The single-writer rule, written into the agent's own prompt because a subagent never sees the conversation where you explained it. Every file that several posts touch belongs to the merge script, and only the main session runs that script.
## Batching many posts
Batches of five work well. Beyond that a single validation failure costs too
much rework.
- **One folder per post**, named for the slug: `agent-epson-escpos`,
`agent-flutter-permissions`, … The merge reads every `agent-*` folder, so five
folders is still one merge — and each post keeps its per-post validation.Where the batch size comes from. Five folders still make one merge, and each post keeps its own validation, so one bad draft costs one folder of rework instead of a whole batch.
Mistakes that cost real time
Two agents writing one shared file
messages/en.json and messages/id.json must keep identical key trees. Parallel writers overwrite each other's keys, and the damage shows up later as a build error that is hard to trace. Each agent stages its keys in its own folder; the main session writes them, one bundle at a time.
Fanning out as wide as the tool allows
The concurrent limit is twenty, but usage runs out first. When this repo once launched about twenty research-heavy agents together, most were cut off by the usage limit mid-write and their half-finished work had to be redone. Batches of four or five finish.
A shared temp folder gets clobbered
Even inside the batch size, three agents once deleted each other's staged files in a shared temp directory. Copy each bundle somewhere safe the moment its agent reports, and validate again right before merging. isolation: worktree would not have helped: it isolates the repository, not the temp folder.
Expecting /rewind to undo a subagent
Checkpoints track the main session's file edits. A background subagent's edits are not restored by /rewind, and neither are changes made through Bash. Commit before a fan-out and revert with git.
What I'd change here: a long description
The blog-post-author description runs to about 660 characters. The docs ask for short descriptions, because every one sits in context and Claude Code warns when they pass 15,000 tokens combined. With one agent it costs little; the next agent this repo adds gets a two-line description and keeps the detail in its body.
| Main conversation | Subagent | Fork (/subtask) | |
|---|---|---|---|
| Starts with | Everything so far | Its prompt, CLAUDE.md, a git snapshot, the task | A copy of the whole conversation |
| Adds to your context | Every read and every output | One final report | One final result |
| Best for | Back-and-forth, small targeted edits | Noisy, self-contained work with a summary | Side tasks that need all the background |
| /rewind restores its edits | Yes, file-tool edits | No: use git | No: use git |
Do it on your own machine
You need Claude Code and a git repository with a few folders of Markdown files. You will write one subagent, run it alone, fan it out, and keep the shared report with the main session.
Create .claude/agents/link-checker.md. The description says when to use it, the tools line leaves out Edit and Write, and the body fixes the one place it may write.
--- name: link-checker description: Checks every external link in ONE folder of Markdown files and reports broken ones. Use for link audits. tools: Read, Grep, Glob, Bash model: inherit --- You check links in exactly one folder, named in the task. Write results only to reports/links-FOLDER.json, where FOLDER is that folder's name. Never edit the Markdown files. Return the number of links checked and each broken link with its HTTP status, nothing else.Ask for one run and watch it in the panel below the prompt. Then run /context: your conversation grew by the report, not by every page it fetched.
Use the link-checker subagent to check docs/guides /contextFan out: three folders, three subagents. Open /tasks while they run.
Run three link-checker subagents in parallel, one each for docs/guides, docs/api and docs/blog /tasksKeep the shared file with the main session: ask Claude to merge the three reports itself, then check that no subagent touched reports/links.json.
Merge reports/links-*.json into reports/links.json yourself. Do not delegate this step.Resume instead of re-running: ask a finished checker for more work and notice that it continues with its history instead of starting over.
Continue that docs/guides link check and also list any redirects
Three questions before you move on
Pick an answer to see why it is right or wrong. Nothing is saved or graded, so guess freely.
Answer in your head, then check
1.What does a custom subagent not see when it starts?Show the answer
Answer:Your conversation, the skills you already invoked, the files Claude already read and your auto memory. It does get its own prompt, Claude's task message, your CLAUDE.md files, a git status snapshot and any preloaded skills.
2.The default concurrent limit is 20. Why does this repo run batches of five?Show the answer
Answer:Every subagent spends from the same usage limits as your main session, and every report lands in your context. A wide wave that hits the limit mid-write leaves partial work to redo, and beyond five a single validation failure costs too much rework.
3.Two subagents both need to add keys to messages/en.json. What is the safe design?Show the answer
Answer:Neither writes it. Each stages its keys in its own folder, and the main session merges them one at a time, then validates. One writer per shared file.
4.You type /agents expecting a creation wizard. What happens in current versions?Show the answer
Answer:Since v2.1.198 it only prints a reminder to ask Claude to create or manage subagents, or to edit .claude/agents/ or ~/.claude/agents/ directly. Describe the subagent you want, or write the file yourself.
Related deep dives on this site
Sources
Primary sources checked on the research date. Follow them for the current version.
- Claude Code docs: Create custom subagents
- Claude Code docs: Subagent frontmatter reference
- Claude Code docs: What loads when a subagent starts
- Claude Code docs: Choose between subagents and the main conversation
- Claude Code docs: Concurrent subagent limit
- Claude Code docs: Resume subagents
- Claude Code docs: Commands reference (/agents, /tasks, /subtask, /btw)
- Claude Code docs: Subagent edits are not restored by rewind
- Claude Code docs: Use subagents for investigation
- Claude Code docs in Indonesian: subagents