handoff

handoff 概览

handoff skill 的作用

handoff 会把当前对话整理成一份给下一位 agent 使用的简明交接文档。它专为需要快速延续上下文的场景设计：把最重要的内容、已经拍板的结论，以及下一轮会话该做什么，压缩成一份可直接接手的材料。

适合谁使用

如果你要在会话之间转交工作、把任务交给另一位 agent，或者准备一份可供 AI 继续执行的简报，就适合用 handoff skill。它尤其适合 repo 工作、多步骤产品任务，以及任何上下文一丢失就会返工的流程。

它为什么不一样

handoff 的核心价值不是泛泛总结。它要求输出一份可执行的交接文档，避免重复已有产物，并通过路径或 URL 把下一位 agent 指向正确的原始材料。比起简单的“总结这段对话”，它显然更适合真正交接。

如何使用 handoff skill

安装 handoff，并从 skill 文件开始读

对于典型的 handoff install，先从 repo 中添加这个 skill，再优先打开 SKILL.md：

npx skills add mattpocock/skills --skill handoff

然后先读 SKILL.md，搞清楚准确的输出结构和行为，再把它用到自己的工作流里。

给 skill 一个明确的会话目标

handoff usage 这种用法，最适合你明确告诉它下一轮会话是做什么。仓库里的参数提示也期待类似这样的聚焦说明：

• “继续排查 payments package 里的 TypeScript 构建失败问题。”
• “接着审 landing page 文案，最终确定 CTA 变体。”
• “在 API schema 调整后，继续完成 auth flow 的实现。”

如果只说“做一个 handoff”，产出的文档通常会更弱。一个明确的下一轮目标，能帮助 skill 判断哪些内容该写进交接里，哪些可以省略。

写之前先读对文件

这个 skill 的设计本来就很轻量，所以主要来源是 SKILL.md。同时也要查看它提到的附近项目产物，而不是把它们原封不动塞进 handoff：

• README.md
• AGENTS.md
• metadata.json
• 如果存在的话，rules/、resources/、references/ 或 scripts/ 文件夹

如果这项工作已经记录在 PRD、计划、ADR、issue、diff 或 commit 里，handoff 应该直接链接到这些材料，而不是重复抄一遍。这样既能保持文档短小，也能让下一位 agent 更快进入状态。

写给下一位 agent，不是写给自己

一份优秀的 handoff 文档通常会包含：

• 当前目标和进度
• 已经做出的决策
• 仍未解决的问题或阻塞点
• 下一步要查看的准确文件路径、URL 或工件
• 对后续会话的技能建议

这条是最核心的使用原则：让下一步一眼就明白该做什么，而不是把整个项目历史重新解释一遍。

handoff skill 常见问题

handoff 只适合长对话吗？

不是。只要下一位 agent 需要更少的准备时间，handoff 就有价值，即使前一轮对话不长但很复杂也一样。只要有需要保留的决策、依赖关系或源材料，它就特别有用。

它和普通 prompt 有什么不同？

普通 prompt 往往只是要求一个总结，然后就停在那里。handoff skill 的目标更明确：它要产出一份交接文档，避免重复，并指向下一轮应该使用的权威产物。

handoff 适合初学者吗？

适合，只要你能清楚说出下一步任务。初学者如果先给出一个简单明确的聚焦说明，再让 skill 负责把交接整理成有用的简报，通常效果最好。

什么时候不该用 handoff？

如果下一轮会话不需要延续上下文，或者所需信息已经完整记录在现成工件里、下一位 agent 会直接去读，那就不要用 handoff。

如何改进 handoff skill

把下一轮目标写得更具体

handoff 输出质量，很大程度取决于你把下一轮会话定义得有多清楚。更好的输入会直接点明具体阶段、子系统或决策点，而不只是泛泛地说整个项目。

指向事实来源工件

如果当前工作已经存在于文档、issue 或 diff 里，请把这些引用带上，这样 handoff 才能保持精简。原因很简单：这个 skill 本来就不是用来重复别处已经保存的材料的。

包含约束和未决问题

最有用的 handoff 文档，往往会把尚未解决的内容写清楚：实现阻塞、取舍、审阅者关切，或仍需确认的假设。这些细节能帮助下一位 agent 避免重复踩进之前的死胡同。

需要时建议后续 skill

这个 skill 明确会要求你提供下一轮可用的 skill 建议，所以如果后续任务更适合另一种工作流，就应当一并写上。比如，handoff 可以根据剩余工作，把下一位 agent 引向规划、编码或评审类 skill。