Codex Skills 进阶：用 references、scripts 与 evals 建立可验证工作流

这是 Codex 系列的第 12 篇。

第 11 篇做出了第一个仓库级 Skill：review-technical-article。当用户说“从读者角度 review 这篇教程”时，它能告诉 Codex 何时介入、按什么顺序检查，以及怎样给出发布结论。

如果这份 Skill 只偶尔使用，到这里就够了。第 12 篇处理的是另一种情况：同一套能力开始被反复使用、修改和共享，原来的一份 SKILL.md 渐渐承受不了全部职责。

来源规则越来越长，主文件开始难读；
日期和图片路径每次都靠模型检查，结果不够稳定；
改完触发描述以后，不知道它会不会漏掉任务或到处误触发；
几个月以后，已经说不清某次测试对应的是哪一版文件。

这一篇不会重新创建另一个玩具 Skill，而是继续改造这个真实案例。重点也不是“凑齐四个目录”，而是判断：什么问题应该继续交给 Agent，什么问题应该沉淀成知识、脚本或评估用例。

版本与证据说明

本文按 2026-07-15 的 OpenAI Skills 文档、Agent Skills specification、Anthropic Agent Skills 与 Claude Code 文档整理，并对照 OpenAI、Anthropic 的官方 GitHub 示例。Codex 是本文的实际运行环境，Claude 只用于说明共用规范和产品边界；官方约定与本文项目自定义字段会分开标注。

本文已经验证目录结构和两个确定性脚本，但没有把“评估清单结构通过”写成“模型行为已经通过”。完整行为评估需要在相互独立的干净任务里运行当前 Skill 和基线，再人工比较结果。

一分钟概览

先把整篇压缩成一条升级路线：

所以，第 12 篇真正讲的是：

先让一个 Skill 能用，
再根据真实问题增加结构，
最后为每种“通过”保留对应证据。

其中最重要的边界是：

目录格式正确
≠ 脚本运行正确
≠ Codex 行为符合预期
≠ 最终文章内容一定正确

图 1 可以从左到右理解：SKILL.md 继续负责判断和编排；详细知识按需进入 references；确定性检查进入 scripts；真实任务留在 evals；最后仍由人决定是否接受结果。

第一次阅读可以先跳过什么

• 只想理解方法：读到第 2 节，再看第 16 节练习和第 17 节清单。
• 准备给 Skill 增加脚本：重点看第 3-5 节和第 13 节的实际结果。
• 准备修改触发条件：重点看第 6-8 节，尤其是当前版与基线隔离。
• 准备迁移到 Claude 或安装社区 Skill：最后再看第 14 节，不需要一开始背产品差异。

最终目录长什么样

这次升级后的目录如下：

.agents/
└── skills/
    └── review-technical-article/
        ├── SKILL.md
        ├── agents/
        │   └── openai.yaml
        ├── references/
        │   └── source-policy.md
        ├── scripts/
        │   ├── article-preflight.mjs
        │   └── validate-evals.mjs
        └── evals/
            ├── evals.json
            └── files/
                └── sample-codex-skill-tutorial.md

这是改造完成后的状态，不是创建 Skill 时必须复制的模板。一个稳定的 instruction-only Skill 仍然可以只有 SKILL.md；只有当上表中的问题真实出现时，才值得增加对应目录。

下载本文验证过的 review-technical-article 1.1.0 Codex 仓库级示例包

压缩包只包含 Skill 目录和一篇明确标注“故意含错”的评估 fixture，不包含博客正文或项目依赖。它验证于 Codex 和当前博客仓库。解压到其他项目以后，仍需安装 Node.js 与 gray-matter，或者把预检脚本改成自包含实现；先运行文中的结构和脚本检查，再决定是否启用隐式调用。

在 npm 项目中可以安装本文实际使用的版本：

npm install --save-dev gray-matter@4.0.3
node .agents/skills/review-technical-article/scripts/article-preflight.mjs --help

使用 pnpm、Yarn 或 Bun 时换成对应的安装命令。若只需要 instruction、references 和 eval 用例，也可以不运行依赖 gray-matter 的文章预检脚本，但必须把这项验证标成未执行。

本文附件的 SHA-256 为 41815817F52B82BFA755F8E1BEEA1106D69C272338FA3F67165A32D264F128C9。它用于确认下载文件与本文最终复验的压缩包一致，不代表包内 Skill 已完成模型行为评估。

1. 先定义要验证哪一层

“这个 Skill 已经验证过”听起来像一个结论，实际上至少包含四个不同问题。先说清正在验证哪一层，后面的脚本和 eval 才不会被过度解读。

对本文这个技术文章审查 Skill，我把可靠拆成四层：

这四层不能相互替代。

例如，article-preflight.mjs 能确认图片文件存在，却不知道图里是否写错了命令；它能确认摘要不是空字符串，却不知道摘要是否准确；它能确认外链返回了 HTTP 200，却不能证明链接内容支持正文里的主张。

所以本文的目标不是“用脚本替代编辑”，而是：

让机器负责适合机器的确定性，
让 Agent 负责需要上下文的判断，
让人保留最终发布责任。

2. 先按问题分工，再决定放在哪里

Skill 变复杂以后，第一个设计问题不是“如何拆文件”，而是“这条内容属于谁”。