交接

它的作用¶

handoff 会将你当前所在的对话压缩成一份交接文档：一个 Markdown 文件，写入操作系统的临时目录而不是工作区，供一个全新的代理读取并接手工作。

它提供的是可移植性，而不是压缩，因此这个技能比听起来更窄。只有当工作必须迁移时，你才需要一个文件：迁移到新的运行环境、新的目录、同事，或你想分叉出去的旁支任务。如果没有东西需要迁移，就不需要 handoff。留在会话中、/clear、一个子代理以及 /compact 可以覆盖普通的阶段结束场景，而且 /compact 比这个技能更常覆盖该场景。

何时使用它¶

你通过输入 /handoff 来调用它；代理不会自行使用它。传入一条关于下一个会话用途的说明，该技能就会为此目的编写文档。

只有四个触发条件，也只有四个：

对于其他情况（同一运行环境、同一目录，你已完成拷问并准备进入实现），使用 /compact。ask-matt 提供了阶段边界处所有五个选项的有序决策树。

分支是人们会忽略的用途¶

该技能的描述读起来像是会话恢复：写一份摘要，在这里结束，在那里恢复。这样理解的话，它看起来像一个更差的 /compact，所以人们会跳过它。分叉场景是值得了解的。你留在自己的会话中，并把累积上下文的副本交给一个并行工作的第二个代理。

通过 prototype 的绕道正是这样使用的。你正深入一场设计对话，遇到一个只有运行代码才能解决的问题，而你不想把已经建立的线程花在查明答案上。交接给一个 prototype 会话，拿到答案，再把答案交回来，并在原始线程中引用它。工作来回交叉两次，你的原始对话保持活跃，你也不需要重新解释任何内容。

阶段边界处的五个选项中有三个保留不同的东西：/compact 保留你的意图，/clear 什么都不保留，/handoff 保留工作可迁移的能力。

什么会迁移，什么不会¶

该文档承载活跃线程（正在进行什么、为什么、下一步是什么），外加一个建议技能部分，指明下一个代理应该使用什么。该技能在写入文件前会隐去机密信息。

它有意不承载任何已经写下来的内容。文档通过路径或 URL 引用规格、计划、ADR、issue、提交和 diff，而从不复制它们。这让文件保持较小，也让已确定的细节保留在一个地方，而不是两份会彼此偏离的副本。

常见问题¶

交接还是压缩？ 除非有东西需要迁移，否则使用 /compact。留在同一任务上是压缩，而不是交接。当运行环境和目录保持不变，并且你需要保持知情时，阶段边界决策树大多数时候会结束于 /compact。/handoff 不会更好地总结。它的优势在于，结果是一个文件，你可以把它带到 /compact 无法到达的地方。

那么 compact、clear 和 handoff 之间的实际区别是什么？ 它们各自保留不同的东西。/compact 压缩当前上下文，并在全新窗口中继续，因此你的意图得以保留。/clear 清空窗口并从无开始。当你身后的一切都可丢弃时，这是正确的；如果并非如此，你就无法撤销它。/handoff 写入一个可移植文件，因此工作能在迁移到别处后存活。这三者都会把一个一手来源（对话实际发生的样子）变成一个二手来源（对它的摘要）。继续是唯一不会这样做的选项，这就是为什么你首先排除它。

我的 handoff 文件去哪了？ 它会进入临时目录，这是该技能被报告最多的问题。该技能会将其解析为 $TMPDIR，否则为 /tmp（Windows 上为 %TEMP%），但路径很长。在继续之前，要求返回路径并保存它。使用临时目录是有意为之，因为 handoff 是一份传输中的文档，而不是你维护的产物。临时目录也不持久，正如下一个问题所解释的。

我的 handoff 在会话之间消失了。 某些环境会在会话之间清空临时目录（Codex 是被报告的情况），重启会清空 /private/tmp。如果下一个会话不会在一小时内开始，或者会在不同的运行环境下开始，请在文件写入后尽快自己把它复制到某个持久位置。同样的情况也适用于文档指向的任何内容：如果某个分派引用了临时目录中的其他文件，下一个代理就无法跟随它。

我实际上如何把它交给下一个代理？ 打开全新会话，并让它指向该路径：读取这个文件，然后继续。指向文件，而不是把摘要粘贴到 shell 命令中。当 shell 把包含反引号或 $(...) 的摘要插值到 claude "<summary>" 中时，会破坏摘要。通常结果是静默截断而不是错误，因此新代理会带着不完整的简报开始，而没有任何提示告诉你。

这和 /branch、--fork-session 或内置的 /handoff 一样吗？ 它们相似，但不相同。/branch 在这里不是一个已发布的技能；/handoff 是规范名称。分叉会继承上下文的精确副本；这个技能生成一个有针对性的压缩，针对已说明的下一个任务，并放在文件中。如果分叉可行（同一台机器、同一运行环境、同一目录），分叉的工作量更小。当目的地是分叉无法到达的地方时，文件是更好的选择。

什么时候应该写入 CLAUDE.md 而不是这里？ 问自己：下个月它是否仍然成立。CLAUDE.md 是关于项目的长期上下文，无论是否相关，都会加载到每个会话中。交接是关于一项正在进行中的工作，一旦该工作完成就没用了。如果你不断重复解释某个事实，它应该放在 CLAUDE.md 中。一个未完成的任务应该放在交接中。

它记录的是“是什么”，而不是“为什么”。 这是一个合理的批评，人们经常提出。有两点有帮助。传递论证（告诉它下一个会话是做什么的），这样该技能会保留与那个相关的推理，而不是将其扁平化。并且留意会话从未验证过的自信断言，例如“X 没有构建”或“Y 已完成”。下一个代理会信任文档，而不会重新检查，因此以事实形式写下的信念会成为后续一切工作的错误前提。在交接之前阅读文档，并将你只是假设的内容降级处理。

为什么它是技能而不是斜杠命令？ 两者都可以；它们适合不同情况。作为技能，它通过这里其他所有内容相同的安装路径发布和更新，因此可以共享。阻止代理自行触发它的是其 frontmatter，而不是机制。

如果满足以下条件，说明它有效¶

• 文档只是对话的一小部分，并且规范、问题和差异以路径和 URL 的形式出现在其中，而不是复制的文本。
• 你可以在没有打开原始会话的情况下冷读它，并知道下一步该做什么。
• 新的代理开始工作，而不是要求你重新解释设置。
• 在分叉情况下，当你回到原始会话时，它保持不变。
• suggested-skills 部分列出了你自己本来会使用的技能。
• 其中没有任何密钥、token 或密码。

它适合的位置¶

handoff 是一个随时可取用的独立技能。它在会话之间工作，而不是在构建链内部工作。它很窄，在阶段边界处，你使用它的频率会低于其他四个选项。它最接近的邻居是 prototype，因为原型位于自己的目录中，而往返出去再回来正是这个技能所针对的操作。当你处于边界并且不确定是继续、清空、交接、委派还是压缩时，ask-matt 有对这些五个选项进行排序的树，并将你路由到该集合中的其余部分。