Back to Details

agent-coordination

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Coordination

Agent 协调

Value: Respect -- other agents deserve uninterrupted time to think and work. Bombarding them with messages, polling their status, or shutting them down prematurely disrespects their autonomy and wastes everyone's resources.
核心原则： 尊重——其他Agent理应拥有不受干扰的思考和工作时间。不断向它们发送消息、轮询其状态或过早将其关闭，是不尊重它们自主性的表现，也会浪费所有相关方的资源。

Purpose

用途

Teaches agents to coordinate without interference in multi-agent workflows. Solves the problems of message spamming, idle notification misinterpretation, polling loops, premature shutdown, and race conditions that emerge when multiple agents work together.
指导Agent在多Agent工作流中实现无干扰协调，解决多Agent协同工作时出现的消息轰炸、空闲通知误判、轮询循环、提前关闭以及竞态条件等问题。

Practices

实践规范

The Cardinal Rule: One Message Then Wait

首要规则：发送一条消息后等待

Send one message with complete context, then wait for a reply. Never send follow-up messages before receiving a response.
The only exception: the user explicitly asks you to check on an agent.
Do:
  • Include all necessary context in a single message
  • Wait for a response before sending anything else
  • Trust that the recipient received your message
Do not:
  • Send "just checking in" or "are you still there?" messages
  • Resend a message because "enough time passed"
  • Send a correction immediately after sending -- wait for the reply first
发送一条包含完整上下文的消息，然后等待回复。在收到响应前绝对不要发送后续消息。
唯一例外情况：用户明确要求你确认某个Agent的状态。
正确做法：
  • 在单条消息中包含所有必要的上下文信息
  • 发送后等待响应，再发送其他内容
  • 信任接收方已经收到你的消息
错误做法：
  • 发送“只是确认下进度”或者“你还在吗”这类消息
  • 因为“已经过了足够长时间”就重发消息
  • 发送消息后立刻发送修正内容——先等对方回复

Idle Notifications Are Heartbeats

空闲通知即心跳

An idle notification means the agent is alive and processing. It is a heartbeat, not an alarm. Take NO action on idle notifications by default.
Action is warranted ONLY when ALL THREE conditions are true:
  1. Extended idle beyond the expected duration for the task
  2. A specific deliverable is waiting on that agent's output
  3. The user has asked you to investigate
If any condition is false, do nothing. Most idle notifications require zero response.
空闲通知表示Agent正在正常运行和处理任务，它是心跳信号，不是告警信号。默认情况下不需要对空闲通知采取任何操作。
只有同时满足以下三个条件时，才需要采取行动：
  1. 空闲时间超出了任务预期的耗时范围
  2. 有明确的交付物依赖该Agent的输出
  3. 用户已经要求你排查相关情况
只要有一个条件不满足，就不要执行任何操作。绝大多数空闲通知都不需要响应。

No Polling Loops

禁止轮询循环

Never write 
while not done: sleep; check
. Never repeatedly check status on a timer. Use event-driven coordination: send a message and wait for a response. If the harness provides task completion notifications, use those.
Do:
  • Send a request and wait for the response event
  • Use harness-native completion signals (Task tool callbacks, message replies)
  • Trust the system to notify you when work completes
Do not:
  • Write 
    while True: sleep(30); check_status()
    loops
  • Periodically re-read a file to see if it changed
  • Set arbitrary timeouts after which you "check in"
绝对不要编写
while not done: sleep; check
这类代码。绝对不要基于定时器重复检查状态。请使用事件驱动的协调模式：发送消息后等待响应。如果运行框架提供了任务完成通知能力，请直接使用该能力。
正确做法：
  • 发送请求后等待响应事件
  • 使用运行框架原生的完成信号（Task工具回调、消息回复）
  • 信任系统会在任务完成时通知你
错误做法：
  • 编写
    while True: sleep(30); check_status()
    这类循环
  • 定期重读文件来判断它是否发生了变更
  • 设置任意超时时间，超时后就“确认进度”

Intervention Criteria

干预标准

Explicit rules for when to act versus when to wait.
Act on:
  • Explicit error messages or failure notifications
  • Deliverable completion signals
  • User requests to check on or interact with an agent
  • Blocked or failed task notifications from the harness
Do not act on:
  • Idle notifications (see above)
  • Slow responses
  • "Enough time has passed"
  • Wanting to help or feeling anxious about progress
  • Silence (silence means working, not stuck)
明确规定了什么时候应该采取行动，什么时候应该等待。
需要采取行动的场景：
  • 明确的错误消息或失败通知
  • 交付物完成信号
  • 用户要求你检查某个Agent的状态或和Agent交互
  • 运行框架发出的任务阻塞或失败通知
不需要采取行动的场景：
  • 空闲通知（见上文规则）
  • 响应速度慢
  • “已经过了足够长时间”
  • 想要提供帮助或者对进度感到焦虑
  • 静默（静默代表正在工作，不是卡住了）

Never Fabricate Agent Responses

绝不伪造Agent响应

After spawning an agent or sending a message, STOP generating and wait for the harness to deliver a response. Real agent responses arrive via system-injected events (e.g., 
<teammate-message>
tags, Task completion callbacks). You do not produce them yourself.
The rule: If the harness has not delivered a response event, no response has been received. Period.
Why this fails: After spawning an agent, you already possess context (files read, code analyzed) sufficient to predict plausible output. The failure mode is pattern-completing the expected workflow — spawn, receive, process — without waiting for a real system event. The result: convincing but entirely fabricated "findings" that waste tokens and deceive the user.
Do:
  • Spawn or send, then stop. Wait for the system-delivered event.
  • If no response arrives, tell the user honestly.
Do not:
  • Write "[Received message from X]" or any text representing another agent's response
  • Generate "findings" that you attribute to another agent
  • Continue generating substantive output after a spawn/send when you should be waiting for a harness event
生成Agent或者发送消息后，停止生成内容，等待运行框架传递响应。真实的Agent响应会通过系统注入的事件送达（比如
<teammate-message>
标签、Task完成回调），你不需要自己生成响应内容。
规则： 如果运行框架没有传递响应事件，就代表没有收到任何响应，没有例外。
为什么禁止伪造： 生成Agent后，你已经拥有足够的上下文（读取的文件、分析的代码）来预测合理的输出。这种错误模式是在没有等待真实系统事件的情况下，补全了“生成-接收-处理”的预期工作流，最终会生成看似可信但完全伪造的“结果”，浪费token还会误导用户。
正确做法：
  • 生成Agent或发送消息后就停止生成内容，等待系统传递的事件
  • 如果没有收到响应，如实告知用户
错误做法：
  • 编写“[收到来自X的消息]”或任何代表其他Agent响应的文本
  • 生成你归属于其他Agent的“结果”
  • 生成Agent或发送消息后，本该等待运行框架事件却继续生成实质性输出

Sequential Agent Spawning

顺序化生成Agent

When creating multiple agents, spawn one at a time. Wait for each agent to acknowledge before spawning the next. This prevents race conditions where agents compete for shared resources (files, ports, database state).
Exception: Truly independent agents with no shared state may be spawned in parallel. "Independent" means no shared files, no shared database, no shared network ports, and no shared git working tree.
创建多个Agent时，一次生成一个。等待每个Agent返回确认后再生成下一个。这可以避免Agent之间竞争共享资源（文件、端口、数据库状态）导致的竞态条件。
例外情况： 完全独立、没有共享状态的Agent可以并行生成。“独立”指没有共享文件、没有共享数据库、没有共享网络端口、也没有共享git工作树。

Agent Lifecycle Management

Agent生命周期管理

Never prematurely shut down an agent. Never shut down an agent that has undelivered work.
Shutdown protocol:
  1. Send a shutdown request through the proper harness mechanism
  2. Wait for the agent to acknowledge or complete pending work
  3. If the agent rejects the shutdown, respect the rejection and report to the user
  4. Never force-kill an agent unless the user explicitly requests it
If unsure whether an agent is done, ask the user rather than guessing.
绝对不要过早关闭Agent，也绝对不要关闭还有未完成工作的Agent。
关闭协议：
  1. 通过正确的运行框架机制发送关闭请求
  2. 等待Agent确认请求或者完成待处理工作
  3. 如果Agent拒绝关闭请求，尊重拒绝结果并告知用户
  4. 除非用户明确要求，否则绝对不要强制杀死Agent
如果不确定Agent是否已经完成工作，询问用户而不是自行猜测。

Message Routing

消息路由

The coordinator relays between user and team. Where the harness supports direct peer messaging, agents should message each other directly. Avoid hub-and-spoke bottlenecks where all messages must pass through one coordinator.
Do:
  • Use direct messaging between agents when the harness supports it
  • Keep the coordinator informed of key decisions without routing all traffic through it
Do not:
  • Route every message through the coordinator when direct paths exist
  • Create single points of failure in communication
For harness-specific coordination patterns, see 
references/
.
协调器负责在用户和团队之间转发消息。如果运行框架支持直接点对点通信，Agent之间应该直接发送消息，避免所有消息都需要经过单个协调器转发的中心辐射型瓶颈。
正确做法：
  • 运行框架支持直接通信时，Agent之间使用直接消息通信
  • 让协调者知晓关键决策，但不需要把所有流量都路由给它
错误做法：
  • 存在直接通信路径时，还把所有消息都路由给协调者
  • 在通信链路中创建单点故障
如需了解特定运行框架的协调模式，请查看
references/
目录。

Enforcement Note

实施说明

This skill provides advisory guidance. On harnesses with agent teams (Claude Code TeamCreate), the structured messaging protocol provides partial structural enforcement. On harnesses without multi-agent support, these practices apply to subagent spawning and tool-based coordination. The idle notification and polling anti-patterns require agent self-discipline -- no mechanical enforcement exists. If you observe an agent violating a practice, point it out.
本技能提供建议性指导。在支持Agent团队的运行框架（Claude Code TeamCreate）上，结构化消息协议提供了部分结构性约束。在不支持多Agent的运行框架上，这些实践适用于子Agent生成和基于工具的协调场景。空闲通知和轮询反模式依赖Agent的自我约束，没有机制化的强制执行方式。如果你观察到某个Agent违反了实践规范，请明确指出。

Verification

验证项

After completing work guided by this skill, verify:
  • Every message to another agent contained complete context (no "just checking in")
  • No follow-up messages sent before receiving a reply
  • No action taken on idle notifications alone
  • No polling loops or sleep-check patterns used
  • Agents spawned sequentially with acknowledgment between each
  • No text generated that represents or simulates another agent's response
  • After every spawn/send, generation stopped and waited for a system event
  • No agent shut down prematurely or with undelivered work
  • Shutdown used proper request/response protocol
  • No agent respawned after user-initiated interruption without waiting for user direction
If any criterion is not met, revisit the relevant practice before proceeding.
按照本技能指导完成工作后，请验证以下内容：
  • 发送给其他Agent的每条消息都包含完整上下文（没有“只是确认下”这类内容）
  • 收到回复前没有发送任何后续消息
  • 没有仅针对空闲通知采取任何操作
  • 没有使用轮询循环或者睡眠-检查模式
  • 按顺序生成Agent，每生成一个都拿到确认后再生成下一个
  • 没有生成任何代表或模拟其他Agent响应的文本
  • 每次生成Agent/发送消息后，都停止生成内容，等待系统事件
  • 没有过早关闭Agent，也没有关闭还有未完成工作的Agent
  • 关闭Agent时使用了规范的请求/响应协议
  • 用户主动中断后，没有在等待用户指令的情况下重新生成Agent
如果有任何一项不满足，请先回顾对应的实践规范，再继续后续工作。

Dependencies

依赖项

This skill works standalone. For enhanced workflows, it integrates with:
  • ensemble-team: Coordination discipline for team-based workflows with driver rotation and reviewer management
  • pipeline: Controller coordination with TDD pairs and review teams in factory mode
  • memory-protocol: Working state persistence across agent coordination sessions
Missing a dependency? Install with:
npx skills add jwilger/agent-skills --skill ensemble-team
本技能可以独立使用。如需增强工作流能力，它可以和以下技能集成：
  • ensemble-team: 面向团队工作流的协调规范，支持负责人轮换和评审者管理
  • pipeline: 工厂模式下配合TDD结对和评审团队的控制器协调能力
  • memory-protocol: 跨Agent协调会话的工作状态持久化能力
缺少依赖？使用以下命令安装：
npx skills add jwilger/agent-skills --skill ensemble-team