A subagent is a separate Claude with its own context window. It’s great for work that’s independent of your main thread — searching the codebase, reviewing a diff, or running several tasks at once — without cluttering your main conversation.
Use the built-in ones
Just ask. Claude Code dispatches subagents when it helps:
Use subagents to find every place we call the old `fetchUser` API.
For independent tasks, ask it to run them in parallel:
In parallel, write tests for the auth module and the billing module.
Make your own subagent
Create .claude/agents/<name>.md with frontmatter and a system prompt:
---
name: test-writer
description: Writes focused unit tests for a given file.
tools: Read, Write, Bash
---
You write minimal, behavior-focused unit tests. Match the project's test style.
Run the tests and make sure they pass before finishing.
Now Claude can hand test-writing to that agent (or you can ask for it by name).
When to use them
- Yes: broad searches, parallel independent tasks, focused reviews, anything you want kept out of the main context.
- No: tightly coupled steps that need shared state — keep those in the main thread.
Next: automate actions with hooks.