Subagents

Subagents are specialized agents that the main agent can delegate tasks to. They have their own system prompts, tool access, and can use different models. This enables focused expertise while preserving the main agent's context.

How It Works

When the main agent encounters a task suited for delegation:

1. It identifies the appropriate subagent based on the task
2. The subagent is spawned with its own context and tools
3. The subagent completes the task and returns results
4. The main agent incorporates the results and continues

Benefits

• Context preservation - Main agent context isn't consumed by specialized tasks
• Focused expertise - Subagents have specialized system prompts
• Different permissions - Subagents can have different tool access
• Model flexibility - Use faster/cheaper models for simple tasks

File Location

Subagents are defined in .claude/agents/:

.claude/
└── agents/
    ├── test-runner.md
    ├── code-reviewer.md
    ├── security-auditor.md
    └── documentation-writer.md

Subagent Structure

Each subagent file defines its configuration:

1# Test Runner
2
3## Description
4Specialist in running and debugging tests. Handles test execution,
5failure analysis, and fix implementation.
6
7## System Prompt
8You are a test automation specialist. Your responsibilities:
9
101. Execute test suites efficiently
112. Analyze test failures thoroughly
123. Identify root causes of failures
134. Implement fixes with minimal changes
145. Verify fixes don't break other tests
15
16Always:
17- Run the full relevant test suite after fixes
18- Explain what caused each failure
19- Document any test environment issues
20
21## Tools
22- Bash
23- Read
24- Write
25- Edit
26
27## Model
28sonnet
29
30## Permission Mode
31default

Configuration Options

System Prompt

The role definition and instructions for the subagent. This shapes its behavior and focus.

Tools

Which tools the subagent can use. Common options:

• Read - Read files
• Write - Create files
• Edit - Modify files
• Bash - Run shell commands
• Glob - Find files by pattern
• Grep - Search file contents

Model

Which AI model to use:

• sonnet - Claude Sonnet (balanced)
• opus - Claude Opus (most capable)
• haiku - Claude Haiku (fastest, cheapest)
• inherit - Use same model as main agent

Permission Mode

Security level for the subagent:

• default - Normal permission checks
• bypassPermissions - Skip permission checks (use with caution)
• planMode - Planning only, no execution

Built-in Subagent Templates

test-runner

Test automation specialist.

• Model: sonnet
• Tools: Bash, Read, Write, Edit
• Focus: Test execution, failure analysis, fixes

code-reviewer

Thorough code review expert.

• Model: sonnet
• Tools: Read, Glob, Grep
• Focus: Quality, patterns, improvements

security-auditor

Security-focused analysis specialist.

• Model: opus (higher capability for security)
• Tools: Read, Glob, Grep, Bash
• Focus: Vulnerabilities, compliance, best practices

documentation-writer

Technical documentation expert.

• Model: sonnet
• Tools: Read, Write, Glob
• Focus: Clear docs, examples, API references

Creating Custom Subagents

Example: Database Migration Subagent

1# Database Migrator
2
3## Description
4Handles database schema changes, migration creation, and data transformations.
5
6## System Prompt
7You are a database migration specialist. Your responsibilities:
8
91. Analyze current schema state
102. Design migration strategies
113. Create forward and rollback migrations
124. Handle data transformations safely
135. Verify migration success
14
15Guidelines:
16- Always create reversible migrations
17- Test migrations on sample data first
18- Document breaking changes
19- Consider performance for large tables
20- Use transactions where possible
21
22## Tools
23- Read
24- Write
25- Bash
26- Grep
27
28## Model
29sonnet
30
31## Permission Mode
32default

Configuration in Agent Workshop

In the Levers Configuration step, the Subagents tab lets you:

• Add from templates - Use pre-built subagent templates
• Create custom - Define your own subagents
• Configure system prompt - Define role and instructions
• Select tools - Choose which tools the subagent can use
• Choose model - Select the AI model
• Set permissions - Configure security level
• Enable/disable - Toggle individual subagents

Best Practices

Keep Subagents Focused

Each subagent should have a clear, narrow focus. Don't create "generalist" subagents that do everything.

Match Model to Task

Use Haiku for simple, fast tasks. Use Opus for complex analysis requiring high capability. Sonnet is a good default.

Minimize Tool Access

Only give subagents the tools they need. A code reviewer doesn't need write access.

Document Delegation Criteria

The description should make clear when to delegate to this subagent.