sub-agents

# Sub-Agents Reference Create specialized AI agents with isolated contexts for specific tasks. ## When to Use - "How do I create a sub-agent?" - "Configure agent tools" - "What built-in agents exist?" - "Agent model selection" - "Agent chaining patterns" ## Quick Start ### Interactive (Recommended) ```bash /agents ``` Opens menu to create, edit, and manage agents. ### Manual Creation ```bash mkdir -p .claude/agents cat > .claude/agents/reviewer.md << 'EOF' --- name: reviewer description: Code review specialist. Use proactively after code changes. tools: Read, Grep, Glob, Bash model: sonnet --- You are a senior code reviewer focusing on quality and security. ## Review Checklist - Code clarity and naming - Error handling - Security vulnerabilities - Test coverage EOF ``` ### CLI-Based ```bash claude --agents '{ "reviewer": { "description": "Code reviewer", "prompt": "Review for quality and security", "tools": ["Read", "Bash"], "model": "sonnet" } }' ``` ## Agent File Format ```yaml --- name: agent-name description: When/why to use this agent tools: Read, Edit, Bash # Optional, inherits all if omitted model: sonnet # sonnet, haiku, claude-opus-4-5-20251101, inherit --- System prompt content here... ``` ## Configuration Fields | Field | Required | Options | |-------|----------|---------| | `name` | Yes | lowercase, hyphens | | `description` | Yes | When to use | | `tools` | No | Tool list (inherits all if omitted) | | `model` | No | `sonnet`, `haiku`, `claude-opus-4-5-20251101`, `inherit` | ## Built-In Agents | Agent | Model | Tools | Purpose | |-------|-------|-------|---------| | General-purpose | Sonnet | All | Complex multi-step tasks | | Plan | Sonnet | Read-only | Plan mode research | | Explore | Haiku | Read-only | Fast codebase search | ## Model Selection | Model | Speed | Best For | |-------|-------|----------| | Haiku | Fastest | Search, quick lookups | | Sonnet | Fast | Most tasks (default) | | Opus | Slower | Complex reasoning | ## Tool Combinations ```yaml # Code Reviewer (read-only) tools: Read, Grep, Glob, Bash # Debugger tools: Read, Edit, Bash, Grep, Glob # Implementer tools: Read, Write, Edit, Bash, Glob ``` ## Example Agents ### Code Reviewer ```yaml --- name: code-reviewer description: Reviews code for quality and security. Use after code changes. tools: Read, Grep, Glob, Bash model: sonnet --- Review code for: - Security vulnerabilities - Code quality issues - Missing error handling - Test coverage gaps Output findings by priority: Critical > Warning > Suggestion ``` ### Debugger ```yaml --- name: debugger description: Debug errors and test failures. tools: Read, Edit, Bash, Grep, Glob model: inherit --- Debugging process: 1. Capture error details 2. Identify failure location 3. Form hypotheses 4. Test and verify 5. Implement fix ``` ## File Locations | Type | Location | Priority | |------|----------|----------| | Project | `.claude/agents/` | Highest | | User | `~/.claude/agents/` | Lower | ## Advanced Patterns ### Resumable Agents ``` [Agent returns agentId: "abc123"] # Later: resume with context claude -r "abc123" "Continue analysis" ``` ### Agent Chaining ``` Use code-analyzer to find issues, then use optimizer to fix them ``` ## Best Practices 1. **Single responsibility** - One clear purpose per agent 2. **Restrict tools** - Only grant what's needed 3. **Clear descriptions** - Action-oriented, include "proactively" 4. **Version control** - Check `.claude/agents/` into git