用途
Handoff 是一个用于 Claude Code 的会话交接技能，主要解决“一次会话结束、需要让下一次会话或另一个人无缝接续”的问题。它通过生成或恢复一份结构化交接文档，把足够的上下文保存下来，使后续会话能够从上次中断的地方继续。
主要能力
该技能围绕一个固定文件 docs/HANDOFF.md 工作，包含两种模式：
- 生成模式（Generate）：在会话中途或结束时，收集并整理当前工作状态，输出一份交接文档。
- 恢复模式（Resume）：读取已有的交接文档，校验环境后帮助新会话快速进入状态。
模式检测规则如下：
| 调用方式 | 模式 |
|---|---|
| /handoff mid-session | 生成 |
| /handoff resume | 恢复 |
| 全新会话（无参数） | 若 docs/HANDOFF.md 存在则恢复，否则生成 |
| 自然语言：“resume”“pick up where we left off”“continue from handoff” | 恢复 |
| 自然语言：“handoff”“wrap up”“pass the baton” | 生成 |
该技能没有路径参数，文件始终是 docs/HANDOFF.md。
使用方式
生成模式
生成前会先收集上下文：
- 自动检测（不询问用户）：Git 分支（git branch --show-current）、工作区是否脏（git status --porcelain）、最近提交（git log --oneline -5）。
- 从对话推断：角色（如 developer、content writer、EOS facilitator、researcher，默认 developer）、当前工作、状态（in_progress | blocked | paused | ready_for_review | complete）、关键参考（2-3 个最重要的文档）、近期改动（含 file:line-range 引用）、经验教训、产物清单、下一步、备注。
- 仅在无法推断时询问用户：如果角色、当前工作或下一步不明确，会提出一个澄清问题，而不是猜测。
输出格式为围栏 markdown 块，包含 YAML frontmatter（handoff_date、git_branch、git_dirty、status、role）以及 Current State、Critical References、Recent Changes、Learnings、Artifacts、Next Steps、Notes 等章节。草稿会先直接打印到对话中，经用户批准或修改后，才写入 docs/HANDOFF.md。若 docs/ 目录不存在，会在用户批准后创建。
恢复模式
恢复模式分三个阶段：
- 查找与读取：读取 docs/HANDOFF.md；若不存在则告知用户并切换到生成模式。解析 YAML frontmatter 和所有 markdown 章节，并读取 Artifacts 中列出的每个本地文本文件。对缺失文件、二进制/不可读文件、超大文件（>500KB 采样首尾各 200 行）、URL（跳过读取，仅作参考）分别记录。
- 校验环境：并行运行 git branch --show-current、git status --porcelain、git log --oneline -5，并与 frontmatter 对比；检查 CLAUDE.md 是否存在并读取。构建不匹配列表。
- 定位与询问：按优先级评估场景——
- Complete（状态为 complete）：告知用户工作已完成，并询问接下来想做什么。
- Stale（handoff_date 距今超过 7 个日历日）：提示可能已过期，询问是信任该交接继续，还是先重新探索代码库。
- Diverged（当前分支或脏状态与 frontmatter 不符）：逐项展示不匹配，询问如何处理。
- Incomplete（状态为 in_progress、blocked、paused 或 ready_for_review）：确认状态，展示阻塞项，聚焦完成第一个未完成步骤，开始前请用户确认。
- Clean（以上均不适用）：给出简要摘要，列出下一步，并询问是否开始第一步。
适用场景
- 工作会话结束时
- 对话中途切换角色或上下文
- 关闭有未完成工作的长时间会话前
- 用户说“handoff”“wrap up”“pass the baton”等
- 从之前的交接文档开始新会话
- 用户说“resume”“pick up where we left off”“continue from handoff”等
限制与规则
- 交接文档应保持简洁，目标是快速上手，而非完整会话记录。
- 无内容的章节应省略（如没有关键参考则跳过该节）。
- 下一步必须具体可执行，例如“continue implementing X”，而非“keep going”。
- 不得包含敏感信息（API 密钥、令牌、密码）。
- 优先使用 path/to/file.ext:line-range 引用，而非内联代码块。
- 生成模式：始终先打印草稿并获用户批准后再写入文件；仅在批准后创建 docs/ 目录。
- 恢复模式：绝不自动执行下一步，始终先通过 AskUserQuestion 确认；在展示分析前读取所有本地文本产物文件；将下一步视为建议而非命令；若找不到 docs/HANDOFF.md，不要猜测，应告知用户并提供生成选项。