| name | context-handoff |
| description | Context hand-off when usage is high — summarize the current task, write a hand-off prompt, review it adversarially, and persist it to ~/tmp so a fresh session can resume. Runs a fixed 4-step flow: summarize -> write prompt -> review -> save. Triggered automatically at ~60% context usage (on CLIs whose hook injects a prompt) or manually via this CLI's handoff entry (/handoff, /skill:context-handoff, $context-handoff, etc.). Use when the user says 'handoff', '交接', '上下文交接', '/handoff', or a hook reminds you to call context-handoff.
|
| allowed-tools | Read, Write, Edit, Bash, Agent |
context-handoff
高上下文用量时的通用、跨 CLI、跨项目上下文交接能力。把当前 session 的任务状态总结成一份新 session 能直接续接的文档，落盘到 ~/tmp。兼容 Claude Code、codex、hermes、kimi、grok、kilo、opencode、gemini 等多 CLI。
两条触发路径，同一份逻辑
本 skill 只有一套 4 步执行逻辑，但有两个入口：
- 自动触发：支持注入的 CLI（如 Claude Code）在上下文用量达约 60% 时，由该 CLI 的 hook 注入提示，指示 agent「调用
context-handoff skill」。agent 收到该提示后，就是在这里——执行下文 4 步。不具备自动注入能力的 CLI（如 kilo / opencode / grok 默认）不会走这条路径。
- 手动触发：用户键入本 CLI 的 handoff 手动入口（Claude Code 用
/handoff，kimi 用 /skill:context-handoff，codex 用 $context-handoff 等），指示 agent 调用本 skill，同样执行下文 4 步。
无论哪条路径，都走下面 Step 1 → 4。不要因为触发方式不同而跳步或改变产物。
触发方式标记（Step 4 元信息头要用）：hook 注入提示触发 = auto；手动入口触发 = manual。若无法判定，默认 manual。
Step 1 — 任务分析与总结
目标：由主 agent直接基于自身持有的本 session 上下文，产出一份带证据的任务总结，严格区分「对话明示」与「推测」。
做法：主 agent 自己回顾本 session。主 agent 天然持有本 session 的完整对话与已执行操作，无需借助 sub-agent——sub-agent 运行在全新上下文，拿不到本 session 的转录；要把会话喂给它就得序列化整段对话，那正是要剔除的「噪音」，自相矛盾。总结必须：
- 回顾本 session 的：任务目标、已完成项、未完成/下一步、关键决策与依据、当前阻塞、相关文件路径与命令。
- 必须区分两类信息：
- 「对话明示」= 用户或 agent 在对话里明确说过的（标注来源：用户原话 / agent 某步操作）。
- 「推测」= 从上下文推断但未被明确确认的（显式打上
[推测] 标记）。
- 带证据：每条关键结论尽量附
文件路径:行号 或对话中的原话引用；拿不准的不要编。
总结完成后进入 Step 2。
Step 2 — 编写 Hand-off Prompt
目标：把总结写成新 session 能直接理解、无需追问的续接 prompt。
使用本 skill 目录下 references/handoff-template.md 的结构（相对路径，各 CLI 读自己安装路径下的副本）。若该模板文件尚未创建，按下述标准结构撰写（与 spec §4.4 落盘格式一致）：
# Hand-off — <任务一句话标题>
## 任务目标 （一句话目标 + 必要背景）
## 已完成 （本 session 已落地的项，带证据）
## 未完成 / 下一步 （可执行的具体动作：命令 / 文件 / 验证点）
## 关键决策与约束 （用户偏好、红线、待验证假设；标注明示 vs 推测）
## 相关文件 / 命令 / 路径 （绝对路径清单）
## 续接指令 （新 session 第一条该做什么）
撰写要点：
- 下一步必须可执行：写具体命令或文件路径，不要写「继续优化」这类空话。
- 路径一律绝对路径（把
~/ 展开成绝对路径，如 /home/<user>/...）。
- 约束要显式：用户说过的红线、偏好、待验证假设都写进来，标注来源。
- 不要包含任何 API key / token / secret（见全局约束）。
Step 3 — 审核与优化
目标：用对抗式视角查漏补缺，确保新 session 拿到文档能零追问续接。
做法（优先）：用本 CLI 的子代理/任务机制派一个对抗式子代理审核 Step 2 的草稿，检查三项：
- 完整性：新 session 据此能否续接？有无信息缺口（缺命令、缺参数、缺前置条件）？
- 准确性：草稿里引用的文件路径/命令是否真实存在？要求子代理用
Read/ls（Bash）抽查验证，不凭记忆下结论。路径不存在的 → 标记为错误。
- 歧义：有无两种解读的表述？有无指代不清（「那个文件」「之前说的」）？
降级分支：若本 CLI 无子代理/任务机制（如 kilo / opencode / grok 默认，或当前 CLI 不支持派子代理），主 agent 自行以对抗视角再审一遍 Step 2 的草稿，同样查完整性 / 准确性抽查（用 Read/Bash 验证关键路径是否存在）/ 歧义三项，不强制派子代理。
主 agent 收到审核反馈（或自审结果）后，据反馈修正草稿（直接在上下文中修正 Step 2 的草稿内容——此时草稿尚未落盘，首次 Write 发生在 Step 4.3），修正后再进入 Step 4。若审核无重大问题（仅措辞建议），可直接进入 Step 4。
Step 4 — 文档保存
目标：把审核后的文档双写到 ~/tmp，并提示用户续接方式。
4.1 生成时间戳
用 Bash 生成时间戳（秒级，避免多 CLI 同分钟撞名）：
date +%Y%m%d-%H%M%S
4.2 收集元信息
generated：上一步的时间戳（转成 YYYY-MM-DD HH:MM:SS 展示）。cli：当前 CLI 名（claude-code / codex / hermes / kimi / grok / kilo / opencode / gemini / unknown）。session_id：优先从 hook 注入提示（auto 触发时提示文本已含 session_id）或本 CLI 的 session 标识获取；若不可得，标注 unknown。context_used：hook 自动触发时，提示文本已带「上下文用量已达约 X%」，直接采用该百分比；manual 触发（无注入文本）时标注 unknown。trigger：auto 或 manual（见上文「触发方式标记」）。
把元信息写成文档头部（紧随标题之后）：
- generated: 2026-07-11 14:30:22
- cli: claude-code
- session: <session_id>
- context_used: ~62%
- trigger: auto | manual
4.3 双写到 ~/tmp/
归档文件（ts+cli 命名唯一，直接 Write）：
| 文件 | 用途 |
|---|
~/tmp/handoff-<ts>-<cli>.md | 人类可读，时间戳+cli 归档 |
~/tmp/handoff-<ts>-<cli>.json | 机器可读，时间戳+cli 归档（同结构，字段名见下） |
固定指针（最新副本，原子换名写入）：
| 文件 | 用途 |
|---|
~/tmp/handoff-latest.md | 人类可读，固定名指针（最新副本） |
~/tmp/handoff-latest.json | 机器可读，固定名指针（最新副本） |
.md 与 .json 内容同构；.json 用结构化字段（title / generated / cli / session / context_used / trigger / goal / done / next / decisions / files / resume_instruction）。
归档写入：handoff-<ts>-<cli>.{md,json} 因 ts（秒级）+ cli 命名唯一，可直接 Write，不撞名。
latest 指针原子换名（防多 CLI 并发交错截断）：先 Write 到每个写者独占的 tmp 名 ~/tmp/handoff-latest.{md,json}.tmp.<cli>.<pid或随机>（tmp 名必须带 cli+唯一标识——若两写者共用固定 tmp 名，后写者覆盖先写者内容、随后先写者的 mv 把已被覆盖的 tmp 移成 latest，造成静默错配），再 Bash mv（等价 fs.rename，原子）覆盖 ~/tmp/handoff-latest.{md,json}——后写者完整胜出而非交错截断。示例：
mv ~/tmp/handoff-latest.md.tmp.<cli>.<pid> ~/tmp/handoff-latest.md
mv ~/tmp/handoff-latest.json.tmp.<cli>.<pid> ~/tmp/handoff-latest.json
latest 读取异常回退：若 ~/tmp/handoff-latest.md 读取异常（截断/空/乱码），按 mtime 回退到最新归档：
ls -t ~/tmp/handoff-*.md | head -1
handoff-latest.* 永远是最新一次交接的副本——每次执行都覆盖写。各 CLI 的 resume 读 latest，零查找。
4.4 哨兵文件（说明，本 skill 不写）
auto 触发时，哨兵 ~/tmp/.handoff-done-<cli>-<session_id> 由该 CLI 的 hook 在触发瞬间写入（含诊断 JSON，作用是抑制本 session 的重复提醒，hook 靠 existsSync 判重后直接 exit 0）。本 skill 绝不写该哨兵——重写会覆盖 hook 的诊断信息。manual 触发无需哨兵。
哨兵命名约束（通用）：
- 哨兵名含 cli 段：
.handoff-done-<cli>-<session_id>（防跨 CLI 误判）。
- session_id 缺失时绝不写哨兵：若 sid 为
unknown 或缺失，hook 必须 exit(0) 不触发、不写哨兵——否则 .handoff-done-<cli>-unknown 一旦写出，该 CLI 所有后续 session 命中判重后永久静默。
- 各 CLI hook 的哨兵命名细节（含 cli 段的具体取值与格式）以该 CLI hook 契约为准。
4.5 输出 Next Up 提示
完成后，向用户输出（中文）本 CLI 的清上下文命令 + resume 命令。通用模板：
交接文档已保存到 ~/tmp/handoff-latest.md（及 .json）。
下一步：执行本 CLI 的清上下文命令，然后在新 session 里运行本 CLI 的 resume 命令续接任务。
Claude Code 示例（CC 手动 /handoff 路径）：
下一步：/clear 清空上下文，然后在新 session 里运行 /handoff resume 续接任务。
其它 CLI 按本 CLI 的实际命令输出（如 kimi 的 resume 入口、codex 的 $context-handoff resume 等）。auto 路径（hook 注入）由 hook 文本自带续接指引，不依赖本节 skill 正文输出。
文件与路径契约（跨文件对齐）
本 skill 与各 CLI 的 hook、command、模板文件之间通过以下契约对齐，改动任一端都需同步另一端：
| 契约项 | 值 |
|---|
| skill name | context-handoff |
| skill 目录 | 本 CLI 的 skills 目录下的 context-handoff/（CC/kimi/grok/hermes/kilo/opencode 各自 skills 目录下独立 symlink 指向仓库；codex 走 ~/.codex/agents 的 TOML；gemini 经 ~/.gemini/skills → ~/.claude/skills 目录级 symlink 共享） |
| 模板文件 | 本 skill 目录下 references/handoff-template.md（相对引用） |
| 归档产物 | ~/tmp/handoff-<YYYYMMDD-HHMMSS>-<cli>.md + .json |
| 固定指针 | ~/tmp/handoff-latest.md + .json |
| 哨兵文件 | ~/tmp/.handoff-done-<cli>-<session_id>（cli 段防跨 CLI 误判；sid 缺失则不写） |
| resume 读路径 | ~/tmp/handoff-latest.md（由本 CLI 的 resume 入口 Read） |
全局约束
- 只读现有文件：本 skill 可 Read 任何现有文件借鉴/验证，但绝不修改本 skill 目录之外的任何现有文件（尤其各 CLI 的 hook、config、settings、其它 skill/command）。
- key 安全：交接文档里绝不写入任何 API key / token / secret。引用配置文件时只写路径，不抄内容。
- 基于事实：不凭训练记忆猜测各 CLI 的 hook/command/skill 机制；拿不准就 Read 现有样本确认，或如实标注不确定性。
