# Claude Teams

> Guide for coordinating multiple Claude Code agents as teams. Use when setting up agent teams, configuring subagents, orchestrating multi-agent workflows, or building programmatic agent systems with the Claude Agent SDK.

- Skill: `vinnie357/claude-teams` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add vinnie357/claude-teams`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vinnie357/claude-teams/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: vinnie357 (https://skillmd.com/u/vinnie357)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/vinnie357/claude-teams

---


# Claude Teams

Coordinate multiple Claude Code agents working together on shared tasks.

## When forming a team

Invoke `/core:agent-loop` for the 4-phase / 6-tier execution model.
Invoke `/claude-code:claude-agents` for agent file format, tool allowlists, and model selection.
Invoke `/core:anti-fabrication` always — every claim about a tool, file, or test result requires tool execution.

Require each teammate to quote one sentence from each loaded skill in its first message as proof of loading. Do not proceed with the teammate's work until proof is received.

Glob patterns like `/core:*` do not expand in Agent prompts. List skill names explicitly.

## Approaches

Three approaches exist for multi-agent coordination, each with different trade-offs:

| Approach | Communication | Coordination | Best For |
|----------|--------------|--------------|----------|
| **Agent Teams** | Peer-to-peer messaging + shared task list | Team lead + self-coordination | Collaborative work requiring discussion |
| **Subagents** | Report back to parent only | Parent manages all | Focused delegated tasks |
| **Agent SDK** | Programmatic message streaming | Developer-controlled | CI/CD, automation, custom apps |

## Agent Teams (Experimental)

First-party multi-agent coordination. A team lead spawns teammates that work independently with peer-to-peer messaging and a shared task list.

Enable with: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`

For setup, configuration, and usage details, see `references/agent-teams.md`.

## Subagents (Task Tool)

Lightweight delegation within a single session. Subagents run in their own context window, complete a task, and return results to the parent.

For subagent types, custom agents, and isolation patterns, see `references/subagents.md`.

## Agent SDK

Programmatic multi-agent orchestration in Python and TypeScript using the same tools that power Claude Code.

For SDK setup, agent definitions, and session management, see `references/agent-sdk.md`.

## Multi-Agent Patterns

Proven patterns for file ownership, task decomposition, scaling, and quality gates.

For architecture guidance and case studies, see `references/patterns.md`.

## Orchestration primitives

`/core:agent-loop` defines the decomposition + delegation flow. Four Claude Code primitives compose with it for long-running or recurring work:

| Primitive | Use when |
|---|---|
| `/loop <prompt>` | You want a self-pacing tick: monitor agents, poll the tracker, advance the queue. Auto-paces via ScheduleWakeup. |
| Routines | Cron-style scheduled remote agents. Use for daily/weekly autonomous runs. |
| Channels | Event-driven (webhook/integration) entry points. Use when an external system kicks the loop. |
| Workflows | Fan-out exceeds one turn, the orchestration itself must be repeatable, or results need independent verification passes — see `/claude-code:claude-workflows`. |

Workflows require explicit opt-in and run in the background; `/core:agent-loop` "Optional: workflow execution substrate" defines how the five-tier pipeline maps onto them.

### /loop example — shepherd a running epic

After dispatching a team for an epic, the operator session runs:

```
/loop /shepherd
```

where `/shepherd` is a project-defined command (not shipped with this plugin — define it in your project's `.claude/commands/`) that, each tick:

1. Reads bees/tracker state for the epic's issues
2. Promotes ready issues to in_progress
3. Notifies the operator if any agent transitioned to a review or needs_help state
4. Halts and pings via PushNotification when the cohort is complete

The `/loop` harness auto-paces via ScheduleWakeup (default 270s — stays inside the prompt-cache TTL). The operator session is hands-off until the loop fires a notification.

This is the recommended composition for long-running multi-agent work: `/core:agent-loop` does the per-spawn discipline; `/loop` does the queue advancement.