Teams

Status: 🧪 Beta

A team is a curated selection of agents — sourced from kits and/or individual specs — configured for a specific project context. Teams are stored as YAML files under .agent-teams/teams/.

Creating a Team

Dashboard → Team Manager → Create Team, or use the Quick Actions card on the home page.

The wizard has three sections:

Basics — enter the team name and description
Members — select agents to include in this team from your available agent list. If no agents exist yet, a shortcut link to Create Agent is shown
Summary — a live preview of the team configuration appears in the right sidebar

Click Create to save the team. The file .agent-teams/teams/<id>.yml is created automatically.

Managing Teams

View All Teams

Dashboard → Team Manager lists all teams with their name, description, agent count, and active status. Click any team card to open it.

The page header has two action buttons: Create Team (opens the wizard) and Design a new team with AI (opens @agent-designer in Copilot Chat).

Teams whose source spec was modified after the last successful sync show a Not synced badge in the Team Manager. Sync the team to clear the badge.

Edit a Team

Dashboard → Team Manager → select team → Edit

The edit page provides four actions:

Action	Description
Save	Write changes to the team YAML file
Cancel	Discard unsaved changes
Delete	Permanently remove this team
Set as Active	Mark this team as the active team for sync operations

Setting the Active Team

Only one team can be active at a time. The active team determines which agents are synced to .github/agents/ and which agents register as Copilot Chat participants.

To change the active team: Dashboard → Team Manager → select team → Edit → Set as Active

The dashboard home page Stats card always shows which team is currently active.

Syncing a Team

Sync resolves the full composition (kit defaults + project profile + team overrides) and writes the final output files for each configured sync target.

Dashboard home → Sync Status card shows a breakdown of pending changes:
- create — new file will be written
- update — existing file will be updated
- skip — no changes detected, file left as-is
Click Sync to apply all changes

The dashboard detects changes to agent and team YAML files automatically — the sync status card updates whenever you save a file.

Output per target

Each sync target writes its output to a different location:

Target	Output
Claude Code	`.claude/agents/<id>.md` per agent + `AGENTS.md` at root
Codex	`AGENTS.md` at project root
Gemini CLI	`GEMINI.md` at project root
OpenAI Agents SDK	`AGENTS.md` at project root
GitHub Copilot	`.github/agents/<id>.agent.md` per agent

For targets that generate a single root file (AGENTS.md, GEMINI.md), context packs are inlined directly into that file by priority: essential packs are always included, standard packs are included up to the configured character budget, and reference packs are listed as links at the bottom.

Previewing changes before sync (CLI)

Use --dry-run to see exactly what would change without writing any files:

agent-teams team:sync --team my-team --dry-run

The output is colour-coded and grouped by target:

  + .claude/agents/frontend-agent.md    [create]
  ~ .claude/agents/backend-agent.md     [update]
  - .claude/agents/legacy-agent.md      [delete]

Add --no-diff to suppress the per-file detail and show only the summary.

MCP Server sync

If any agent in the team declares mcpServers, Agent Teams merges them into the project MCP config files during sync:

Copilot target → .vscode/mcp.json (servers key)
Claude Code target → .mcp.json at project root (mcpServers key)

Servers are merged by id. Existing entries are never overwritten, so project-level overrides are always preserved. See MCP Servers in the Agents reference.

Merge Strategies

When multiple sources define the same agent field (kit default, project profile, team override), the Merge Engine resolves the conflict using one of four strategies:

Strategy	Behaviour
`team-priority` (default)	Team overrides win over profile and kit
`profile-priority`	Project profile wins over kit and team
`kit-priority`	Kit defaults win — overrides are ignored
`explicit-only`	Only fields explicitly set at team level are used

Reference: Team YAML Format

The dashboard writes and reads this format automatically. You can also edit the file directly in VS Code.

id: frontend-team
name: Frontend Team
description: Team focused on React and TypeScript frontend work

kits:
  - id: testing-vitest
    enabled: true

agents:
  - id: vitest-worker
    enabled: true
  - id: test-orchestrator
    enabled: false

overrides:
  vitest-worker:
    skills:
      - code_analysis
      - testing

Fields

Field	Required	Description
`id`	✅	Unique team identifier (kebab-case)
`name`	✅	Display name
`description`	—	Team purpose
`kits`	—	List of kit IDs to include, each with an `enabled` flag
`agents`	—	Per-agent overrides with `enabled` flag
`overrides`	—	Field-level overrides applied to specific agents within this team

Creating a Team​

Managing Teams​

View All Teams​

Edit a Team​

Setting the Active Team​

Syncing a Team​

Output per target​

Previewing changes before sync (CLI)​

MCP Server sync​

Merge Strategies​

Reference: Team YAML Format​

Fields​