Claude Code Subagents: 5 Examples to Copy and Why Yours Don't Run

Published 2026-10-21 · 6 min read · by AgentKit Co

A Claude Code subagent is a Markdown file that defines a helper with its own system prompt, its own tool list and, if you want, its own model. When a task matches the subagent's description, Claude hands the task to it. The subagent works in a separate context window and sends back a summary, so the search results, logs or test output it read never fill up your main conversation.

This page gives five subagent files you can paste today, explains where to put them, and lists the usual reasons Claude ignores a subagent you wrote. Everything here was checked against Anthropic's subagents documentation on 2026-10-21. Claude Code changes quickly, so re-check the docs for anything you rely on.

Where subagent files go

If two subagents share a name, the docs give the session --agents flag priority over project files, project files priority over your user folder, and your user folder priority over plugins. Both agent folders are scanned recursively, so subfolders like agents/review/ are fine; identity comes only from the name field.

The file format in 20 seconds

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and give
specific, actionable feedback on quality, security and best practices.

Only name and description are required. tools is an allowlist; leave it out and the subagent inherits every tool available to subagents. model accepts sonnet, opus, haiku, a full model ID, or inherit. The text after the closing --- becomes the subagent's system prompt. The docs note that a subagent gets only this prompt plus basic environment details, not the full Claude Code system prompt, so write it like a complete brief.

Example 1: a read-only code reviewer

---
name: code-reviewer
description: Reviews the current diff for bugs, missing tests and risky changes. Use after writing or modifying code, before committing.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Review only what changed. Start with `git diff` (and `git diff --staged`).
For each finding give: file:line, severity (bug / risk / nit), what is wrong,
and the smallest fix. Flag missing or weakened tests. Do not edit files.
If the diff is clean, say so in one line instead of inventing issues.

The description says when to use it ("after writing or modifying code"), which is what Claude matches on. Bash is included so it can run git diff; if you'd rather it couldn't run commands at all, drop Bash and paste the diff into your request.

Example 2: a cheap Haiku explorer

---
name: explorer-haiku
description: Fast, low-cost read-only codebase search. Use proactively for "where is X defined/used" lookups instead of reading many files in the main conversation.
tools: Read, Grep, Glob
model: haiku
---

Search narrowly: Glob for file names, Grep for symbols. Read only the line
ranges you need. Answer in 1 to 3 sentences, then list key locations as
path:line with one line each. Keep the reply under about 40 lines.

This is the subagent that saves the most context. Lookups that would otherwise drag a dozen files into your main session come back as a short list. The docs also mention that a user or project subagent named Explore replaces the built-in Explore agent and keeps its own model, so you can create one called Explore with model: haiku if you want every built-in exploration to use Haiku.

Example 3: a test runner that returns only failures

---
name: test-runner
description: Runs the test suite (or a subset) and reports only the failures. Use whenever tests need to be run.
tools: Bash, Read, Grep
model: haiku
---

Find the project's test command (package.json scripts, Makefile, pyproject).
Run it. Report: the exact command, pass/fail counts, and for each failure
the test name, the assertion message and the file:line. Never paste full
logs. Do not change any files.

Full test output is one of the fastest ways to fill a context window. Here the subagent reads all of it and passes back a few lines.

Example 4: a researcher that can't write

---
name: safe-researcher
description: Researches how something works in this repo or its dependencies without changing anything.
disallowedTools: Write, Edit
---

Answer the question with evidence: quote the relevant code with file:line.
Say clearly what you could not confirm.

This one uses disallowedTools instead of tools: it keeps everything it would inherit (Bash, MCP tools and so on) except file writes. If you set both fields, the docs say disallowedTools is applied first and tools is then resolved against what's left.

Example 5: a CI failure investigator

---
name: ci-failure-investigator
description: Investigates a failing CI run or pasted CI log and finds the first real error. Use when a pipeline fails.
tools: Read, Grep, Glob, Bash
---

Find the first error, not the last one; later failures are often fallout.
Say whether it reproduces locally (run the same command if it's safe and
cheap). Report: the failing step, the root error line, the likely cause,
and the smallest fix. Do not push, re-run pipelines or change CI config.

Why Claude ignores your subagent

1. The description is vague. Claude decides whether to delegate based on the description. "Helps with tests" rarely triggers; "Runs the test suite and reports only failures. Use whenever tests need to be run." does. Phrases like "use proactively" or "use after modifying code" give Claude a trigger.
2. You expected it to run on its own every time. Automatic delegation is a judgment call. To force it, @-mention it: type @ and pick it from the list, or type @agent-test-runner. You can also say "Use the test-runner subagent to..." in plain words, or start a whole session as that agent with claude --agent test-runner.
3. The frontmatter doesn't parse or a field is misspelled. Field names are camelCase (disallowedTools, maxTurns) and the docs say Claude Code silently ignores fields it doesn't recognize. Running claude plugin validate .claude/agents reports files whose frontmatter doesn't parse (it needs a recent Claude Code version).
4. Two files share a name. In the same folder tree only one loads, and the docs say which one is chosen by file read order, not a documented rule. /doctor reports duplicates.
5. The tools list resolves to nothing. If every entry is misspelled, Claude Code usually refuses to launch the subagent and the error names the bad entries.
6. You created ~/.claude/agents/ mid-session. The docs say a running session doesn't notice a newly created agents directory, so restart Claude Code once. Edits to files in folders it already watches are picked up within a few seconds.
7. Too many long descriptions. Every custom subagent's description sits in context. Above 15,000 tokens combined, Claude Code warns at startup. Keep descriptions to a sentence or two and put the detail in the body, which loads only when the subagent runs.

Things worth knowing before you add ten of them

• Subagents make their own requests, and the docs say those count toward the same usage limits as your main conversation. A Haiku subagent is cheaper per token, but it isn't free.
• Plugin subagents ignore the hooks, mcpServers and permissionMode fields for security reasons. Copy the file into .claude/agents/ if you need them.
• Custom subagents still load your CLAUDE.md unless you set omitClaudeMd: true, so a short, accurate project file helps every subagent too. Our free AGENTS.md generator writes one, plus a CLAUDE.md that imports it.

Subagents pair well with commands you start yourself: see 8 Claude Code custom slash command examples, including one that hands a review to a forked Explore subagent.

Want these already written? The Claude Code Subagent Pack ($29, 30-day refund) has 18 subagents in folders like the ones above (review, testing, debugging, code changes, research, docs), an installer that skips files you already have unless you pass --force, a format checker and a 16-page guide.

Keep reading