11 min read

3个月457个PR|看OpenAI团队如何把Skills写代码用到极致

Source: http://x.com/i/article/2033078289603121152

大多数团队用 AI 做工程的方式是这样的:

Copilot 补全几行代码,Review 还是人一行行看。 CI 挂了,人去查日志。文档过期了,人去补。 发布前检查?人做。Changeset 验证?人做。PR 描述?还是人写。

AI 是用上了,但工作流没变。

写代码快了一点,其他所有事还是一样慢。

OpenAI Agents SDK 团队做了一件不一样的事。

他们不是让 AI 写更多代码——他们让 AI 接管了代码之外的几乎所有重复性工程劳动。

验证、审查、发布检查、文档同步、PR Review……全部系统化交给 Codex。

3个月,两个仓库合并了 457 个 PR。方案已经公开。

非常值得拆开看看。

一、先看数字

2025年12月到2026年2月,对比此前三个月:

  • Python 仓库:182 → 226 个 PR
  • TypeScript 仓库:134 → 231 个 PR

这两个仓库不是小项目。截至2026年3月,Python 包 30 天内约 1470 万次 PyPI 下载,TypeScript 包约 150 万次 npm 下载。

提升不是靠加人。

是靠改工作流。

怎么改的?

二、三样东西,管住整个仓库

整套方案极简,只有三个核心组件:

shell

仓库/
├── AGENTS.md           # 仓库级策略:什么时候必须做什么
├── .agents/skills/     # 本地 Skills:每个是一小段可执行的知识包
│   ├── skill-a/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   └── references/
│   └── skill-b/
│       └── ...
└── GitHub Actions       # CI 中运行时接入

核心思路:给 Codex 稳定的仓库上下文,让重复性工程工作的速度和准确性都上来。

听起来简单。

但设计细节里全是讲究。

三、Skills:把「怎么干活」放在代码旁边

一个 Skill = 一个 SKILL.md 清单 + 可选的 scripts/ 和 references/。

关键设计:渐进式披露。

Codex 不会一开始就把所有上下文塞进去。流程是:

先看 name 和 description → 选中后加载 SKILL.md → 需要时才读参考资料或跑脚本。

这和大多数人用 AI 的方式正好相反。

大多数人恨不得把所有信息一股脑丢给模型,然后祈祷它能理解。

OpenAI 的做法是:先给最少的信息,让模型自己判断需要什么,再按需加载。

Python 仓库的 Skills 包括:implementation-strategy、code-change-verification、openai-knowledge、pr-draft-summary、docs-sync、test-coverage-improver 等。

JavaScript 仓库额外增加了:changeset-validation、examples-auto-run、integration-tests、release-review。

比具体列表更重要的是模式:每个 Skill 都有明确的契约、清晰的触发条件、具体的输出。

还有一个值得注意的设计:最有用的 Skills 不是硬性门禁。

docs-sync 和 test-coverage-improver 是「先报告再动手」的工作流——检查 diff 或覆盖率,排优先级,征得批准后才编辑。

这比让 AI 直接改东西安全得多。

先诊断,再下刀。这个原则不只适用于医学。

接下来是整篇文章里最实用的一个细节。

description 不是注释,是路由信号

SKILL.md frontmatter 里的 description,不是给人看的说明文字。

它是 Codex 启动时用来决定「要不要激活这个 Skill」的唯一依据。完整的 SKILL.md 和脚本只在被选中后才加载。

看 code-change-verification 的对比:

太模糊:

description: Run the mandatory verification stack in the OpenAI Agents JS monorepo.

实际使用的:

description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo.

短版本说了做什么,但没说什么时候触发、什么类型的变更该触发、检查是否可选。

长版本三个都回答了。

再看 pr-draft-summary:

太模糊:

description: Create a PR title and draft description for a pull request.

实际使用的:

description: Create a PR title and draft description after substantive code changes are finished. Trigger when wrapping up a moderate-or-larger change (runtime code, tests, build config, docs with behavior impact) and you need the PR-ready summary block with change summary plus PR draft text.

这告诉 Codex 三件事:这是任务结束时的 Skill;适用于实质性变更而非每次对话;输出是结构化的 PR-ready 块。

如果 Skill 触发不准,第一件事不是加代码——是改 description。

模型做判断,脚本做机械活

什么时候该用脚本,什么时候该交给模型?

判断标准很简单:

模型每次都要重新摸索同一段 shell 命令 → 变成脚本。 任务依赖上下文、权衡或解释 → 留给模型。

格式化、lint、跑测试 → 脚本。 判断 PR 影响范围、评估发布风险、分析 diff → 模型。

脚本保证可重复,模型保证有判断力。各干各擅长的活。

四、AGENTS.md:让 Skill 从「可选」变成「必须」

Skills 本身是被动的。它们只是放在那里,等着被调用。

AGENTS.md 的作用是:在正确的时机,强制调用。

这个文件随代码库分发,在 Agent 开始工作前生效。规则全是简短的 if/then:

  • 编辑运行时或 API 变更前 → 必须调用 `$implementation-strategy`
  • 变更影响 SDK 代码、测试、示例或构建行为 → 必须调用 `$code-change-verification`
  • JS 包变更影响发布元数据 → 必须调用 `$changeset-validation`
  • 涉及 API 或平台集成 → 必须调用 `$openai-knowledge`
  • 工作完成准备交接 → 必须调用 `$pr-draft-summary` 精简结构:

markdown

# AGENTS.md
## Project overview

- Core SDK code lives under `src/agents/` or `packages//src/`.

- Tests live under `tests/` or `packages//test/`.

- Sample apps live under `examples/`.
## Mandatory skill usage

- Use `$implementation-strategy` before editing runtime or API changes.

- Run `$code-change-verification` when runtime code, tests, examples,
  or build/test behavior changes.

- Use `$openai-knowledge` for API or platform work.

- Use `$pr-draft-summary` when substantial code work is ready for review.
## Build and test commands

- Python: `make format`, `make lint`, `make typecheck`, `make tests`

- TypeScript: `pnpm i`, `pnpm build`, `pnpm -r build-check`, `pnpm lint`, `pnpm test`
## Compatibility rules

- Preserve positional compatibility for public constructors and dataclass fields.

Python 仓库还在 AGENTS.md 里记录了公共 API 兼容性规则:保持导出构造函数参数和 dataclass 字段的位置含义,新增可选参数追加在末尾,不得不调整顺序就加兼容性测试。

把发布关键的兼容性规则和 Skill 触发条件放在同一个文件里——这个做法值得抄。

验证规则也藏着一个重要设计。

`$code-change-verification` 不是「每次都跑全套验证」。

是:代码变了才跑。但跑了没过,就不能说完成。

条件触发 → 纯文档 PR 保持轻量。 强制通过 → 代码变更不能绕过标准检查。

不该验证的,一秒都不浪费。该验证的,一步都不能跳。

Python 验证栈:

make format → make lint → make typecheck → make tests

JavaScript 验证栈(严格顺序):

pnpm i → pnpm build → pnpm -r build-check → pnpm -r -F "

@openai

/*" dist:check → pnpm lint → pnpm test

Skill 编码了「已验证」的定义。AGENTS.md 让这个定义可强制执行。

两层分离,非常干净。 JavaScript 仓库还有一个额外的强制步骤:`$changeset-validation`。

当 `packages/` 或 `.changeset/` 变更时,模型必须创建或更新正确的 changeset,验证 bump 级别,确认 changeset 匹配 diff。

不是检查文件存不存在——是让 Codex 对 git diff 做判断。

几条仓库特定策略:

  • 已有分支 changeset 就复用,不新建
  • 摘要一行,Conventional Commit 格式,可直接当 commit 标题
  • 1.0 前避免 major bump;preview-only 新增不改变现有行为则视为 patch
  • 根据实际包变更验证 bump 级别

Codex 在声称完成之前,必须先验证自己创建的发布元数据。这个约束很关键。

五、最有意思的部分:让 AI 验证 AI

如果前面是「怎么管」,这一节是「怎么验」。

这是整套方案里最精彩的设计。

第一层:examples-auto-run

以前验证示例靠人工——跑一遍,肉眼看日志,判断输出对不对。

一个示例还行,几十个不可持续。

团队先构建了非交互式执行的底层支持:auto 回复交互提示、auto 审批 HITL/MCP/apply_patch、不适合自动化的放 skip 列表、写结构化日志、生成重跑文件。

然后关键的一步:runner 只负责执行和保存日志。验证交给 Codex 逐个对照源码来做。

Codex 怎么验证?

  • 读示例源码和注释
  • 推断预期流程
  • 打开对应日志
  • 比较预期行为 vs 实际 stdout/stderr
  • 每个成功的示例都做,不是抽查

为什么不在脚本层面写断言?

因为对于调用真实 API、使用工具或产生结构化输出的示例,退出码为 0 根本不够。模型能根据上下文判断「这个输出合不合理」,固定断言做不到。

脚本让运行可重复、保存证据。模型用证据做比 pass/fail 更精细的判断。这就是组合的价值。

第二层:integration-tests(JavaScript 仓库)

更进一步——把包发布到本地 Verdaccio registry,在 Node.js、Bun、Deno、Cloudflare Workers、Vite React 应用等多个环境下测试安装和运行。

捕获的是完全不同类别的问题:不是「示例在仓库里能跑吗」,而是「包在发布、安装、运行后还正常吗」。

第三层:release-review

找到上一个 release tag → 与最新 main 做 diff → 让 Codex 检查向后兼容性、回归、缺失的迁移说明 → 做出发布就绪判断。

看一个真实例子(PR #2480):

Release call: 🟢 GREEN LIGHT TO SHIP. Minor-version bump includes expected breaking change (Python 3.9 drop) with no concrete regressions found. Python 3.9 support removed - Risk: 🟡 MODERATE. Users pinned to Python 3.9 will be unable to install 0.9.0. - Evidence: pyproject.toml now sets requires-python = ">=3.10" - Action: Ensure release notes clearly call out the Python 3.9 drop.

设计原则:review 从「可安全发布」开始,仅当 diff 中有具体证据才切换为阻塞,每个阻塞必须附解除清单。

安全就说安全,不安全就指证据和后续步骤。

比泛泛的「请审查一下这个发布」有用一万倍。

PR Review 的分工

最后说一个很多人会关心的问题:Codex 做 Review,人还需要做什么?

答案是:都做,但做不同的事。

Codex 负责的审查:

  • 直接的 bug、回归、缺失测试
  • 反复检查相同的正确性模式
  • 小修复和常规改进的审查

这些事它做得非常一致,比人可靠。

人负责的审查:

  • API/架构变更——多种合理设计,需要维护者做选择
  • 行为变更——影响产品预期、兼容承诺或发布策略
  • 命名/迁移/发布沟通——难点在于选择对用户最清晰的方案
  • 跨团队对齐——范围划定、排序、决定什么现在发什么以后发 重复性审查不再阻塞在稀缺的 reviewer 时间上。维护者专注于判断力真正有价值的审查。

这个分工本身,就是吞吐量提升的主要来源之一。

六、你可以带走的三个模式

拆完整套方案,核心就三件事:

1. 声明式控制

用 AGENTS.md 的 if/then 规则强制 Skill 调用——不是建议,是必须。

description 是路由信号,不是注释——写清楚什么时候触发、什么类型的变更、什么输出。

兼容性规则和触发条件放同一个文件,随代码分发。

2. 分层执行

脚本做机械活,模型做判断。重复摸索的 shell 命令下沉为脚本,依赖上下文的判断留给模型。

验证两层分离:条件触发(不浪费轻量 PR 的时间)+ 强制通过(代码变更不能绕过)。

3. 安全模式

最有用的 Skill 不是上来就改——检查、排序、征得同意再编辑。

release review 从「安全」开始,只在有具体证据时阻塞,阻塞必须附解除清单。

本地跑稳了再进 CI——手动使用阶段是发现边界情况的地方。

不需要一次全搞。

从一个高频重复的工作流开始。写一个 Skill,在 AGENTS.md 里加一条 if/then 规则,跑几轮看效果。

大多数团队让 AI 写代码。 少数团队让 AI 管住整个工程流程。

区别不在于用了什么模型。 在于有没有一套系统,让 AI 知道什么时候该做什么、做完怎么验证、验证没过怎么办。

这套方案的本质不是「让 AI 写更多代码」,是让 AI 接管代码之外的一切重复性工程劳动。

这才是 AI 工程化的正确打开方式。

如果这篇拆解对你有帮助,欢迎转发给你的团队一起看。

Reference:

https://developers.openai.com/blog/skills-agents-sdk