本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/blog/skills-agents-sdk
使用 skills 加速 OSS 维护
在 OpenAI Agents SDK 仓库中使用 skills 和 GitHub Actions 来优化 Codex 工作流。
我们使用 Codex 来改变维护 OpenAI Agents SDK 仓库的方式。仓库本地的 skills、AGENTS.md 和 GitHub Actions 让我们能够将重复性的工程工作，例如验证、发布准备、示例的集成测试以及 PR 审查，转化为可重复的工作流。即使采用的是相当简单的设置，这也帮助我们提升了这些活跃仓库的开发吞吐量。在 2025 年 12 月 1 日到 2026 年 2 月 28 日期间，这两个仓库合并了 457 个 PR，相比此前三个月（2025 年 9 月 1 日至 2025 年 11 月 30 日）的 316 个有所增加（Python：182 -> 226，TypeScript：134 -> 231）。
快速介绍一下，SDK 提供 Python 和 TypeScript 两个版本。它提供了构建 agentic 应用所需的核心组件，同时也是一种简洁的方式，可在 Realtime API 之上使用多个 agents、工具以及 human-in-the-loop 控制来构建语音 agents。它已被大规模使用：截至 2026 年 3 月 6 日，在最近 30 天窗口中，Python 包在 PyPI 上约有 1470 万次下载，TypeScript 包在 npm 上约有 150 万次下载。
这套设置很简单：
AGENTS.md中的仓库策略.agents/skills/中的仓库本地 skills- 这些 skills 中可选的脚本和参考资料
- 当相同工作流应在 CI 中运行时，使用 Codex GitHub Action
这套设置让 Codex 能够稳定地获取有关仓库如何运作的上下文，从而提升重复性工程工作的速度和准确性。
如果你维护的是公开的开源项目，请参阅 Codex for OSS。符合条件的维护者可以申请包含 Codex 的 ChatGPT Pro、API credits，以及对 Codex Security 的有条件访问权限。
将工作流保留在仓库中
在这些仓库中，我们使用 skills 来封装仓库特定的工作流。一个 skill 是一个小型的操作知识包：包含一个 SKILL.md 清单，以及可选的 scripts/、references/ 和 assets/。Codex 自定义文档 解释了为什么这种方式效果很好：skills 非常适合可重复的工作流，因为它们可以携带更丰富的说明、脚本和参考资料，而不会在一开始就膨胀 agent 的上下文。
这与 skills 使用的渐进式披露模型一致：
- 它首先看到诸如
name和description之类的元数据 - 只有在选中该 skill 时才会加载
SKILL.md - 只有在需要时才会读取参考资料或运行脚本
这两个 SDK 仓库都将这些工作流保留在代码附近：
Python 仓库是更简单的基线：
code-change-verification会在代码或构建行为发生变化时，运行所需的格式化、lint、类型检查和测试栈。docs-sync会根据代码库审查文档，并找出缺失、不正确或过时的文档。examples-auto-run会以自动模式运行示例，并提供日志和重新运行辅助工具。final-release-review会对比上一个发布 tag 与当前发布候选版本，并检查发布就绪情况。implementation-strategy会在编辑运行时或 API 变更之前决定兼容性边界和实现方法。openai-knowledge会通过官方 Docs MCP 工作流拉取最新的 OpenAI API 和平台文档。pr-draft-summary会在交接时准备分支名建议、PR 标题和草稿描述。test-coverage-improver会运行覆盖率分析、找出最大的缺口，并提出高影响力的测试建议。
JavaScript 仓库遵循相同的总体模式，然后为其 npm monorepo 和发布流程增加了一些仓库特定的 skills：
changeset-validation会检查 changesets 和版本提升级别是否确实与包 diff 相匹配。integration-tests会将包发布到本地 Verdaccio registry，并在受支持的运行时中验证安装和运行行为。pnpm-upgrade会以协调一致的方式更新 pnpm 工具链和 CI pin。
比起具体清单，更重要的是这种模式。每个 skill 都有一个狭窄的契约、一个清晰的触发条件和一个具体的输出。
一些最有用的 skills 并不是硬性门禁。docs-sync 和 test-coverage-improver 是“先报告”的工作流：它们会检查当前 diff 或覆盖率产物，确定优先级，并在进行编辑前请求批准。在 Python 仓库中，docs-sync 还将源代码中的 docstring 和注释视为生成参考文档的事实来源，而不是手工修补生成出的输出。仅用于 JavaScript 的 pnpm-upgrade skill 也是狭窄维护工作流的一个好例子：它会一起更新本地 pnpm 版本、packageManager 和工作流 pin，而不是退回到大范围的搜索替换。
让工作流成为必需项
当仓库在恰当的时机要求使用 skills 时，skills 会变得更有用。这正是 AGENTS.md 发挥作用的地方。
AGENTS.md 指南 将这些文件描述为仓库级指令：它们会随着代码库一起存在，并在 agent 开始工作之前生效。它还建议将这些文件保持简短。在 Agents SDK 仓库中，我们用这部分空间写入 Codex 每次都应遵循的规则，并将价值最高的规则放在顶部附近。
在实践中，这两个仓库都使用简短的 if/then 规则来强制要求使用 skill。在编辑可能影响兼容性边界的运行时或 API 变更之前，先调用 $implementation-strategy 来决定兼容性边界和实现方法。如果变更影响 SDK 代码、测试、示例或构建行为，则调用 $code-change-verification。如果 JavaScript 包变更影响发布元数据，则调用 $changeset-validation。如果工作涉及 OpenAI API 或平台集成，则调用 $openai-knowledge。当工作完成并准备交接时，调用 $pr-draft-summary。
这种结构也与 agents.md 的建议一致：将项目概览、构建和测试命令、代码风格、测试指导、安全注意事项以及其他仓库特定规则放在一个地方。Agents SDK 仓库遵循这一形态，但它们将日常工作中最重要的操作触发条件放在最前面。一个精简版如下所示：
# AGENTS.md
## Project overview
- Core SDK code lives under `src/agents/` or `packages/*/src/`.
- Tests live under `tests/` or `packages/*/test/`.
- Sample apps and integration surfaces live under `examples/`.
## Mandatory skill usage
- Use `$implementation-strategy` before editing runtime or API changes that may affect compatibility boundaries.
- Run `$code-change-verification` when runtime code, tests, examples, or build/test behavior changes.
- Use `$openai-knowledge` for OpenAI 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.
真实文件随后会在这个基线上添加仓库特定的细节，例如 JavaScript 仓库中的 $changeset-validation，以及这两个文件中关于运行时、文档和发布的更详细指导。如果你想看完整示例，请参阅 openai-agents-python 中的 AGENTS.md 和 openai-agents-js 中的 AGENTS.md。
AGENTS.md 不仅用于 skill 触发器。Python 仓库还在其中记录了一条公共 API 兼容性规则：保持已导出构造函数参数和 dataclass 字段的位置含义不变，尽可能将新的可选参数追加到末尾，并在无法避免重新排序时添加兼容性测试。这也是一种很好的模式：将发布关键的兼容性规则与 skill 触发器保存在同一个地方。
验证规则
一个清晰的例子是 $code-change-verification。
在这两个仓库中，规则并不是“始终运行一个很长的验证栈”。规则是“当运行时代码、测试、示例或构建/测试行为发生变化时运行它，并且在它通过之前不要将工作标记为完成”。
条件性部分让仅文档相关的工作保持轻量。强制性部分则确保 SDK 代码变更会经过仓库的标准验证步骤。
实际的验证栈被编码在 skills 自身中。
在 Python 仓库中，它要求：
make format
make lint
make typecheck
make tests
在 JavaScript 仓库中，该 skill 要求严格按照以下顺序执行：
pnpm i
pnpm build
pnpm -r build-check
pnpm -r -F "@openai/*" dist:check
pnpm lint
pnpm test
这个 skill 编码了仓库对“已验证”的定义，而 AGENTS.md 让这个定义可以被强制执行。
Changeset 验证
JavaScript 仓库对包变更还有一个额外的强制步骤：$changeset-validation，它基于 Changesets 构建。
当 packages/ 下的任何内容发生变化，或者 .changeset/ 发生变化时，模型不能只运行测试。它还必须创建或更新正确的 changeset、验证 bump 级别，并确认 changeset 实际上与 diff 匹配。
这个 skill 做的不只是检查文件是否存在。它要求 Codex 判断 git diff，并将验证规则保存在共享 prompt 中，以便本地运行和 GitHub Actions 使用相同的逻辑。它还编码了仓库特定的策略，例如：
- 当分支上已经存在 changeset 时，使用现有的分支 changeset，而不是再创建一个
- 将摘要保持为一行，采用 Conventional Commit 风格，以便它也可以作为 commit 标题
- 在 1.0 之前，普通功能开发应避免 major bump；如果明确标注为仅预览的新增内容不改变现有行为，则将其视为 patch 变更
- 根据实际的包变更验证所需的 bump 级别
这使 Codex 必须先验证它自己创建的发布元数据，然后才能说工作已完成。
使用最新文档
两个仓库都要求在工作涉及 OpenAI API 或平台集成时使用 $openai-knowledge。
这个 skill 是官方 OpenAI Docs MCP 的一个轻量封装。它不会让模型凭记忆回答，而是指示 Codex 使用 OpenAI Developer Documentation MCP server 来查找当前文档，涵盖 Responses API、tools、streaming、Realtime 和 MCP 等接口。
如果本地 Codex 环境中尚未配置 MCP server，该 skill 会引导维护者查看 Docs MCP quickstart 和 official MCP server endpoint。
准备 PR 交接
在实质性工作结束时，两个仓库都会使用 $pr-draft-summary。
这个 skill 只会在任务实际上已经完成或已准备好评审，并且变更涉及有意义的代码、测试、示例、会影响行为的文档，或构建/测试配置时触发。然后它会自动收集分支名、working tree 状态、已更改文件、diff 统计以及最近的 commits，并生成：
- 一个分支名建议
- 一个 PR 标题
- 一份 PR 描述草稿
输出格式是刻意严格规定的。一个典型结果如下所示：
# Pull Request Draft
## Branch name suggestion
git checkout -b fix/tracing-lazy-init-fork-safety
## Title
fix: #2489 lazily initialize tracing globals to avoid import-time fork hazards
## Description
This pull request fixes import-time tracing side effects that could break fork-based process models by moving tracing bootstrap to lazy, first-use initialization.
It updates tracing setup so initialization happens once on first access while preserving the existing public tracing APIs.
It also adds regression tests for import-time behavior, one-time bootstrap, and custom provider handling.
This pull request resolves #2489.
一旦你信任模型能够验证并总结它自己的工作，让它生成 PR 草稿就成了一个很自然的最后步骤。这样可以让交接保持一致，并减少在编码工作已经完成后重复撰写内容的工作量。
编写更好的 description
skill 的 SKILL.md frontmatter 中的 description 字段是路由契约的一部分。
这是结构性的，不是风格性的。Agent Skills specification 将 name 和 description 规定为 SKILL.md frontmatter 的必需字段，其 progressive-disclosure 模型说明，这些字段会在启动时为所有 skills 加载。完整的 SKILL.md 正文以及任何 scripts/、references/ 或 assets/ 只会在 skill 实际被激活时才稍后加载。
Codex skills docs 和 customization docs 从 Codex 的角度描述了相同的行为：Codex 启动时先使用每个 skill 的 metadata 进行发现，只有在它选择了某个 skill 时才会加载 SKILL.md，并且只在需要时才读取 references 或运行 scripts。Skills in OpenAI API cookbook 同样明确地描述了 hosted-shell 这一侧：OpenAI 会先读取每个 skill 的 name、description 和路径，模型利用这些信息来决定何时读取完整的 SKILL.md。其中的 SKILL.md frontmatter section 更直接地说明了同一点：name 和 description 对发现和路由很重要。
在 Agents SDK 仓库中，这意味着在 Codex 读取 skill 其余部分之前，description 就已经是主要的路由信号之一。
下面是来自 code-change-verification 的一个具体示例。
过于模糊：
description: Run the mandatory verification stack in the OpenAI Agents JS monorepo.
更好（实际使用的 description）：
description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo.
较短的版本已经告诉 Codex 这个 skill 是做什么的，但它仍然没有说明 skill 在什么时候适用、哪些类型的变更应该触发它，或者这些检查是否是可选的。更具体的版本则把这三点都告诉了模型。
同样的模式也出现在 pr-draft-summary 中。
过于模糊：
description: Create a PR title and draft description for a pull request.
更好（实际使用的 description）：
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.
再次强调，真实的 description 是路由 metadata。它告诉 Codex：
- 这是一个任务结束时使用的 skill
- 它用于实质性变更，而不是每一次聊天轮次
- 输出是一个可直接用于 PR 的区块，而不仅仅是一段文字总结
从这些仓库中得到的一条实际经验是：要花时间打磨 description。如果路由感觉不可靠，请先修正 metadata，再去添加更多代码。
将机制放进脚本
接下来，下一个问题是：哪些内容应留给模型处理，哪些内容应该下沉到脚本中。
一个可靠的划分方式是：
- 解释、比较和报告由模型负责
- 确定性的、重复执行的 shell 工作放进
scripts/
这与公开指导一致。Codex customization docs 将 skills 描述为一种方式，用于为 Codex 提供更丰富的说明、脚本和参考资料，以支持可重复的工作流，而不会在一开始就让上下文膨胀。这很适合 model-first 的设置：让 Codex 处理工作中依赖上下文的部分，而只在需要时引入脚本来处理确定性的部分。Skills in OpenAI API cookbook 也建议将 skill 脚本设计成微型 CLI：脚本应可从命令行运行、输出确定性的 stdout、在使用方式错误或发生错误时明确失败，并在需要时将输出写入已知文件路径。
在 Agents SDK 仓库中，我们尽量在模型的智能真正有用的地方使用模型，例如：
- 阅读源代码以推断预期行为
- 将日志与该预期行为进行比较
- 判断一个发布 diff 是否包含真实的兼容性风险
- 生成维护者可以据此采取行动的解释
然后由脚本处理围绕这些工作的机制性事项，例如：
- 按固定顺序运行仓库要求的验证命令
- 启动示例运行、收集每个示例的日志，并为失败项写入 rerun 文件
- 在发布就绪审查之前获取上一个发布 tag
- 暴露诸如
start、stop、status、logs、tail、collect和rerun之类的辅助命令，以便相同工作流可以被轻松重复执行
如果模型每次都必须重新摸索同一套 shell 配方，这通常意味着这套配方应该成为一个脚本。如果任务依赖上下文、权衡或解释，那么这部分就应该留给模型。
自动化集成测试
两个仓库中最有用的工作流领域之一是自动化集成测试。这里有两个相关层面：在两个仓库中自动验证仓库内示例；以及在 JavaScript 仓库中，单独验证已发布的包在以用户实际使用方式安装时是否仍然可用。
在这套方案之前，验证示例有一部分是手工完成的。你可以运行这些示例，但最后一步通常依赖于目视检查日志，或通过人工判断输出看起来是否正确。对于单个示例，这还算可管理。但在一个不断增长的 SDK 仓库中，这种方式很难扩展。
第一层是 examples-auto-run，不过这个 skill 是在运行器之后才出现的。要想真正自动化示例验证，我们首先必须在两个仓库中构建底层支持，使示例能够以非交互方式执行。这意味着必须能够以自动模式运行示例脚本，包括那些通常涉及提示或审批的示例。
这些基础工作包括：
- 自动回答常见的交互式提示
- 在运行器支持的情况下，自动批准 HITL、MCP、
apply_patch和 shell 操作 - 将仍然不适合自动化的示例保留在自动跳过列表中，例如需要额外运行时设置的 realtime 或 Next.js 应用示例
- 为每次示例运行写入结构化日志
- 生成重跑文件，以便在失败时无需重跑全部内容就能重试
在这个基础打好之后，我们将其组织成一个 skill，这样整个工作流就变得可复用且易于调用。在 Python 仓库中，examples-auto-run 封装了 uv run examples/run_examples.py --auto-mode --write-rerun --main-log ... --logs-dir ...。在 JavaScript 仓库中，它封装了构建检查，然后以自动模式运行 pnpm examples:start-all，并支持按示例记录日志和重跑。
为了提升验证质量，运行器的职责是执行这些示例，并将它们的 stdout 和 stderr 保存在按示例划分的日志中。然后这个 skill 让 Codex 逐个检查这些日志，并将其与源代码进行比较：
- 读取示例源代码和注释
- 推断预期流程
- 打开对应日志
- 比较预期行为与实际 stdout 和 stderr
- 对每个成功的示例都这样做，而不只是检查一个样本
这比试图将正确性编码为固定的脚本级断言更准确也更灵活。成功退出码很有用，但对于那些会与真实 API 通信、使用工具或生成结构化输出的示例来说，仅有退出码还不够。通过先记录实际输出，再将其与源代码仔细比对，我们就能根据每个示例的真实意图来验证它。
在 JavaScript 仓库中，还有第二层：独立的 integration-tests skill。这个工作流不止是在原地运行源示例。它会将这些包发布到本地 Verdaccio registry，并在多个环境中测试安装和运行，包括 Node.js、Bun、Deno、Cloudflare Workers，以及一个 Vite React 应用。这能够捕获另一类问题：不再是“示例能否在仓库中运行？”，而是“包在发布、安装以及运行时集成之后，是否仍然表现正确？”
综合来看，这些工作流说明了为什么将 skills、脚本和模型判断结合起来是有用的。脚本让运行过程可重复、能捕获证据，并覆盖那些手工检查起来很繁琐的安装路径。然后 Codex 利用这些证据，进行比简单脚本化通过/失败检查更细致的比较。
添加发布检查
发布准备是这种模式发挥作用的另一个领域。
两个仓库中的 release-review 工作流，都是先找出上一个发布 tag，将其与最新的 main 做 diff，然后让 Codex 检查这个 diff，关注以下方面：
- 公共 API 和面向用户的 SDK 行为中的向后兼容性问题
- 回归问题，包括那些较小的预期行为变化
- 对于需要它们的变更，是否缺少迁移说明或 release note 更新
基于这些发现，这个 skill 会对整体发布就绪性做出判断。
一个具体示例是 openai/openai-agents-python#2480，在这个案例中，发布审查整体保持绿色，同时仍指出了弃用 Python 3.9 以及它所需要的 release note 跟进：
发布就绪性审查（摘录）
发布结论：
🟢 可以发布。此次小版本升级包含了预期中的破坏性变更
（弃用 Python 3.9），但未发现具体回归问题。
范围摘要：
- 38 个文件变更（+1450/-789）；涉及的关键区域：`src/agents/tool.py`，
`src/agents/extensions/`、`src/agents/realtime/`、`tests/`、
`pyproject.toml`、`uv.lock`。
已移除 Python 3.9 支持
- 风险：🟡 中等。固定使用 Python 3.9 的用户将无法安装
0.9.0 版本。
- 证据：`pyproject.toml` 现在将 `requires-python` 设为 `">=3.10"`，并移除了
Python 3.9 classifier；CI 中针对 3.9 的跳过逻辑也已删除。
- 行动：确保 release notes 明确说明弃用 Python 3.9，并确认
打包元数据保持为 `>=3.10`。
这个 skill 还定义了 gate 决策是如何做出的。审查从“可以安全发布”这一默认前提出发，只有当 diff 显示出真实问题的具体证据时，才会切换为阻塞结论。每一个阻塞结论都必须附带一份具体的解除阻塞清单。这样输出就更容易使用：绿色结果意味着在 diff 中没有发现阻塞发布的问题，而阻塞结果则意味着确实存在真实问题，并且下一步行动也很明确。
这比泛泛地说一句“请审查此次发布”更有用。它迫使模型基于具体 diff 进行推理，并用可操作的方式解释结果。如果发布是安全的，就明确说明；如果不是，就指出确切证据以及所需的确切后续动作。
在 CI 中运行工作流
一旦某个 skill 在本地已经有用，Codex GitHub Action 就能很方便地在 CI 中自动化同样的工作流。当本地工作流已经稳定时，这种方式效果最好，因为手动使用正是你调试指令、打磨脚本以及发现真实边界情况的阶段。
对于公共仓库来说，触发器设计和 skill 本身同样重要。GitHub Action 安全检查清单 建议限制可以启动工作流的人，优先使用可信事件或显式批准，对来自 PR、提交、issue 或评论的提示输入进行清洗，使用 drop-sudo 或非特权用户来保护 OPENAI_API_KEY，并将 Codex 作为作业中的最后一步运行。
如果一个工作流具有写入能力，并且会接收不受信任的公开输入，那么风险通常在于 skill 周边的触发器设计、输入处理和运行时权限。
在 PR 审查中使用 Codex
在这些仓库中，skills 只是提升生产力故事的一部分。Codex GitHub PR auto review 是另一部分。
自从 Codex GitHub PR auto review 可用以来，Codex 一直是这些仓库中大多数代码变更的有用审查者。我们将它作为审查流程中的常规组成部分，而不是特殊场景下才使用的工具。
对于直接的程序错误、回归问题和缺失测试，如今在实践中依赖 Codex 作为必经审查路径已经足够安全。它能够始终如一地反复检查相同的正确性模式，并且已经消除了小修复和常规改进中的一个主要瓶颈。
同伴审查仍然重要，但针对的是另一类变更。
当主要问题不再是“这段代码是否正确？”，而是“在多个都合理的选项中我们应该选择哪一个，以及应该如何发布它？”时，人工审查仍然至关重要。这包括：
- API 或架构变更：存在多个合理设计，维护者需要做出明确选择
- 会影响产品预期、向后兼容承诺或发布策略的行为变更
- 命名、迁移和发布沟通方面的决策，其中难点在于选择对用户和贡献者来说最清晰的方案
- 需要在维护者或团队之间达成一致的变更，例如确定工作范围、安排先后顺序，或决定哪些内容应当现在发布、哪些以后再发
Codex 在所有这些场景中仍然可以提供有价值的帮助，但它们依然受益于人工决策者和直接讨论。
AGENTS.md 也可以编码这种分工：仓库可以告诉 Codex，什么对正确性审查来说算重要，而 Codex 可以一致地应用这些指导。
这也显著提高了吞吐量。重复性的审查和验证工作，不再要求每一个低风险变更都等待稀缺的审查者时间；与此同时，维护者可以继续专注于那些更依赖上下文、真正需要他们判断的高层次审查。这种转变帮助我们更快地处理积压 bug 和较小的功能改进。
最后的想法
在 OpenAI Agents SDK 仓库中，skills 在作为仓库日常工作方式的一部分时效果最好。
AGENTS.md 告诉 Codex 哪些工作流是必需的。description 告诉它何时应当路由到这些工作流。scripts/ 处理确定性的部分。模型处理上下文相关的部分。而一旦某个工作流在本地足够稳固，Codex GitHub Action 就可以将同样的流程带入 CI。
这让这些仓库中的日常工程工作变得更加明确，也更加可靠。它也让更快地发布小改进变得更容易，因为验证、发布审查和 PR 交接现在都遵循同一种可重复的流程。