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:

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:

# Interactive mode - browse and select subagents
claude /agents

# List available subagents without starting session
claude agents

For scripted workflows, pass JSON directly:

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

Step 3: Creating Custom Subagents

Create subagents in your project's directory:

mkdir -p .claude/agents/code-reviewer

Each subagent needs an file:

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

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

Use Explore to find authentication middleware in this codebase

Plan

• Structured thinking for features

• Break down complex tasks

• Identify dependencies

Usage:

Use Plan to outline a user authentication system

General

• Flexible for varied tasks

• Write code, refactor, test

Usage:

Use General to write tests for the auth module

Step 5: Agent Teams (Experimental)

For advanced scenarios, Agent Teams lets multiple subagents collaborate:

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

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:

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