| 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 提取脚本获取数据：
bash ~/.claude/skills/handoff/scripts/git-extract.sh
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. 操作指引
如何继续:
cd <project-dir> 进入项目目录- 阅读
.handoffs/handoff-YYYY-MM-DD.md 了解上下文
- 执行
git log --oneline -5 查看最新提交
如何回滚:
git reset --hard <commit-hash>
项目启动:
由 AI 自动检测并生成启动命令
注意事项:
- 用户偏好（如"不要 build"、"用 pnpm 而不是 npm"）
- 特殊约定
写作原则
- 下一个 AI 不看代码也能操作: 所有信息必须自包含，不依赖阅读源码
- 精确到文件和变量: 不要写"修改了样式"，要写"修改了
index.css 的 --color-primary 变量"
- 记录设计决策: 不只记录"做了什么"，还要记录"为什么这样做"
- 诚实记录未完成项: 不要把半成品标为已完成
- Git 节点可追溯: 每个 commit 都要记录，方便回滚
- 中文撰写: 所有内容用中文，禁止使用 emoji
