# Creating Agent Teams

> Use when facing a complex task that could benefit from multiple agents, parallel work, or specialized roles - triggers on "create a team", "parallelize", "multi-agent", or cross-layer implementation needs

- **Type:** Skill
- **Install:** `agentstack add skill-zoranspirkovski-creating-agent-teams-creating-agent-teams`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ZoranSpirkovski](https://agentstack.voostack.com/s/zoranspirkovski)
- **Installs:** 0
- **Category:** [Communication](https://agentstack.voostack.com/c/communication)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ZoranSpirkovski](https://github.com/ZoranSpirkovski)
- **Source:** https://github.com/ZoranSpirkovski/creating-agent-teams/tree/main/skills/creating-agent-teams

## Install

```sh
agentstack add skill-zoranspirkovski-creating-agent-teams-creating-agent-teams
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Creating Agent Teams

## Overview

This skill helps you decide whether a task needs a single agent, parallel subagents, or a coordinated team - and compose effective teams with the right models, agent types, and communication patterns.

**Core principle:** Don't create a team when a single sonnet agent could do it in one pass. Teams add coordination overhead - use them only when parallelism or specialization provides real benefit.

**Official documentation:** [Agent Teams on code.claude.com](https://code.claude.com/docs/en/agent-teams)

## Prerequisites

Agent teams are experimental and disabled by default. Ensure this is enabled before creating any team:

```json settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

## Agent Roster

Predefined agents the Orchestrator picks from based on task needs. Only spawn agents whose scope is actually touched.

| Agent | Model | Type | Role | Default Scope |
|-------|-------|------|------|---------------|
| **Orchestrator** | opus | general-purpose | Plans, delegates, synthesizes. Never implements directly. | Full project awareness via Explorer |
| **Explorer** | haiku | Explore | Answers Orchestrator's questions about the codebase. Finds files, patterns, conventions. | Targeted dirs only — search what's asked |
| **Frontend** | sonnet | general-purpose | React components, views, styling, state management | `frontend/` only |
| **Backend** | sonnet | general-purpose | Rails controllers, models, services, business logic | `app/`, `lib/`, `config/` |
| **API** | sonnet | general-purpose | Endpoints, serializers, shared contracts across apps | API-related files across all apps |
| **iOS** | sonnet | general-purpose | Swift/SwiftUI, MVVM architecture | `mobile/ios/` only |
| **Android** | sonnet | general-purpose | Kotlin/Compose implementation | `mobile/android/` only |
| **Database** | sonnet | general-purpose | Migrations, schema design, query optimization | `db/`, model files |
| **Debugger** | sonnet | general-purpose | Writes tests, debugs failures, validates implementations | Scoped to failing area |
| **Copywriter** | haiku | general-purpose | User-facing text, labels, error messages, i18n strings | String/locale files only |
| **Reviewer** | sonnet | code-reviewer | Quality gate. Reviews against spec and coding standards. | Files changed by other agents |

**Rules:**
- Explorer and Reviewer are always present for any implementation task
- Only spawn agents whose scope is actually touched
- If a task doesn't fit any predefined agent, define a custom agent with clear scope, model, and type — but this should be rare
- Maximum 6 agents per team. If more are needed, break into phases.

## Communication Matrix

Two modes: **Hub-and-spoke** (default) for implementation work, and **Discussion mode** for debate/investigation tasks. The Orchestrator chooses which mode to use based on the task and offers it to the user.

### Mode A: Hub-and-Spoke (Default)

All communication flows through the Orchestrator. No agent-to-agent direct messaging.

```
                    ┌──────────┐
                    │ Explorer │
                    └────┬─────┘
                         │
┌──────────┐    ┌────────┴────────┐    ┌──────────┐
│ Frontend ├────┤  ORCHESTRATOR   ├────┤ Backend  │
└──────────┘    │    (opus)       │    └──────────┘
                │                 │
┌──────────┐    │  All messages   │    ┌──────────┐
│   iOS    ├────┤  route through  ├────┤ Android  │
└──────────┘    │  this node      │    └──────────┘
                │                 │
┌──────────┐    │                 │    ┌──────────┐
│ Database ├────┤                 ├────┤   API    │
└──────────┘    │                 │    └──────────┘
                │                 │
┌──────────┐    │                 │    ┌──────────┐
│ Debugger ├────┤                 ├────┤ Reviewer │
└──────────┘    └────────┬────────┘    └──────────┘
                         │
                    ┌────┴──────┐
                    │Copywriter │
                    └───────────┘
```

**Use for:** Implementation, feature work, any task where agents write code to distinct files.

#### Hub-and-Spoke Rules

| Rule | Description |
|------|-------------|
| **No cross-talk** | Agents never message each other directly. All goes through Orchestrator. |
| **Results only** | Agents send: what was done, files changed, blockers. No reasoning, no summaries. |
| **Ask when blocked** | If an agent can't proceed, it messages Orchestrator with the specific blocker — not a general status update. |
| **Orchestrator relays context** | If Frontend needs info about the API contract, Orchestrator asks API agent (or Explorer) and relays the answer. |
| **Explorer is Orchestrator's lens** | Orchestrator never searches the codebase itself. It asks Explorer to find what it needs. |
| **Reviewer talks last** | Reviewer only activates after implementation agents complete. Reports to Orchestrator who decides on fixes. |

### Mode B: Discussion Mode (Peer-to-Peer)

Agents message each other directly to debate, challenge, and build on findings. Orchestrator acts as moderator, not relay. **All discussion is logged to a shared file** as a permanent record.

```
┌────────────┐    ┌────────────┐
│ Panelist A ├────┤ Panelist B │
└─────┬──────┘    └──────┬─────┘
      │       ╲  ╱       │
      │        ╲╱        │
      │        ╱╲        │
      │       ╱  ╲       │
┌─────┴──────┐    ┌──────┴─────┐
│ Panelist C ├────┤ Panelist D │
└─────┬──────┘    └──────┬─────┘
      │                  │
      └───────┬──────────┘
         ┌────┴─────┐
         │MODERATOR │
         │ (opus)   │
         └──────────┘
              │
       ┌──────┴──────┐
       │ DISCUSSION  │
       │    LOG      │
       │ (temp/*.md) │
       └─────────────┘
```

**Use for:** Debugging with competing hypotheses, architecture decisions with tradeoffs, design reviews, any task where the goal is consensus through debate rather than parallel execution.

#### Discussion Log Setup

The Moderator creates a shared discussion log file that all panelists write to. This provides a permanent record of the conversation that would otherwise be lost.

**Log location:** `temp/discussions/{team-name}-{timestamp}.md`

**Moderator responsibilities:**
1. Create `temp/discussions/` directory if it doesn't exist
2. Create the log file with header before spawning panelists
3. Include the log file path in each panelist's spawn prompt
4. Append synthesis and consensus to the log at the end

**Log format:**
```markdown
# Discussion Log: {topic}

**Team:** {team-name}
**Started:** {ISO timestamp}
**Participants:** {comma-separated list}
**Question:** {the question being debated}

---

## Round 0: Research

(Panelists append their research findings here)

---

## Round 1: Present

(Panelists append their presentations here)

---

## Round 2: Debate

(Panelists append challenges and responses here)

---

## Consensus

(Moderator appends final synthesis here)
```

**Message signing format:**
```markdown
### [{Agent-Name}] - {Round N} - {HH:MM:SS}

{message content}

---
```

Example:
```markdown
### [Panelist-1] - Round 1 - 14:23:45

Based on my investigation of the authentication flow, I found evidence that
the session timeout is the root cause:

- `auth/session.ts:142` - timeout set to 30 seconds
- `middleware/auth.ts:89` - no session refresh on activity

I believe the bug is in the session timeout configuration.

---
```

**Handling concurrent writes:**
- Panelists must use the **Edit tool** to append, not the Write tool (which overwrites)
- Each panelist appends to their round's section using a unique signature header
- If two panelists write simultaneously, both entries will appear (order may vary)
- The timestamp in the signature helps establish chronological order
- Moderator can reorder entries during synthesis if needed

#### When to Offer Discussion Mode

Detect these signals in the user's request and offer discussion mode as an option:

| Signal | Example |
|--------|---------|
| **Multiple hypotheses** | "Figure out why X is happening" (root cause unknown) |
| **Tradeoff analysis** | "Should we use approach A or B?" |
| **Devil's advocate needed** | "Poke holes in this design" |
| **Consensus-seeking** | "What's the best way to handle X?" |
| **Investigation with unknowns** | "Users report X but we can't reproduce" |

If detected, present both options to the user:

```
This task could use either approach:

1. Hub-and-spoke (standard) — Orchestrator assigns investigation areas,
   agents report back, Orchestrator synthesizes.
2. Discussion mode — Agents investigate independently then debate each
   other's findings. Produces stronger conclusions through adversarial
   testing but uses more tokens (peer messages).

Which approach do you prefer?
```

#### Discussion Mode Rules

| Rule | Description |
|------|-------------|
| **Peer messaging allowed** | Agents message each other directly via `SendMessage` type `message`. |
| **Challenge, don't agree** | Agents must attempt to disprove other agents' conclusions before accepting them. |
| **Evidence required** | Every claim must reference specific files, lines, or logs. No speculation without evidence. |
| **Moderator synthesizes** | Orchestrator monitors the discussion and synthesizes the final consensus. Does not participate in the debate. |
| **Rounds are bounded** | Orchestrator sets a round limit (typically 2-3). After final round, Orchestrator calls for conclusions. |
| **Explorer still serves all** | Explorer remains available to any agent who needs codebase evidence during discussion. |
| **No code changes** | Discussion mode is read-only. If the conclusion requires implementation, switch to hub-and-spoke for the execution phase. |
| **Log all contributions** | Every panelist appends their findings, challenges, and responses to the shared discussion log with their signature. |
| **Moderator owns the log** | Moderator creates the log file, includes its path in spawn prompts, and appends the final consensus. |

#### Discussion Mode Lifecycle

```
1. Orchestrator creates temp/discussions/ folder and initializes log file with header
2. Orchestrator spawns Explorer + 3-5 panelists (Explore type, sonnet)
   - Each panelist's spawn prompt includes the log file path
3. Each panelist investigates independently (Round 0 — research)
   - Panelists append signed research notes to the log
4. Panelists share initial findings with each other (Round 1 — present)
   - Panelists append signed presentations to the log
5. Panelists challenge each other's findings (Round 2 — debate)
   - Panelists append signed challenges and responses to the log
6. Optional: Round 3 if no convergence
7. Orchestrator synthesizes consensus, appends to log, and reports to user
8. If implementation needed: switch to hub-and-spoke with the consensus as spec
```

#### Token Cost of Discussion Mode

Peer messages mean N agents can each send messages to N-1 others. With 4 panelists and 2 debate rounds, that's up to ~24 messages vs ~8 in hub-and-spoke. **Only use when the quality of the conclusion justifies the cost.** For straightforward debugging where the bug is likely in one place, hub-and-spoke is cheaper and sufficient.

## Token Optimization Rules

Baked into every agent's prompt to prevent wasteful behavior.

### All Agents

| Rule | Enforcement |
|------|-------------|
| **Think silently** | All reasoning happens in extended thinking. Output only results, decisions, and blockers. |
| **Scoped search** | Only search directories/files relevant to your task. Never glob `**/*` across the whole project. |
| **Read selectively** | Read specific files, not entire directories. If you need a function, grep for it — don't read the whole file hoping to find it. |
| **No exploratory browsing** | Don't read files "to understand the codebase." You get a file list from the Orchestrator. Work within it. |
| **Expand scope only when blocked** | If your assigned files aren't enough, message Orchestrator explaining what you need and why. Don't search on your own. |
| **Minimal output** | Report format: files changed, what was done, blockers if any. No summaries of what you read, no restating the task. |

### Orchestrator

| Rule | Enforcement |
|------|-------------|
| **Never search directly** | Use Explorer to find files, patterns, conventions. Opus tokens are expensive — don't spend them on grep. |
| **Provide file lists upfront** | Before assigning a task, use Explorer to identify the exact files the agent needs. Include them in the task assignment. |
| **Batch Explorer queries** | Ask Explorer multiple questions in one message rather than one at a time. |

### Explorer

| Rule | Enforcement |
|------|-------------|
| **Targeted searches** | Answer the specific question asked. Don't return extra context "just in case." |
| **Paths over content** | Return file paths and line numbers. Only include code snippets when specifically asked. |
| **Stop when answered** | Once you have the answer, stop searching. Don't keep looking for more matches. |

## Step 1: Analyze the Task

This is the most important step. Extract these dimensions before making any decisions:

### 1a. Identify the Work Units

Break the task into discrete pieces of work. Ask:
- What distinct things need to happen?
- Which pieces can happen in parallel vs must be sequential?
- Do any pieces need results from another piece?

### 1b. Map Work Units to Agents

```
Work unit involves...          → Spawn agent
─────────────────────────────────────────────
Codebase questions             → Explorer (always spawned)
React components/views/styling → Frontend
Rails models/controllers/logic → Backend
API endpoints/serializers      → API
Schema changes/migrations      → Database
Swift/SwiftUI code             → iOS
Kotlin/Compose code            → Android
User-facing text/labels        → Copywriter
Tests/debugging                → Debugger
Quality review                 → Reviewer (always spawned for implementation)
```

### 1c. Common Task-to-Team Mappings

| Task Type | Agents Spawned | Mode |
|-----------|---------------|------|
| Backend bug fix | Explorer + Backend + Debugger + Reviewer | Hub-and-spoke |
| New React feature | Explorer + Frontend + API + Reviewer | Hub-and-spoke |
| Full-stack feature | Explorer + Frontend + Backend + API + Reviewer | Hub-and-spoke |
| Cross-platform feature | Explorer + API + Frontend + iOS + Android + Reviewer | Hub-and-spoke |
| Database migration | Explorer + Database + Backend + Reviewer | Hub-and-spoke |
| UI polish / copy changes | Explorer + Frontend + Copywriter + Reviewer | Hub-and-spoke |
| Investigation / research | Explorer only (multiple queries) | Hub-and-spoke |
| Root cause unknown bug | Explorer + 3-5 panelists | **Offer discussion** |
| Architecture decision | Explorer + 3-4 panelists | **Offer discussion** |
| Design review / critique | Explorer + 3-4 panelists | **Offer discussion** |

### 1d. Produce a Recommendation

Present to the user before executing:

```
Analysis:
- Task breaks into N work units: [list them]
- [X] can run in parallel, [Y] are sequential
- Recommended approach: [single/parallel/team]

Agents:
- [agent] — [why needed]
- [agent] — [why needed]

Execution order:
1. Explorer maps relevant files
2. [task] (parallel with 3)
3. [task] (parallel with 2)
4. Reviewer validates all changes
```

## Step 2: Choose the Approach

### Single Agent
**When:** 1 work unit, or tightly coupled tasks where output of one feeds the next.

Use a single `Task` tool call with the right model. No team overhead.

### Parallel Subagents
**When:** 2+ independent tasks, no shared state, fire-and-forget.

Spawn multiple `Task` calls in a single message. Each runs independently and reports back. No `TeamCreate` needed.

### Full Team
**When any of these apply:**
- 3+ tasks needing coordination or handoffs
- Different specializations required
- Long-running work where agen

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ZoranSpirkovski](https://github.com/ZoranSpirkovski)
- **Source:** [ZoranSpirkovski/creating-agent-teams](https://github.com/ZoranSpirkovski/creating-agent-teams)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zoranspirkovski-creating-agent-teams-creating-agent-teams
- Seller: https://agentstack.voostack.com/s/zoranspirkovski
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.