Menu
Specialized AI assistants for task-specific workflows with separate context. Learn when to delegate, configure tools, and apply best practices.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | Subagents Guide |
| description | Specialized AI assistants for task-specific workflows with separate context. Learn when to delegate, configure tools, and apply best practices. |
| allowed-tools | Read, Glob, Grep, Bash |
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
Defines required structure, frontmatter format, and best practices for SKILL.md files. Use BEFORE creating or editing any skill - this is the spec to follow, not optional reference.
Diagnose and fix bugs through systematic investigation, root cause analysis, and targeted validation. Use when something is broken, errors occur, performance degrades, or unexpected behavior manifests.
Systematically evaluate code changes for security, correctness, performance, and spec alignment. Use when reviewing PRs, assessing code quality, or verifying implementation against requirements.
Maintain project documentation synchronized with code. Keep feature specs, API contracts, and README current with init-project standards. Use when updating docs after code changes, adding new features, or ensuring documentation completeness.
Systematically trace code flows, locate implementations, diagnose performance issues, and map system architecture. Use when understanding how existing systems work, researching concepts, exploring code structure, or answering "how/where/why is X implemented?" questions.
Coordinate concurrent task execution through agent delegation. Plan independent work, manage dependencies, and execute multiple agents simultaneously. Use when handling multiple unrelated tasks, research investigations, or layer-based implementations that can run concurrently.