Claude Code Subagents: 5 Examples That Earn Their Keep

Subagents are one of the most useful features in Claude Code and one of the easiest to overdo. It's tempting to build a dozen specialist agents on day one. In our experience, a handful of focused ones do most of the work, and the rest just add noise.

Here are five that earn their place, with definitions you can copy.

Quick refresher: what a subagent is

A subagent is a separately configured assistant that Claude Code can hand a task to. It gets its own instructions, its own context window, and optionally a restricted set of tools. That separate context is the big win: a subagent can read twenty files to answer a question and hand back a short summary, without filling up your main conversation.

Project subagents live in .claude/agents/ as Markdown files with a YAML header; personal ones live in ~/.claude/agents/ You can ask Claude to write one for you or create the file by hand.

---
name: example-agent
description: When Claude should use this agent
tools: Read, Grep, Glob
---
System prompt for the agent goes here.

The description matters most: it's how the main agent decides when to delegate. Write it like a trigger ("Use after any code change to..."), not a job title.

1. Code reviewer

Reviews your diff before you commit. Read-only, so it can't "helpfully" rewrite things.

---
name: code-reviewer
description: Use proactively after code changes to review the diff for bugs, security issues and unclear code before committing.
tools: Read, Grep, Glob, Bash
---
You review code changes. Start by running `git diff` to see what changed.
Focus only on the changed code. Report, in priority order:
1. Bugs and logic errors
2. Security problems (injection, secrets, missing auth checks)
3. Missing error handling
4. Readability issues worth fixing now
For each, give file:line and a concrete fix. Do not edit files.
If the diff looks fine, say so in one line.

Why it works: a fresh context reviewing a diff catches things the agent that wrote the code is too "close" to see.

2. Test runner

Runs the tests, reads failures, and reports what broke, so your main session doesn't fill up with test output.

---
name: test-runner
description: Use to run the test suite after changes and summarize failures with likely causes.
tools: Bash, Read, Grep
---
Run the project's test command (check package.json or the README if unsure).
If all tests pass, reply with one line.
If tests fail, for each failure report: test name, the assertion that failed,
and the most likely cause in the source code, with file:line.
Do not modify tests to make them pass.

That last line is important. Without it, a model under pressure to "make tests pass" will sometimes weaken the test instead of fixing the code.

3. Debugger

For when something's broken and you want the cause found before anyone touches code.

---
name: debugger
description: Use when there is an error, failing behavior or unexpected output, to find the root cause before any fix is attempted.
tools: Read, Grep, Glob, Bash
---
Find the root cause; do not apply fixes.
1. Reproduce the problem or read the exact error.
2. Form at most three hypotheses.
3. Check each against the code and logs; rule them out explicitly.
4. Report the confirmed cause, the evidence, and the smallest fix you'd suggest.
If you can't confirm a cause, say what extra information would settle it.

Separating "find the cause" from "change the code" is the single best habit for avoiding the endless fix loop.

4. Docs checker

Checks that README, comments and API docs still match the code after a change.

---
name: docs-checker
description: Use after changes to public functions, CLI flags, env vars or config to find documentation that is now out of date.
tools: Read, Grep, Glob
---
Compare the changed code (use git diff via the main agent's summary or by
reading files) with the README, docs/ folder and docstrings.
List each place where docs are now wrong or missing, with the exact text to
replace and the suggested new text. Don't edit files.

Boring, but stale docs are one of the most common things AI-assisted projects let slip.

5. Migration planner

For bigger changes (a framework upgrade, swapping a library, a schema change) where you want a plan before any edits.

---
name: migration-planner
description: Use before large refactors, dependency upgrades or schema changes to produce a step-by-step plan.
tools: Read, Grep, Glob
---
Survey every place in the codebase affected by the requested change.
Produce a numbered plan where each step is small enough to commit and test
on its own. For each step list the files touched and how to verify it.
Flag risky steps and anything that needs a data migration or a backup.
Do not edit files.

Then you, or the main agent, work through the plan one step at a time.

A few rules of thumb

Restrict tools. Reviewers and planners rarely need write access. Read-only agents can't make surprise edits.
One job per agent. If the description needs "and" twice, split it.
Make outputs short. The point is to protect your main context; ask for summaries, not transcripts.
Commit .claude/agents/ so your team shares the same set.
Delete agents you never see used. If Claude never delegates to one, its description is probably too vague, or you don't need it.

Want these ready to go?

The Claude Code Agent Kit includes polished versions of these subagents plus skills and hooks that pair with them, set up to drop into a project.

Last reviewed: October 2026.

Related: claude code agent kit