# Agent Team

> Launches coordinated agent teams for tasks requiring persistent cross-talk, shared state, and lifecycle management, with team design, advisor coordination, and quality gates.

- Skill: `samyakjhaveri/agent-team` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds add samyakjhaveri/agent-team`
- Raw SKILL.md: https://api.skillmd.com/api/skills/samyakjhaveri/agent-team/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML, Agent Building
- Tags: Advisor, Agent Teams, Critic, Multi Agent, Orchestration, Teamcreate
- Author: SamyakJhaveri (https://skillmd.com/u/samyakjhaveri)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/samyakjhaveri/agent-team

---


# Creating Agent Teams

Launch coordinated agent teams for tasks requiring persistent cross-talk, shared
state, and teammate lifecycle management.

**Trigger:** `/agent-team <task-description>` or `/agent-team`

## Arguments

- `$ARGUMENTS` — Free-text task description. If omitted, ask the user.
- `--scenario <name>` — Use a pre-built template from [scenarios.md](scenarios.md).
  Skips Phase 2 (team design). Still requires user approval before launching.
  Valid: `feature-implementation`, `failure-investigation`, `documentation-assembly`,
  `multi-system-analysis`, `advisor-guided-implementation`.
- `--teammates N` — Override default teammate count.
- `--all-opus` — Use Opus for all teammates (no advisor pattern). For tasks where
  Sonnet workers aren't sufficient (complex architecture, deep reasoning).
- `--no-critic` — Skip critic review (read-only/exploratory tasks only).
- `--fast` — Skip plan approval (urgent tasks only).

## When to Use

```dot
digraph when_to_use {
    "Complex task needing\nmultiple workers?" [shape=diamond];
    "Workers need to\ncommunicate findings?" [shape=diamond];
    "Tasks fully\nindependent?" [shape=diamond];
    "Single agent or subagent" [shape=box];
    "dispatching-parallel-agents" [shape=box];
    "creating-agent-teams" [shape=box style=filled fillcolor=lightgreen];

    "Complex task needing\nmultiple workers?" -> "Single agent or subagent" [label="no"];
    "Complex task needing\nmultiple workers?" -> "Workers need to\ncommunicate findings?" [label="yes"];
    "Workers need to\ncommunicate findings?" -> "Tasks fully\nindependent?" [label="no"];
    "Workers need to\ncommunicate findings?" -> "creating-agent-teams" [label="yes"];
    "Tasks fully\nindependent?" -> "dispatching-parallel-agents" [label="yes"];
    "Tasks fully\nindependent?" -> "creating-agent-teams" [label="no — shared state\nor synthesis needed"];
}
```

**Use agent teams when:**
- Teammates must share findings with each other (not just report to parent)
- One teammate's output feeds another's input (synthesis)
- Extended work (~5-30 min per teammate) with context accumulation
- Shared task list tracking is needed

**Don't use when:**
- Tasks are fully independent → use `dispatching-parallel-agents`
- Quick structured verdicts (~30s-2min) → use subagents
- Single-file edits → teammate overhead exceeds benefit
- Two teammates would edit the same file → overwrite conflicts

## Workflow

### Phase 1: Understand the Task

1. Parse `$ARGUMENTS` for what the team should accomplish.
2. If unclear, ask the user for clarification.
3. Identify files, systems, and scope involved.
4. If `--scenario` used, load template from [scenarios.md](scenarios.md), skip to Phase 3.

### Phase 2: Design the Team

1. Determine minimum teammates (prefer fewer, focused teammates).
2. For each teammate define:
   - **Name** — descriptive, lowercase-with-hyphens
   - **Role** — one sentence
   - **Scope** — specific files/areas they own (NO overlap between teammates)
   - **Skills/Agents** — which pre-made agents or skills they should use
3. Default team includes an **advisor** (Opus) as first teammate. Workers default to
   `model: "sonnet"`, critic defaults to `model: "sonnet"`. For analytically heavy tasks
   (failure investigation, complex debugging), consider `--all-opus` or promoting specific
   workers to Opus.

4. Present to the user:

```
## Proposed Team: <team-name>

| Teammate | Model  | Role | Scope | Skills/Agents |
|----------|--------|------|-------|---------------|
| advisor  | opus   | Strategic reviewer | All areas (read-only) | — |
| planner  | sonnet | ... | ... | /writing-plans |
| ...      | sonnet | ... | ... | ... |
| critic   | sonnet | ... | ... | self-critic |

Estimated cost: ~Nx (see Cost table below)
```

5. **Wait for user approval.** Do NOT proceed until approved.

### Phase 3: Create and Launch

Execute these steps in exact order:

**Step 1 — TeamCreate.** Always the first action.
```
TeamCreate(team_name="<descriptive-name>")
```
If you find yourself about to call Agent without `team_name`, STOP.
Agent calls without `team_name` create isolated subagents that cannot cross-talk,
do not appear as teammates, and miss all coordination benefits.

**Step 2 — Create tasks** with TaskCreate for each unit of work.

**Step 2.5 — Spawn advisor FIRST** (skip if `--all-opus`):
```
Agent(
  prompt="<filled advisor-prompt.md>\n\n## YOUR TASK\n<advisor scope>",
  model="opus",
  team_name="<team-name-from-step-1>",
  name="advisor"
)
```
Read [advisor-prompt.md](advisor-prompt.md) and fill all `[FILL]` placeholders.
**Wait for advisor's "ADVISOR READY" message before spawning any workers.**

**Step 3 — Compose teammate prompts.** For EVERY worker/critic teammate:
1. Read [teammate-prompt.md](teammate-prompt.md)
2. Fill in ALL `[FILL]` placeholders with the teammate's specific scope, skills, etc.
3. Append the teammate's task description after the directives block

**Step 4 — Spawn workers** with Agent tool:
```
Agent(
  prompt="<filled teammate-prompt.md>\n\n## YOUR TASK\n<task description>",
  model="sonnet",
  team_name="<team-name-from-step-1>",
  name="<teammate-name>"
)
```
Every `Agent` call MUST include `team_name`.
Use `model="sonnet"` by default. Use `model="opus"` only if `--all-opus` was specified
or if the scenario recommends Opus for specific workers (see [scenarios.md](scenarios.md)).

**Step 5 — Manage lifecycle:**
- Assign tasks as teammates become available
- Aggregate results and present to the user
- Escalate decisions to the user (teammates don't contact user directly)
- Watch for handoff signals (teammate-prompt.md Section 5)
- When a teammate signals context relay: spawn child, pass handoff summary, confirm
- Shut down teammates when their work is done

**Advisor Coordination** (skip if `--all-opus`):
1. After each worker milestone -> forward summary to advisor via `SendMessage(to="advisor")`
2. Advisor returns guidance -> relay to relevant worker via `SendMessage(to="worker-N")`
3. If worker reports "consulted advisor: no" -> ask worker to justify or consult
4. Before Phase 4 -> `SendMessage(to="advisor", message="PRE-REVIEW: <summary of all work>")`
5. If worker stuck (2 failed attempts) -> escalate to advisor
6. During advisor relay handoff: pause milestone forwarding, wait for new advisor READY signal

### Phase 4: Quality Gate

Skip this phase only if `--no-critic` was specified.

1. **Sonnet critic reviews ALL changes** by other teammates (cheaper first pass). Checks:
   - Factual accuracy — claims match actual data files
   - Stale references — files, functions, numbers that don't exist
   - Consistency — no contradictions between teammate outputs
   - Completeness — all assigned tasks actually done
   - Scope compliance — no unauthorized file changes

2. **Escalate complex findings to advisor** (skip if `--all-opus`):
   - Ambiguous or borderline issues where the critic is unsure
   - Cross-cutting concerns that span multiple workers' outputs
   - Advisor provides final strategic sign-off before presenting to user

3. Present critic findings (+ advisor arbitration if applicable) to the user.

4. If issues found -> fix loop:
   a. Plan which teammate owns the fix
   b. Get user approval
   c. Teammate implements fix
   d. Critic re-reviews
   e. Max 3 iterations, then escalate to user

5. Final report to the user:
   - What was done (with file paths)
   - What decisions were made (and why)
   - What files were changed
   - Any open items or concerns

## Available Agents & Skills for Teammates

Teammates should reuse these rather than building from scratch:

| Agent/Skill | Use for |
|------------|---------|
| `explorer` agent | Read-only codebase exploration |
| `plan-reviewer` agent (spec audit mode) | Auditing spec documents |
| `plan-reviewer` agent | Adversarial plan review |
| `self-critic` agent | Adversarial self-review |
| `verification-lead` agent | Cross-checking docs vs code |
| `/writing-plans` skill | Creating implementation plans |
| `/validate` skill | Post-session validation |
| `/multi-review` skill | Multi-agent code review |

## `--all-opus` Behavior

When `--all-opus` is specified:
- All teammates spawn with `model: "opus"`
- No advisor teammate is created
- `advisor-prompt.md` is NOT used
- Workers use `teammate-prompt.md` without Section 7 (Section 7 says "skip if --all-opus")
- Phase 4 critic is Opus (no escalation needed)
- Phase 3 Step 2.5 is skipped entirely

## Cost Estimation

**Default (advisor pattern):**

| Team | Mix | Cost vs All-Opus |
|------|-----|-----------------|
| Advisor + 1W + critic | 1 Opus + 2 Sonnet | ~45-55% |
| Advisor + 2W + critic | 1 Opus + 3 Sonnet | ~35-45% |
| Advisor + 3W + critic | 1 Opus + 4 Sonnet | ~30-40% |

Note: Opus is 5x Sonnet per token. Advisor uses fewer tokens than workers (guidance
only, no file editing). Ranges account for varying advisor utilization.

**`--all-opus` (full power):**

| Team Size | Token Multiplier | When to Use |
|-----------|-----------------|-------------|
| Lead + 1 | ~2x | Simple comparison tasks |
| Lead + 2 | ~3x | Most analysis (debugging, review) |
| Lead + 3 | ~4x | Multi-system analysis |
| Lead + 4+ | ~5x+ | Rare; large-scale comparison only |

## Known Limitations

- **Delegate mode bug:** Teammates may not receive all tool results. Workaround:
  `claude --teammate-mode in-process`.
- **File conflicts:** Two teammates editing the same file causes overwrites. Assign
  explicit file ownership in Phase 2.
- **Context exhaustion:** Large directories fill context fast. Teammates MUST follow
  the context relay protocol in [teammate-prompt.md](teammate-prompt.md) Section 5.

## Controls Cheat Sheet

| Action | How |
|--------|-----|
| Cycle through teammates | `Shift+Down` |
| View a teammate's session | `Enter` on selected |
| Message teammate directly | Type while viewing |
| Return to lead | `Escape` |
| Toggle shared task list | `Ctrl+T` |
| Shut down one teammate | Tell lead: "Ask {name} to shut down" |
| Clean up entire team | Tell lead: "Clean up the team" |
| Force in-process mode | `claude --teammate-mode in-process` |