| name | claude-code-handoff |
| description | 从 Claude Code 的 Session 解析 jsonl 对话记录,接续执行任务 |
| argument-hint | Claude Code 的 session ID(如 UUID),或具体的 session.jsonl 文件路径 (必填) |
| license | Apache-2.0 |
| author | github/cafe3310 |
| depends_on_skill | [] |
| depends_on_binary | ["python3"] |
claude-code-handoff
解析本地 Claude Code 的 session jsonl 结构,诊断中断原因,自动恢复上下文或交接文档并指导接续任务。
适用场景
- 任务接力:开发工作由 Claude Code CLI 启动并开发至一半,现在需要由 Gemini (Antigravity 平台) 接管。
- 死锁/限制中断恢复:Claude Code 在运行过程中遇到了 API 频率超限 (429 Rate Limit) 或上下文超长窗口超限 (422 Context Window Exceeded) 等错误强制中止,需要无缝迁移至 Gemini 续作。
- 状态诊断:快速查看本地最新的 Claude Code session,查看最后执行的对话历史、调用的工具以及运行时的 git 分支和 cwd 信息。
工作原理
- 定位 Session 文件:
根据传入的
session ID(如 UUID)或 session 文件名,在 Claude 目录(包括官方的 ~/.claude/projects/)中自动搜索对应的 .jsonl 文件。同时也支持传入具体的本地文件路径。
- 提取历史与状态:
- 提取 session 中最近几轮的对话历史;
- 从
attachment 事件中提取最后生成的 HANDOFF.md ;
- 分析最近的
system 和 assistant 事件是否有报错。
- 输出 Handoff 并落盘:
- 自动在项目根目录生成/更新
HANDOFF.md。如果 session 包含已加载的 HANDOFF.md 附件,则以它为准;否则根据最近的上下文合成一份草拟版本。
- 生成一段指令用于用户直接复制粘贴给接续的 Agent 引导后续工作。
使用步骤
- 用户在对话中调用此技能,传入特定的 session ID 或 jsonl 文件路径。
- Agent 执行解析脚本:
python3 {path_to_public-agent-skills}/skills/claude-code-handoff/scripts/claude_handoff_parser.py -f <session_id_or_file_path> [-o /path/to/HANDOFF.md]
- 根据输出中的提示复制接力指令,并加载更新后的
HANDOFF.md 继续工作。