Give Claude a Teammate: Subagents
On Day 3 we covered the four basics that make everything else click: CLAUDE.md, skills, context, and tools. The most important one was context — everything Claude can see right now. Today we build directly on it. What if a messy side task could happen somewhere else, so your main context stays clean? That is exactly what a subagent does.
What is a subagent?
A subagent is a specialized helper that handles one type of task and reports the result back to you. When Claude hits a task that matches a subagent, it hands the work over, and the subagent works independently and returns only a summary. The key detail is context: each subagent runs in its own context window, with its own tools and its own permissions. So running tests or reading a pile of logs — all that noise stays inside the subagent, and your main chat only gets the clean answer.
How do you create one?
A subagent is just a Markdown file with a little YAML on top. Drop it in .claude/agents/ for one project, or in ~/.claude/agents/ to use it everywhere. You can write it by hand or ask Claude to write it for you. Only two fields are required: name and description. The description is what Claude reads to decide when to delegate, so write it clearly.
---
name: test-runner
description: Runs the test suite and reports only the failing tests. Use proactively after code changes.
tools: Read, Bash, Grep
model: haiku
---
You are a test runner. Run the tests, then report only the failures with their error messages. Keep it short.The frontmatter is where a subagent becomes powerful. A tools list locks it down to exactly what it needs — a read-only researcher gets no Write or Edit. Set the model to a cheaper, faster option like haiku to control cost. And the memory field gives the subagent a persistent folder that survives across sessions, so it remembers patterns and recurring bugs over time.
When one agent is not enough: teams
- A subagent does one focused task and reports a clean summary back to you
- It runs in its own context window, so logs and search noise stay out of your main chat
- You create it as a Markdown file in .claude/agents/ — only name and description are required
- Subagents only report back to you; when workers must talk to each other, a lead coordinates an agent team
Try it: create your first subagent
Enough theory — let us make a real one. We will build a code-reviewer subagent that looks at your recent changes and gives short, useful feedback. Follow these steps in any project.
- 1. In your project root, make the folder .claude/agents/ if it is not there yet.
- 2. Inside it, create a file named code-reviewer.md and add YAML frontmatter on top — name and description are required, tools and model are optional.
- 3. Save the file. Claude Code watches this folder and picks up the new subagent within a few seconds. If the folder did not exist when your session started, restart Claude Code once.
- 4. Now ask Claude to use it — by name, or by @-mention to be sure the right one runs.
---
name: code-reviewer
description: Reviews recent code changes for quality, security, and best practices. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior code reviewer. When invoked, look at the recent changes and give specific, actionable feedback on quality, security, and best practices. For each issue, show the problem and suggest a fix. Keep it short.That description line is the important bit — Claude reads it to decide when to hand work over. Because it says use proactively after code changes, Claude will often reach for this subagent on its own. But you can always call it directly.
Use the code-reviewer subagent to review my recent changesHere is what happens: Claude spins up the subagent in its own context window — you may see it run as a separate task. It reads the changed files, thinks, and does all of that noisy work away from your main chat. When it is done, it returns only a short summary of findings — the issues and suggested fixes — not the full file dumps. Your main context stays clean, which is exactly the point of a subagent.
Next post: hooks — scripts that run automatically on events like before a tool runs.