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)

/agents

Opens menu to create, edit, and manage agents.

Manual Creation

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

claude --agents '{
  "reviewer": {
    "description": "Code reviewer",
    "prompt": "Review for quality and security",
    "tools": ["Read", "Bash"],
    "model": "sonnet"
  }
}'

Agent File Format

---
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

# 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

---
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

---
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