OpenAI 官方 Skills 仓库上线：首批实用技能拆解

实战教程

OpenAI 把 Codex 的 Agent Skills 做成了官方仓库，分 .system 和 .curated 两层，附带 skill-installer 一键安装。本文拆解首批值得先看的几个技能，以及 Skill、AGENTS.md、prompt 三者的边界。

OpenAI 官方 Skills 仓库上线：首批实用技能拆解

OpenAI 把 Codex 的 Agent Skills 做成官方仓库了，地址是 github.com/openai/skills。这件事比单看 README 要更有意思——它不是又一个 awesome-list，而是 OpenAI 自己在示范「一个 Skill 应该长什么样」。如果你最近在折腾 Codex，或者更广义地在写 agent，这个仓库值得花一小时翻一遍，比你从零摸索快很多。

仓库目录分两层：.system 是 Codex 内置的系统级技能，.curated 是官方筛选过的可选技能。后者才是普通开发者要看的重点，里面每个技能都是一个完整文件夹，包含 SKILL.md、scripts/、references/，结构高度一致。

openai/skills 仓库目录结构截图

为什么 Skill 这套东西现在变重要了

过去半年 GitHub Trending 的变化很明显：单一模型项目越来越少，围绕 agent、skills、memory、workflow 的「组织层」项目越来越多。社区关注点正在从「模型能做什么」转向「系统怎么长期运行、怎么协同交付」。

Skill 就是这条主线上的一块拼图。它解决的问题很具体——同一类任务你不想每次重新写 prompt，也不想把所有规则塞进 AGENTS.md 让上下文爆炸。Skill 是一个介于「一次性 prompt」和「项目永久规则」之间的中间层：可复用、可版本化、可分享。

Anthropic 之前在 Claude 那边已经把 Skills 跑通了一轮，OpenAI 这次的做法更工程化——直接给你一个官方目录、一个安装器、一套目录约定。某种程度上，这是 OpenAI 在确立 Codex 生态的「应用商店」雏形。

首批值得先看的几个技能

我把 .curated 里的技能翻了一遍，挑出几个对绝大多数开发者都有用的，按优先级排：

1. playwright / playwright-interactive

浏览器自动化技能。前端开发场景下用处最大——它不只读代码，会真的把页面打开看一眼。

这个技能解决的痛点是：模型写完 UI 改动后，经常自信地说「完成了」，但实际上按钮溢出、深色模式对比度爆炸、移动端被遮挡了一半。让 agent 自己截一张图、看一眼 console error，比你 review 五遍代码都管用。

playwright-interactive 是它的进阶版，可以做点击、滚动、表单填写这类交互流程的验证。

2. pdf

处理 PDF 的读取、渲染、版式检查。重点不是「让模型读 PDF」——那种事丢给多模态模型也能做——而是「按固定流程把 PDF 拆开、提取结构化内容、再校验」。

比让模型直接「猜 PDF 内容」靠谱得多，尤其是涉及表格、多栏排版、扫描件的场景。

3. openai-docs

这个技能本身用处一般，但它的设计思路值得抄。它做的事情是：当任务涉及 OpenAI API 时，强制 agent 去查官方文档，而不是依赖模型自己的记忆。

API 这种东西迭代太快，模型训练数据里的版本大概率已经过期。把「查文档」这个动作固化进 Skill，比起反复提醒模型「请参考最新文档」要可靠得多。同理，你可以照这个模式给任何快速迭代的 SDK 写一个 docs-check skill。

4. gh-fix-ci / gh-address-comments

GitHub 工作流相关。gh-fix-ci 把「读失败日志 → 定位失败原因 → 修复 → 重新跑 → 验证」写成了一条明确流程；gh-address-comments 处理 PR review comments，把每条评论拆成可执行的修改项。

这类技能最大的价值是「把一个混乱的诊断过程结构化」。CI 挂了之后人类通常的做法是凭直觉看一眼日志猜原因，agent 没有这个直觉，必须有明确步骤。

5. security-best-practices

安全检查清单类的任务特别适合做成 Skill，因为：

  • 清单本身是稳定的（OWASP Top 10 不会一周一变）
  • 不能靠模型临场发挥，必须逐项检查
  • 输出格式可以严格固定

看完这个技能之后再去写自己的合规检查、代码审计类 Skill，会清楚很多。

怎么装

仓库 README 提到了一个有意思的东西——skill-installer。它本身也是一个 Skill，作用是「让 agent 自己从 curated 列表里挑技能装」，类似 App Store 的安装器。

在 Codex 里直接调用：

$skill-installer playwright
$skill-installer openai-docs
$skill-installer gh-fix-ci

装完重启 Codex，让新技能被识别。这个设计挺巧妙——把「技能管理」本身也变成了一个技能，agent 在跑任务过程中如果发现自己缺能力，可以主动去装。

Skill、AGENTS.md、普通 prompt 的边界

这是用 Codex 的人最容易犯迷糊的地方。三者都能塞规则，到底哪条规则放哪？我的分法：

AGENTS.md：项目长期事实

- Use pnpm, not npm.
- UI components live in src/components.
- Run pnpm lint before finishing.
- Do not edit generated files.

这种规则的特征是：稳定、只对当前项目有意义、换个项目就不适用。

Skill：可复用的任务流程

比如 code-review、frontend-visual-check、release-notes、pdf-extract。它们不是某个项目独有的，而是某一类任务的标准做法。换项目也能用，所以应该独立出来。

普通 prompt：本次具体需求

把登录页的错误提示改成 toast，并保持现有 API 不变。

一次性目标，不要写进 Skill，也不要塞进 AGENTS.md。

写之前问自己三句话：

  1. 这条规则下周还会用吗？会 → AGENTS.md
  2. 这个流程换项目也能用吗？能 → Skill
  3. 这是本次任务独有的吗？是 → prompt

三层清晰分开之后，上下文会干净很多，Codex 的输出质量也会明显稳一截。

写一个自己的 Skill：前端视觉检查

光看不练没用，举个最常见的场景：给前端项目做一个 Playwright 视觉检查 Skill。

目标是让 agent 在做完 UI 改动后，自动跑这套流程：启动 dev server → 打开页面 → 截桌面和移动端截图 → 检查空白、报错、遮挡、溢出 → 报告问题。

SKILL.md 大概长这样：

---
name: frontend-visual-check
description: Verify frontend UI changes with Playwright screenshots across desktop and mobile viewports. Use after implementing or modifying visible UI.
---

# Frontend Visual Check

When active:

1. Start the project dev server using the repo's documented command.
2. Open the changed route in a real browser.
3. Capture desktop and mobile screenshots.
4. Check for blank page, console errors, overlapping text, and broken layout.
5. Report screenshot paths and concrete issues.

Default viewports:
- Desktop: 1440x900
- Mobile: 390x844

Do not mark UI work complete if the page is blank or visibly broken.

这里几个细节值得注意：

  • description 一定要写清楚「什么时候用」。这是 agent 决定是否激活这个 Skill 的依据，写得含糊就会乱触发或不触发。
  • 步骤要明确编号，模型对有序列表的服从度比散文好得多。
  • 最后那句 hard rule（页面空白时不准声称完成）是兜底——agent 经常会乐观地报告成功，必须明确写出禁止条件。

Skill 触发后 agent 自动截图并报告 UI 问题的流程示意

几条踩坑后的 Skill 设计原则

翻完官方仓库再对照自己写过的 Skill，几个反复出现的原则：

  1. 描述写清楚「什么时候用」。这是 description 字段的唯一职责，别拿它写功能介绍。
  2. 大文件放 references/，不要全塞进 SKILL.md。SKILL.md 是给模型看的入口，太长会冲淡核心指令。补充材料、模板、长清单都放外面，让模型按需读。
  3. 重复操作写 scripts/。能用脚本完成的就不要让模型自己组合命令——脚本是确定的，模型每次的命令拼装是概率的。
  4. 输出格式固定。固定的 Markdown 模板、固定的 JSON schema，能极大减少每次输出的漂移。
  5. 先抄结构，再发明范式。一开始就照官方仓库的目录摆，等你写过五六个 Skill 之后再考虑自己的约定。

写在最后

OpenAI 这次推 Skills 仓库的意义，不在于多了几个能用的工具，而在于它在「Codex 应该怎么被扩展」这件事上给了一个明确答案。Anthropic 那边的 Claude Skills 是另一条路径，两家方向上其实趋同——都在把 agent 的能力从「一个大 prompt」拆成「一组可组合的小模块」。

对开发者来说，现在是入场写 Skill 的好时机：标准刚立、示例齐全、工具链跑通。等生态再大一些，能不能写出被广泛用的 Skill 就是另一回事了。

顺带说一句，如果你想拿 GPT、Claude、Gemini 横向对比着试 Skill 设计——同一个任务在不同模型上的拆解粒度会有挺大差异——可以用 OpenAI Hub 这种聚合平台一个 Key 切换，省得每家单独申请。

参考来源