Create a New Team

Define a multi-agent team composition that coordinates two or more agents to accomplish tasks requiring multiple perspectives, specialties, or phases. The resulting team file integrates with the teams registry and can be activated in Claude Code by name.

When to Use

• A task requires multiple perspectives that a single agent cannot provide (e.g., code review plus security audit plus architecture review)
• You need a recurring collaborative workflow with consistent role assignments and handoff patterns
• An existing agent composition is being used repeatedly and should be formalized
• A complex process naturally decomposes into phases or specialties handled by different agents
• You want to define a coordinated group for sprint-based, pipeline-based, or parallel work

Inputs

• Required: Team name (lowercase kebab-case, e.g., data-pipeline-review)
• Required: Team purpose (one paragraph describing what problem requires multiple agents)
• Required: Lead agent (must exist in agents/_registry.yml)
• Optional: Coordination pattern (default: hub-and-spoke). One of: hub-and-spoke, sequential, parallel, timeboxed, adaptive
• Optional: Number of members (default: 3-4; recommended range: 2-5)
• Optional: Source material (existing workflow, runbook, or ad-hoc team composition to formalize)

Procedure

Step 1: Define Team Purpose

Articulate what problem requires multiple agents working together. A valid team purpose must answer:

1. What outcome does this team deliver? (e.g., a comprehensive review report, a deployed application, a sprint increment)
2. Why can't a single agent do this? Identify at least two distinct specialties or perspectives required.
3. When should this team be activated? Define the trigger conditions.

Write the purpose as one paragraph that a human or agent can read to decide whether to activate this team.

Got: A clear paragraph explaining the team's value proposition, with at least two distinct specialties identified.

If fail: If you cannot identify two distinct specialties, the task likely does not need a team. Use a single agent with multiple skills instead.

Step 2: Select Lead Agent

The lead agent orchestrates the team. Choose an agent from agents/_registry.yml that:

• Has domain expertise relevant to the team's primary output
• Can decompose incoming requests into subtasks for other members
• Can synthesize results from multiple reviewers into a coherent deliverable

# List all available agents
grep "^  - id:" agents/_registry.yml

The lead must also appear as a member in the team composition (the lead is always a member).

Got: One agent selected as lead, confirmed to exist in the agents registry.

If fail: If no existing agent fits the lead role, create one first using the create-agent skill (or agents/_template.md manually). Do not create a team with a lead that does not exist as an agent definition.

Step 3: Select Member Agents

Choose 2-5 members (including the lead) with clear, non-overlapping responsibilities. For each member, define:

• id: Agent name from the agents registry
• role: A short title (e.g., "Quality Reviewer", "Security Auditor", "Architecture Reviewer")
• responsibilities: One sentence describing what this member does that no other member does

# Verify each candidate agent exists
grep "id: agent-name-here" agents/_registry.yml

Validate non-overlap: no two members should have the same primary responsibility. If responsibilities overlap, either merge the roles or sharpen the boundaries.

Got: 2-5 members selected, each with a unique role and clear responsibilities, all confirmed in the agents registry.

If fail: If a needed agent does not exist, create it first. If responsibilities overlap between two members, rewrite them to clarify boundaries or remove one member.

Step 4: Choose Coordination Pattern

Select the pattern that best fits the team's workflow. The five patterns and their use cases:

Pattern	When to Use	Example Teams
hub-and-spoke	Lead distributes tasks, collects results, synthesizes. Best for review and audit workflows.	r-package-review, gxp-compliance-validation, ml-data-science-review
sequential	Each agent builds on the previous agent's output. Best for pipelines and staged workflows.	fullstack-web-dev, tending
parallel	All agents work simultaneously on independent subtasks. Best when subtasks have no dependencies.	devops-platform-engineering
timeboxed	Work organized into fixed-length iterations. Best for ongoing project work with a backlog.	scrum-team
adaptive	Team self-organizes based on the task. Best for unknown or highly variable tasks.	opaque-team

Decision guide:

• If the lead must see all results before producing output: hub-and-spoke
• If agent B needs agent A's output to start: sequential
• If all agents can work without seeing each other's output: parallel
• If work spans multiple iterations with planning ceremonies: timeboxed
• If you cannot predict the task structure in advance: adaptive

Got: One coordination pattern selected with a clear rationale for the choice.

If fail: If unsure, default to hub-and-spoke. It is the most common pattern and works for most review and analysis workflows.

Step 5: Design Task Decomposition

Define how a typical incoming request gets split across team members. Structure this as phases:

1. Setup phase: What the lead does to analyze the request and create tasks
2. Execution phase: What each member works on (in parallel, in sequence, or per-sprint depending on coordination pattern)
3. Synthesis phase: How results are collected and the final deliverable is produced

For each member, list 3-5 concrete tasks they would perform on a typical request. These tasks appear in both the "Task Decomposition" prose section and the CONFIG block's tasks list.

Got: A phase-structured decomposition with concrete tasks per member, matching the chosen coordination pattern.

If fail: If tasks are too vague (e.g., "reviews things"), make them specific (e.g., "reviews code style against tidyverse style guide, checks test coverage, evaluates error message quality").

Step 6: Write the Team File

Copy the template and fill in all sections:

cp teams/_template.md teams/<team-name>.md

Fill in the following sections in order:

1. YAML frontmatter: name, description, lead, version ("1.0.0"), author, created, updated, tags, coordination, members[] (each with id, role, responsibilities)
2. Title: # Team Name (human-readable, title case)
3. Introduction: One paragraph summary
4. Purpose: Why this team exists, what specialties it combines
5. Team Composition: Table with Member, Agent, Role, Focus Areas columns
6. Coordination Pattern: Prose description plus ASCII diagram of the flow
7. Task Decomposition: Phased breakdown with concrete tasks per member
8. Configuration: Machine-readable CONFIG block (see Step 7)
9. Usage Scenarios: 2-3 concrete scenarios with example user prompts
10. Limitations: 3-5 known constraints
11. See Also: Links to member agent files and related skills/teams

Got: A complete team file with all sections filled in, no placeholder text remaining from the template.

If fail: Compare against an existing team file (e.g., teams/r-package-review.md) to verify structure. Search for template placeholder strings like "your-team-name" or "another-agent" to find unfilled sections.

Step 7: Write the CONFIG Block

The CONFIG block between <!-- CONFIG:START --> and <!-- CONFIG:END --> markers provides machine-readable YAML for tooling. Structure it as follows:

<!-- CONFIG:START -->
```yaml
team:
  name: <team-name>
  lead: <lead-agent-id>
  coordination: <pattern>
  members:
    - agent: <agent-id>
      role: <role-title>
      subagent_type: <agent-id>  # Claude Code subagent type for spawning
    # ... repeat for each member
  tasks:
    - name: <task-name>
      assignee: <agent-id>
      description: <one-line description>
    # ... repeat for each task
    - name: synthesize-report  # final task if hub-and-spoke
      assignee: <lead-agent-id>
      description: <synthesis description>
      blocked_by: [<prior-task-names>]  # for dependency ordering
```
<!-- CONFIG:END -->

The subagent_type field maps to Claude Code agent types. For agents defined in .claude/agents/, use the agent id as the subagent_type. Use blocked_by to express task dependencies (e.g., synthesis is blocked by all review tasks).

Got: CONFIG block is valid YAML, all agents match those in the frontmatter members list, and task dependencies form a valid DAG (no cycles).

If fail: Validate YAML syntax. Verify that every assignee in the tasks list matches an agent in the members list. Check that blocked_by references only task names defined earlier in the list.

Step 8: Add to Registry

Edit teams/_registry.yml to add the new team:

- id: <team-name>
  path: <team-name>.md
  lead: <lead-agent-id>
  members: [<agent-id-1>, <agent-id-2>, ...]
  coordination: <pattern>
  description: <one-line description matching frontmatter>

Update the total_teams count at the top of the registry (currently 8; it becomes 9 after adding one team).

# Verify the entry was added
grep "id: <team-name>" teams/_registry.yml

Got: New entry appears in the registry, total_teams count is incremented by one.

If fail: If the team name already exists in the registry, choose a different name or update the existing entry. Verify the YAML indentation matches existing entries.

Step 9: Run README Automation

Regenerate README files from the updated registry:

npm run update-readmes

This updates the dynamic sections in teams/README.md and any other files with <!-- AUTO:START --> / <!-- AUTO:END --> markers that reference team data.

Got: Command exits 0, teams/README.md now lists the new team.

If fail: Run npm run check-readmes to see which files are out of sync. If the script fails, verify package.json exists in the repository root and js-yaml is installed (npm install).

Step 10: Verify Team Activation

Test that the team can be activated in Claude Code:

User: Use the <team-name> team to <typical task description>

Claude reads teams/<team-name>.md, extracts the CONFIG block, and orchestrates activation:

1. Calls TeamCreate with the team name and description
2. Spawns teammates via the Agent tool using each member's subagent_type from the CONFIG block
3. Creates tasks via TaskCreate with the blocked_by dependencies from the CONFIG block
4. The lead agent coordinates work following the coordination pattern

Note: Teams are not auto-discovered from .claude/teams/. Claude reads the definition directly from teams/ when asked.

Got: Claude reads the team file, creates the team via TeamCreate, spawns the correct agents, and follows the coordination pattern.

If fail: Verify the team file is at teams/<team-name>.md (not in a subdirectory). Check that all member agents exist in agents/. Confirm the CONFIG block has valid YAML with subagent_type for each member. Confirm the team is listed in teams/_registry.yml.

Step 11: Scaffold Translations

Required for all teams. This step applies to both human authors and AI agents following this procedure. Do not skip — missing translations accumulate into stale backlog.

Scaffold translation files for all 4 supported locales immediately after committing the new team:

for locale in de zh-CN ja es; do
  npm run translate:scaffold -- teams <team-name> "$locale"
done

Then translate the scaffolded prose in each file (code blocks and IDs stay in English). Finally regenerate the status files:

npm run translation:status

Got: 4 files created at i18n/{de,zh-CN,ja,es}/teams/<team-name>.md, all with source_commit matching current HEAD. npm run validate:translations shows 0 stale warnings for the new team.

If fail: If scaffold fails, verify the team exists in teams/_registry.yml. If status files don't update, run npm run translation:status explicitly.

Validation

• Team file exists at teams/<team-name>.md
• YAML frontmatter parses without errors
• All required frontmatter fields present: name, description, lead, version, author, coordination, members[]
• Each member in frontmatter has id, role, and responsibilities
• All sections present: Purpose, Team Composition, Coordination Pattern, Task Decomposition, Configuration, Usage Scenarios, Limitations, See Also
• CONFIG block exists between <!-- CONFIG:START --> and <!-- CONFIG:END --> markers
• CONFIG block YAML is valid and parseable
• All member agent ids exist in agents/_registry.yml
• Lead agent appears in the members list
• No two members share the same primary responsibility
• Team is listed in teams/_registry.yml with correct path, lead, members, and coordination
• total_teams count in registry is incremented
• npm run update-readmes completes without errors

Pitfalls

• Too many members: Teams with more than 5 members become hard to coordinate. The overhead of distributing tasks and synthesizing results outweighs the benefit of additional perspectives. Split into two teams or reduce to the essential specialties.
• Overlapping responsibilities: If two members both "review code quality," their findings will conflict and the lead wastes time deduplicating. Each member must have a clearly distinct focus area.
• Wrong coordination pattern: Using hub-and-spoke when agents need each other's output (should be sequential), or using sequential when agents can work independently (should be parallel). Review the decision guide in Step 4.
• Missing CONFIG block: The CONFIG block is not optional prose decoration. It is the machine-readable specification Claude uses to orchestrate TeamCreate, agent spawning, and task creation. Without it, the team can only be activated through ad-hoc prose interpretation, which is less reliable.
• Lead agent not in members list: The lead must also appear as a member with their own role and responsibilities. A lead who only "coordinates" without doing substantive work wastes a slot. Give the lead a concrete review or synthesis responsibility.

Related Skills

• create-skill - follows the same meta-pattern for creating SKILL.md files
• create-agent - create agent definitions that serve as team members
• commit-changes - commit the new team file and registry updates