Claude Code Subagents: Guide, Templates, and Generator

Feature Comparison

What Are Claude Code Subagents?

Claude Code subagents are named specialist agents that Claude can delegate to for focused work. Each subagent can have a description, system prompt, allowed tools, model choice, and separate context window so the main session stays cleaner.

• Project subagents live in .claude/agents/ and can be shared with a repository.
• Personal subagents live in ~/.claude/agents/ and are available across projects.
• A subagent file uses YAML frontmatter plus Markdown instructions.
• Claude Code can choose subagents automatically from the description, or a user can request one directly.

Official And Community Resources

Use official docs for syntax and lifecycle behavior, then adapt community templates only after reviewing permissions and prompts.

When To Use Subagents

Use subagents when the work is separable, specialized, or repeated often enough to justify a durable role. Keep simple one-file edits in the main session.

• Use a research subagent for docs, code search, and dependency investigation.
• Use a reviewer subagent for focused risk review after implementation.
• Use a test fixer when test failures need a separate diagnosis loop.
• Use a migration planner before large package moves or framework upgrades.
• Use a security reviewer when auth, permissions, secrets, or tool access changes.

20 Common Subagent Templates

The generator below includes these 20 high-use templates for Claude Code teams.

• code-reviewer, test-writer, bug-hunter, frontend-implementer, api-integrator
• database-migration-planner, security-reviewer, performance-profiler, docs-writer, release-notes-writer
• dependency-upgrader, refactor-planner, mcp-config-reviewer, prompt-engineer, qa-scenario-builder
• monorepo-coordinator, design-implementation-auditor, incident-investigator, data-analyst, localization-reviewer

Copyable Markdown Subagent

Start with a small, explicit subagent. The description should explain when Claude should choose it, and the prompt should define scope, output, and validation.

---
name: code-reviewer
description: Review diffs for correctness, security, regressions, and missing tests.
tools: Read, Grep, Glob, Bash(git diff *)
model: sonnet
---

Inspect the current diff. Return findings first with file and line references, then list test gaps and residual risks.

## Output

- Findings ordered by severity.
- File and line references where possible.
- Validation commands checked or still needed.

Copyable YAML Variant

YAML is useful when documenting an internal subagent catalog before converting each role into .md files.

name: security-reviewer
description: Check auth, secrets, injection, SSRF, file access, and unsafe tool use.
tools: Read, Grep, Glob, Bash(git diff *)
model: opus
instructions: |
  Focus on exploitable paths and concrete mitigations.
  Do not over-report generic best practices.

Project Configuration Pattern

For a team, commit reviewed project subagents and link them from CLAUDE.md so developers know which roles exist.

.claude/
  agents/
    code-reviewer.md
    test-writer.md
    mcp-config-reviewer.md
CLAUDE.md

# CLAUDE.md note
Use the code-reviewer subagent for PR-risk review and the test-writer subagent when behavior changes need coverage.

Subagents, Hooks, MCP, And Worktrees

Subagents pair well with hooks, MCP, and isolated worktrees, but each layer needs a clear boundary.

• Hooks run deterministic lifecycle commands; subagents perform reasoning or specialist review.
• MCP gives a subagent external context such as GitHub, docs, browser, or database access.
• Worktree isolation helps when multiple agents need to modify separate branches or tasks.
• Tool restrictions should be narrow for reviewers, security agents, and docs agents.

Common Mistakes

Subagents become noisy when roles overlap, tools are too broad, or no one owns final integration.

• Avoid asking multiple subagents to edit the same files at the same time.
• Avoid vague prompts such as be helpful or write clean code.
• Avoid broad Bash access for review-only agents.
• Keep one main agent responsible for merging results and running final checks.

FAQ