Team Composition Patterns

What Is This

The Team Composition Patterns skill provides a systematic approach to designing, configuring, and deploying agent teams for collaborative software development workflows using Claude Code's Agent Teams feature. This skill focuses on selecting the optimal team size, agent types (subagent_type), and display configurations to match the complexity and requirements of various development tasks. It includes heuristics for determining how many agents to assign, guides for choosing between preset and custom team configurations, and recommendations for role-based agent type selection. The skill also covers environment-specific display modes to ensure effective coordination in both local and CI environments.

The Team Composition Patterns skill is essential for maximizing efficiency and reliability when leveraging multi-agent teams for tasks such as code reviews, feature development, debugging, security audits, and migrations.

Why Use It

Selecting the right team composition is crucial for the success of collaborative and automated workflows. Improper team sizing or agent type selection can lead to bottlenecks, incomplete coverage, or redundant work. This skill addresses these challenges by offering:

• Preset configurations for common workflows such as code review, feature development, and debugging.
• Custom composition options for non-standard tasks like migrations or security audits.
• Role-based agent selection to ensure each agent is equipped with the necessary tools and capabilities.
• Environment-aware display modes to optimize agent team interaction and visibility.

Adopting these patterns helps teams avoid over- or under-provisioning, ensures agents are purpose-fitted for their responsibilities, and streamlines both collaborative and automated processes.

How to Use It

1. Determining Team

Size

Use the provided sizing heuristics to match the team size to the task complexity:

For example, for a small bug fix:

team = create_team(size=2, config='review')

For a large migration:

team = create_team(size=5, config='custom_migration')

2. Selecting Team Composition

Patterns

Choose the appropriate pattern based on the workflow:

• Review Team: Focused on auditing code for quality and correctness.
• Feature Team: Oriented towards developing and integrating new capabilities.
• Debug Team: Specialized in identifying and resolving defects.
• Custom Teams: Tailored for unique workflows such as migrations or security audits.

Example configuration for a review team:

team_config:
  name: code_review
  agents:
    - role: reviewer
      subagent_type: static_analysis
    - role: reviewer
      subagent_type: linter

3. Selecting Agent

Types (subagent_type) for Roles

Assign each role an agent type that matches its responsibility:

• static_analysis: For automated code correctness checks.
• linter: For style and formatting enforcement.
• security_audit: For vulnerability scanning.
• migration_assistant: For codebase migration tasks.
• feature_dev: For new feature implementation.

Example for a migration team:

team_config:
  name: migration_team
  agents:
    - role: lead
      subagent_type: migration_assistant
    - role: auditor
      subagent_type: static_analysis
    - role: tester
      subagent_type: linter

4. Configuring Display

Modes

Adapt the display mode to the environment to maximize agent visibility and interaction:

• tmux: Suited for local terminal multiplexing.
• iTerm2: For enhanced GUI-based terminal management on MacOS.
• in-process: For continuous integration (CI) or headless environments.

Example (Python):

spawn_team(
    config='feature_team',
    display_mode='tmux'
)

5. Building Custom Team

Compositions

When standard presets are insufficient, design a custom team:

• Identify all required concerns (e.g., migration, security, testing).
• Assign a dedicated agent (with the correct subagent_type) for each concern.
• Size the team according to the number and complexity of concerns.

Custom team example:

team_config:
  name: security_migration
  agents:
    - role: migration_lead
      subagent_type: migration_assistant
    - role: security_reviewer
      subagent_type: security_audit
    - role: test_engineer
      subagent_type: linter

When to Use It

Use the Team Composition Patterns skill in these scenarios:

• When deciding how many agents to spawn for a given task.
• When selecting from preset team configurations (review, feature, debug).
• When assigning agent types to specific roles for optimal capability alignment.
• When configuring or troubleshooting agent displays in local or CI environments.
• When building teams for atypical workflows (e.g., migration, security audit).

Important Notes

• Always match team size and agent types to the actual complexity and requirements of the task.
• Over-provisioning agents can cause resource waste and coordination overhead.
• Under-provisioning may result in missed issues or slower progress.
• Ensure each agent is equipped with a subagent_type that matches its assigned role.
• Select the display mode that best fits your environment to maintain agent visibility and collaboration.
• Regularly review and adjust team compositions as workflows evolve or requirements change.

The Team Composition Patterns skill is a foundational capability for anyone orchestrating multi-agent teams in Claude Code, ensuring each task receives the right expertise and coverage for reliable, scalable software delivery.