使用 Skills 加速开源维护：OpenAI Agents SDK 团队实战经验

OpenAI Agents SDK 团队分享如何使用 Codex Skills、AGENTS.md 和 GitHub Actions 将重复的工程工作转化为可复用工作流，显著提升开源仓库的开发效率。

效果数据

在 2025 年 12 月 1 日到 2026 年 2 月 28 日期间，Python 和 TypeScript 两个仓库共合并 457 个 PR，较前三个月（9-11 月，316 个）提升约 45%。

仓库	前三个月	后三个月	增长
Python SDK	182	226	+24%
TypeScript SDK	134	231	+72%

作为背景，SDK 在 PyPI 上约 1470 万月下载，npm 上约 150 万月下载。

整体架构

设置非常简单：

AGENTS.md 中的仓库策略
.agents/skills/ 中的仓库本地 Skills
Skills 内的可选脚本和参考资料
需要在 CI 中运行相同工作流时使用 Codex GitHub Action

这为 Codex 提供了关于仓库工作方式的稳定上下文，提高了重复工程工作的速度和准确性。

1. 把工作流放在仓库里

用 Skills 捕获仓库特定的工作流。Skill 是一小包运营知识：SKILL.md 清单，加上可选的 scripts/、references/ 和 assets/。

渐进式信息披露模型：

启动时只看到 name 和 description 元数据
选择 Skill 后才加载 SKILL.md
需要时才读取参考资料或运行脚本

Python 仓库的 Skills：

Skill	功能
`code-change-verification`	代码变更后运行格式化、lint、类型检查和测试
`docs-sync`	审计文档与代码库的一致性
`examples-auto-run`	自动运行示例并记录日志
`final-release-review`	对比上次发布标签，检查发布就绪状态
`implementation-strategy`	编辑运行时或 API 变更前决定兼容性边界
`openai-knowledge`	通过 Docs MCP 拉取最新的 OpenAI API 文档
`pr-draft-summary`	准备分支名建议、PR 标题和描述草稿
`test-coverage-improver`	运行覆盖率分析，提出高影响力测试建议

JavaScript 仓库额外 Skills：

Skill	功能
`changeset-validation`	检查 changeset 和 bump 级别是否匹配包变更
`integration-tests`	发布到本地 Verdaccio 注册表，验证安装和运行行为
`pnpm-upgrade`	协调更新 pnpm 工具链和 CI pins

关键模式：每个 Skill 都有窄契约、清晰的触发条件和具体的输出。

2. 让工作流成为强制性的

AGENTS.md 中使用简短的 if/then 规则：

markdown

## 强制 Skill 使用

- 编辑运行时或 API 变更前 → 调用 $implementation-strategy
- 变更影响 SDK 代码、测试、示例或构建行为时 → 调用 $code-change-verification
- 触及 OpenAI API 或平台集成时 → 调用 $openai-knowledge
- 工作完成准备交接时 → 调用 $pr-draft-summary

条件性让纯文档工作保持轻量，强制性确保代码变更必须通过仓库的标准验证步骤。

AGENTS.md 中还可以记录发布关键兼容性规则，例如：保持导出构造函数参数和 dataclass 字段的位置含义，新可选参数追加在末尾。

3. 验证规则详解

code-change-verification 的规则不是"始终运行完整验证栈"，而是"运行时代码、测试、示例或构建行为变更时运行，且不通过不算完成"。

Python 仓库验证栈：

bash

make format && make lint && make typecheck && make tests

JavaScript 仓库验证栈（严格顺序）：

bash

pnpm i && pnpm build && pnpm -r build-check
&& pnpm -r -F "@openai/*" dist:check && pnpm lint && pnpm test

changeset-validation（JS 仓库独有）让 Codex 负责：

判断 git diff
创建或更新正确的 changeset
验证 bump 级别是否匹配
仓库特定策略（1.0 前避免 major bump，preview-only 作为 patch 等）

4. 使用最新文档

当工作涉及 OpenAI API 或平台集成时，$openai-knowledge 强制 Codex 通过 OpenAI Developer Documentation MCP 服务器查询最新文档，而非依赖记忆中的旧信息。

5. 准备 PR 交接

$pr-draft-summary 在实质性工作完成后触发，自动收集分支名、工作树状态、变更文件、diff 统计和最近提交，产出：

分支名建议
PR 标题
PR 描述草稿

输出格式故意设计为结构化的，便于直接使用。

6. 写好 Skill 描述

Skill 的 description 是路由元数据，不是装饰。好的描述要告诉 Codex 三件事：Skill 做什么、何时触发、输出是什么。

反面示例：

description: 为 PR 创建标题和描述草稿。

正面示例：

text

description: 在实质性代码变更完成后创建 PR 标题和描述草稿。
在包装中等或更大的变更（运行时代码、测试、构建配置、有行为影响的文档）
且需要变更摘要 + PR 草稿文本时触发。

实用建议：如果路由不稳定，先修元数据，再加代码。

7. 把机械操作放在脚本里

可靠的分工：

模型负责：解读、比较、报告
脚本负责：确定性的重复 shell 工作

如果模型每次都要重新发现同一个 shell 配方，那就是脚本该做的事。如果任务依赖上下文、权衡或解释，那部分留给模型。

8. 自动化集成测试

两层集成测试：

第一层 — 示例自动运行：

非交互模式运行示例
自动回答交互式提示
结构化日志 + 失败重跑文件
Codex 逐个检查日志与源代码的预期行为对比

第二层 — 包集成测试（JS 仓库）：

发布到本地 Verdaccio 注册表
在 Node.js、Bun、Deno、Cloudflare Workers、Vite React App 中验证安装和运行
捕获的是"发布后安装是否正常"而非"仓库内是否运行"

9. 发布检查

发布审查从"安全发布"开始，只有 diff 中有具体问题证据时才切换为阻塞调用。每个阻塞调用必须附带明确的重启清单。

实际案例（Python 仓库 #2480）：

text

发布决策: 🟢 可以发布。次版本 bump 包含预期的破坏性变更
（Python 3.9 移除），未发现具体回归。

Python 3.9 支持移除
- 风险: 🟡 中等。使用 Python 3.9 的用户将无法安装 0.9.0
- 行动: 确保发布说明明确标注 Python 3.9 移除

10. 在 CI 中运行

Skill 在本地稳定后，Codex GitHub Action 可以将相同流程自动化到 CI。对于公开仓库，触发器设计同样重要：

限制谁可以启动工作流
优先使用受信任事件或显式审批
清理来自 PR/commit/issue/comment 的提示输入
保护 OPENAI_API_KEY（使用 drop-sudo 或非特权用户）
将 Codex 作为 job 的最后一步运行

11. 用 Codex 做 PR Review

适合 Codex 自动审查的场景：

程序 bug、回归、缺失测试
一致的模式检查

仍需人工审查的场景：

API 或架构变更（多种合理设计需维护者选择）
影响产品期望和向后兼容承诺的行为变更
命名、迁移和发布沟通决策
需要跨维护者或团队协调的变更

AGENTS.md 可以编码这种分工：告诉 Codex 正确性审查中什么重要，Codex 可以一致地应用该指导。

总结

AGENTS.md 告诉 Codex 哪些工作流是必需的。description 告诉它何时路由到这些工作流。scripts/ 处理确定性部分。模型处理上下文部分。一旦工作流在本地稳定，Codex GitHub Action 将相同流程带入 CI。

这让日常工程工作更加明确和可靠，也让小改进的发布更快，因为验证、发布审查和 PR 交接现在遵循相同的可重复流程。

参考资源

本文翻译自 OpenAI Developers 博客，作者 Kazuhiro Sera。