craft-handoff

craft-handoff 的用途是结束会话时产出一对可让下一次会话接续的交接材料。

主要能力

丰富文档：位于 ~/.craftkit/handoff/docs/<worktree-slug>.md，是持久的项目叙事，在下一次同一项目交接时归档并覆盖。
恢复提示词：位于 ~/.craftkit/handoff/pending/<timestamp>-<worktree-slug>.md，是用户粘贴或由钩子自动加载的内容，去除 frontmatter 后镜像到剪贴板。
两者作为一个整体，绝不只写其一。如果会话没有值得携带的状态，则不写任何内容并说明。

使用方式

工作流包含以下步骤：

收集（Gather）：运行 node <skill-dir>/scripts/gather-state.mjs，逐字使用其 “--- Handoff target ---” 中的值（PENDING_PATH、DOC_PATH、ARCHIVE_DIR、WORKTREE_SLUG、frontmatter，并在文档的 frontmatter 中添加 next:）。不使用脚本时，用 git 收集分支、状态、diff 统计和近期日志，并按 references/operational-details.md 推导路径。在 git 仓库之外，跳过仓库状态，依赖对话内容。
提炼（Distill）：只携带下一次会话无法从 diff 重建的内容，包括已完成的结果、带原因的决策、未奏效的做法、当前阻塞，以及带有可观察成功标准的下一步。省略空章节。若有多个不相关线索，询问要携带哪一个，或取最近的一个并在文档中说明。
先写文档，再写提示词。理由、备选方案和时间顺序放入文档；定位快照放入提示词。如果提示词成稿后文档又发生变化，需重新生成提示词。
持久化（Persist）：在 ~/.craftkit/handoff/ 下创建 docs/、pending/、archive/；归档现有 DOC_PATH；写文档；将带 frontmatter 的提示词写入 PENDING_PATH；把提示词正文复制到剪贴板：sed '1,/^---$/d;1,/^---$/d' "$PENDING_PATH" | bash <skill-dir>/scripts/copy-clipboard.sh。剪贴板失败不致命，需报告，文件才是交付物。若文档已写但提示词写入失败，则只写提示词（重跑文档步骤会归档刚写的文档）。

输出格式

丰富文档：frontmatter 加单个 <context> 正文：Project、Done、State、Decisions、What didn't work、Next。不含 <task> 或 <rules>。
恢复提示词：<context>（Project、State、Done 快照、Decisions、Background 指向文档）/ <task>（下一步动作和成功标准）/ <rules>（路径约定、先读文档，以及仅实际适用的约束、关键文件和验证命令）。骨架见 references/artifact-shapes.md。
恢复提示词必须在文档不可达时仍能独立成立：分支和状态、带成功标准的具体下一步、限定它的约束与决策（包括不要重做的被否决方案），以及先读丰富文档的指示。
聊天返回：用围栏代码块给出恢复提示词，一行说明提示词路径、文档路径和剪贴板状态，以及用户的下一步。仅在相关时提及自动加载钩子或 /goal 候选项。已写丰富文档时不要粘贴它。

限制与护栏

从两份产物中隐去密钥、令牌、客户数据和个人数据。
只报告实际运行过的验证。
仓库路径为 worktree 相对路径；handoff 存储路径和 frontmatter 中的 worktree: 值保持绝对路径，因为钩子按该绝对路径匹配，且下一次会话可能不共享当前工作目录。

按需加载的参考文件

技能介绍