先还原一个你大概率经历过的下午：上午用 Codex 推进某个功能，聊透了架构取舍、踩平了一个依赖的坑、否掉了一个方案。下午你换了另一个客户端接着干——新会话对项目一无所知。目标是什么？干到哪了？哪些决定不能翻？上次的坑在哪？你要么从头复述一遍，要么眼睁睁看它把上午刚否掉的方案兴冲冲重做一遍，把上午刚踩过的坑原样再踩一次。

project-handoff-skill 把交接变成项目里的一组文件：新会话开工前先看交接状态再动手。它不绑定任何一家客户端——只依赖所有 agent 都认的 AGENTS.md 开放约定，谁接手都一样。

这个 skill 来自我的日常：五六个 agent 客户端来回切，每次交接都靠人肉复述。试过让 agent 自己写交接笔记，问题是没人管得住它的形状——有的越写越肥把上下文吃光，有的写完就忘没人接着看。于是把交接本身固化成 skill：开关一次问清、记录自动落盘、体积有硬预算。

五个该装它的场景

场景一：你在多个客户端之间来回切

上午 Codex、下午 ZCode、晚上 Kimi Code CLI——换客户端不想重新交代背景。装好后对 AI 说一句「用 project-handoff 给这个项目配置交接模式」，它完成用户级安装并在项目根放一个开关文件。之后每个新会话 AI 自动检查：没配置过，问一次「要不要开启交接」；配置过，静默沿用，绝不再问。

场景二：项目跨天跨周，会话开了又关

每次回来想直接续上，而不是翻聊天记录拼凑进度。开启交接后，项目里有一份 HANDOVER.md——目标、进度、红线决定、踩坑记录都在里面，新会话开工前先读它。写到哪、接下来干什么、哪些地方不能动，一眼看到。

场景三：被迫中途换工具

配额用尽、上下文塞满、某家模型当天不可用——你不得不换，而新工具必须立刻知道干到哪、哪些不能碰。这正是交接文件的主场：它不依赖任何特定客户端的会话记忆，文件在项目里，谁来都能读。

场景四：你吃过「漏讲一句」的亏

忘了说上次否掉了 A 方案，agent 重做一遍；忘了说那个依赖有坑，它原样再踩一次。交接记录把这些「负知识」钉在明面上——否掉的决定、绕开的路径、复现过的坑——新会话开工前就看到，而不是撞上之后再听你复盘。

场景五：一个项目多个人（或多个 agent）接力

你下班了，接手的人和它的 agent 需要同一份「干到哪了」。交接文件就在仓库里，人读得懂，agent 也读得懂——接力双方看的是同一份事实。

这些情况别装

安利文的诚意包括告诉你什么时候不该用：只用一个客户端从不切换的，单客户端自己的会话记忆就够，交接文件纯属开销；一次性脚本仓库没有「下一次会话」，交接无从谈起；如果你完全不理解 agent 为何物、工具全由别人代管，多出来的文件和询问只会添乱。

它凭什么管得住自己

agent 自己写交接笔记最常见的三种失控——越写越肥、写完没人看、不知道该不该写——这个 skill 各有一道闸：

  • 占用有界：交接记录超 8KB / 300 行自动瘦身，只留最近三节，其余进归档；运行记录每个 agent 保留 20 条，更旧的压成归档索引。agent 平时只读小文件。
  • 足迹自解释：一条「帮我体检交接配置」让 agent 跑 --status——这是什么、开还是关、哪些文件属于它、怎么关怎么删，一条命令答全。
  • 心跳锁判孤儿：会话半路死掉没人收尾，超时自动标记「已中断，待接手」，下一个 agent 一眼看到。
  • 隐私红线：钩子只记录事件名、时间、会话编号，从不记录提示词、回复、命令内容——仓库里有测试专门钉住这条承诺，45 个回放用例跑在 macOS + Linux 的 CI 上。

安装与使用

# 方式一：skills CLI（推荐）
npx skills add kelegele/project-handoff-skill

# 方式二：手动放进技能目录（目录名须为 project-handoff）
# 跨 agent 通用: ~/.agents/skills/   ZCode: ~/.zcode/skills/   Codex: ~/.codex/skills/

# 更新
npx skills update project-handoff

装好后触发只需要两句话术：

用 project-handoff 给这个项目配置交接模式

帮我体检交接配置

不想装任何东西？把仓库地址发给你的 agent：「帮我安装这个 skill：https://github.com/kelegele/project-handoff-skill」。

日常服务命令（都对 AI 说人话即可，agent 会去跑脚本）：

你说它跑干什么
开启/关闭交接--enable / --disable幂等开关；关闭只翻开关，保留全部记录
体检交接配置--doctor配置 / 钩子接线 / 权限 / 时区逐项体检，PASS/FAIL/WARN 分级
交接什么状态--status模式、文件所有权、最近运行、占用、卸载方法
清理交接记录--gc运行记录轮转 + 交接记录瘦身

三个高频疑问

换一个它不认识的 agent 还能用吗？ 能。共享工件只依赖 AGENTS.md 通用约定，任何兼容客户端读同一份文件交接；自动记录是加分项，某家接不上不影响交接本身。

会反复问我开不开吗？ 不会。首次问一次，之后有效配置静默沿用；配置坏了会点名具体问题，不会装作没配置过。

怎么彻底卸载？ --status 给出完整清单：删项目里的开关文件与 docs/execution/，去掉 AGENTS.md 交接段，删技能目录里的 project-handoff/，全程无残留依赖。

现在就开始

最小成本的试用：挑一个你确实在多工具间切换的项目，装上，开启交接，然后正常干半天活、换一个客户端续一次。你会立刻看出交接文件替你省掉了多少复述。

仓库在 GitHub，问题与想法欢迎提 Issues。它和 agentsmd-skill 是同一套思路的两块拼图：agentsmd 管「教训沉淀成规则」（用法见场景指南，设计见设计哲学篇），project-handoff 管「进度交接给下一个会话」——一个让 AI 记住怎么干，一个让 AI 知道干到哪。