Orchestrates Claude Code agent teams for parallel multi-agent workflows on complex tasks using TeamCreate, SendMessage, TaskUpdate, and shared task lists. Enable with --enable-teams flag.
npx claudepluginhub laurigates/claude-plugins --plugin agent-patterns-pluginThis skill is limited to using the following tools:
> **Experimental**: Agent teams require the `--enable-teams` flag and may change between Claude Code versions.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.
Experimental: Agent teams require the
--enable-teamsflag and may change between Claude Code versions.
| Use agent teams when... | Use subagents instead when... |
|---|---|
| Multiple agents need to work in parallel | Tasks are sequential and interdependent |
| Ongoing communication between agents is needed | One focused task produces one result |
| Background tasks need progress reporting | Agent output feeds directly into next step |
| Complex workflows benefit from task coordination | Simple, bounded, isolated execution |
| Independent changes to the same codebase (with worktrees) | Context sharing is fine and efficient |
Lead Agent (orchestrator)
├── TeamCreate — creates team + shared task list
├── Agent tool — spawns teammate agents
├── SendMessage — communicates with teammates
├── TaskUpdate — assigns tasks to teammates
└── Teammates (run in parallel)
├── Read team config from ~/.claude/teams/<name>/config.json
├── TaskList/TaskUpdate — claim and complete tasks
└── SendMessage — report back to lead
| Tool | Purpose |
|---|---|
TeamCreate | Create team and shared task list directory |
TeamDelete | Clean up team when all work is complete |
SendMessage | Send DMs, broadcasts, shutdown requests, plan approvals |
TaskOutput | Get output from a background agent |
TaskStop | Stop a running background agent |
TeamCreate({
team_name: "my-project",
description: "Working on feature X"
})
This creates:
~/.claude/teams/<team-name>/ — team config directory~/.claude/tasks/<team-name>/ — shared task list directoryTaskCreate({
team_name: "my-project",
title: "Implement security review",
description: "Audit auth module for vulnerabilities",
status: "pending"
})
Use the Agent tool to spawn each teammate with the team context:
Agent tool with:
subagent_type: "agents-plugin:security-audit"
team_name: "my-project"
name: "security-reviewer"
prompt: "Join team my-project and work on security review task..."
TaskUpdate({
team_name: "my-project",
task_id: "task-1",
owner: "security-reviewer",
status: "in_progress"
})
Teammates send messages automatically — they are delivered to the lead's inbox between turns. No polling needed.
| State | Meaning |
|---|---|
pending | Not yet started |
in_progress | Assigned and active (one at a time per teammate) |
completed | Finished successfully |
blocked | Waiting on another task |
Teammates should claim tasks in ID order (lowest first) — earlier tasks often set up context for later ones.
Teammates should check TaskList after completing each task to find available work:
TaskList({ team_name: "my-project" })
→ Returns all tasks with status, owner, and blocked-by info
Claim an unassigned task:
TaskUpdate({ team_name: "my-project", task_id: "N", owner: "my-name" })
| Type | Use When |
|---|---|
message | Direct message to a specific teammate |
broadcast | Critical team-wide announcement (use sparingly — expensive) |
shutdown_request | Ask a teammate to gracefully exit |
shutdown_response | Approve or reject a shutdown request |
plan_approval_response | Approve or reject a teammate's plan |
SendMessage({
type: "message",
recipient: "security-reviewer", // Use NAME, not agent ID
content: "Please also check the payment module",
summary: "Adding payment module to scope"
})
SendMessage({
type: "broadcast",
content: "Stop all work — critical blocker found in auth module",
summary: "Critical blocker: halt work"
})
Broadcasting sends a separate delivery to every teammate. With N teammates, that's N API round-trips. Reserve for genuine team-wide blockers.
Read the team config to find other members:
Read ~/.claude/teams/<team-name>/config.json
→ members array with name, agentId, agentType
Always use the name field (not agentId) for recipient in SendMessage.
Teammates go idle after every turn — this is normal. Idle ≠ unavailable. Sending a message to an idle teammate wakes them.
in_progress at a timeTaskUpdate (not SendMessage) to report task completionSendMessage — plain text output is NOT visible to the team leadSendMessage({
type: "shutdown_request",
recipient: "security-reviewer",
content: "All tasks complete, wrapping up"
})
SendMessage({
type: "shutdown_response",
request_id: "<id from shutdown_request JSON>",
approve: true
})
After all teammates shut down:
TeamDelete()
→ Removes ~/.claude/teams/<name>/ and ~/.claude/tasks/<name>/
TeamDelete fails if teammates are still active.
TeamCreate: "code-review"
Tasks: security-audit, performance-review, correctness-check
Teammates: security-agent, performance-agent, correctness-agent (all parallel)
Lead: collects results, synthesizes findings
TeamCreate: "feature-impl"
Tasks: backend-api, frontend-ui, tests
Teammates: each spawned with isolation: "worktree"
Lead: delegates git push (sub-agents must not push independently in sandbox)
If a task is blocked on another, set the blocked_by field in TaskCreate. Teammates check TaskList and skip blocked tasks until the blocking task is completed.
| Role | Behavior | When to Use |
|---|---|---|
| Lead | Orchestrates, assigns tasks, receives results | Always — coordinates the team |
| Teammate | Parallel execution with messaging | Ongoing collaboration, progress reporting |
| Subagent | Focused, isolated, returns single result | Simple bounded tasks, no coordination needed |
In web sessions (CLAUDE_CODE_REMOTE=true):
git push — delegate all push/PR operations to the lead| Context | Approach |
|---|---|
| Quick parallel review | Spawn 2–4 teammates, broadcast task assignments |
| Large codebase split | Assign directory subsets as separate tasks |
| Long-running work | Background teammates, poll via TaskList |
| Minimize API cost | Prefer message over broadcast |
| Fast shutdown | Send shutdown_request to each teammate, then TeamDelete |
TeamCreate with team name and descriptionTaskCreate for each work unitteam_name and nameTaskUpdate to assign tasks to teammates (or let teammates self-assign)SendMessageSendMessage shutdown_request to each teammate when doneTeamDelete after all teammates shut down| Path | Contents |
|---|---|
~/.claude/teams/<name>/config.json | Team members (name, agentId, agentType) |
~/.claude/tasks/<name>/ | Shared task list directory |
| Mistake | Correct Approach |
|---|---|
| Using agentId as recipient | Use name field from config.json |
| Sending broadcast for every update | Use message for single-recipient comms |
| Polling for messages | Messages delivered automatically — just wait |
| Sending JSON status messages | Use TaskUpdate for status, plain text for messages |
| Sub-agent pushes to remote | Delegate push to lead orchestrator |
| TeamDelete before shutdown | Shutdown all teammates first |
.claude/rules/agent-development.md — agent file structure, model selection, worktree isolation.claude/rules/agentic-permissions.md — granular tool permission patterns.claude/rules/sandbox-guidance.md — web sandbox constraints and push delegation