team-communication-protocols

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Team Communication Protocols

Agent团队通信协议

Protocols for effective communication between agent teammates, including message type selection, plan approval workflows, shutdown procedures, and common anti-patterns to avoid.

适用于Agent队友间高效通信的协议，包括消息类型选择、计划审批工作流、关闭流程以及需要避免的常见反模式。

When to Use This Skill

何时使用此技能

Establishing communication norms for a new team
Choosing between message types (message, broadcast, shutdown_request)
Handling plan approval workflows
Managing graceful team shutdown
Discovering teammate identities and capabilities

为新团队建立通信规范
在消息类型（message、broadcast、shutdown_request）之间进行选择
处理计划审批工作流
管理团队优雅关闭
发现队友的身份和能力

Message Type Selection

消息类型选择

message

(Direct Message) — Default Choice

message

（直接消息）—— 默认选择

Send to a single specific teammate:

json

{
  "type": "message",
  "recipient": "implementer-1",
  "content": "Your API endpoint is ready. You can now build the frontend form.",
  "summary": "API endpoint ready for frontend"
}

Use for: Task updates, coordination, questions, integration notifications.

发送给单个特定队友：

json

{
  "type": "message",
  "recipient": "implementer-1",
  "content": "Your API endpoint is ready. You can now build the frontend form.",
  "summary": "API endpoint ready for frontend"
}

适用场景：任务更新、协调沟通、问题咨询、集成通知。

broadcast

— Use Sparingly

broadcast

— 谨慎使用

Send to ALL teammates simultaneously:

json

{
  "type": "broadcast",
  "content": "Critical: shared types file has been updated. Pull latest before continuing.",
  "summary": "Shared types updated"
}

Use ONLY for: Critical blockers affecting everyone, major changes to shared resources.

Why sparingly?: Each broadcast sends N separate messages (one per teammate), consuming API resources proportional to team size.

同时发送给所有队友：

json

{
  "type": "broadcast",
  "content": "Critical: shared types file has been updated. Pull latest before continuing.",
  "summary": "Shared types updated"
}

仅适用于：影响所有人的关键阻塞问题、共享资源的重大变更。

为何要谨慎使用？：每条broadcast会发送N条独立消息（每个队友一条），消耗的API资源与团队规模成正比。

shutdown_request

— Graceful Termination

shutdown_request

— 优雅终止

Request a teammate to shut down:

json

{
  "type": "shutdown_request",
  "recipient": "reviewer-1",
  "content": "Review complete, shutting down team."
}

The teammate responds with

shutdown_response

(approve or reject with reason).

请求队友关闭：

json

{
  "type": "shutdown_request",
  "recipient": "reviewer-1",
  "content": "Review complete, shutting down team."
}

队友会回复

shutdown_response

（批准或附带理由拒绝）。

Communication Anti-Patterns

通信反模式

Anti-Pattern	Problem	Better Approach
Broadcasting routine updates	Wastes resources, noise	Direct message to affected teammate
Sending JSON status messages	Not designed for structured data	Use TaskUpdate to update task status
Not communicating at integration points	Teammates build against stale interfaces	Message when your interface is ready
Micromanaging via messages	Overwhelms teammates, slows work	Check in at milestones, not every step
Using UUIDs instead of names	Hard to read, error-prone	Always use teammate names
Ignoring idle teammates	Wasted capacity	Assign new work or shut down

反模式	问题点	更佳做法
广播常规更新内容	浪费资源、产生噪音	给受影响的队友发送直接消息
发送JSON状态消息	并非为结构化数据设计	使用TaskUpdate来更新任务状态
在集成节点不进行通信	队友基于过时的接口进行开发	当你的接口准备就绪时发送消息通知
通过消息进行微观管理	让队友不堪重负、拖慢工作进度	在里程碑节点检查，而非每一步都跟进
使用UUID而非名称	难以阅读、容易出错	始终使用队友的名称
忽略闲置的队友	浪费产能	分配新工作或关闭该队友

Plan Approval Workflow

计划审批工作流

When a teammate is spawned with

plan_mode_required

Teammate creates a plan using read-only exploration tools
Teammate calls
```
ExitPlanMode
```
which sends a
```
plan_approval_request
```
to the lead
Lead reviews the plan
Lead responds with
```
plan_approval_response
```
:

Approve:

json

{
  "type": "plan_approval_response",
  "request_id": "abc-123",
  "recipient": "implementer-1",
  "approve": true
}

Reject with feedback:

json

{
  "type": "plan_approval_response",
  "request_id": "abc-123",
  "recipient": "implementer-1",
  "approve": false,
  "content": "Please add error handling for the API calls"
}

当某个队友以

plan_mode_required

模式启动时：

队友使用只读探索工具创建计划
队友调用
```
ExitPlanMode
```
，向负责人发送
```
plan_approval_request
```
负责人审核计划
负责人回复
```
plan_approval_response
```
：

批准：

json

{
  "type": "plan_approval_response",
  "request_id": "abc-123",
  "recipient": "implementer-1",
  "approve": true
}

附带反馈的拒绝：

json

{
  "type": "plan_approval_response",
  "request_id": "abc-123",
  "recipient": "implementer-1",
  "approve": false,
  "content": "Please add error handling for the API calls"
}

Shutdown Protocol

关闭协议

Graceful Shutdown Sequence

优雅关闭流程

Lead sends shutdown_request to each teammate
Teammate receives request as a JSON message with
```
type: "shutdown_request"
```
Teammate responds with
```
shutdown_response
```
:
- ```
approve: true
```
  — Teammate saves state and exits
- ```
approve: false
```
  + reason — Teammate continues working
Lead handles rejections — Wait for teammate to finish, then retry
After all teammates shut down — Call
```
Teammate
```
cleanup

负责人向每个队友发送shutdown_request
队友收到请求，格式为
```
type: "shutdown_request"
```
的JSON消息
队友回复
```
shutdown_response
```
：
- ```
approve: true
```
  — 队友保存状态并退出
- ```
approve: false
```
  + 理由 — 队友继续工作
负责人处理拒绝请求 — 等待队友完成当前任务后重试
所有队友关闭后 — 调用
```
Teammate
```
清理操作

Handling Rejections

处理拒绝请求

If a teammate rejects shutdown:

Check their reason (usually "still working on task")
Wait for their current task to complete
Retry shutdown request
If urgent, user can force shutdown

如果某个队友拒绝关闭：

查看其拒绝理由（通常是“仍在处理任务”）
等待其完成当前任务
重试关闭请求
若情况紧急，用户可强制关闭

Teammate Discovery

队友发现

Find team members by reading the config file:

Location:

~/.claude/teams/{team-name}/config.json

Structure:

json

{
  "members": [
    {
      "name": "security-reviewer",
      "agentId": "uuid-here",
      "agentType": "team-reviewer"
    },
    {
      "name": "perf-reviewer",
      "agentId": "uuid-here",
      "agentType": "team-reviewer"
    }
  ]
}

Always use
name
for messaging and task assignment. Never use

agentId

directly.

通过读取配置文件查找团队成员：

位置：

~/.claude/teams/{team-name}/config.json

结构：

json

{
  "members": [
    {
      "name": "security-reviewer",
      "agentId": "uuid-here",
      "agentType": "team-reviewer"
    },
    {
      "name": "perf-reviewer",
      "agentId": "uuid-here",
      "agentType": "team-reviewer"
    }
  ]
}

**始终使用

name

**进行消息发送和任务分配。切勿直接使用

agentId

。",

team-communication-protocols

Original

Translation

Team Communication Protocols

Agent团队通信协议

When to Use This Skill

何时使用此技能

Message Type Selection

消息类型选择

`message`
(Direct Message) — Default Choice

`message`
（直接消息）—— 默认选择

`broadcast`
— Use Sparingly

`broadcast`
— 谨慎使用

`shutdown_request`
— Graceful Termination

`shutdown_request`
— 优雅终止

Communication Anti-Patterns

通信反模式

Plan Approval Workflow

计划审批工作流

Shutdown Protocol

关闭协议

Graceful Shutdown Sequence

优雅关闭流程

Handling Rejections

处理拒绝请求

Teammate Discovery

队友发现

team-communication-protocols

Original

Translation

Team Communication Protocols

Agent团队通信协议

When to Use This Skill

何时使用此技能

Message Type Selection

消息类型选择

message (Direct Message) — Default Choice

message（直接消息）—— 默认选择

broadcast — Use Sparingly

broadcast — 谨慎使用

shutdown_request — Graceful Termination

shutdown_request — 优雅终止

Communication Anti-Patterns

通信反模式

Plan Approval Workflow

计划审批工作流

Shutdown Protocol

关闭协议

Graceful Shutdown Sequence

优雅关闭流程

Handling Rejections

处理拒绝请求

Teammate Discovery

队友发现

`message`
(Direct Message) — Default Choice

`message`
（直接消息）—— 默认选择

`broadcast`
— Use Sparingly

`broadcast`
— 谨慎使用

`shutdown_request`
— Graceful Termination

`shutdown_request`
— 优雅终止