用途
handoff 用于解决 agent 会话中断后的工作接续问题。它生成一份 handoff-<session-id>.md 文件，放在仓库根目录，作为后续会话首先阅读的“桥梁”。持久记录由 git 本身承担，而 handoff 承载的是 git 无法保存的临时状态：哪些工作只做了一半、接手者应优先验证什么、如何恢复本次会话。
每个会话对应一个文件，因此并行会话不会互相覆盖；在同一会话中重复运行 /handoff 只会更新该会话自己的文件。该文件设计为不提交：在 superskills 检出中它被 gitignore 忽略，在其他位置则保持未被跟踪状态。
触发方式
- 手动：用户随时调用 /handoff。
- 自动：插件的 UserPromptSubmit 钩子会在每个触发条件达到时提醒 agent 运行此技能，条件包括本次会话上下文窗口达到 HANDOFF_USAGE_THRESHOLD（默认 90%）、账号 5 小时窗口达到 HANDOFF_FIVE_HOUR_THRESHOLD（默认 90%）、或周窗口达到 HANDOFF_WEEKLY_THRESHOLD（默认 95%）。该功能读取 superskills statusline 发布的数值（./setup --statusline）；若未启用 statusline，则只能手动调用。触发前要求会话已有至少三条助手回复；上下文下降（压缩）后，下一次攀升会再次触发。提醒会提供 transcript_path 和 session_id。
使用方式
第一步：运行本技能的 session-ref 脚本，路径相对于技能目录解析：
bash "$(dirname <this-SKILL.md-path>)/scripts/session-ref.sh"
若调用方提供了会话 id 和 transcript 路径，可先设置环境变量使其优先于自动探测：
HANDOFF_SESSION_ID="<session_id>" HANDOFF_SESSION_FILE="<transcript_path>" \
bash "$(dirname <this-SKILL.md-path>)/scripts/session-ref.sh"
脚本会输出要写入的 handoff 文件名、会话文件绝对路径，以及针对检测到的运行环境（Claude Code / Codex / OpenCode）的已验证恢复命令，或未知环境的诚实回退说明。若输出 caution 行，需先核实 transcript 确属本会话（检查其修改时间）。
第二步：按规定的结构撰写笔记，内容为纯事实：提交哈希、file:line 定位、精确命令，不填充、不推测。结构包括 Session（脚本输出原文）、Goal（一句话完成定义）、Done（带提交哈希或 file:line 的已完成项）、In flight（进行中：已有内容、缺失内容、未验证内容）、Next steps（每步为可直接执行的精确命令）、Verify（证明目标达成的命令）、Do not redo（已完成的且不应重复的工作、已尝试且走不通的方案）、Context（本次决策、用户偏好、计划文件等指针）。目标篇幅 40–80 行；若笔记比其所概括的会话状态还长，即视为失败。
更新时整篇就地重写，绝不追加、不嵌套，不保留“上一次 handoff”或“更新前状态”之类区块；被取代的状态不随文传递——已落地的 In flight 条目移入 Done 并附哈希，并离开 In flight。若 $ARGUMENTS 携带用户备注，则并入 Context。
组合与适用场景
- 在配额硬停止时，/quota-resilience 会把该文件并入 QUOTA-RESUME.md 并删除原文件，只保留一座“桥”。
- 并行会话各自拥有不同的 handoff-<id>.md，文件头记录由哪个会话写入；没有指针的接手者读取仓库根目录最新的 handoff-*.md，并核对文件头中的会话与实际工作是否对应。
- 在没有会话持久化的极简环境中，该文件是唯一桥梁；当 session-ref 输出未知环境回退时，应在笔记中说明，让接手者依据笔记加 git 重建状态。
限制
自动触发依赖 statusline 提供的数值，否则仅能手动调用；笔记需保持简短、事实化，且面向完全没有本次会话记忆的新 agent，每行须自解释（不使用“如上”、不带先行词的代词），在已完成工作上继续推进且不重复已完成工作。