用 Claude Code 或者 Codex 跑长任务的人，多半都装过这类东西，让 Agent 把计划写进文件，/clear 之后还能接着干。
planning-with-files 走的就是这条路，三个 markdown 文件扔在项目里，上下文是 RAM，磁盘才是硬盘，hook 每轮把计划重新注入回上下文。
我翻它文档的时候，先看到的不是功能列表，是安装文档里的一张表：有几条安装路径根本不注册 hooks，而且不会报错。
而 hooks 是这个 Skill 唯一的差异化机制，没有 hooks，它就是一份躺在硬盘上的 markdown 模板。
先说结论：这东西值得用，但装完必须验一次。它的所有失败都是静默的，装坏了和还没建计划，在终端上长得一模一样。
!image
为什么坏了你看不出来
hook 的设计约定是永远返回 0。
这是对的设计，不然一个编辑器插件出点小毛病就能把你整个会话搞崩。
代价是所有异常都被吞掉了，解析不出计划目录，退出 0；注入了个空字符串，退出 0；路径比较失败什么都没干，还是退出 0。
更新记录里有一句话说得很直白：这类失败全部是静默的，所以一个装坏的安装，看起来就跟你还没建计划一样。
这种 bug 真出过，有一类路径问题，在装了 Windows 原生 coreutils 的机器上，会让整套机制彻底关闭。不是变慢，是每次 hook 触发都什么都不注入。
修这个 bug 的记录里有一句话我印象很深：在能复现的那台机器上 33 个本地测试是红的，而 CI 一直是绿的。
可以想象这个场景，装完了，/plan 敲下去文件也建出来了，task_plan.md 就在项目根目录躺着，每天用着，觉得还行，实际上它一次都没被注入回上下文。
!image
第一个坑：你装的那条路可能没带 hooks
安装文档里那张表，三列分别是 Skill 文件、斜杠命令、hooks。
插件路由（/plugin marketplace add 加 /plugin install）三样都有，而且它的 SessionStart 恢复是静默跑的。
npx skills add 这条，Skill 文件到位了，斜杠命令一个都没有，因为 commands/ 目录压根不复制。它的 hooks 是 activation-scoped 的，也没有 SessionStart。
npm install 更直接，只把包放进 node_modules，hooks 一个不注册，Skill 要你自己拷出来。手动拷到 ~/.claude/skills/ 的，跟 npx 那条一个待遇。
问题就在这儿。npx skills add 这条一直是以一行搞定的姿态出现的，装的人最多，也没人提示过少了什么。
现在文档给它加了一句警告：走 skill 路由可能是静默没 hooks 的，在意这个就别走。
正确的装法现在只有一条：
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
Codex 那边是另一套，走工作区的 .codex/hooks.json 或者 Codex 插件。
有意思的是 Codex 挂的生命周期 hook 有七个，比 Claude Code 插件的六个还多一个 PermissionRequest。
!image
第二个坑：装对了路子，也可能没注册上
这一条更隐蔽。文档把它归成两个条件，满足任意一个，独立 Skill 路由就是没有活跃 hooks 的状态。
一个是项目信任。 装在仓库里的 .claude/skills/，只有在这个项目的信任对话框被点过之后才会激活。headless 会话、脚本化跑的会话，从来没点过那个框，项目级 Skill 一个都不加载，而且什么都不打印。
另一个是调用时机。 独立 SKILL.md 里声明的 hooks 是 activation-scoped，意思是要等 Claude 在这个会话里先调用过这个 Skill，它们才注册上去。插件路由不一样，它在启动时就把生命周期描述符注册好了。
第二条的后果很具体：新开一个会话，第一句话就说继续上次那个任务。这时候 Skill 还没被调用过，hooks 还没注册，计划也就没被读回来。而恢复上次进度恰恰是你装它的全部理由。
所以装完得跑一次体检
项目为这件事专门做了个自检命令，/plan-doctor，插件路由自带。
不是插件路由的，直接在项目根目录跑脚本：
sh scripts/plan-doctor.sh
它一次回答五件事：在这个目录下计划解析得出来吗、解析出来的是哪一份、注入到底吐没吐出内容、这份计划有没有做过哈希校验、这台机器上有哪几个安装面。最后再甩一个数字，一次 hook 触发实际花了多少毫秒。
最后那个数字顺便解决了另一个疑问。这个 Skill 是每轮对话都要触发 hook 的，很多人担心卡。早期确实卡，一次触发要两秒到两秒四。
后来作者把逐候选的 grep -Eq 和 basename 调用换成了 shell 内建的 case 模式和参数展开，解析器的根路径也改成每次运行只算一遍。同一台机器上再测，一次触发 289 毫秒。
装完先跑这条，比什么都实在。
!image
第三个坑：它只有六成概率会被想起来
这一条不只对这个 Skill 成立，装了一堆 Skill 的人都用得上。
这个项目七月自己跑过一次测量：Skill 靠描述被触发，命中率是 60% 到 67%。同样的要求写成常驻加载的规则文件，100%。
差的那三四成，就是你以为它在工作、其实它压根没被想起来的部分。
文档给的做法是往 CLAUDE.md 里补一行，全局的那份也行：
When a task needs 3+ steps or 5+ tool calls, invoke the planning-with-files skill first and keep task_plan.md current.
描述负责被发现，规则行负责每次都触发。这两样不冲突，没有复杂任务在跑的时候，它们的成本都是零。
补一句，这个数字是在 Claude Code 上测出来的，给的也是 CLAUDE.md 的写法，但真正起作用的机制是常驻加载的规则文件，用 Codex 的话，对应位置就是 AGENTS.md，一样的道理：规则文件每次都在上下文里，Skill 描述得靠模型临场想起来。
几个容易踩的地方
三个计划文件默认是 gitignore 的，而且不会自动归档，下一个任务直接覆盖根目录那份。文档里说得很明白，这是工作内存，不是交付物，值得留下的东西要自己提升到代码、commit 或者文档里。别把它当项目文档用。
多会话并行写同一份计划，有个守卫会在勾选项或完成阶段数下降时提醒你。但那是事后的提示，不是锁，也不是合并机制，它不保证能发现每一次覆盖。真要并行，用 PLAN_ID 把每个任务钉到自己的目录。
会话追赶那两个显式模式，--metadata 只出聚合计数，--replay 会吐出受限的片段。文档特地标注了，那些片段要按不可信数据对待。别把它当成可信上下文直接喂回去。
Claude Code 自带的 plan mode 和这个不是二选一。plan mode 管的是动手之前的方案审批，这个管的是干活过程中的状态持久化。接力关系，交接只有一步：方案定了之后让 Agent 把它写成 task_plan.md 的阶段。
写在最后
这个 Skill 的思路不复杂，计划写在磁盘上，每轮对话由 hook 把它重新注入回上下文，所以 /clear、压缩和崩溃都冲不掉它。这件事本身是成立的，值得用。
但它的全部价值都押在 hooks 这一层上。而这一层的失败全是静默的，装错路径、项目信任没点过、Skill 在这个会话里还没被调用过，三种情况下它都不报错，终端看着和正常跑没有区别。
所以真正要记住的只有一句：装完别默认它在跑。
已经装了的： 看一眼斜杠命令列表里有没有 /plan-doctor。没有就说明走的是 Skill 路由，hooks 大概率没注册上，重装成插件路由。
准备第一次装的： 只走插件路由，装完立刻跑体检，再往 CLAUDE.md 里补那一行触发句。这三步做完再谈好不好用。
几个任务并行跑的： 用 PLAN_ID 把每个任务钉到自己的目录，别让两个会话抢同一份计划。那个守卫是事后提醒，不是锁。
它不会让 Agent 变强，只是让它别跑着跑着忘了自己在干嘛。前提是那条注入链路真的通着。