Specialized AI assistants for task-specific workflows with separate context. Learn when to delegate, configure tools, and apply best practices.
Subagents are pre-configured AI personalities that Claude Code delegates to handle specific task types. Each operates independently with:
| Benefit | Impact |
|---|---|
| Context Preservation | Main thread stays focused; subagent pollution isolated |
| Specialized Expertise | Domain-tuned instructions improve success rates |
| Flexible Permissions | Grant only necessary tools to each subagent |
| Reusability | One config used across projects and teams |
Delegate when:
Don't delegate:
# Open subagents interface (Recommended approach)
/agents
# Or create manually: project subagents go here
mkdir -p .claude/agents
# User subagents (available everywhere)
mkdir -p ~/.claude/agents
Steps:
/agents commandSubagents are Markdown files with YAML frontmatter:
---
name: subagent-name
description: When this subagent should be used and its expertise area
tools: Read, Write, Bash # Optional — inherit all if omitted
model: sonnet # Optional — sonnet, opus, haiku, or 'inherit'
---
Your system prompt goes here. Define role, capabilities, constraints,
and specific instructions. Include examples, checklists, and best practices.
| Field | Required | Notes |
|---|---|---|
name |
✓ | lowercase, hyphens only; used for invocation |
description |
✓ | Natural language; used for auto-delegation. Use "proactively" to trigger automatic use |
tools |
— | Comma-separated list. Omit to inherit all tools from main thread |
model |
— | sonnet (default), opus, haiku, or 'inherit' for consistency |
| Type | Location | Scope | Priority |
|---|---|---|---|
| Project | .claude/agents/ |
This project only | Higher |
| User | ~/.claude/agents/ |
All projects | Lower |
Project subagents override user-level ones with the same name.
Principle: Least Privilege
Only grant tools necessary for the subagent's purpose. This:
Common tool combinations:
# Code reviewer
tools: Read, Grep, Glob, Bash
# Data analyst
tools: Read, Write, Bash
# Test automation
tools: Bash, Read, Edit, Write
# Debugger
tools: Read, Edit, Bash, Grep, Glob
# Documentation writer
tools: Read, Write, Glob, Grep
Omit tools to let subagent inherit all (including MCP tools).
Claude Code proactively delegates when:
description field matches contextTo encourage automatic use, include "proactively" in description:
description: Use proactively to run tests and fix failures
Request a subagent directly:
Use the code-reviewer subagent to check my recent changes
Have the debugger investigate this test failure
Ask the data-scientist subagent for a SQL analysis
---
name: code-reviewer
description: Expert code review specialist. Use proactively after writing code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked, run git diff to identify recent changes and review modified files.
Review checklist:
- Readability and naming
- No duplicated code
- Proper error handling
- No exposed secrets
- Input validation implemented
- Test coverage adequate
- Performance considerations addressed
Organize feedback by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
Include specific examples for all recommendations.
---
name: test-runner
description: Test automation expert. Use proactively to run tests and fix failures.
tools: Bash, Read, Edit
---
You are a test automation specialist. When you see code changes, proactively run appropriate tests.
If tests fail:
1. Analyze failure messages and logs
2. Identify root cause
3. Fix the issue while preserving test intent
4. Re-run tests to confirm
For each failure, provide:
- Root cause explanation
- Code fix
- Prevention recommendations
Focus on fixing the underlying issue, not just symptoms.
---
name: debugger
description: Debugging specialist. Use proactively when encountering errors or unexpected behavior.
tools: Read, Edit, Bash, Grep, Glob
---
You are an expert debugger specializing in root cause analysis.
Debugging process:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works
For each issue, provide:
- Root cause explanation with evidence
- Specific code fix
- Testing approach
- Prevention recommendations
Focus on fixing the underlying issue, not just symptoms.
Design focused subagents
Write detailed system prompts
Limit tool access intentionally
Start with Claude-generated agents
Version control project subagents
.claude/agents/ into gitUse specific descriptions for auto-delegation
For complex workflows, sequence multiple subagents:
> First use the code-analyzer subagent to find performance issues,
then use the optimizer subagent to fix them
Each subagent completes its work, then the next is invoked with its results.
Latency trade-off:
When to use subagents: Substantial work, deep investigation, complex logic, long tasks When to skip: Quick edits (≤3 files), rapid iteration, simple clarifications
/agents Command (Recommended)/agents
Provides interactive interface to:
Create project subagent:
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
name: test-runner
description: Use proactively to run tests and fix failures
---
[Your system prompt here]
EOF
Create user subagent:
mkdir -p ~/.claude/agents
# Create file same way as project subagent
