Handoff — Claude Code 会话交接技能
在上下文快耗尽时自动生成结构化交接文件，跨会话链式衔接，避免每个新会话重复踩坑。
技能行为透明：仅本地写文件、读 git 状态，可选外部依赖（beads/OpenViking）在缺失时跳过；提交前向用户确认并支持 close without commit，归档不删除而非破坏性操作。扣分点：close-session 流程默认 git add 全部会话相关文件并提交，最小权限和确认机制不完整；发布者身份未经验证。
内部指令自洽，对 bd 不可用、无 beads、目录不存在等异常路径有明确降级（skip/ask/默认新链），失败反馈要求清晰。扣分点：静态审查无法执行关键路径（链检测 grep、两阶段写作、自校验），无测试证据；长上下文分块协议依赖模型自觉遵守，确定性有限。
触发词明确（explicit invocation 为主），明确了不适用情形（plan mode、讨论中、模糊请求先询问），目标场景（长会话上下文交接）清晰。扣分点：强依赖 Claude Code 环境与英文交互约定；未声明对非 git、无 CLI 跟踪器环境的边界细节；无中文支持说明（核心功能不依赖境外服务，扣分有限）。
文档分层良好：主 SKILL.md + references 子文档（模板、校验、深挖协议、关会话流程），README 含安装/卸载/许可证，MIT 协议清晰。扣分点：无版本号/changelog 记录在技能文件内，维护责任与更新路径未声明，已知限制披露不完整。
结构化交接文件与可直接粘贴的续接提示是直接可用的输出，模板设计覆盖面广，边际价值主张（减少重复探索）合理。扣分点：静态审查无法验证产出质量；README 的 A/B 对比测试仅为作者声称，无原始数据；强制行数下限（150-800 行）可能产生冗长输出，成本/收益比例未经验证。
源文件本身即为可审计的一手材料，引用了第三方研究（lost in the middle）但无出处链接。扣分点：A/B 测试声明不可复现，无测试套件或 CI 覆盖技能关键路径，事实与推断未分离（如 '20-40% 浪费' 数字无来源），静态只能给低分。
- close-session 默认提交行为：'Yes' 会提交本会话相关文件，用户若不细看文件清单可能意外提交无关内容；建议使用 close without commit 或逐项确认。
- README 中的 A/B 测试对比与 20-40% 效率声明均为作者自述，未经独立验证。
- beads 与 OpenViking 为可选依赖，缺失时功能降级（无链标签、无记忆持久化）；技能文件内无版本号或变更记录。
- 强制最低行数（150-800 行）可能导致冗长交接文件，对小会话不成比例。
- 发布者身份未经验证；本评估为静态源码审查，未执行任何技能路径。
这个 Skill 能做什么，适合哪些场景？
Handoff 是一个 Claude Code 技能，当上下文即将耗尽（典型场景约 75%）或工作暂停时，深度挖掘整个对话历史并生成结构化的交接 Markdown 文件。它会并行收集 git 状态、检测同一工作流中已有的交接文件（链式追踪与序号递增）、按上下文规模选择不同强度的挖掘策略，并对产出做自检验。最终生成一个可直接粘贴到新会话的恢复提示词，让下一个会话精确接续。文件写入 plans/handoffs/ 或 .claude/handoffs/，可选集成 Beads 任务追踪。
运行 git log/diff/status/branch 收集外部状态；扫描 plans/handoffs/ 等目录检测同链前序交接文件（Tier A 粘贴提示确定性匹配、Tier B bead 启发式扫描）；按上下文规模执行 Quick/Deep/Chunked 三档对话挖掘（12 项提取清单：目标、已尝试方案、失败原因、测量数据、用户偏好等）；按 300-400 行（标准窗口）或 500-800 行（1M 窗口）的行数预算两阶段写入交接文件；读取 references/validation.md 做自校验；可选更新 Beads（bd update/bd remember）；最后报告文件路径、链信息与下一步动作，并询问是否关闭会话、提交代码并生成粘贴提示词。完成链可归档到 plans/handoffs/archive/。
- 长会话接近上下文上限的开发者，想在关闭前保存全部进展而非依赖 Claude 的自动压缩摘要
- 跨多天推进同一功能修复的工程师，希望第三天的会话自动继承前两天的链式上下文与失败记录
- 使用 Beads 或其他 CLI 任务追踪器的团队，想让交接文件自动挂接到活跃任务上
- 经常因『重新发现已尝试过的失败方案』浪费 20-40% 会话时间的重度 Claude Code 用户
- 使用 1M 上下文窗口、单会话积累数十万 token 历史的用户，需要分块 map-reduce 式挖掘
这个 Skill 有哪些优点和局限？
- 链式追踪机制让第 N 次会话继承全部前序上下文（chain tag + 序号）
- 两阶段写入加自校验强制最低行数，避免内容空洞的简短交接
- 特别强调记录失败方案——这是最昂贵、最容易被重新发现的上下文
- 明确防护：拒绝在计划模式、模糊询问或自由发挥场景下生成交接文档
- 上下文规模自适应，500K+ token 时切换为 map-reduce 多轮挖掘
- MIT 许可，可与 Beads、OpenViking、任意 CLI 任务追踪器搭配
- 强依赖 Claude Code 特性（触发短语、$ARGUMENTS、斜杠命令），移植到其他客户端需改写
- 生成的交接文件很长（数百行），对上下文窗口小的客户端成本不低
- Beads（bd CLI）与 OpenViking 集成均为可选依赖，未安装时部分功能降级
- README 中的 A/B 测试结论由作者自述，无独立验证或测试套件
- 链式父文件检测的 Tier B 是启发式的，遇到模糊情况需用户人工确认
如何安装这个 Skill？
git clone https://github.com/REMvisual/claude-handoff.git 然后 cp -r claude-handoff/skills/handoff ~/.claude/skills/（仓库还包含 handoffplan 技能，可一并复制）。在 Claude Code 中输入 /handoff 验证是否出现在自动补全中。可选安装 PreCompact 钩子：复制 hooks/precompact-handoff.sh 到 ~/.claude/hooks/ 并 chmod +x。建议在 CLAUDE.md 中加入『结束会话时始终使用 /handoff 技能』以防技能被绕过。
如何使用这个 Skill？
直接输入 /handoff 即可，无需参数；也可附带原因如 /handoff "context low" 或 "end of day"。触发短语包括 'do a handoff'、'running out of context'、'save session progress' 等。技能运行完成后会给出形如 'Read plans/handoffs/HANDOFF_xxx.md (seq 2, chain-x) and continue' 的粘贴提示词，复制到新会话即可接续。
这个 Skill 与同类方案有什么区别？
README 将其与 Claude 内置的上下文压缩摘要对比：内置摘要缺乏链式追踪、自校验、证据挖掘，A/B 测试（同一 bug、同一代码库、全新会话）中基于技能的会话零人工干预、还原了完整失败调用链，而自由摘要会话需要人工纠正并只提出表面修复。同仓库还有姊妹技能 handoffplan，区别在于 /handoff 面向『暂停探索』（下个会话继续摸底），/handoffplan 面向『研究完毕准备开发』（额外生成带阶段的执行计划），本技能仅为前者。