agent-teams

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Teams

Agent 团队

Experimental: Agent teams require the
--enable-teams
flag and may change between Claude Code versions.

实验性功能：Agent 团队需要使用
--enable-teams
参数，且在不同 Claude Code 版本之间可能发生变动。

When to Use This Skill

何时使用该技能

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

当出现以下情况时使用Agent团队	当出现以下情况时改用子Agent
多个Agent需要并行工作	任务为顺序执行且相互依赖
需要Agent之间持续通信	单个聚焦任务仅产出一个结果
后台任务需要上报进度	Agent输出直接作为下一步的输入
复杂工作流需要任务协调	执行简单、有边界、相互隔离的任务
对同一代码库进行独立变更（使用worktree）	上下文共享高效且无问题

Core Concepts

核心概念

Team Architecture

团队架构

Lead Agent (orchestrator)
    ├── TeamCreate — creates team + shared task list
    ├── Task 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

Lead Agent (orchestrator)
    ├── TeamCreate — creates team + shared task list
    ├── Task 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

Native Team Tools

原生团队工具

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`	创建团队和共享任务列表目录
`TeamDelete`	所有工作完成后清理团队资源
`SendMessage`	发送私信、广播、关闭请求、方案审批
`TaskOutput`	获取后台Agent的输出
`TaskStop`	停止运行中的后台Agent

Team Setup Workflow

团队搭建工作流

1. Create the Team

1. 创建团队

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 directory

TeamCreate({
  team_name: "my-project",
  description: "Working on feature X"
})

该操作会创建：

```
~/.claude/teams/<team-name>/
```
— 团队配置目录
```
~/.claude/tasks/<team-name>/
```
— 共享任务列表目录

2. Create Initial Tasks

2. 创建初始任务

TaskCreate({
  team_name: "my-project",
  title: "Implement security review",
  description: "Audit auth module for vulnerabilities",
  status: "pending"
})

TaskCreate({
  team_name: "my-project",
  title: "Implement security review",
  description: "Audit auth module for vulnerabilities",
  status: "pending"
})

3. Spawn Teammates

3. 生成团队成员

Use the Task 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..."

使用Task工具为每个团队成员传入团队上下文生成实例：

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..."

4. Assign Tasks

4. 分配任务

TaskUpdate({
  team_name: "my-project",
  task_id: "task-1",
  owner: "security-reviewer",
  status: "in_progress"
})

TaskUpdate({
  team_name: "my-project",
  task_id: "task-1",
  owner: "security-reviewer",
  status: "in_progress"
})

5. Receive Results

5. 接收结果

Teammates send messages automatically — they are delivered to the lead's inbox between turns. No polling needed.

团队成员会自动发送消息，消息会在轮次间隙投递到负责人的收件箱，无需轮询。

Task Management

任务管理

Task States

任务状态

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

状态	含义
`pending`	尚未启动
`in_progress`	已分配且正在处理（每个成员同一时间仅处理一个任务）
`completed`	已成功完成
`blocked`	等待其他任务完成

Task Priority

任务优先级

Teammates should claim tasks in ID order (lowest first) — earlier tasks often set up context for later ones.

团队成员应按ID顺序（从小到大）认领任务——更早的任务通常会为后续任务搭建上下文。

TaskList Usage

TaskList 使用方式

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" })

团队成员完成每个任务后应查询

TaskList

以寻找可用工作：

TaskList({ team_name: "my-project" })
→ Returns all tasks with status, owner, and blocked-by info

认领未分配的任务：

TaskUpdate({ team_name: "my-project", task_id: "N", owner: "my-name" })

Communication (SendMessage)

通信（SendMessage）

Message Types

消息类型

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

类型	使用场景
`message`	给特定成员发送私信
`broadcast`	重要的全团队公告（谨慎使用——成本较高）
`shutdown_request`	请求成员优雅退出
`shutdown_response`	同意或拒绝关闭请求
`plan_approval_response`	同意或拒绝成员的方案

DM Example

私信示例

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: "message",
  recipient: "security-reviewer",  // Use NAME, not agent ID
  content: "Please also check the payment module",
  summary: "Adding payment module to scope"
})

Broadcast (use sparingly)

广播（谨慎使用）

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.

SendMessage({
  type: "broadcast",
  content: "Stop all work — critical blocker found in auth module",
  summary: "Critical blocker: halt work"
})

广播会给每个成员单独发送一条消息。如果有N个成员，就会产生N次API往返。请仅在真正的全团队阻塞场景下使用。

Teammate Behavior

团队成员行为规范

Discovering Team Members

查找团队成员

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.

读取团队配置以查找其他成员：

Read ~/.claude/teams/<team-name>/config.json
→ members array with name, agentId, agentType

在SendMessage的

recipient

字段中请始终使用name字段（而非agentId）。

Idle State

空闲状态

Teammates go idle after every turn — this is normal. Idle ≠ unavailable. Sending a message to an idle teammate wakes them.

团队成员在每个轮次结束后会进入空闲状态——这是正常现象。空闲≠不可用。向空闲成员发送消息即可唤醒。

Key Teammate Rules

团队成员核心规则

Mark exactly ONE task
```
in_progress
```
at a time
Use
```
TaskUpdate
```
(not
```
SendMessage
```
) to report task completion
System sends idle notifications automatically — no need for status JSON messages
All communication requires
```
SendMessage
```
— plain text output is NOT visible to the team lead

同一时间仅将一个任务标记为
```
in_progress
```
使用
```
TaskUpdate
```
（而非
```
SendMessage
```
）上报任务完成状态
系统会自动发送空闲通知——无需发送状态JSON消息
所有通信都需要使用
```
SendMessage
```
——纯文本输出对团队负责人不可见

Shutdown Procedures

关闭流程

Graceful Shutdown (Lead → Teammates)

优雅关闭（负责人→成员）

SendMessage({
  type: "shutdown_request",
  recipient: "security-reviewer",
  content: "All tasks complete, wrapping up"
})

SendMessage({
  type: "shutdown_request",
  recipient: "security-reviewer",
  content: "All tasks complete, wrapping up"
})

Teammate Approves Shutdown

成员同意关闭

SendMessage({
  type: "shutdown_response",
  request_id: "<id from shutdown_request JSON>",
  approve: true
})

SendMessage({
  type: "shutdown_response",
  request_id: "<id from shutdown_request JSON>",
  approve: true
})

Cleanup (Lead)

资源清理（负责人）

After all teammates shut down:

TeamDelete()
→ Removes ~/.claude/teams/<name>/ and ~/.claude/tasks/<name>/

TeamDelete fails if teammates are still active.

所有成员关闭后：

TeamDelete()
→ Removes ~/.claude/teams/<name>/ and ~/.claude/tasks/<name>/

如果仍有成员处于活跃状态，TeamDelete会执行失败。

Common Patterns

常见模式

Parallel Code Review

并行代码评审

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: "code-review"
Tasks: security-audit, performance-review, correctness-check
Teammates: security-agent, performance-agent, correctness-agent (all parallel)
Lead: collects results, synthesizes findings

Parallel Implementation with Worktrees

使用Worktree并行开发

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)

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)

Blocked Task Resolution

阻塞任务解决

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.

如果某个任务依赖其他任务，在TaskCreate中设置

blocked_by

字段。团队成员会查询TaskList，跳过阻塞任务直到依赖的任务完成。

Team Roles

团队角色

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

角色	行为	使用场景
负责人（Lead）	编排流程、分配任务、接收结果	始终需要——负责协调团队
团队成员（Teammate）	并行执行任务，支持消息通信	持续协作、进度上报场景
子Agent（Subagent）	聚焦、隔离执行，返回单个结果	简单有边界的任务，无需协调

Sandbox Considerations

沙箱注意事项

In web sessions (

CLAUDE_CODE_REMOTE=true

Sub-agents (teammates) may encounter TLS errors on
```
git push
```
— delegate all push/PR operations to the lead
Each teammate runs in its own process context
Worktree isolation is recommended for independent filesystem changes

在Web会话中（

CLAUDE_CODE_REMOTE=true

）：

子Agent（团队成员）执行
```
git push
```
时可能遇到TLS错误——将所有推送/PR操作交给负责人执行
每个成员运行在独立的进程上下文中
对于独立的文件系统变更，推荐使用Worktree隔离

Agentic Optimizations

Agent优化建议

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

场景	方案
快速并行评审	生成2-4个成员，广播任务分配
大型代码库拆分	将不同目录子集分配为独立任务
长期运行工作	后台运行成员，通过TaskList轮询状态
最小化API成本	优先使用 `message` 而非 `broadcast`
快速关闭	向每个成员发送shutdown_request，然后执行TeamDelete

Quick Reference

快速参考

Workflow Checklist

工作流检查清单

```
TeamCreate
```
with team name and description
```
TaskCreate
```
for each work unit
Spawn teammates via Agent tool with
```
team_name
```
and
```
name
```
```
TaskUpdate
```
to assign tasks to teammates (or let teammates self-assign)
Receive messages automatically; respond via
```
SendMessage
```
```
SendMessage shutdown_request
```
to each teammate when done
```
TeamDelete
```
after all teammates shut down

使用
```
TeamCreate
```
创建团队，填写团队名称和描述
为每个工作单元执行
```
TaskCreate
```
通过Agent工具生成成员，传入
```
team_name
```
和
```
name
```
参数
执行
```
TaskUpdate
```
为成员分配任务（或允许成员自行认领）
自动接收消息；通过
```
SendMessage
```
回复
任务完成后向每个成员发送
```
shutdown_request
```
所有成员关闭后执行
```
TeamDelete
```

Key Paths

关键路径

Path	Contents
`~/.claude/teams/<name>/config.json`	Team members (name, agentId, agentType)
`~/.claude/tasks/<name>/`	Shared task list directory

路径	内容
`~/.claude/teams/<name>/config.json`	团队成员信息（name、agentId、agentType）
`~/.claude/tasks/<name>/`	共享任务列表目录

Common Mistakes

常见错误

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

错误	正确做法
使用agentId作为收件人	使用config.json中的 `name` 字段
每次更新都发送广播	单收件人通信使用 `message`
轮询获取消息	消息会自动投递——只需等待
发送JSON状态消息	状态更新使用 `TaskUpdate` ，消息使用纯文本
子Agent推送到远程仓库	将推送操作交给负责人编排器执行
关闭前执行TeamDelete	先关闭所有成员