用途
session-handoff 用于解决长时间运行的 AI 代理上下文耗尽的问题。它生成完整的交接文档，使新的 AI 代理会话能够在没有歧义的情况下继续此前的工作。该技能会在以下情况触发：用户要求交接、保存记忆或保存上下文；上下文将满；用户希望继续此前的工作或加载已有交接。当发生大量工作（例如 5 次以上文件编辑、复杂调试、重大决策）后，该技能也会主动建议创建交接文档。
模式选择
技能会先判断当前属于哪种模式：如果用户想保存当前状态、暂停工作或上下文将满，则走 CREATE 工作流；如果用户想继续此前的工作、加载上下文或提到已有交接，则走 RESUME 工作流。
创建交接（CREATE Workflow）
- 生成脚手架：运行
python scripts/create_handoff.py [task-slug]，脚本会创建.claude/handoffs/目录（如需要）、生成带时间戳的文件名，并预填时间戳、项目路径、git 分支、近期提交、修改过的文件；若为延续性交接，可加--continues-from参数，例如python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md，脚本会添加交接链链接。 - 补全文档：填写所有 [TODO: ...] 章节，优先处理「当前状态摘要」「重要上下文」「即时后续步骤」「已做决策及其理由」。模板结构参见 references/handoff-template.md。
- 校验：运行
python scripts/validate_handoff.py <handoff-file>，检查是否仍有占位符、必需章节是否齐全、是否检测到潜在密钥（API key、密码、token）、引用的文件是否存在，并给出 0–100 的质量分。存在密钥或分数低于 70 时不应定稿。 - 向用户确认：报告文件位置、校验分数与警告、捕获的上下文摘要，以及下次会话的第一个行动项。
恢复交接（RESUME Workflow）
- 列出可用交接：
python scripts/list_handoffs.py，显示日期、标题和完成状态。 - 检查过期程度：
python scripts/check_staleness.py <handoff-file>，等级分为 FRESH（可直接恢复）、SLIGHTLY_STALE（查看变更后恢复）、STALE（谨慎核实）、VERY_STALE（考虑新建交接）。检查项包括创建后的时长、git 提交、文件变更、分支分叉和缺失的引用文件。 - 完整读取相关交接文档；若属于链式交接（含 Continues from 链接），同时读取上一份交接。
- 按 references/resume-checklist.md 核对上下文：项目目录与 git 分支是否匹配、阻塞项是否解决、假设是否仍成立、修改文件是否冲突、环境状态。
- 从「即时后续步骤」第 1 项开始工作，并参考「关键文件」「发现的关键模式」「潜在陷阱」等章节。
- 工作中更新「待办工作」的完成状态、补充新发现；长会话可用
--continues-from新建交接并串联。
交接链
长期项目可串联多份交接文档（handoff-1 → handoff-2 → handoff-3），每份链接到前一份、可将旧交接标记为已被取代，为新代理提供上下文线索。恢复时先读最新一份，再按需参考更早的。
存储与脚本
交接文档存放在 .claude/handoffs/，命名格式为 YYYY-MM-DD-HHMMSS-[slug].md，例如 2024-01-15-143022-implementing-auth.md。脚本包括：create_handoff.py（生成交接）、list_handoffs.py（列出交接）、validate_handoff.py（校验完整性与安全性）、check_staleness.py（评估是否过期）。参考文件包括 handoff-template.md 和 resume-checklist.md。