Documentation > Tutorials > Creating Agent Teams

Guide ID	T-5
Audience	Developers
Prerequisites	T-2: Skills vs Agents vs Teams, 2+ skills created
Time	20 minutes
Difficulty	Intermediate

Creating Agent Teams

Agent teams coordinate multiple Claude Code agents working together on complex tasks that exceed the scope of any single agent. This tutorial walks you through choosing a topology, creating a team, validating the configuration, checking spawn readiness, and reviewing the deployed team. You will need at least two existing skills to assign to team members.

Step 1: Choose a Topology

Before creating a team, decide which coordination pattern fits your use case. GSD Skill Creator supports three topologies:

Topology	Structure	Best For
leader-worker	One coordinator distributes tasks to specialists	Parallel research, investigation, review tasks
pipeline	Sequential stages with an orchestrator	Data processing, transformation workflows, build pipelines
swarm	Peer agents with lightweight coordination	Multiple perspectives on the same problem, brainstorming

For this tutorial, we will create a leader-worker team — the most common topology. One lead agent coordinates the work and synthesizes results from multiple worker agents.

Step 2: Create the Team

Launch the interactive creation wizard:

skill-creator team create

Follow the prompts:

• Name: Enter a lowercase, hyphenated name (e.g., research-team)
• Pattern: Select leader-worker
• Description: Describe the team’s purpose (e.g., “Parallel research across multiple dimensions”)
• Member count: Choose the number of worker agents (default: 3)

For scripted or non-interactive usage, you can pass all options as flags:

skill-creator team create --name=research-team --pattern=leader-worker --members=3

The command creates a JSON configuration file in .claude/teams/research-team.json that defines the team structure, members, and their roles.

Step 3: Validate the Configuration

Run the validation pipeline to check that the team configuration is correct and complete:

skill-creator team validate research-team

Validation runs six checks:

• Schema validity — Required fields present with correct types
• Lead agent resolution — The leadAgentId matches a member’s agentId
• No duplicate IDs — Every member has a unique agentId
• Topology rules — Correct agent types for the chosen pattern (e.g., leader-worker requires exactly one coordinator)
• Tool overlap detection — Warnings when multiple members share write tools
• Skill conflict detection — Warnings when members have semantically overlapping skill assignments

Errors are blocking — the team cannot deploy with errors. Warnings are informational — they highlight potential issues but do not prevent deployment.

Step 4: Check Spawn Readiness

Verify that all member agent files exist on disk and are ready for deployment:

skill-creator team spawn research-team

The spawn command checks each member’s agent file in .claude/agents/. If all files exist, you see a success message:

Team 'research-team' is ready. 4 members resolved: research-synthesizer, researcher-alpha, researcher-beta, researcher-gamma

If agent files are missing, the command reports which ones are not found and offers to generate them interactively. It also provides fuzzy name suggestions if a member ID has a typo.

Step 5: Review Team Status

View the full team configuration and validation summary:

skill-creator team status research-team

This displays the team name, topology, description, lead agent, creation date, a table of all members with their agent IDs, names, types, and models, and a compact validation summary.

Built-in GSD Templates

GSD Skill Creator includes two pre-configured team templates for common GSD workflows:

Template	Members	Pattern	Use Case
Research Team	5 (1 synthesizer + 4 researchers)	leader-worker	Parallel ecosystem research during planning phases
Debugging Team	4 (1 coordinator + 3 investigators)	leader-worker	Adversarial debugging with multiple investigation angles

These templates are available programmatically through the API and can serve as starting points for custom teams.

Managing Teams

After creation, use these commands to manage your teams:

# List all teams
skill-creator team list

# Validate all teams at once
skill-creator team validate --all

# Get JSON output for scripting
skill-creator team list --json
skill-creator team status research-team --json

What’s Next

• Skills vs Agents vs Teams — Review the conceptual differences between all three abstraction levels
• Architecture — Explore the system architecture behind team coordination and agent resolution