Codex 如何扩展 Agent Skills？claude-skills 使用方法详解

Codex 扩展 Agent Skills 的核心，不是把 Claude Code 的插件原样搬过来，而是让 Codex 能读到同一套 SKILL.md、脚本和参考资料。claude-skills 之所以值得看，是因为它在 README 里明确把 OpenAI Codex 放进支持工具，并提供了 agent-skills-cli 和手动复制两条路线。

如果你已经在 Codex 里用过本地 Skill，会发现它和普通提示词不一样。Skill 的 description 决定什么时候触发，正文规定执行边界，references 保存长资料，scripts 承担可重复检查。claude-skills 把这些内容打包成现成目录，Codex 只要能找到这些目录，就能在匹配任务时加载。

方法一：用 agent-skills-cli 同步

README 给 Codex 的安装命令很直接：

npx agent-skills-cli add alirezarezvani/claude-skills --agent codex

这条路线适合想快速试用的人。安装后，先不要立刻让 Codex 修改真实项目；更稳的测试是问它“列出已可用的技能，并解释某个技能什么时候会触发”。失败场景：命令执行完成，但当前 Codex 会话没有重新加载技能目录，你会误以为技能无效。遇到这种情况，重开会话或检查安装目录比反复改 prompt 更有用。

方法二：克隆仓库后挑选复制

手动路线适合团队。你可以先 clone 仓库，只挑 engineering、marketing-skill、markdown-html 或某个单独技能目录，复制到 ~/.codex/skills。这个方式慢一点，但便于审查脚本、删掉不需要的 references，也便于团队固定版本。

失败场景：直接复制整个仓库到 skills 目录，导致目录层级不符合 Codex 预期。一个可用 Skill 通常应该是单独文件夹，里面有 SKILL.md；如果 Codex 只看到外层仓库文件，而不是技能包本身，就不会按你想的方式触发。

Codex 使用 claude-skills 时要看三件事

1. 触发词是否清楚。description 写得越具体，Codex 越容易在正确任务里调用。
2. 脚本是否可信。尤其是会扫描仓库、生成文件、运行命令的技能，先在测试目录跑。
3. 输出是否可验收。好技能会给检查点和失败处理，而不是只给一段漂亮解释。

这三件事决定 Skill 是否真正提高效率。很多人安装技能库后没有感觉，是因为只多了一堆说明文件，却没有把任务写成可触发的场景。

什么时候适合扩展，什么时候先别动

适合扩展的场景包括：固定代码评审标准、反复生成发布清单、经常做 API 设计审查、需要把 Markdown 转成 HTML、希望让 Codex 按安全清单检查技能。先别动的场景也明确：项目权限很敏感、团队还没看过脚本、你只需要一次性问答、或者当前任务不允许本地文件写入。

把 claude-skills 接进 Codex，最好当成“给 Agent 装工作手册”，而不是“给模型加魔法”。工作手册写得再好，也要你限定任务、检查输出、控制权限。做到这一点，Codex 的扩展才会从提示词堆叠变成可复用流程。