技能不生效？别急着重写
技能写出来，用的时候可能不按预期工作。这一节讲怎么调试和优化技能，让你别一遇到问题就推翻重来。
先定位，再动手。
对 codex-review 尤其重要：评审技能一旦写好就面向全组使用，出了问题如果直接推翻重写，既浪费又让全组跟着停摆。学会「先定位再动手」，才能精准修、快恢复。
技能失效的四个常见原因
1. 没被触发
你调用了技能，但它根本没执行。多半是：
- 目录路径放错了，Claude Code 没找到它
- SKILL.md 里没写清「触发条件/描述」，AI 不知道该不该用它
排查：确认路径正确、描述里写清「何时用」。
对 codex-review：如果你说「审一下这次改动」它却只简单看了两眼、没走三路并行，多半就是没被触发——检查技能是否在正确的技能目录、描述里是否写清了「审查改动时触发」。
2. 执行偏离
技能执行了，但行为和你想要的不一致。多半是：
- 步骤写得模糊，AI 自由发挥了
- 缺少输出规范，不知道做到什么算完
排查：把步骤写具体，把输出格式写死。
对 codex-review：如果它跑了但没按三档输出、或没做冲突对账，就是执行偏离——回去把 SKILL.md 的输出规范写得更强制。
3. 内容过时
技能还是上个月的，项目已经变了。技术栈、规范变了，技能没跟上。
排查：检查技能内容是否和当前项目一致。
对 codex-review：项目换了框架、规范改了，评审技能里的检查点（比如某个过时的 API 模式）就成了过时内容，审出的结论会误导人。
4. 太复杂没人用
技能写了一大堆，又长又绕，AI 执行困难，人也懒得调。
排查：精简技能，一次只干一件事。
对 codex-review：如果三路子 Agent 的检查点堆了几十条，AI 执行慢、容易漏，人也懒得触发。保持每路检查点精炼。
调试的步骤
1. 单独调用技能，观察它有没有执行
2. 执行了 → 看哪一步偏离预期 → 定位是「描述/步骤/规范」哪里的问题
3. 没执行 → 查路径和触发描述
4. 改 SKILL.md → 再调一次验证
一次改一处，别一次改好几处，否则不知道哪个改动起作用了。
对 codex-review，把它翻成一个可复用的排查清单：
排查 codex-review 技能：
1. 触发了吗？→ 没触发查路径和「触发时机」描述
2. 三路并行了吗？→ 没并行，查步骤里的「并行派子 Agent」写没写清
3. 按三档输出了吗？→ 没按，查输出规范强不强制
4. 做冲突对账了吗？→ 没做，查「冲突对账」这条约定够不够硬
5. 改一处 → 再跑一次验证
优化技能的几个技巧
- 加示例：在技能里放一两个「输入/输出」例子，AI 更容易对齐
- 写边界：明确「什么时候不要用这个技能」，避免误用
- 版本号：在 SKILL.md 里写版本，方便追踪变更
- 真实验证：每次改动都在真实任务里跑一遍，而不是只看文本
对 codex-review 的优化：
- 加示例：在 SKILL.md 里放一个「三档输出的例子」，AI 更清楚结论长什么样。
- 写边界：明确「1~2 个文件的小改动，不用走完整三路」，避免滥用。
- 版本号：写
version: 1.1之类，团队能追踪变更。 - 真实验证：每次改完检查点，都找一个真实分支跑一次，而不是只看 SKILL.md 文本。
一个调试案例
你的「代码审查」技能只输出「看起来不错」，没按规范分三档。定位：
问题：审查没按「必须改/建议改/可不改」分档输出。
定位：SKILL.md 的输出规范写得不够强制。
修：在输出规范里加一行「必须严格按三档输出，缺一档即不合格」。
再调：验证输出是否分档了。
一次改一处，验证通过。
对 codex-review 一个更真实的案例——三路并行变成了单路综合：
问题：说好并行三路，结果只输出一份综合意见。
定位：SKILL.md 步骤里没写死「并行」和「每路独立输出」。
修：在步骤里加「必须分别派出三个独立子 Agent，各自输出三档清单」，
并在输出规范里加「三路结论必须分开标注来源，不得合并成一份」。
再调：跑一次，确认看到三路独立结论。
定位到「步骤/规范」，改 SKILL.md 相应处，一次改一处验证。
落地练习
② 怎么判断做对了：你能走完「观察现象 → 定位到描述/步骤/规范哪一处 → 改那一处 → 验证」的完整闭环；每次只改一处，且能说清是哪个改动让结果变化。
③ 卡住了怎么办：如果改了没反应，先确认「改对地方了吗」——问题在输出规范你却改了描述，自然没用；如果定位不准，单独调用技能、观察它到底执行到哪一步偏了，再对症改那一处。
常见坑：一次改好几处，不知道哪个生效
调试技能最大的忌讳是同时改好几处：改了描述、又改了步骤、还改了输出规范，结果跑起来变好了——但你根本不知道是哪一个改动起的作用，下次再出问题，依旧两眼一抹黑。
调试的铁律是一次只改一处、改完就验证。这样每个改动的好坏都能归因。多个问题就一次修一个，串行来，别想着一把梭。
小结
- 先定位再动手，别一遇问题就重写
- 四类原因：没触发 / 执行偏离 / 内容过时 / 太复杂
- 一次改一处，改完真实调用验证
- 加示例、写边界、写版本，技能更稳
- codex-review 已能调试优化，下一模块进入权限与安全
下一模块进入「权限与安全模型」——给 codex-review 限定「评审能做什么、不能做什么」。