agent-teams-guide_skill

Overview

This skill provides a practical guide for orchestrating and controlling Claude Code agent teams. It explains how to create and start teams, assign and delegate tasks, manage display modes, and shut teams down cleanly. Use it to run parallel investigations, code reviews, and coordinated multi-agent workflows.

How this skill works

The guide describes the team architecture: a single team lead (the main session), multiple teammates (separate Claude Code instances), and a shared task list for coordination. It covers enabling the experimental feature, spawning teammates with focused prompts, switching display modes (in-process vs split-pane), direct messaging, delegate mode, and cleanup. Troubleshooting steps and limitations are included to help recover from common issues.

When to use it

• When you need multiple perspectives or parallel workstreams (research, reviews).
• When a task can be partitioned into independent files or self-contained units.
• When you want competing hypotheses investigated in parallel.
• When coordinating cross-layer work (frontend, backend, tests).
• Not for sequential tasks or heavy same-file edits.

Best practices

• Provide full context in the teammate spawn prompt; teammates don’t inherit lead history.
• Split work into appropriately sized, self-contained tasks to minimize coordination overhead.
• Avoid file conflicts by assigning different files ownership to teammates.
• Use delegate mode to keep the lead as coordinator, not implementer.
• Monitor progress regularly, synthesize results, and steer teammates as needed.

Example use cases

• Parallel code review: spawn reviewers for security, performance, and test coverage and aggregate reports.
• Refactor planning: spawn an architect to propose plans and require plan approval before changes.
• Investigations: spawn multiple agents to test competing hypotheses and have them challenge each other.
• Feature development: split a new feature into independent modules and assign teammates to each module.