# Setting Up Claude Code Subagents for Multi-Agent Workflows

## Introduction

The moment your codebase exceeds a few thousand lines, you face a choice: one AI assistant trying to do everything, or multiple specialized agents each handling their own piece. The first option gets expensive and slow. The second mirrors how real engineering teams work.

This guide shows you exactly how to set up Claude Code's subagent system to create multi-agent workflows that scale. You'll learn the commands, proper directory structure, and best practices from real usage.

**What you'll learn:**

*   How to use the `/agents` command
    
*   Creating custom subagents in `claude/agents/`
    
*   Leveraging built-in subagents (Explore, Plan, General)
    
*   When to use Agent Teams (experimental)
    
*   Code examples you can run today
    

## Prerequisites

Before starting, ensure you have:

*   Claude Code installed (v2.1.32+ recommended)
    
*   A project directory where you'll create subagents
    
*   Basic familiarity with YAML frontmatter
    

Installation check:

```bash
claude --version
```

If this returns a version number, you're ready.

## Step 1: Understanding Subagents

Subagents are lightweight, specialized AI assistants that operate within your main Claude Code session. Unlike a single AI that tries to do everything, each subagent excels at specific tasks.

The key benefits:

*   **Task specialization** — Each agent has focused instructions
    
*   **Clean context** — Main session stays uncluttered
    
*   **Parallel capability** — Multiple agents can work simultaneously
    
*   **Reusable** — Custom agents work across projects
    

## Step 2: Using the /agents Command

The main interface for subagent management:

```bash
# Interactive mode - browse and select subagents
claude /agents

# List available subagents without starting session
claude agents
```

For scripted workflows, pass JSON directly:

```bash
claude --agents '[{"name": "Explore", "model": "haiku", "task": "find auth middleware"}]'
```

## Step 3: Creating Custom Subagents

Create subagents in your project's directory:

```bash
mkdir -p .claude/agents/code-reviewer
```

Each subagent needs an file:

```markdown
---
name: code-reviewer
description: Reviews code for security and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer. For each pull request:
1. Identify security vulnerabilities
2. Check for performance issues
3. Verify test coverage
4. Suggest specific fixes

Provide actionable feedback with code examples.
```

The directory structure:

```plaintext
.claude/agents/
├── code-reviewer/agent.md
├── security-auditor/agent.md
└── docs-writer/agent.md
```

Supported YAML fields (confirmed):

*   name (required)
    
*   description (required)
    
*   tools
    
*   model (haiku/sonnet/opus)
    
*   skills
    
*   hooks
    
*   permissionMode
    

## Step 4: Built-in Subagents

Claude Code includes three built-in subagents:

**Explore** (Haiku-powered)

*   Fast code surveys
    
*   Find file locations
    
*   Quick orientation
    

Usage:

```plaintext
Use Explore to find authentication middleware in this codebase
```

**Plan**

*   Structured thinking for features
    
*   Break down complex tasks
    
*   Identify dependencies
    

Usage:

```plaintext
Use Plan to outline a user authentication system
```

**General**

*   Flexible for varied tasks
    
*   Write code, refactor, test
    

Usage:

```plaintext
Use General to write tests for the auth module
```

## Step 5: Agent Teams (Experimental)

For advanced scenarios, Agent Teams lets multiple subagents collaborate:

```json
// settings.json
{
  "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": 1
}
```

**Warning:** This feature is experimental. Don't rely on it for production workflows.

## Step 6: Adding MCP Servers (Optional)

MCP servers extend Claude's capabilities:

```bash
claude mcp add github
claude mcp list
claude mcp remove github
```

This is secondary to the core subagent system.

## Code Examples

Here are verified working examples:

```bash
# 1. List all subagents
claude agents

# 2. Create project subagent directory
mkdir -p .claude/agents/security-reviewer

# 3. Create agent.md file
cat > .claude/agents/security-reviewer/agent.md << 'EOF'
---
name: security-reviewer
description: Security audit specialist
tools: Read, Glob, Grep
model: sonnet
---
You are a security auditor. Find vulnerabilities in the code.
EOF

# 4. Use subagent in conversation
"Use security-reviewer to audit the auth module"
```

## Troubleshooting

**Subagent not found**

*   Verify directory:
    
*   Check agent.md file exists
    
*   Restart Claude Code session
    

**Tools not working**

*   Verify tools field in YAML
    
*   Some tools require specific permissions
    

**Agent Teams not working**

*   Requires experimental flag enabled
    
*   May need v2.1.32+