Agent Teams Setup Guide

Technical documentation for implementing autonomous AI teams in Claude Code.

---

What Are Agent Teams?

Agent Teams are coordinated AI agents that work together on multi-step tasks. Each agent specializes in a specific role and communicates with others through a shared task system and file-based handoffs.

Core mechanism:

Team Lead → Creates tasks → Assigns to specialists
    ↓
Specialist agents work autonomously in parallel or sequence
    ↓
File-based handoffs between stages
    ↓
Team Lead receives completed work

Benefits:

• Separation of concerns (one agent, one responsibility)
• Quality gates between stages
• Persistent state across sessions
• Parallel execution capability

---

Agent Teams vs Subagents

Feature	Subagents	Agent Teams
Use Case	Quick queries, one-off tasks	Multi-step production workflows
Duration	Minutes	Hours to days
Coordination	None (sequential only)	Full peer-to-peer coordination
Communication	Through you only	Direct agent-to-agent via SendMessage
Memory	None (task-scoped)	Persistent via task list and files
Working Directory	Temporary	Persistent folders per agent
Task Tracking	None	Shared task list
Best For	File searches, research, exploration	Content pipelines, dev workflows, QA

When to use what:

• Subagents: “Find all React imports” or “Explore the auth system”
• Agent Teams: “Build a content production pipeline” or “Implement feature X from research to deployment”

---

Architecture

System Structure

~/.claude/                      # Auto-created by Claude Code
├── teams/
│   └── content-pipeline/
│       └── config.json         # Team metadata
└── tasks/
    └── content-pipeline/
        ├── 1.json              # Task definitions
        └── 2.json

/your-project/                  # Your workspace
├── .claude/
│   └── settings.local.json     # Permissions config
├── CLAUDE.md                   # Project instructions
├── researcher/
│   ├── ROLE.md
│   └── [work files]
├── content-specialist/
│   ├── ROLE.md
│   └── [work files]
├── content-writer/
│   ├── ROLE.md
│   └── [work files]
├── content-reviewer/
│   ├── ROLE.md
│   └── [work files]
├── handoffs/                   # Agent communication
│   ├── 01_researcher.md
│   ├── 02_specialist.md
│   ├── 03_writer.md
│   └── 04_reviewer.md
└── final-output/
    └── [completed articles]

Communication Flow

┌──────────────┐
│  Team Lead   │ ← You interact here
└──────┬───────┘
       │ SendMessage + Task assignments
       │
       ├─────────────┬──────────────┬──────────────┐
       ↓             ↓              ↓              ↓
┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│Researcher│  │Specialist│  │  Writer  │  │ Reviewer │
└────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘
     │             │              │              │
     └─────────────┴──────────────┴──────────────┘
              File-based handoffs via
              /handoffs/ directory

Key components:

1. Team config (~/.claude/teams/) - Auto-created, stores team metadata
2. Task list (~/.claude/tasks/) - Auto-created, shared task queue
3. Project folders - You create these, one per agent
4. Handoffs - Explicit file-based communication between agents

---

Setup

Prerequisites

• Claude Code installed
• Basic terminal knowledge (copy-paste commands)
• Project folder location chosen

1. Create Project Structure

# Create and enter project folder
mkdir -p ~/agent-content-team
cd ~/agent-content-team

# Create folder structure
mkdir -p researcher content-specialist content-writer content-reviewer
mkdir -p handoffs final-output .claude

Verify: Run ls and confirm all folders exist.

---

2. Configure Permissions

cat > .claude/settings.local.json << 'EOF'
{
  "permissions": {
    "defaultMode": "bypassPermissions",
    "allow": [
      "WebSearch",
      "WebFetch(domain:*)"
    ]
  }
}
EOF

What this does:

• bypassPermissions: Disables approval prompts for file operations and bash commands
• WebSearch/WebFetch: Allows agents to access internet

Security note: Only use bypassPermissions in trusted projects. Agents will have file system access within the project.

Verify: cat .claude/settings.local.json

---

3. Create Agent Roles

# Researcher
cat > researcher/ROLE.md << 'EOF'
# Researcher Role

## Mission
Conduct thorough internet research and compile credible sources.

## Responsibilities
- Search Google, Reddit, HN, blogs
- Gather 20-25 sources
- Organize by theme
- Include URLs, dates, key quotes

## Deliverable
File: `research.md`
Structure: Key findings, sources by theme, statistics

## Handoff
Create `/handoffs/01_researcher_handoff.md` when complete
EOF

# Content Specialist
cat > content-specialist/ROLE.md << 'EOF'
# Content Specialist Role

## Mission
Transform research into strategic content brief.

## Responsibilities
- Identify compelling angle
- Define target audience
- Extract core messages
- Recommend structure
- Define tone and voice

## Deliverable
File: `content-brief.md`
Include: Angle, ICP, core messages, structure, tone, SEO keywords

## Handoff
Create `/handoffs/02_specialist_handoff.md` when complete
EOF

# Content Writer
cat > content-writer/ROLE.md << 'EOF'
# Content Writer Role

## Mission
Write clear, engaging articles for non-technical readers.

## Responsibilities
- Follow content brief structure
- Write 1,500-2,500 words
- Simple, accessible language
- Cite all sources

## Deliverable
File: `article-draft.md`
Requirements: Follow brief, cite statistics, non-technical language

## Handoff
Create `/handoffs/03_writer_handoff.md` when complete
EOF

# Content Reviewer
cat > content-reviewer/ROLE.md << 'EOF'
# Content Reviewer Role

## Mission
Quality gate - verify facts and enforce standards.

## Responsibilities
- Cross-check facts against research
- Verify sources for all claims
- Check tone and clarity
- Approve OR request revisions

## Deliverable
If approved: `approval.md` with status and quality notes
If revisions needed: `revision-request.md` with specific fixes

## Handoff
Create `/handoffs/04_reviewer_handoff.md` when complete
EOF

Verify: ls */ROLE.md shows 4 files.

---

4. Create Project Instructions

cat > CLAUDE.md << 'EOF'
# Project Instructions for Claude

## Team Usage
ALWAYS use the `content-pipeline` team for all work in this project.

When working on tasks:
1. Check team status
2. Set `team_name: "content-pipeline"` when spawning agents
3. Coordinate via TaskList, TaskCreate, TaskUpdate
4. Communicate via SendMessage

## Team Structure
- team-lead (you) - Coordinates and manages tasks
- researcher - Conducts research and compiles sources
- content-specialist - Transforms research into content briefs
- content-writer - Writes articles based on briefs
- content-reviewer - Reviews content for quality and accuracy

## Workflow
1. Create tasks using TaskCreate
2. Assign tasks to appropriate team members using TaskUpdate
3. Monitor progress via TaskList
4. Coordinate with teammates using SendMessage
5. Use `/handoffs/` directory for work transitions

## Key Rules
- Never work solo - delegate to appropriate specialist
- All work tracked via task list
- All coordination via SendMessage
- Each agent works only in their own folder
- Use `/handoffs/` for transitions between agents
EOF

Verify: cat CLAUDE.md

---

5. Initialize Team

Open Claude Code:

1. Launch Claude Code application
2. File > Open Folder > Select your project folder
3. Paste the following into Claude Code chat:

Set up agent team for content production.

TEAM NAME: content-pipeline

AGENTS (all using claude-opus-4-6):
1. Researcher (general-purpose)
2. Content Specialist (general-purpose)
3. Content Writer (general-purpose)
4. Content Reviewer (general-purpose)

WORKFLOW:
- Researcher creates /handoffs/01_researcher_handoff.md
- Content Specialist creates /handoffs/02_specialist_handoff.md
- Writer creates /handoffs/03_writer_handoff.md
- Reviewer creates /handoffs/04_reviewer_handoff.md

Please:
1. Use TeamCreate tool to create "content-pipeline" team
2. Use Task tool to spawn all 4 agents with settings above
3. Each agent should read their ROLE.md from their folder
4. Verify all agents are active

After setup, I'll assign the first content topic.

Claude will create the team and spawn agents. Wait for confirmation that all 4 agents are active.

---

Usage

Create Your First Article

In Claude Code chat:

Create an article about "AI Coding Tools for Founders"

Target audience: Technical founders with 1-5 person teams
Angle: Practical tools that save time
Length: 1,500-2,000 words

Please:
1. Create Task #1 for Researcher
2. Assign to researcher agent
3. Monitor progress through pipeline
4. Update me when each phase completes

Monitor Progress

Ask Claude:

What's the status of all tasks?

Or check files manually:

# See latest handoff status
ls -lt handoffs/

# Read specific handoff
cat handoffs/01_researcher_handoff.md

Review Completed Work

Ask Claude:

Read the final article: /final-output/[article-name].md

Show me:
- Word count
- Key topics covered
- Any revisions made by reviewer

Request Revisions

If changes needed:

The article looks good, but please:
1. Add section on cost comparison
2. Include more specific examples
3. Expand conclusion

Assign this as revision task to the writer.

---

Troubleshooting

Team Not Found

Symptom: Claude says content-pipeline team doesn’t exist

Diagnose:

ls ~/.claude/teams/

Fix: If content-pipeline folder missing, run initialization prompt again. Ensure you’re in correct project directory.

---

Agent Not Responding

Symptom: Agent stuck, no handoff after 30+ minutes

Diagnose: Ask Claude:

Check status of [agent-name]:
- What task is assigned?
- Last activity?
- Any errors?

Fix:

1. Restart agent: “Please restart the [agent-name] agent”
2. Reassign task: “Please reassign Task #X to [agent-name]”
3. Check if previous agent created their handoff file

---

Handoff File Missing

Symptom: Next agent waiting but previous agent didn’t create handoff

Check:

ls -la handoffs/
ls -la researcher/research.md
ls -la content-specialist/content-brief.md

Fix: Ask Claude:

Please check:
1. Did [previous-agent] complete their work?
2. Is their deliverable in their folder?
3. If yes, manually create the handoff file based on completed work

---

Quality Issues

Symptom: Articles don’t meet standards

Fix:

1. Update ROLE.md with specific requirements

Edit content-reviewer/ROLE.md and add detailed checklist:

## Approval Checklist
- All statistics have sources cited
- No jargon without explanation
- Reading level: Grade 8-10
- At least 3 concrete examples
- Clear next step in conclusion
- Meta description under 160 characters
- Title under 60 characters

2. Add example outputs to ROLE.md

Show agents what good output looks like.

3. Refine content briefs

Update content-specialist/ROLE.md with more detailed brief requirements.

---

Performance Issues

Symptom: Pipeline takes 4+ hours per article

Fix:

1. Use mixed models for speed:

Edit ~/.claude/teams/content-pipeline/config.json:

• Researcher: "model": "claude-sonnet-4-5-20250929" (faster)
• Content Specialist: "model": "claude-sonnet-4-5-20250929"
• Writer: "model": "claude-opus-4-6" (keep quality)
• Reviewer: "model": "claude-sonnet-4-5-20250929"

Then tell Claude: “Please reload the team configuration”

2. Reduce scope:

• Target 1,000-1,500 words instead of 2,000
• Reduce sources from 20-25 to 10-15

---

Cost Issues

Symptom: API costs higher than expected

Fix:

Use mixed models (see Performance Issues above).

Cost comparison per 1,500-2,000 word article:

• All Opus 4.6: ~$4.75
• Mixed (Sonnet 4.5 + Opus 4.6): ~$2.75

Savings: ~40-50% with minimal quality impact.

---

Quick Reference

File Structure

• ~/.claude/teams/ - Team configs (auto-created)
• ~/.claude/tasks/ - Task queue (auto-created)
• .claude/settings.local.json - Permissions
• CLAUDE.md - Project instructions
• [agent]/ROLE.md - Agent responsibilities
• /handoffs/ - Agent-to-agent communication
• /final-output/ - Completed work

Key Tools (Claude Code chat)

• TeamCreate - Create new team
• Task - Spawn agent or assign work
• TaskList - View all tasks
• TaskCreate - Create new task
• TaskUpdate - Update task status
• SendMessage - Agent-to-agent communication

Common Commands

Ask Claude:

# Check status
What's the status of all tasks?

# Restart agent
Please restart the [agent-name] agent

# Reload team config
Please reload the team configuration

# Create new task
Create Task #X for [agent-name] to [task description]

Terminal:

# Check handoffs
ls -lt handoffs/

# Read handoff
cat handoffs/01_researcher_handoff.md

# Verify setup
cat .claude/settings.local.json
cat CLAUDE.md
ls */ROLE.md

---

Concepts Summary

Agent Teams: Coordinated autonomous agents with shared task list and peer-to-peer communication.

Subagents: Quick helpers for one-off tasks that report back to you.

File-based handoffs: Explicit communication between agents via /handoffs/ directory.

Task list: Shared queue at ~/.claude/tasks/[team-name]/ with JSON task definitions.

Quality gates: Each agent reviews previous agent’s work before proceeding.

Persistent state: Team configuration and tasks persist across sessions.

---

Next Steps

1. Run first article - Start with a familiar topic
2. Refine roles - Update ROLE.md files based on outputs
3. Optimize costs - Experiment with mixed models
4. Scale up - Run 2-3 articles in parallel once comfortable
5. Adapt workflow - Apply to other use cases (documentation, social posts, etc.)

---

Documentation version: v3
Last updated: 2026-02-09