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

• Single responsibility - One clear purpose per agent

• Restrict tools - Only grant what's needed

• Clear descriptions - Action-oriented, include "proactively"

• Version control - Check .claude/agents/ into git