context-handoff

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 步执行逻辑，但有两个入口：

1. 自动触发：支持注入的 CLI（如 Claude Code）在上下文用量达约 60% 时，由该 CLI 的 hook 注入提示，指示 agent「调用 context-handoff skill」。agent 收到该提示后，就是在这里——执行下文 4 步。不具备自动注入能力的 CLI（如 kilo / opencode / grok 默认）不会走这条路径。
2. 手动触发：用户键入本 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 的草稿，检查三项：

1. 完整性：新 session 据此能否续接？有无信息缺口（缺命令、缺参数、缺前置条件）？
2. 准确性：草稿里引用的文件路径/命令是否真实存在？要求子代理用 Read/ls（Bash）抽查验证，不凭记忆下结论。路径不存在的 → 标记为错误。
3. 歧义：有无两种解读的表述？有无指代不清（「那个文件」「之前说的」）？

降级分支：若本 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}——后写者完整胜出而非交错截断。示例：

# 写者独占 tmp 名（pid 或随机后缀保证唯一），再原子 mv
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 现有样本确认，或如实标注不确定性。