使用 handoff 技能实现跨会话、跨 Agent 的工作交接从/compact到便携式交接文档【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills导读handoff是本仓库Skills for Real Engineers见 README.md中 productivity 分类下的一个用户主动调用技能它把当前对话压缩成一份handoff 文档——一个写入操作系统临时目录而非工作区的 Markdown 文件让一个全新的 Agent 读取后能无缝接手工作。它的核心价值不是压缩对话而是可移植性portability。读完本文你将掌握/handoff与/compact、/clear、subagent 之间的本质区别四种必须用文件的场景交接文档里该带什么、不该带什么以及 fork 出并行任务这一最常被忽略的用法。一、/handoff是什么一份可携带的交接文档而非更好的压缩handoff把当前对话压缩成一份handoff 文档一个 markdown 文件写入操作系统的临时目录而不是当前工作区供一个新的 agent 读取后接手工作。它的实际收益是可移植性而不是压缩。这一点让这个技能比字面上看起来更窄你只有在工作需要旅行时才需要这个文件——迁移到一个新的 harness、一个新的目录、交给一位同事或者 fork 出一个并行侧任务。如果没有任何东西需要移动你就不需要 handoff停留在当前 session、/clear、subagent 和/compact已经覆盖了常规的阶段收尾场景而且/compact的覆盖面比这个技能更大。在仓库中的技能实现 handoff/SKILL.md 明确写道将当前对话总结成一份 handoff 文档让新 Agent 可以继续工作保存到用户操作系统的临时目录而不是当前工作区文档中包含 suggested skills 小节列出下一个 Agent 应该为 Skill 工具调用哪些技能不重复复制已沉淀在规格书、计划、ADR、issue、commit、diff 中的内容而是用路径或 URL 引用脱敏任何敏感信息如 API 密钥、密码、个人可识别信息如果用户传入了参数将参数视为对下一会话工作重点的描述并据此裁剪文档。二、什么时候用四种触发场景一张表说清/handoff需要你主动输入来触发You invoke this by typing /handoffAgent 不会自行调用它。你需要传递一条关于下一个会话用来干什么的说明文档就会围绕它生成。四种触发场景是全部场景为什么要一个文件切换 harnessClaude → Codex新 harness 看不到旧的 context迁移到不同目录或仓库原型目录是常见情况把工作交给同事他们需要一份可读的东西fork 阶段中发现的侧任务你继续工作第二个 Agent 接手分支除此之外的情况同一个 harness、同一个目录、你已经 grilling 与 PHASE-BOUNDARIES.md。从源码确认为什么它只能被用户调用这个技能被刻意设计为user-invoked仅用户调用。看它的 frontmatterhandoff/SKILL.md 顶部--- name: handoff description: Compact the current conversation into a handoff document for another agent to pick up. argument-hint: What will the next session be used for? disable-model-invocation: true ---disable-model-invocation: true意味着模型不能自行触发它。对于 Codex对应的声明在 agents/openai.yamlinterface: display_name: Handoff short_description: Compact a conversation into a handoff policy: allow_implicit_invocation: falseallow_implicit_invocation: false与disable-model-invocation: true是同一语义在两种 harness 下的表达。为什么故意这样设计productivity/README.md 将 handoff 归入 User-invoked 一栏并说明这类技能只在输入时才可触达。而 writing-for-agents/SKILL-MECHANICS.md 解释了机制层面的权衡user-invoked技能从 Agent 的可达范围中剥离 description不产生任何上下文加载成本代价是认知负担由人来承担——你是那个必须记住它存在的人而model-invoked技能用永久上下文加载换取 Agent 的自主发现能力。handoff 选择前者是因为何时交接是高度主观的判断不该交给 Agent 自作主张。三、分支fork才是最容易被人忽略的用法技能描述读起来像是会话恢复写个摘要、在这里结束、在那里恢复。按这个理解它看起来像是一个更差的/compact于是很容易被略过。但fork 场景才最值得了解你留在自己的会话中把已积累上下文的副本交给一个并行工作的第二个 Agent。这正是经由 prototype 的绕行所使用的模式。你正深陷一场设计讨论遇到一个只有运行代码才能解决的问题而你不愿意为寻找答案花掉已经建立的讨论线索。于是handoff 出去——把上下文交给一个原型会话打开一个针对该文件的新会话跑 prototype用一次性代码回答问题见 prototype/SKILL.md 中用一次性代码回答设计问题的定位handoff 回来——把学到的答案带回并在原线索中引用它。两次穿越、一次活会话、没有任何东西需要重新解释。原型之所以是 handoff 最亲密的邻居正是因为原型活在自己的目录里而出往返两次的穿越正是这个技能存在的意义。ask-matt 的主流程也明确把这一步编了进去ask-matt/SKILL.md分支能否在对话中解决每个问题——如果某个问题需要可运行的答案状态、业务逻辑、必须亲眼看到的 UI就经由一个原型绕行由/handoff双向桥接原型活在自己的目录里这正是/handoff的用途。阶段边界上的五个选项各自保留了不同的东西/compact保留你的意图/clear什么都不保留/handoff保留工作的移动能力。四、文档里带什么、不带什么handoff 文档携带活的线程当前在飞的是什么whats in flight、为什么why、下一步是什么whats nextsuggested skills 小节指明下一个 Agent 应该为 Skill 工具调用的技能这是 SKILL.md 里明确要求的结构敏感信息在写入前会被脱敏redacted——API 密钥、密码、个人可识别信息。它刻意不携带任何已经写下来的东西规格书、计划、ADR、issue、commit 和 diff 都按路径或 URL 引用绝不复制。这带来两个好处文件保持小巧已沉淀的细节留在唯一的地方而不是两处会逐渐漂移drift的副本。这个引用而非复制原则在 handoff/SKILL.md 中是硬性指令Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.五、常见问题辨析FAQ 深度展开Handoff 还是 compact默认用/compact除非有东西在旅行。同一任务上的延续是 compact 而非 handoff同 harness、同目录、需要你保持参与——这是阶段边界决策树大多数时候落脚的地方。/handoff的优势不在于它总结得更好而在于结果是你能带走、而/compact够不到的文件。compact、clear、handoff 三者到底有什么区别三者保留的是三种不同的东西/compact压缩当前 context 并在新窗口继续——意图幸存/clear清空窗口、从零开始——当身后的一切都可丢弃时正确若不可丢弃则是一条单行道/handoff写出一份便携文件——工作本身幸存于迁移。注意三者都把一手来源primary source对话本身变成了二手来源secondary source对话的摘要。唯一不做这种转换的动作是Continue继续这也是为什么它总是第一个被排除的选项。PHASE-BOUNDARIES.md 用一张表量化了这个取舍来源信息噪音移动空间一手Continue完整多小二手/compact、/handoff有损少大这就是为什么决策树的问题 1 排在最前只有当留在原地的代价大于收益时你才付出有损的代价。我的 handoff 文件去哪儿了临时目录。这是该技能被报告最多的摩擦点路径很长、各操作系统不同在 Windows 上 Agent 有时要试好几次才能找到正确路径。请它把路径告诉你并保存下来然后再继续。使用临时目录是刻意为之handoff 是一份中转文档transit document不是你需要维护的产物。它也不是一份持久文档——见下一个问题。我的 handoff 在会话之间消失了有些环境会在会话之间清理临时目录已报告的案例是 Codex而/private/tmp在重启后会清空。如果下一个会话不在一个小时内开始、或者会在不同的 harness 下开始请在文件写入后立即自行把它复制到某个持久位置。同理适用于文档所指向的一切一个引用临时目录中其他文件的交接文档是下一个 Agent 无法遵循的交接。我到底怎么把它交给下一个 Agent打开新会话并指向路径读取这个文件然后继续。指向文件而非把摘要粘贴进 shell 命令——含反引号或$(...)的摘要被插值进claude summary时会被搞坏常见的失败是静默截断而非报错于是新 Agent 拿着一份悄悄不完整的简报开工。这和/branch、--fork-session、内置的/handoff一样吗类似但不相同。/branch在本仓库并非已发布技能/handoff才是规范名称。fork 继承 context 的精确副本本技能产出一份针对性的压缩瞄准一个陈述好的下一个任务写入文件。在 fork 可行的地方同机器、同 harness、同目录fork 更省事一旦目的地是 fork 去不了的地方文件就胜出。什么时候内容该进CLAUDE.md而不是 handoff问一句下个月它还成立吗CLAUDE.md是关于项目的常驻上下文无论相关与否都会加载进每个会话。handoff 只关于一件在飞的工作一旦落地就死亡。反复需要重新解释的事实是CLAUDE.md的问题一件半成品任务是 handoff 的场合。本仓库根目录就有一份 CLAUDE.md 作为项目自身的常驻上下文示例。它捕获了 what却没捕获 why这是一个公允且反复出现的批评。两件事有帮助传参数告诉它下一个会话用来干什么让与那个任务相关的推理被保留而不是被压平——SKILL.md 中argument-hint: What will the next session be used for?正是为此设计警惕会话从未验证过的自信断言X 没构建、Y 完成了。下一个 Agent 会把文档当作契约不会重新检查——所以一个被当作事实写下的信念会成为后续所有工作的虚假前提。在交接前通读文档把任何只是假设的内容降级表述。为什么是技能skill而不是斜杠命令slash command两者都能工作适配不同场景。作为技能它通过与其他一切相同的安装路径分发和更新这正是它可共享的原因Agent 不会自行触发它这一约束由它的 frontmatter 设定而非由机制决定。安装路径见 README.md 的安装说明Claude Code 插件claude plugins install mattpocock-skills或其他 Agent 用npx skillslatest add mattpocock/skills并勾选所需技能。六、怎样算成功了验收清单根据原文档以下情况出现时说明 handoff 用对了文档只占对话的一小部分规格、issue 和 diff 以路径和 URL而非复制文本的形式出现你能在没有原会话打开的情况下冷读它并知道下一步做什么新 Agent 直接开始工作而不是让你重新解释一遍背景设定在 fork 场景中你回来时原会话还原封不动地待在那里suggested skills 小节点名的正是你自己会伸手去用的那个技能里面没有任何密钥、令牌或密码。七、它在这个技能体系中的位置handoff是一个随时可用的独立技能reach-for-it-anytime standalone活在会话之间的接缝处而非构建链内部但它很窄——诚实的说法是在阶段边界上的五个选项中你会用得比另外四个更少。它最亲密的邻居是 prototype因为原型活在自己的目录里而出去再回来的往返穿越正是这个技能的用途。当你处在一个阶段边界、不确定该 Continue、clear、hand off、委派给 subagent 还是 compact 时ask-matt 带着那棵把五个选项排序的决策树完整决策逻辑见 PHASE-BOUNDARIES.md从下到上依次排除 Continue、/clear、/handoff、subagent最后才落到作为默认项而非首选的/compact并把你路由到其余技能之上。记住那句话/compact是默认不是第一选择——它坐在树的底部因为树顶的四个问题全都更便宜或更精确当人们从这里开始失败模式是新会话对一个被摘要压平的决策自信地犯下错误。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考