Codex 自定义技能，四件比我预想麻烦的事

Codex 自定义技能，四件比我预想麻烦的事

用 Codex Desktop 做自动化这段时间，我陆续写了十来个 skill，也在把 OpenClaw 里的东西往这边迁。遇到的问题不是什么大 bug，基本都是些"写完才发现"的细节，但每次都要来回折腾半天。记下来，省得下次再踩。

---

一、第一个 skill 连创建都没过

skill-creator 是 Codex 内置的系统技能，用来初始化新技能的目录结构。我用它创建 requirement-consistency-check 时，命令本身执行正常，但最后报了这个：

exec_command failed: CreateProcess { message: "Codex(Sandbox(Denied { ... }))" }

Codex 有一套沙箱策略叫 workspace-write，只允许写当前工作目录和白名单里的路径。~/.codex/skills/ 不在工作区里，所以脚本一往那写文件就被拦。不是权限问题，就是策略设计如此——需要手动批准一次"命令前缀"才能继续：

Approved command prefix saved:
- ["python3", "/Users/k/.codex/skills/.system/skill-creator/scripts/init_skill.py"]

批准完就好了。但这个流程每次建新技能都要经历一遍。如果经常要写 skill，直接把 ~/.codex/skills/ 加进 Codex 配置的 writable_roots 一劳永逸。

创建完之后记得跑内置的校验脚本：

python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py \
  ~/.codex/skills/requirement-consistency-check
# Skill is valid!

---

二、写了技能，AI 根本没按它说的做

这个问题藏得比较深。

requirement-consistency-check 这个技能，我在 SKILL.md 里写的是"产出结构化 Markdown 报告"。用起来之后用了一句：

"使用技能后不应该生成一个报告文件吗，文件地址在哪？"

打开对话才发现，AI 把整份分析结果直接输出在聊天窗口里，没有写任何文件。

技术上讲，AI 没错——"产出报告"这四个字，对话输出确实也算"产出"。我以为写"报告"就等于"写文件"，但对 AI 来说这两件事完全不同。

后来改了 SKILL.md，强制说死：

### 强制落盘规则
不允许只返回文本分析结论，必须调用脚本并写入报告文件。
默认输出路径：./reports/requirement-check/requirement_consistency_时间戳_report.md
回答中必须给出落盘的绝对路径。

而且要明确禁掉随机路径，否则 AI 会往 /tmp/ 写——写进去了你也不知道在哪：

禁止输出到 /tmp/ 或随机 UUID 路径。
文件名格式：req_check_{需求名}_{yyyyMMdd_HHmmss}.md

这件事的教训是：SKILL.md 里的每条规则，要当成给一个字面理解能力极强、但没有上下文推断习惯的人写的。"应该输出报告"和"必须写入文件到 X 路径"，对它来说是完全不同的指令。

---

三、备份了一个 .bak 目录，之后连续用错版本

4 月 2 日下午改了技能，顺手做了一次备份：

~/.codex/skills/requirement-consistency-check.bak.20260402_151420/

接下来两天的 session，引用技能路径时，两次都选了 .bak 版本。旧版的 SKILL.md 结构完整、能正常运行，只是缺少新加的约束规则——所以 AI 也没报错，就这么悄悄用了两天旧版。

问题在于备份目录放在了 ~/.codex/skills/ 里面，Codex 技能扫描时两个目录都能发现，名字又长得像，手误很自然。

现在的做法：原地覆盖，版本管理交给 git，SKILL.md 纳入 git 跟踪。非要备份就备份到 skills 目录之外的地方，比如 ~/.codex/skills-archive/。

---

四、OpenClaw 里的技能，在 Codex 里完全不认识

这件事我拖了挺久才处理。

在 OpenClaw 里积累了 18 个技能：

~/.openclaw/skills/
├── diff-test-analyzer          # 分支 diff + 测试建议
├── requirement-consistency-check
├── requirement-analyzer
├── advanced-memory
├── auto-model-switcher
├── self-improving
├── session-auto-clean
└── ... 共 18 个

Codex 的技能目录是 ~/.codex/skills/，和 OpenClaw 完全分开，互不相认。在 Codex session 里用 $diff-test-analyzer，会直接没响应——技能不在发现路径里，等于不存在。

实际处理 diff-test-analyzer 时，AI 的回应是这样的：

"这个技能文件在本机能读到，但它不在当前会话的已注册技能列表里，所以我会把它当作补充流程参考来用，不把它当正式可调用技能。"

也就是说，它能读 SKILL.md，但不会把 SKILL.md 里的规则当约束来执行。分析脚本倒是能直接跑：

~/.openclaw/skills/diff-test-analyzer/scripts/analyze-branch.sh \
  ali-customer-application feature_282tw9_es_field_compatible

但这样绕过了技能系统，脚本输出不会遵循 SKILL.md 里定义的格式，也没有技能上下文注入。

最直接的解法是软链接：

ln -s ~/.openclaw/skills/diff-test-analyzer ~/.codex/skills/diff-test-analyzer

零复制，两边同步更新。缺点是依赖 OpenClaw 目录存在，目录一移走链接就断了。

另一个做法是完整迁移到 ~/.codex/skills/，改掉脚本里硬编码的 OpenClaw 路径，独立维护。高频使用的先迁移，低频的先软链，两种方式混着用。

---

最后

写 Codex 技能这件事，深度很容易被低估。SKILL.md 写三行也能跑，但"能调用"和"按预期工作"之间的差距，往往就藏在那些没写清楚的细节里：输出是对话还是文件、路径是固定的还是随机的、触发后必须做什么不能做什么。