Codex Skills 入门：把重复任务沉淀成可复用能力

这是 Codex 系列的第 11 篇。

前十篇一直在解决“怎样把一次工程任务做对”：读项目、写 Prompt、建立 AGENTS.md、控制权限、修 bug、走 GitHub 交付。到了这一篇，问题开始变化：

如果同一套做法已经反复出现，
怎样让下一次任务不必从头解释？

答案不只是保存一段 Prompt，而是把触发条件、执行步骤、停止条件和验收格式一起沉淀成 Skill。

这一篇会在当前博客仓库里创建一个真实的 review-technical-article Skill。它负责从事实准确性、复现性、读者收益和发布条件四个方向审查技术教程。你可以把它换成代码 review、发布检查、故障复盘或其他重复工作流，但教程里的判断方法不变。

版本说明

本文按 2026-07-15 的 OpenAI 官方 Skills 文档和 Agent Skills specification 整理。当前官方推荐仓库级 Skill 放在 .agents/skills；一些旧文章或旧环境里出现的 .codex/skills 不作为本文默认路径。OpenAI 的 openai/skills 仓库目前也已经标记为 deprecated，新的官方示例正在迁移到 openai/plugins。

本文讲的是本地目录中的 Skill 编写与发现，适用于 Codex 桌面端、CLI 和 IDE。开始前先确认当前工作目录位于目标项目内，并且 Codex 可以读取和写入该目录。面向 ChatGPT Web 或团队分发的 Plugin 工作流不在本篇范围内。

一分钟概览

如果只记住五句话，可以先记这五句：

1. Skill 是一个目录，最少只有一个 SKILL.md。
2. name 和 description 决定 Codex 能不能找到它，正文决定找到以后怎么做。
3. 仓库专用 Skill 放 .agents/skills，个人通用 Skill 放 ~/.agents/skills。
4. 第一个 Skill 先保持 instruction-only，不要急着添加脚本和外部工具。
5. 测试不能只看“会不会触发”，还要看“不该触发时能不能保持安静”。

从反复重写 Prompt 到可重复调用的 Codex Skill：把触发条件、执行步骤和验收标准写入 Skill，再通过正向与负向测试持续改进

图 1：Skill 不是 Prompt 收藏夹。它保存的是一套能被发现、执行、检查和继续改进的工作流。

跟做结束后，仓库里会得到这个目录：

.agents/
└── skills/
    └── review-technical-article/
        └── SKILL.md

实际项目还可以有 agents/openai.yaml、references/、scripts/ 和 assets/。但这一篇只做最小闭环，复杂结构留到第 12 篇。

如果使用内置 Skill Creator，它可能同时生成可选的 agents/openai.yaml。本文仓库保留了这份界面元数据，但本篇工作流不依赖它；手动跟做时只有 SKILL.md 也可以被 Codex 发现。

1. 先判断：这个任务真的需要 Skill 吗

不是每段好 Prompt 都值得变成 Skill。

我会先看三个条件：

重复：同类任务已经出现不止一次
稳定：步骤和验收标准大体不变
可判断：能说清什么时候该用、什么时候不该用

三项同时成立，才值得沉淀。

一个实用判断是：如果你只是嫌 Prompt 太长，先尝试把项目规则移进 AGENTS.md；如果你希望 Codex 在某类任务出现时主动选择一套流程，再考虑 Skill。

前者解决“这个项目一直怎样工作”，后者解决“遇到这种任务时怎样工作”。

2. Skill 到底保存什么

OpenAI 当前把 Skill 定义为一个包含 instructions、resources 和可选 scripts 的目录。最小结构只有 SKILL.md：

my-skill/
└── SKILL.md

完整结构可以继续扩展：

my-skill/
├── SKILL.md             # 必需：元数据和执行流程
├── agents/
│   └── openai.yaml      # 可选：界面、调用策略、工具依赖
├── references/          # 可选：按需读取的规范和资料
├── scripts/             # 可选：确定性执行脚本
└── assets/              # 可选：产物模板、图标和样例

这几部分并不平级：

这一点很重要，因为它决定了 Skill 应该怎样写。

3. 渐进式加载：description 为什么比长正文更重要

Codex 使用 progressive disclosure，也就是渐进式加载。

任务开始时，它不会把所有 Skills 的正文全部塞进上下文，而是先看到每个 Skill 的 name、description 和文件路径。只有任务与某个 Skill 匹配，或者你显式点名它，Codex 才读取完整 SKILL.md。正文里如果再引用 references/ 或 scripts/，这些资源也只在需要时读取或执行。

Codex Skill 的三层渐进式加载：先看 name、description 和路径，匹配后读取 SKILL.md，真正需要时再读取 references、执行 scripts 或使用 assets

图 2：description 负责找到入口，SKILL.md 负责带路，resources 负责处理复杂细节。

官方文档还给了一个容易忽略的限制：初始 Skill 列表最多使用模型上下文窗口的 2%；如果上下文窗口大小未知，则最多使用 8,000 个字符。Skills 太多时，Codex 会先缩短 description，必要时还可能省略部分 Skill 并给出提示。

这意味着：

• description 的关键词要靠前。
• 一句话要同时说明“做什么”和“什么时候用”。
• 不要用“万能助手”“提高效率”这类没有检索价值的词。
• 一个 Skill 只负责一个明确任务。

Skill 正文写得再好，如果 description 找不到入口，它就只是躺在目录里的文档。

4. 先定义任务合同，不要急着建文件

我们的案例是“技术文章 review”。在写 SKILL.md 之前，先把它的任务合同写成四行：

这里最容易犯的错误，是只写目标，不写非目标。

如果 description 只有“帮助审查文章”，那么下面这些相邻任务都可能被错误地扩大成完整技术审查：

• 写一篇新文章。
• 改写标题。
• 只修正错别字或调整语言流畅度。
• 总结一篇新闻。
• 核查一个与整篇审稿无关的孤立事实。

它们相邻，但不是同一件事。Skill 如果什么都想接，最后就没有稳定行为。

5. 选择作用域：放在仓库还是用户目录

当前官方文档列出的常用作用域是：

Codex 会从当前工作目录向仓库根目录扫描 .agents/skills。这让 monorepo 可以同时拥有根级通用 Skill 和子模块专用 Skill。

本文选择仓库根目录：

ralf-blog/.agents/skills/review-technical-article/

原因很直接：这个 Skill 依赖博客的写作规则、分类、frontmatter 和文章风格，应该和仓库一起维护。等它脱离本博客也能稳定工作，再考虑移到 ~/.agents/skills。

还要注意一个当前行为：如果两个位置存在同名 Skill，Codex 不会把它们合并，两个都可能出现在选择器里。因此不要用同一个 name 做“局部覆盖”，最好给不同 Skill 使用可区分的名称。

6. 创建第一个 Skill

有两种方法。

6.1 使用内置 Skill Creator

在 Codex 中显式调用：

$skill-creator

可以这样描述任务：

请在当前仓库的 .agents/skills 下创建 review-technical-article。

它用于审查中文或英文技术文章和教程，重点检查：
1. 事实准确性；
2. 读者能否复现；
3. 是否有可带走产物；
4. 是否达到发布条件。

当用户要求从零写文章或只改错别字时，不应触发。
先做 instruction-only Skill，不要添加 scripts 和 references。

Skill Creator 会继续确认触发条件和资源需求。对于第一个 Skill，instruction-only 是更稳的默认值。

6.2 手动创建

PowerShell：

New-Item -ItemType Directory -Force `
  .agents\skills\review-technical-article

Bash：

mkdir -p .agents/skills/review-technical-article

然后创建：

.agents/skills/review-technical-article/SKILL.md

手动创建更适合理解格式；Skill Creator 更适合减少 YAML、目录和可选元数据方面的机械错误。

7. 先写对 frontmatter

最小 frontmatter 只有两个必填字段：

---
name: review-technical-article
description: Review technical articles and tutorials for factual accuracy, reader utility, reproducibility, structure, and publication readiness. Use when the user asks to review or decide whether a technical post is useful or ready to publish. Do not use for writing a new article from scratch or for simple spelling correction only.
---

Agent Skills specification 对这两个字段有明确约束：

规范还定义了 license、compatibility、metadata 和实验性的 allowed-tools。第一个 Skill 不需要就不要添加，尤其不要把实验字段当成跨 Agent 都一致的权限保证。

7.1 一个太宽的 description

description: 帮助用户处理文章。

问题有三个：

• “处理”没有说明动作。
• “文章”没有说明类型。
• 没有触发边界和非目标。

7.2 一个更可用的 description

description: Review Chinese or English technical articles and tutorials for factual accuracy, reader utility, reproducibility, structure, and publication readiness. Use when the user asks for a substantive technical review, audit, usefulness assessment, collectability assessment, or publication verdict. Do not use for drafting or rewriting an article, title work, language-only proofreading, simple spelling correction, or checking one isolated fact.

它不追求优美，而是追求可检索：

• 任务对象：technical articles and tutorials。
• 动作：review、audit、assess usefulness、decide readiness。
• 评价目标：factual accuracy、reader utility、reproducibility。
• 负向边界：drafting、rewriting、title work、language-only proofreading、isolated fact check。

这里的 description 就是触发合同。

description 可以写中文，规范没有要求必须使用英文。本例使用英文，是为了同时覆盖中文博客任务和常见英文动作词；真正应该优先选择的，是你的使用者最常输入的语言和关键词。

8. 完整的 SKILL.md

下面是一个可以直接复制的 instruction-only 精简版。博客仓库里的实际版本沿用同一骨架，只把复现性、实用性和阅读结构的检查项写得更细。

---
name: review-technical-article
description: Review Chinese or English technical articles and tutorials for factual accuracy, reader utility, reproducibility, structure, and publication readiness. Use when the user asks for a substantive technical review, audit, usefulness assessment, collectability assessment, or publication verdict. Do not use for drafting or rewriting an article, title work, language-only proofreading, simple spelling correction, or checking one isolated fact.
---

# Review Technical Article

Review a technical article like an editor who must protect both the
reader's time and the author's credibility. Lead with actionable findings,
then give a publication verdict.

## Inputs

Before reviewing, establish:

- The target article or file.
- The intended reader and what they should be able to do afterward.
- The promised artifact, such as a template, command, checklist, or demo.
- Applicable repository instructions, especially `AGENTS.md`.
- The article's stated verification date for time-sensitive facts.

If the intended reader or artifact is unclear, infer it from the title,
summary, and opening, then state the inference.

## Review Rules

- Findings come before praise or summary.
- Cite file paths and tight line references for local files.
- Separate official facts, community observations, and author judgment.
- Verify current product names, commands, models, APIs, permissions,
  and limits against primary or official sources.
- Never claim a command, build, or workflow was tested without evidence.
- Preserve the author's voice. Do not turn a technical note into marketing.
- Do not edit the article unless the user asks for changes.

## Workflow

### 1. Check the article contract

Answer four questions:

1. What concrete problem does the article solve?
2. Who can follow it without hidden prerequisites?
3. What can the reader take away or complete?
4. How will the reader know the result is correct?

### 2. Audit factual accuracy

Extract and verify claims that can become stale or cause harm:

- Product names and availability.
- CLI commands, flags, paths, and configuration fields.
- API, model, permission, security, pricing, and quota claims.
- Repository status and third-party tool behavior.

Add a date anchor to version-sensitive facts. Mark unavailable evidence
as unverified instead of guessing.

### 3. Test reproducibility

Check prerequisites, working directory, expected outputs, failure signals,
safety boundaries, verification commands, final state, and uncertainty.

### 4. Test practical value

Look for a reusable artifact, a realistic example, recovery guidance,
non-use cases, and one bounded 30-60 minute practice task.

### 5. Check reading structure

Verify the opening, one-minute overview, section order, code and diagrams,
image captions, final checklist, and next exercise.

### 6. Classify findings

- `P0`: Dangerous or fundamentally false.
- `P1`: Blocks publication or prevents reproduction.
- `P2`: Material improvement to usefulness.
- `P3`: Editorial polish.

Do not inflate style preferences into high-severity findings.

## Output Format

Use this order:

1. Verdict: Ready / Ready after revision / Not ready.
2. Findings ordered by P0-P3 with location, impact, and concrete revision.
3. Reader value scorecard, 0-2 each:
   factual reliability, reproducibility, practical payoff,
   reading structure, and original judgment.
4. What already works.
5. The smallest publication gate.

Use these thresholds as guidance:

- Ready: no P0/P1 and total 8-10.
- Ready after revision: no P0, but at least one P1 or total 6-7.
- Not ready: any P0, an unverified central claim, or total below 6.

The score supports findings; it never overrides a concrete risk.

这个 Skill 有意没有加入 references/ 和 scripts/。

文章审查涉及大量上下文判断，不同文章允许不同改法，先用高自由度的文字规则更合理。等我们发现“链接检查”“frontmatter 检查”“命令版本提取”需要每次机械重复，再在第 12 篇加入确定性脚本。

9. 为什么正文要这样组织

一个 Skill 正文至少要解决五件事：

这里没有写“你是一位世界级编辑”之类角色设定。对工程 Skill 来说，步骤、证据和输出通常比夸张角色更稳定。

也没有把博客的所有写作规则复制进 Skill。仓库已有 AGENTS.md，Skill 只要求先读取适用的项目规则，避免两份规则以后互相漂移。

10. 让 Codex 发现和调用 Skill

Codex 当前支持显式和隐式两种调用方式。

10.1 显式调用

在 CLI 或 IDE 中可以运行 /skills，也可以在 Prompt 里输入 $ 选择 Skill：

$review-technical-article

请审查 content/blog/2026-07-14-codex-skills-introduction.md，
重点判断事实是否过期、读者能否在 45 分钟内完成练习，
以及是否达到发布条件。先给 findings，不要直接修改。

显式调用适合：

• 第一次验证新 Skill。
• 任务边界很严格。
• 同时安装了多个相似 Skill。
• 需要确定使用哪一套输出格式。

10.2 隐式调用

不点名 Skill，直接描述任务：

从读者角度 review 这篇技术教程，
判断是否有实用价值、是否值得收藏、是否适合发布。

如果 description 足够准确，Codex 可以自动选择 Skill。

Codex 会自动检测 Skill 文件变化。如果新增或修改后没有出现，先确认路径、文件名和 frontmatter，再重启 Codex。不要在目录错误时反复改 description。

11. 用四类 Prompt 测触发边界

很多人创建 Skill 后，只测试一条“请使用这个 Skill”的 Prompt。这个测试只能证明文件能被点名，不能证明 description 有效。

至少要准备四类测试：

Codex Skill 触发测试矩阵：显式调用必须加载，正向语义应该自动匹配，写作等相邻任务不应误触发，模糊表达不应自动扩大成完整技术审查

图 3：正向测试和负向测试同样重要。能触发但到处误触发的 Skill，不算可用。

测试时最好开新的 task，并且不要提前把“应该触发”或“应该输出什么”告诉 Codex。当前长对话已经包含 Skill 正文，会污染测试结果；新的 task 更接近真实发现过程。

每次记录四项：

测试入口、Codex 版本和日期
是否出现了可见的 Skill 调用标记；若入口不展示，则记录为“不可直接观察”
是否遵守正文工作流
是否给出约定的输出结构

这些记录分别对应环境、发现、执行和交付。不要因为输出“看起来很像”就断言 Skill 一定被隐式加载；入口不展示调用标记时，只能把工作流和输出格式作为间接证据。

12. 结构验证不等于行为验证

本文示例已经通过本地 Skill Creator 的快速结构验证。它能检查：

• SKILL.md 是否存在。
• YAML frontmatter 是否可解析。
• name 和 description 是否存在。
• name 是否使用合法字符。
• description 是否超过长度限制。

如果已经安装 Agent Skills 的 reference validator，还可以使用规范提供的 skills-ref 验证方式：

skills-ref validate .agents/skills/review-technical-article

但结构正确只说明“文件格式可读”，不说明下面这些行为已经正确：

• description 是否会命中真实用户表达。
• 负向任务是否会误触发。
• 步骤是否缺少输入。
• 输出是否真的可执行。
• Skill 与仓库 AGENTS.md 是否冲突。

所以一个最低限度的验收是：结构验证通过，加四类 Prompt 测试通过。

13. 常见失败模式

13.1 Skill 没出现在列表里

按顺序检查：

路径是不是 .agents/skills/<skill-name>/SKILL.md
文件名是不是大写的 SKILL.md
frontmatter 是否从文件第一行开始
name 是否和目录一致
当前 Codex task 的工作目录是否在目标仓库中
是否需要重启 Codex

13.2 显式调用有效，隐式调用无效

大概率不是正文问题，而是 description 问题。

修改方向：

• 把关键对象放前面，如 technical article、PDF、PR review。
• 补上用户真实会说的动作词。
• 写清何时使用，不只写能力介绍。
• 删除“高效”“智能”“专业”等检索价值低的词。

13.3 很多无关任务都会触发

description 太宽，或者一个 Skill 承担了多个任务。

不要只加一句“按需使用”。更有效的做法是：

• 写出明确非目标。
• 把写作和 review 拆成两个 Skill。
• 对高风险 Skill 关闭隐式调用，只允许显式选择。

agents/openai.yaml 可以通过 policy.allow_implicit_invocation: false 关闭隐式调用，但这属于进阶配置，第 12 篇再展开。

13.4 能触发，但输出仍然很空

正文只有原则，没有交付协议。

例如“关注读者体验”不够，至少要继续写清：

• 从哪几个问题判断。
• 怎样区分阻塞项和优化项。
• 输出需要哪些字段。
• 什么条件算可以发布。

13.5 SKILL.md 越写越长

这通常说明详细规范、样例或脚本应该拆出去了。

Agent Skills specification 建议 SKILL.md 正文控制在 5,000 tokens 内，并尽量少于 500 行；详细内容放进一层 references/，避免深层引用链。

第一个 Skill 不必追求这个上限。能在 100-200 行内说清任务，通常更容易维护。

14. Skill 不会绕过权限，也不天然可信

Skill 改变的是“Codex 按什么流程工作”，不是“Codex 获得什么权限”。

它仍然受到当前 sandbox、approval、网络、文件系统和连接器权限约束。一个 Skill 写着“发布文章”，不代表它自动拥有 Cloudflare、GitHub 或博客后台权限。

同样，安装第三方 Skill 不是安装一段无害文字。Skill 可以：

• 指导 Codex 读取文件。
• 引导它调用外部工具。
• 附带可执行 scripts。
• 通过 Plugin 继续带入 MCP、hooks 和连接器。

所以安装前至少检查：

把 Skill 当成小型代码依赖来 review，比把它当成 Prompt 模板更接近真实风险。

15. 30 分钟练习：做一个属于自己的 Skill

不要直接复制本文的文章 review 案例。选一个你最近重复做过的任务，按下面时间盒完成。

0-5 分钟：找重复任务

写出最近一个月做过至少两次的工作：

• review PR。
• 检查博客 frontmatter。
• 整理故障复盘。
• 发布前检查链接和图片。
• 把会议记录转成行动项。

5-10 分钟：写任务合同

输入是什么：
目标是什么：
输出是什么：
什么时候不该使用：

10-20 分钟：创建最小 SKILL.md

只写：

• name。
• description。
• Inputs。
• Workflow。
• Output。
• Stop conditions。

暂时不添加 scripts、MCP 和复杂资源。

20-25 分钟：做结构检查

• 目录名与 name 一致。
• frontmatter 可解析。
• description 同时写了做什么和何时用。
• 正文没有 TODO 和空章节。
• 输出格式可以直接检查。

25-30 分钟：跑四类 Prompt

至少测试：

1 条显式调用
1 条正向隐式调用
1 条相邻负向任务
1 条模糊边界任务

失败后只改对应层：发现失败改 description，执行失败改 Workflow，交付失败改 Output。不要每次把整份 Skill 推翻重写。

16. 本篇可直接收藏的检查清单

[是否值得做]
- 任务已经重复出现
- 步骤和验收相对稳定
- 能写清何时用、何时不用

[目录]
- 仓库级放 .agents/skills
- 用户级放 ~/.agents/skills
- 目录名与 name 一致

[frontmatter]
- name 使用小写字母、数字和连字符
- description 写明对象、动作、触发条件和非目标
- 不随意使用实验字段

[正文]
- 输入明确
- 步骤可执行
- 停止条件明确
- 输出格式可检查
- 不复制 AGENTS.md 已经维护的项目规则

[测试]
- 显式调用通过
- 正向隐式调用通过
- 负向样例不误触发
- 模糊边界不自动扩大任务
- 在新 task 中验证，避免上下文泄漏

[安全]
- Skill 没有扩大实际权限
- 第三方正文、scripts 和依赖已经 review
- 没有声称未执行过的验证

17. 当前官方资料里一个需要更新的点

过去很多 Codex Skills 教程会把 openai/skills 当成主要示例仓库。这个仓库当前已经在 README 中标记为 deprecated，并指向新的 openai/plugins 仓库。

这不表示 Skill 被 Plugin 取代。更准确的关系是：

Skill 负责定义可复用工作流
Plugin 负责把 Skills、Apps、MCP、hooks 和资源打包分发

个人或仓库内部编写 Skill，仍然可以直接从 .agents/skills 开始。等你要把它分发给团队、组合多个 Skills，或者附带连接器，再进入 Plugin。

18. 下一步：从“能用”进入“可靠”

这一篇完成的是最小闭环：

发现重复任务
  -> 定义触发合同
  -> 写 instruction-only SKILL.md
  -> 显式 / 隐式调用
  -> 正向 / 负向测试

它已经比收藏一段 Prompt 更稳定，但还没有解决几个进阶问题：

• 详细规范怎样移进 references/。
• 哪些步骤值得写成 scripts。
• 怎样做一组可重复的 Skill eval。
• 怎样设置 agents/openai.yaml 和工具依赖。
• 怎样避免 Skill 更新后悄悄退化。

第 12 篇会继续改造这个 review-technical-article：加入引用规范、可执行检查脚本、触发评估用例和版本化验收，让它从“能触发的一份说明书”变成“可以持续验证的工作流”。

参考资料

OpenAI 官方

• Build skills
• Plugins
• Build plugins
• Record & Replay
• openai/plugins
• openai/skills：当前已标记 deprecated，仅用于理解历史迁移。

开放规范

• Agent Skills specification

本文没有把 Claude Skills 作为功能事实来源。不同 Agent 的 Skill 思路可以相互参考，但目录发现、调用方式、元数据和权限边界仍以当前 Codex 官方文档为准。