long-task-coordinator

long-task-coordinator 技能概览

long-task-coordinator 是做什么的

long-task-coordinator 是一个面向长周期任务协作的协调技能，适合那些需要跨中断、跨交接、跨多轮间隔仍能继续推进的工作。它的核心作用很直接：把长期运行的工作从脆弱的聊天记忆里移出来，落到一个可持久保存的状态文件中，并通过明确的状态流转、恢复检查和下一步追踪来保证任务可继续、可核对。

谁适合安装它

这个技能最适合做 agent orchestration、委派式调研、迁移项目、批处理任务，或任何可能需要暂停、稍后恢复、等待其他 worker 返回结果的工作流。如果你的日常流程里经常出现“明天再接着做”或“先派出去，稍后回来检查”的场景，那么 long-task-coordinator 会非常契合。

用户真正要解决的问题

用户安装 long-task-coordinator，并不只是为了“把计划写得更好”。他们安装它，是为了让长任务真正具备可恢复性，而且过程记录足够诚实：

• 在上下文丢失后恢复状态
• 在 coordinator 和 workers 之间追踪责任归属
• 明确表示“正在等待”的状态
• 避免错误宣称任务已完成
• 在恢复工作时依赖已保存的真实状态，而不是靠回忆之前的聊天内容猜测

它和普通规划提示词的区别

long-task-coordinator 的差异点不在领域知识，而在工作流纪律：

• 一个持久化状态文件
• 一个固定循环：READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END
• 明确的状态，例如 running、awaiting-result、paused、blocked 和 complete
• 优先先持久化、再汇报，这样下一次会话才能可靠恢复

最适合与不适合的场景

当任务会跨多个会话、涉及 subagents 或后台任务、或者需要检查点和重试机制时，就应使用 long-task-coordinator。如果只是一个很小的一次性任务，就没必要上这个技能。仓库里也明确把更轻量的规划场景引导到 planning-with-files，而不是在不需要恢复能力时平白增加长任务协调的额外负担。

如何使用 long-task-coordinator 技能

long-task-coordinator 的安装方式

仓库 README 展示了手动安装方式：通过软链接把这个技能挂到你的 client skill 目录中，例如：

ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.claude/skills/long-task-coordinator
ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.codex/skills/long-task-coordinator
ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.gemini/skills/long-task-coordinator

如果你使用的是 skill manager，要确认最终安装路径暴露出来的仍然是实际的 skills/long-task-coordinator 目录内容，而不只是整个 repo 根目录。

优先阅读这些文件

如果你想快速但稳妥地上手 long-task-coordinator，建议按下面顺序阅读：

1. skills/long-task-coordinator/SKILL.md
2. skills/long-task-coordinator/references/workflow.md
3. skills/long-task-coordinator/evals/prompts.md
4. skills/long-task-coordinator/README.md

这个顺序之所以有效：

• SKILL.md 定义了触发条件和核心规则
• references/workflow.md 给出了真正可落地的状态文件模式
• evals/prompts.md 展示了“正确行为”应该长什么样
• README.md 用来确认安装方式和核心循环

这个技能需要什么输入

当你提供以下信息时，long-task-coordinator 的表现通常最好：

• 任务目标
• 明确的成功标准
• 当前工作是否已经在进行中
• 持久化状态文件应该放在哪里
• 是否已有正在工作的 worker 或 subagent 分配
• 下一个检查点的触发条件，比如时间或某个状态
• 已知的阻塞项或依赖关系

没有这些信息，模型仍然可以启动，但它会做出更多假设，最终产出的协调记录也会更弱。

把模糊请求改成高质量调用

较弱的请求：

Help me keep track of this migration.

更好的请求：

Use long-task-coordinator for this migration. Create or recover a durable state file at docs/migration-state.md. Goal: migrate service auth to OAuth2. Success criteria: tests pass, rollout notes written, old auth path disabled. We may hand work to subagents and resume across sessions. If any work is in flight, use an explicit waiting state instead of implying failure.

更强的版本之所以更好，是因为它一开始就明确了持久化方式、任务范围、完成逻辑和协调风格。

尽早创建持久化状态文件

使用 long-task-coordinator 时，最关键的操作习惯，就是在任务变复杂之前先把状态文件建起来。参考文档推荐的路径模式包括：

• docs/<topic>-execution-plan.md
• docs/<topic>-state.md
• worklog/<topic>-state.md

至少要持久化这些信息：

• Goal
• Success criteria
• Status
• Current step
• Completed work
• Next action
• Next checkpoint
• Blockers
• Owners

这是采用 long-task-coordinator 的关键点：如果你跳过状态文件，这个技能的大部分价值都会直接流失。

每一轮都走恢复循环

仓库定义的核心循环，就是 long-task-coordinator 实际使用中的关键机制：

READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END

放到实际工作里，意思就是：

1. 先读取已保存状态
2. 验证当前状态是否仍然成立
3. 检查委派出去的工作是否已经返回
4. 决定是继续、等待、重试、暂停还是关闭
5. 写回更新后的状态
6. 然后才向用户汇报

正是这个顺序，保证了下一次会话仍然可以恢复。

使用明确状态，尤其是 awaiting-result

这个技能一个细微但非常有价值的点，就是使用 awaiting-result。很多 agent 会伪造进展：一个任务明明只是已经派出、仍在处理中，却被描述成“失败了”或“做完了”。long-task-coordinator 提供了更干净的状态模型：

• running：coordinator 正在主动推进
• awaiting-result：worker 或 job 仍在执行、结果未回
• paused：有意暂停
• blocked：因外部约束无法推进
• complete：只有在成功标准真正满足时才能使用

对于 Agent Orchestration 来说，这是整个 long-task-coordinator 技能里最有用的区分之一。

面向委派工作的推荐流程

一个比较好的运行模式是：

1. 定义任务和成功标准
2. 创建状态文件
3. 把边界清晰的工作分配给 worker
4. 记录 owner 和预期返回条件
5. 如果在等待结果，就把状态设为 awaiting-result
6. 恢复时依赖状态文件，而不是记忆
7. 更新已完成事项和下一步动作
8. 只有在检查过标准之后，才标记为 complete

相比开放式的“继续做下去”提示，这种方式更安全，因为交接过程可审计、可追踪。

实用且效果好的提示词模式

高质量的 long-task-coordinator 使用提示，通常都会带上恢复语义。比如：

• “Use long-task-coordinator and recover from any existing state before proposing next steps.”
• “Persist the updated status before reporting.”
• “If a worker is still in flight, mark awaiting-result and define the next checkpoint.”
• “Do not mark complete unless the saved state and success criteria agree.”

这些模式与仓库里的 eval prompts 直接对齐，也能有效减少“看起来很确定、实际并不可靠”的输出。

常见采用错误

大多数失败案例并不是因为功能不够，而是流程上出了问题：

• 依赖聊天记录，而不是文件
• 用模糊的状态描述，而不是预定义状态
• 先汇报进展，再更新已保存状态
• 委派工作时没有记录 owner
• 没检查验收标准就标记完成
• 把 long-task-coordinator 用在本来就很短、不值得引入协调开销的任务上

long-task-coordinator 技能 FAQ

简单任务值得安装 long-task-coordinator 吗

通常不值得。如果任务很短、只在单次会话里完成、也不需要恢复能力，那么 long-task-coordinator 只会增加额外开销。仓库里已经明确把它定位为适用于“会超出单轮对话寿命”或“依赖持久状态”的工作。

它和 planning-with-files 有什么区别

planning-with-files 是更轻量的选择，适合主要需要结构化规划的场景。long-task-coordinator 则更适合可恢复执行、显式等待状态，以及处理中断后的恢复。若你更看重状态完整性，而不仅仅是步骤组织，就应该选它。

long-task-coordinator 适合 Agent Orchestration 吗

适合。这是它最明确的匹配场景之一。这个技能就是为 coordinator-worker 架构、委派执行、后台任务和跨会话交接设计的。它的 owner 追踪能力和 awaiting-result 状态，对于 Agent Orchestration 尤其实用。

它是否依赖特定 runtime 或 framework

不依赖。README 把它描述为有意保持抽象且可移植的技能，不假设特定领域，也不绑定特定 runtime。它的核心要求只有一个：你的 agent 能在工作区里读取和写入一个持久化文件。

新手能用这个 long-task-coordinator 技能吗

可以，前提是他们已经理解自己要协调的任务。这个技能本身概念并不复杂，但新手很容易过度使用它。如果你的工作并不涉及中断、委派或可恢复执行，那就应该先从更简单的规划技能开始。

什么情况下不该用 long-task-coordinator

以下情况应避免使用：

• 任务可以一次跑完
• 没有后续恢复的需求
• 没有委派 worker 或后台进程参与
• 你不想多维护一个状态文件

在这些场景下，普通提示词通常更快。

如何改进 long-task-coordinator 技能的使用效果

先把成功标准写得更强

影响质量最大的杠杆，是把“何时算完成”写得更清楚。不要只写“完成迁移”，而应该改成类似：

• auth tests pass
• production config updated
• rollback note added
• legacy path disabled

成功标准越具体，模型就越难过早结束任务。

让状态文件具体、稳定、易于再次发现

不要把状态藏在一个随意命名的临时文件里。应放在像 docs/oauth-migration-state.md 这样可预期的位置。好的恢复能力，前提是下一次会话无需猜测就能找到那个文件。

明确记录责任归属

想把 long-task-coordinator 用得更稳，始终要记录清楚谁负责什么：

• Origin：定义任务
• Coordinator：维护状态和执行顺序
• Worker：执行边界明确的工作

这个小习惯能显著减少重复劳动、任务卡住和多 agent 参与时的混乱。

用检查点条件增强提示词

弱检查点会写成“稍后再看”。强检查点则会写成“当 worker 返回测试结果时恢复，或者最晚在 15:00 UTC 恢复，以先发生者为准”。触发条件越明确，coordinator 偏离节奏的可能性就越低。

防止虚假的进展汇报

一种常见失败模式，是报告读起来很顺，但实际并不可靠。可以通过明确要求 long-task-coordinator 做下面这些事来修正：

• 先读取已保存状态
• 验证状态是否仍然准确
• 先持久化更新，再做总结
• 区分 waiting 和 blocked
• 依据成功标准来证明 complete 的合理性

这样能让 long-task-coordinator 的输出在跨会话场景下仍然值得信赖。

把 eval prompts 当作验收测试

evals/prompts.md 的用途不只是做 smoke testing。你完全可以把这些 prompts 当成自己本地定制方案的检查清单：

• 它能否安全恢复被中断的工作？
• 它是否如实表达等待中的状态？
• 它是否能通过已保存状态证明任务真的完成？

如果你定制后的用法过不了这些测试，那说明你的 orchestration 模式仍然过于松散。

第一次运行后继续迭代

完成第一轮协调后，回头检查状态文件，把所有模糊点继续收紧：

• 替换模糊状态
• 补上缺失的 owners
• 澄清 blockers
• 拆分过大的 next actions
• 加入真正明确的 checkpoint condition

long-task-coordinator 的效果通常会在前几轮里迅速提升，因为之后每一次恢复依赖的都是这份持久化状态，而不是聊天记忆。