👥 AI Agent Teams — Multiple Claudes Working Together

What Is a Sub-Agent? — Delegating Work to Team Members

A team lead doesn’t do everything alone, right? Simple tasks get delegated: “handle this and just give me the result.” Meanwhile, the lead works on other things.

Claude Code works the same way. The main Claude (team lead) creates sub-agents (team members) to handle tasks and receive results. That’s the Agent tool.

Sub-agents are created automatically by the main Claude. You don’t need to create them yourself. If you say “analyze this folder,” Claude determines it’s complex enough and spins up sub-agents automatically.

How Sub-Agents Are Created

Key Characteristics

Analyze all TypeScript files in the src folder
and summarize each file's role in one line.

# If there are many files, Claude automatically spawns
# sub-agents to analyze them in parallel.

What Are Agent Teams? — Building a Project Team

If sub-agents are “delegating to one team member,” Agent Teams are “assembling an entire project team.” The lead distributes work and multiple members work simultaneously.

Think of a product launch: designer handles design, developer handles code, marketer handles promotion — all at once. Agent Teams work the same way.

How Agent Teams Work

Create an agent team to refactor this project.
- 1 person for TypeScript conversion
- 1 person for Tailwind migration
- 1 person for test code

Work on everything simultaneously.

# You need to explicitly request "create an agent team."
# Claude may suggest a team, but you must approve it.

When Do You Need a Team?

Not every task needs an Agent Team. Simple tasks need just one sub-agent; only large-scale work needs a team. The distinction is simple.

Real Scenarios Where Agent Teams Shine

Creating Custom Agents — Your Own Expert Team

So far, Claude created sub-agents automatically. But you can go further: pre-define your own experts.

Having a dedicated “code review specialist” on your team would be handy, right? In Claude Code, you can create custom agents that handle specific roles.

How to Create — Just One File

Create a .claude/agents/ folder in your project and add a markdown file (.md) inside. The filename becomes the agent name.

my-project/
├── .claude/
│   └── agents/
│       ├── code-reviewer.md    ← Code review expert
│       ├── doc-writer.md       ← Documentation expert
│       └── deploy-expert.md    ← Deployment expert
├── src/
└── package.json

Writing an Agent File

Add YAML frontmatter for settings, then describe the agent’s role and rules in the body. Required fields are name and description. The description is what Claude uses to decide “when to invoke this agent.” Optionally specify tools and model.

---
name: code-reviewer
description: Reviews code changes and finds bugs, security vulnerabilities, and improvement opportunities.
tools: Read, Grep, Glob, Bash
model: sonnet
---

# Code Reviewer

## Role
- Thoroughly review code changes
- Find potential bugs
- Check security vulnerabilities
- Suggest performance improvements

## Rules
- Always specify file names and line numbers
- Classify severity in 3 levels (High/Medium/Low)
- Provide code examples with fix suggestions
- Always mention positive aspects too

---
name: doc-writer
description: Analyzes code and writes README, API docs, and usage guides.
tools: Read, Grep, Glob
model: haiku
---

# Documentation Writer

## Role
- Read code and write clear documentation
- Auto-generate and update README.md
- Document API endpoints
- Write installation/usage guides

## Rules
- Write in English (keep code terminology as-is)
- Accessible to non-developers
- Always include runnable code examples
- Markdown format with table of contents

---
name: deploy-expert
description: Deploys projects to Vercel, GitHub Pages, etc. and sets up CI/CD.
---

# Deployment Expert

## Role
- Build and deploy projects
- Set up CI/CD pipelines
- Manage environment variables
- Post-deployment verification

## Rules
- Always run build tests before deploying
- Environment variables managed only in .env
- Verify the actual URL after deployment
- Include rollback instructions

Description Is the Key to Invocation

The description line is the most important. Claude reads it to decide “should I invoke this agent?” Like reading a job description to assign the right person.

2 Ways to Use Custom Agents

Review this PR.

# Claude auto-invokes the code-reviewer agent.

Use the code-reviewer sub-agent to review this commit.

# code-reviewer agent is directly invoked.

Sub-Agent vs Agent Team — Which to Use?

They look similar but serve different purposes. Here’s a quick comparison.

Where Do Custom Agents Fit?

Custom agents are a type of sub-agent. Default sub-agents (Explore, Plan, etc.) are auto-created by Claude, while custom agents are pre-defined experts that Claude invokes. They’re separate from Agent Teams.

Try It Yourself

Reading alone won’t click. Follow these exercises.

Analyze all files in this project and
summarize what each file does in one line.
Organize as a table.

/agents
# → Select "Create new agent"
# → Choose User-level or Project-level
# → Describe the role and Claude auto-generates it

Create a report-writer.md file in .claude/agents/.

Role: Expert that analyzes data and creates beautiful HTML reports
Rules:
- Always include charts and tables
- Write in English
- Summarize key insights in 3 lines
- Clean design (gradient + card layout)

Create an agent team to improve this project.
- One person for TypeScript conversion
- One person for documentation (README, CHANGELOG)
- One person for test code

Work simultaneously.

Verification Checklist

Tips + Sources

Practical tips for effective agent usage.