Agent Teams Skill

This skill enables Claude Code to orchestrate multiple AI agents working together as a team, with shared task lists, inter-agent messaging, and coordinated workflows.

Description

The Agent Teams skill implements a native protocol for coordinating multiple Claude Code instances as a collaborative team. It provides:

• Team Management: Create and manage agent teams with shared configuration
• Task Coordination: Shared task lists with dependencies, ownership, and status tracking
• Inter-Agent Messaging: Direct messages, broadcasts, and protocol requests between teammates
• Agent Spawning: Launch new Claude Code teammates in tmux panes
• Lifecycle Management: Graceful shutdown, force termination, and cleanup

When to Use

Use this skill when you need:

• Multiple AI agents working on different parts of a complex project simultaneously
• Coordinated workflows where agents need to communicate and share progress
• Parallel execution of independent tasks with dependency management
• A lead agent orchestrating and delegating work to specialized teammates

Core Concepts

Teams

• One team per session, stored in ~/.claude/teams/<team-name>/
• Team configuration tracks all members and their metadata
• Lead agent (you) coordinates the team

Tasks

• Shared task list stored in ~/.claude/tasks/<team-name>/
• Tasks have: ID, status (pending/in_progress/completed), owner, dependencies
• Tasks can block other tasks or be blocked by them

Messages

• JSON-based inboxes under ~/.claude/teams/<team-name>/inboxes/
• Message types: plain messages, broadcasts, task assignments, shutdown requests
• File locking ensures concurrency safety

Teammates

• Spawned as separate Claude Code processes in tmux panes
• Each gets unique agent ID (name@team), color, and inbox
• Receive initial prompt via inbox and work autonomously

Internal Commands

This skill uses internal CLI commands that are automatically available via uvx. You don't need to install anything separately - just use the skill and the commands work automatically.

All commands follow this pattern:

uvx --from . claude-teams-cli <command> [args]

Important: Hide this complexity from users. They should never see or need to know about the CLI commands. The skill handles everything internally.

Usage Instructions

1. Create a Team

First, create a new team:

uvx --from . claude-teams-cli team-create myproject --description "Development team for feature X"

This creates:

• Team config at ~/.claude/teams/<team-name>/config.json
• Task directory at ~/.claude/tasks/<team-name>/
• Inbox for team-lead

2. Create Tasks

Define the work to be done:

uvx --from . claude-teams-cli task-create myproject "Implement API endpoints" "Create REST API endpoints for user management"
uvx --from . claude-teams-cli task-create myproject "Write unit tests" "Add comprehensive unit tests for API"
uvx --from . claude-teams-cli task-create myproject "Update documentation" "Document new API endpoints"

Tasks get auto-incrementing IDs (1, 2, 3, ...).

3. Spawn Teammates

Launch specialized agents to work on tasks:

uvx --from . claude-teams-cli spawn-teammate myproject backend-dev \
  "You are a backend developer. Check your inbox for task assignments and work on implementing API endpoints." \
  --model sonnet \
  --subagent-type general-purpose

uvx --from . claude-teams-cli spawn-teammate myproject tester \
  "You are a QA engineer. Write comprehensive tests for the codebase." \
  --model haiku \
  --subagent-type general-purpose

4. Assign Tasks

Assign tasks to teammates (this sends inbox notification):

uvx --from . claude-teams-cli task-update myproject 1 --owner backend-dev --status in_progress
uvx --from . claude-teams-cli task-update myproject 2 --owner tester --status pending

5. Send Messages

Communicate with teammates:

# Direct message
uvx --from . claude-teams-cli send-message myproject message \
  --recipient backend-dev \
  --content "Please prioritize the user authentication endpoints first" \
  --summary "Priority guidance on auth endpoints"

# Broadcast to all
uvx --from . claude-teams-cli send-message myproject broadcast \
  --summary "Code freeze at 5pm today" \
  --content "Please commit your work by 5pm"

6. Monitor Progress

Check task status and read messages:

uvx --from . claude-teams-cli task-list myproject
uvx --from . claude-teams-cli read-inbox myproject team-lead
uvx --from . claude-teams-cli read-config myproject

7. Shutdown Teammates

When work is complete:

# Request graceful shutdown
uvx --from . claude-teams-cli send-message myproject shutdown_request \
  --recipient backend-dev \
  --content "Work is complete, please shut down"

# After receiving shutdown_approved in your inbox:
uvx --from . claude-teams-cli process-shutdown-approved myproject backend-dev

# Or force kill if unresponsive:
uvx --from . claude-teams-cli force-kill-teammate myproject backend-dev

8. Delete Team

Clean up when done:

uvx --from . claude-teams-cli team-delete myproject

Tool Reference

All tools are available via the skill's tool wrappers:

• team_create - Create a new team
• team_delete - Delete a team and all data
• read_config - Read team configuration
• spawn_teammate - Spawn a new teammate
• send_message - Send messages (message/broadcast/shutdown_request/shutdown_response/plan_approval_response)
• read_inbox - Read agent's inbox
• poll_inbox - Long-poll for new messages (up to 30s)
• task_create - Create a new task
• task_update - Update task (status, owner, dependencies, metadata)
• task_list - List all tasks
• task_get - Get specific task details
• force_kill_teammate - Force kill a teammate
• process_shutdown_approved - Process graceful shutdown

Workflow Example

# 1. Setup
uvx --from . claude-teams-cli team-create webapp --description "Build new webapp feature"

# 2. Plan work
uvx --from . claude-teams-cli task-create webapp "Design database schema" "Design and document DB schema for new feature"
uvx --from . claude-teams-cli task-create webapp "Implement backend API" "Build REST API endpoints"
uvx --from . claude-teams-cli task-create webapp "Create frontend UI" "Build React components"
uvx --from . claude-teams-cli task-create webapp "Write tests" "Add unit and integration tests"

# 3. Add dependencies (frontend depends on backend)
uvx --from . claude-teams-cli task-update webapp 3 --add-blocked-by 2

# 4. Spawn team
uvx --from . claude-teams-cli spawn-teammate webapp db-architect "Design database schema. Check tasks assigned to you."
uvx --from . claude-teams-cli spawn-teammate webapp backend-dev "Implement backend APIs. Check tasks assigned to you." --model sonnet
uvx --from . claude-teams-cli spawn-teammate webapp frontend-dev "Build React frontend. Check tasks assigned to you." --model sonnet
uvx --from . claude-teams-cli spawn-teammate webapp qa-engineer "Write comprehensive tests. Check tasks assigned to you." --model haiku

# 5. Assign initial tasks
uvx --from . claude-teams-cli task-update webapp 1 --owner db-architect --status in_progress
uvx --from . claude-teams-cli task-update webapp 2 --owner backend-dev --status pending
uvx --from . claude-teams-cli task-update webapp 4 --owner qa-engineer --status pending

# 6. Monitor and coordinate
uvx --from . claude-teams-cli task-list webapp
uvx --from . claude-teams-cli read-inbox webapp team-lead
# Send guidance as needed with send-message

# 7. Cleanup when done
uvx --from . claude-teams-cli send-message webapp shutdown_request --recipient db-architect
# After receiving approvals in inbox:
uvx --from . claude-teams-cli process-shutdown-approved webapp db-architect
# Finally:
uvx --from . claude-teams-cli team-delete webapp

Requirements

• Python 3.12+ (installed automatically via uvx)
• uv/uvx (Python package manager) - Install: curl -LsSf https://astral.sh/uv/install.sh | sh
• tmux
• Claude Code CLI on PATH

Note: The skill automatically manages Python dependencies via uvx. Users don't need to manually install Python packages.

Storage Layout

~/.claude/
├── teams/<team-name>/
│   ├── config.json          # team config + member list
│   └── inboxes/
│       ├── team-lead.json   # lead agent inbox
│       ├── worker-1.json    # teammate inboxes
│       └── .lock
└── tasks/<team-name>/
    ├── 1.json               # task files (auto-incrementing IDs)
    ├── 2.json
    └── .lock

Notes

• One team per skill session
• Team names must be filesystem-safe (letters, numbers, hyphens, underscores)
• Teammates spawn in separate tmux panes with their own Claude Code sessions
• All operations are concurrency-safe with file locking
• Messages are JSON-based with read/unread tracking
• Tasks support dependency chains (blocks/blockedBy) with cycle detection