handoff

name	handoff
version	1.0.0
description	生成或读取 Handoff 交接文档。用户说"handoff"、"交接"、"交接文档"、"看前一个 agent"、"上一份 handoff" 时触发。也支持 /handoff 命令。

Handoff 交接文档 Skill

激活流程

技能激活后，先问用户："你是要读一份 handoff（看前一个 agent 做了什么），还是生成一份新的 handoff 交接文档？"

• 如果用户说 读 → 执行「读取路由」
• 如果用户说 写 → 执行「生成路由」
• 如果用户触发词已明确（如"生成交接文档"→ 写，"看看前一个 agent"→ 读），直接走对应路由，跳过询问

---

读取路由

1. 扫描 handoff 文件

ls .handoffs/handoff-*.md 2>/dev/null

如果没有 .handoffs/ 目录或没有任何 handoff 文件，告知用户：

当前项目没有找到 handoff 交接文档记录。

2. 确定读哪一份

• 用户没指定 → 读最新一份（按文件名排序取最后）
• 用户指定了日期（如"看 2026-08-10 的"）→ 读 handoff-2026-08-10.md，如果当天有多个版本，取序号最大者
• 如果指定日期的文件不存在，告知用户并用最新一份作为 fallback

3. 总结内容

用 Read 工具读取文件，然后按以下模板章节的结构向用户总结：

章节	总结要点
项目概述	项目名称、类型、一句话说明
完成的工作	目标 + 核心改动概览 + 几条关键 commit
未完成的工作	剩余的高优先项 + 已知问题
操作指引	如何继续的步骤 + 注意事项

不主动执行代码，不检查 git 状态，不推进未完成项。

---

生成路由

0. 前置准备

执行 git 提取脚本获取数据：

# 脚本在 skill 目录下：~/.claude/skills/handoff/scripts/git-extract.sh
# 可用 .cmd 版本（Windows）
bash ~/.claude/skills/handoff/scripts/git-extract.sh    # Bash
# 或 scripts\git-extract.cmd                             # Windows CMD

1. 收集数据

从以下来源收集信息：

A. 会话内容（从当前对话提取）

• 本次会话的目标（用户最初的需求）
• 关键设计决策和理由
• 未完成的工作和已知问题
• 用户偏好（如包管理器、不要 build 等）

B. Git 提取脚本输出

• 项目技术栈（package.json、pyproject.toml、go.mod 等元数据 + 目录结构）
• 当前分支名
• 基线 commit（从上一份 handoff 的最后 commit 开始，或最初 commit）
• 从基线到 HEAD 的 commit 日志（表格格式）
• 每个 commit 的变更文件列表
• 关键代码片段（复杂逻辑区域）

C. 项目结构推断

• 前端目录结构
• 后端目录结构
• 包管理器类型

2. 确定文件名

.handoffs/handoff-YYYY-MM-DD.md

如果同一天已有文件，追加序号：

.handoffs/handoff-YYYY-MM-DD.md       # 第一份
.handoffs/handoff-YYYY-MM-DD-2.md     # 第二份
.handoffs/handoff-YYYY-MM-DD-3.md     # 第三份

3. 确保输出目录存在

mkdir -p .handoffs

4. 生成文档

按以下模板结构生成文档，每个章节的详细模板见 references/ 目录下的对应文件。

---

文档模板

1. 项目概述

由 AI 从项目元数据文件和目录结构推断，自动填充。参考 references/project-overview.md。

2. 本次会话完成的工作

目标: 一句话说明本次会话的目标

Git 节点记录:

Commit Hash	描述	关键改动
abc1234	feat: 添加用户登录	新增 auth/login.tsx，修改 api/auth.ts
...	...	...

具体改动清单:

按功能模块分条列出，每条必须包含：

• 修改了哪个文件
• 改了什么（具体到 CSS 变量名、类名、组件名、函数名）
• 为什么这样改（设计决策）
• 关键代码片段（如果涉及复杂逻辑）

已修改文件列表:

文件路径	改动内容摘要
src/components/Login.tsx	新增登录表单组件，使用 --color-primary

3. 尚未完成的工作

按优先级分三级：

优先级	做什么	为什么还没做
高	用户密码加密	等待后端接口就绪
中	错误提示优化	非 MVP 必须
低	添加单元测试	功能稳定后再补

如果有已知的 bug 或问题，也列在这里。

4. 项目约定参考

参考 references/project-conventions.md。

AI 根据项目类型自动填充内容。对于前端项目，自动检测 CSS 变量、设计 token、组件库等约定。对于非前端项目，输出架构约定、命名规范、数据流模式等。

5. 操作指引

如何继续:

1. cd <project-dir> 进入项目目录
2. 阅读 .handoffs/handoff-YYYY-MM-DD.md 了解上下文
3. 执行 git log --oneline -5 查看最新提交

如何回滚:

git reset --hard <commit-hash>

项目启动: 由 AI 自动检测并生成启动命令

注意事项:

• 用户偏好（如"不要 build"、"用 pnpm 而不是 npm"）
• 特殊约定

---

写作原则

1. 下一个 AI 不看代码也能操作: 所有信息必须自包含，不依赖阅读源码
2. 精确到文件和变量: 不要写"修改了样式"，要写"修改了 index.css 的 --color-primary 变量"
3. 记录设计决策: 不只记录"做了什么"，还要记录"为什么这样做"
4. 诚实记录未完成项: 不要把半成品标为已完成
5. Git 节点可追溯: 每个 commit 都要记录，方便回滚
6. 中文撰写: 所有内容用中文，禁止使用 emoji