Sub-Agents

Overview

Subagents are specialized AI assistants in Claude Code that handle task-specific workflows. Each has a specific purpose, custom system prompt, and configurable tool access.

Context Preservation

Separate context windows prevent main conversation pollution

Specialized Expertise

Fine-tuned for specific domains with custom prompts

Reusability

Share across projects and teams via version control

Flexible Permissions

Different tool access levels per subagent

Quick Start

Open the agents management interface with:

/agents

This command lets you:

Create new subagents (project-level or user-level)
Edit existing subagents and their tool permissions
Delete custom subagents
View all subagents (built-in, user, project)

Tip: Generate with Claude first, then customize. Press e to edit the system prompt in your own editor.

Configuration

File Locations

Type	Location	Scope
Project subagents	`.claude/agents/`	Current project (highest priority)
User subagents	`~/.claude/agents/`	All projects
Plugin agents	Plugin's `agents/` directory	Plugin scope

File Format

---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: Read, Grep, Glob, Bash  # Optional - inherits all tools if omitted
model: sonnet  # Optional - 'sonnet', 'opus', 'haiku', or 'inherit'
permissionMode: default  # Optional - default, acceptEdits, bypassPermissions
skills: skill1, skill2  # Optional - auto-load skills
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.

Configuration Fields

Field	Required	Description
`name`	Yes	Unique identifier (lowercase letters and hyphens)
`description`	Yes	Natural language description of purpose
`tools`	No	Comma-separated tool list (inherits all if omitted)
`model`	No	`sonnet`, `opus`, `haiku`, or `inherit`
`skills`	No	Comma-separated skill names to auto-load

Available Tools

Subagents can access any of Claude Code's internal tools:

Read Edit Write Bash Grep Glob

Built-in Agents

General-Purpose Subagent

Model: Sonnet Tools: All Read & Write

Complex, multi-step tasks requiring both exploration and modification. Used when tasks need capable reasoning to interpret results.

Example: "Find all places where we handle authentication and update them to use the new token format"

Plan Subagent

Model: Sonnet Tools: Read, Glob, Grep, Bash Read-only

Research and analysis without modifications. Automatically used in plan mode to gather codebase context before presenting a plan.

Example: Used when Claude is in plan mode and needs to research codebase

Explore Subagent

Model: Haiku (fast) Tools: Glob, Grep, Read, Bash Strictly Read-only

Fast codebase search and analysis. More efficient than main agent doing multiple searches directly.

Thoroughness levels: Quick, Medium, Very thorough

Example Agents

Code Reviewer

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Debugger

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach

Test Writer

---
name: test-writer
description: Test generation specialist. Creates comprehensive test suites with edge cases. Use after implementing new features.
tools: Read, Write, Bash, Grep, Glob
model: sonnet
---

You are a test automation expert specializing in comprehensive test coverage.

When invoked:
1. Analyze the code to be tested
2. Identify all code paths and edge cases
3. Generate test cases with proper mocking
4. Ensure tests are independent and repeatable

Test categories:
- Unit tests for individual functions
- Integration tests for component interactions
- Edge cases and boundary conditions
- Error handling scenarios

Best practices:
- Use descriptive test names
- Follow AAA pattern (Arrange, Act, Assert)
- Mock external dependencies
- Test both success and failure paths

Best Practices

1

Start with Claude-generated agents

Generate initial subagent with Claude, then iterate to personalize

2

Design focused subagents

Single, clear responsibilities (not "do everything" agents)

3

Write detailed prompts

Include specific instructions, examples, and constraints

4

Limit tool access

Grant only necessary tools for the subagent's purpose

5

Version control

Check project subagents into version control for team collaboration

Advanced Usage

Chaining Subagents

> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

Resumable Subagents

Continue previous subagent conversations with full context:

# Initial invocation
> Use the code-analyzer agent to start reviewing the authentication module
[Agent returns agentId: "abc123"]

# Resume the agent
> Resume agent abc123 and now analyze the authorization logic as well
[Agent continues with full context from previous conversation]

CLI-Based Configuration

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

.claude