安装此技能
npx skills@latest add mattpocock/skills --skill=handoff 然后在你的编码 agent 里输入 /handoff 。
本页目录
它做什么
handoff 把你正在进行的这场对话压缩成一份交接文档（handoff document）：一个 markdown 文件，写到操作系统的临时目录里，而不是写进工作区，一个全新的 agent 可以读它来接手这项工作。
它给你的是可移植性（portability），不是压缩，所以这个技能比它听起来要窄。只有当工作必须迁移时，你才需要一个文件：迁移到一个新的运行环境（harness）、一个新的目录、一位同事那里，或者一个你想分叉出去的支线任务。如果没有任何东西需要迁移，你就不需要交接文档。留在原会话（session）里、/clear、一个子代理（subagent）以及 /compact 覆盖了阶段结束时常见的情形，而 /compact 比这个技能更常覆盖它。
什么时候用它
你通过输入 /handoff 来调用它；agent 不会主动去拿它。传一条关于下一场会话是为了什么的说明，技能就会为那个目的写这份文档。
有四个触发条件，而且只有四个：
| 情形 | 为什么需要一个文件 |
|---|---|
| 更换运行环境（Claude → Codex） | 新的运行环境看不到旧的上下文（context） |
| 移动到另一个目录或仓库 | 原型目录是常见情形 |
| 把工作发给一位同事 | 他们需要能读的东西 |
| 分叉一个在阶段中途发现的支线任务 | 你继续工作；第二个 agent 接手那个分叉 |
对其他任何情况（同一个运行环境、同一个目录，你刚做完质询（grilling）正要进入实现），用 /compact。ask-matt 有那棵在阶段边界上给全部五个选项排序的树。
分叉是人们跳过的用法
这个技能的描述读起来像会话恢复：写一份摘要，在这里结束，在那里继续。按那种读法，它看起来像一个更差的 /compact，所以人们跳过它。分叉这一情形才是值得了解的那个。你留在自己的会话里，把累积上下文的一份副本交给一个并行工作的第二个 agent。
绕道 prototype 用的就是这个。你正深处一场设计对话，撞上一个只有运行代码才能解决的问题，而你又不想把已经建立的那条讨论串花在弄清楚它上面。把工作分叉给一场原型会话，拿到答案，把答案带回来，并从原来的讨论串引用它。工作往返两次，你原来的对话保持存活，而你什么都不用重新解释。
阶段边界上的五个选项里有三个保存的东西各不相同：/compact 保存你的意图，/clear 什么都不保存，/handoff 保存工作迁移的能力。
什么会跟着走，什么不会
文档携带活的讨论串（什么正在进行、为什么、下一步是什么），再加上一个建议技能小节，点名下一个 agent 该去拿什么。技能在写文件之前会隐去机密。
它刻意不携带任何已经写下来的东西。文档用路径或 URL 引用规范文档、计划、ADR、issue、提交和 diff，绝不复制它们。这让文件保持小，也让已经定下来的细节留在一个地方，而不是变成会彼此漂移的两份副本。
常见问题
交接文档还是压缩？
除非有东西要迁移，否则用 /compact。留在同一个任务上是压缩，不是交接。当运行环境和目录保持不变，而你需要留在这个循环里时，阶段边界那棵树大多数日子都停在 /compact。/handoff 并不会总结得更好。它的优势在于结果是一个文件，你可以把它带到 /compact 够不到的地方。
那么压缩、清除和交接到底有什么区别？
每一个保存的东西都不一样。/compact 压缩这份上下文并在一扇全新的窗口里继续，所以你的意图存活下来。/clear 清空窗口，从零开始。当你身后的一切都是一次性的，这是对的；而如果不是，你无法撤销它。/handoff 写一个可携带的文件，所以工作能经受住搬到别处的迁移。三者都把一份**一手来源（primary source）（当时实际发生的对话）变成一份二手来源（secondary source）**（对它的摘要）。继续是唯一不这样做的选项，这就是为什么你先把它排除掉。
我的交接文件去哪了？
它去临时目录，这是关于这个技能报告得最多的问题。技能把它解析为 $TMPDIR，否则是 /tmp（Windows 上是 %TEMP%），但路径很长。在继续之前，把路径要回来并记住它。临时目录是刻意的，因为交接文档是一份在途中的文档，不是一个你维护的产物。临时目录也不持久，下一个问题会解释这一点。
我的交接文件在会话之间消失了。
有些环境会在会话之间清空临时目录（Codex 是被报告的那种情况），而重启会清空 /private/tmp。如果下一场会话不会在一小时内开始，或者会在另一个运行环境下开始，那就在文件一写出来时自己把它复制到某个持久的地方。文档指向的任何东西也一样：如果一份派发引用了临时目录里的其他文件，下一个 agent 就无法顺着找到它们。
我到底怎么把它交给下一个 agent？
打开那场全新的会话，指向那个路径：读这个文件，然后继续。指向文件，而不是把摘要粘贴进一条 shell 命令。当你把一段包含反引号或 $(...) 的摘要插进 claude "<summary>" 时，shell 会把它弄乱。通常的结果是静默截断而不是报错，于是新的 agent 带着一份不完整的简报开始，而没有任何东西告诉你。
这和 /branch、--fork-session 或者内置的 /handoff 是一回事吗？
它们相似，但不相同。/branch 在这里不是一个随附的技能；/handoff 才是正式名称。分叉继承的是上下文的一份精确副本；这个技能产出的是有针对性的压缩，对准一个说明清楚的下一个任务，放在一个文件里。在分叉够用的地方（同一台机器、同一个运行环境、同一个目录），分叉更省事。当目的地在分叉去不了的地方时，文件是更好的选择。
什么时候某样东西该放进 CLAUDE.md 而不是这里？
问一问它下个月是否仍然成立。CLAUDE.md 是关于项目的常驻上下文，不管相不相关都会加载进每一场会话。交接文档说的是某一件正在进行的工作，那件工作落地之后它就没用了。如果你反复重新解释同一个事实，它属于 CLAUDE.md。一个做了一半的任务属于交接文档。
它抓到的是「什么」，不是「为什么」。 这是一个公允的批评，人们经常提。两件事有帮助。把理由传进去（告诉它下一场会话是为了什么），这样技能就会保留与那件事相关的推理，而不是把它压平。还要留意这场会话从未验证过的自信断言，比如「X isn’t built」或「Y is done」。下一个 agent 信任这份文档，不会重新核对它，于是一个被写成事实的信念就成了后续一切的错误前提。在你把它交出去之前读一遍文档，把你只是假定的任何东西降级。
为什么它是一个技能，而不是一个斜杠命令？ 两者都行；它们适合不同的情形。作为一个技能，它通过和这里其他一切相同的安装路径随附与更新，这让它可以共享。阻止 agent 自行触发它的是它的 frontmatter，而不是机制。
它生效的标志
- 文档只占这场会话的一小部分，而规范文档、issue 和 diff 在文档里以路径和 URL 出现，而不是以复制来的文本出现。
- 你能在没有原会话打开的情况下冷读它，并知道下一步该做什么。
- 那个全新的 agent 开始工作，而不是要你重新解释一遍背景。
- 在分叉的情形里，你回来时原来的会话没有改变。
- 建议技能小节点名的，正是你自己会去拿的那个技能。
- 里面没有任何东西是一把密钥、一个 token 或一个密码。
它在体系中的位置
handoff 是一个随时可用的独立技能（Standalones）。它在会话之间工作，而不是在一条构建链内部工作。它是一个很窄的技能，在阶段边界上，你会比其他四个选项更少用到它。它最近的邻居是 prototype，因为原型住在自己的目录里，而出去再回来的往返正是这个技能的用武之地。当你在一个边界上，不确定该继续、清除、交接、委派还是压缩时，ask-matt 有那棵给这五个选项排序的树，并在其余技能集合里为你路由。