OpenAI 官方博客：用技能（Skills）加速开源项目维护
OpenAI 官方博客：用技能（Skills）加速开源项目维护
OpenAI 官方博客：用技能（Skills）加速开源项目维护 OpenAI 官方博客：用技能（Skills）加速开源项目维护 Modified March 18 Code block Plain Text description: Run the mandatory verification stack in the OpenAI Agents JS monorepo. 更好的写法（实际使用的描述）： Code block Plain Text description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo. 简短版本已经告诉了 Codex 技能做什么，但没有说明它何时适用、哪类变更应该触发它、以及这些检查是否可选。更具体的版本把这三点都说清楚了。 同样的模式也出现在 pr draft summary 上。 太笼统： Code block Plain Text description: Create a PR title and draft description for a pull request. 更好的写法（实际使用的描述）： Code block Plain Text 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： • 这是一个任务结束时的技能 • 它适用于实质性变更，而不是每次对话 • 输出是一个可直接用于 PR 的结构化块，而不仅仅是一段文字摘要 这些仓库的经验是：在 description 上花时间。如果路由感觉不可靠，先修描述，再加代码。 把机械性操作放进脚本 接下来的问题是：什么该留在模型里，什么该下沉到脚本中。 一个可靠的划分原则是： • 解读、对比和报告留给模型 • 确定性的、重复的 shell 操作放进 scripts/ 这与公开的指导一致。Codex 自定义文档 [8] 把技能描述为一种方式，让 Codex 获得更丰富的指令、脚本和参考资料来执行可重复的工作流，同时不会一开始就撑大上下文。这适合以模型为先的架构：让 Codex 处理依赖上下文的部分，只在需要时引入脚本处理确定性的部分。Skills in OpenAI API cookbook [22] 也建议把技能脚本设计成微型 CLI：从命令行运行、输出确定性的 stdout、出错时显式报错，需要时把输出写入已知的文件路径。 在 Agents SDK 仓库中，我们尽量把模型用在它的智能真正有价值的地方，例如： • 阅读源码以推断预期行为 • 将日志与预期行为进行对比 • 判断一个发布差异中是否存在真正的兼容性风险 • 生成维护者可以据此行动的解释 脚本则负责这些工作周围的机械性操作，例如： • 按固定顺序运行仓库要求的验证命令 • 启动示例运行、收集每个示例的日志、为失败的示例生成重试文件 • 在发布就绪性审查之前获取上一个发布标签 • 暴露诸如 start 、 stop 、 status 、 logs 、 tail 、 collect 和 rerun 之类的辅助命令，让同一个工作流可以方便地反复运行 分工原则：模型负责解读对比判断，脚本负责执行收集重复 如果模型每次都要重新发现同一套 shell 脚本流程，那通常意味着这套流程应该变成一个脚本。如果任务取决于上下文、权衡或解释，那部分就该留在模型里。 自动化集成测试 两个仓库中最有用的工作流领域之一是自动化集成测试。这里有两个相关的层次：在两个仓库中自动验证仓库内的示例，以及在 JavaScript 仓库中单独验证发布的包在用户实际的安装方式下是否仍能正常工作。 在这套配置之前，验证示例大多靠手动。你可以运行示例，但最后一公里往往取决于肉眼检查日志或凭经验判断输出是否正确。对一个示例来说还能应付，但在一个不断增长的 SDK 仓库中就难以为继了。 第一层是 examples auto run ，但技能是在运行器之后才出现的。要实现示例验证的自动化，我们首先得在两个仓库中构建非交互式示例执行的底层支持。这意味着让示例脚本能够在自动模式下运行，包括那些通常需要用户输入或审批的示例。 这些基础工作包括： • 自动回答常见的交互式提示 • 在运行器支持的范围内，自动通过人工审核环节（HITL）、MCP、 apply patch 和 shell 操作 • 把仍不适合自动化的示例放在跳过列表中，例如需要额外运行时配置的 Realtime 或 Next.js 应用示例 • 为每次示例运行编写结构化日志 • 生成重试文件，这样失败时无需重新运行所有内容 基础就位后，我们把它组织成了一个技能，让工作流变得可复用且易于调用。在 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 保存到逐示例的日志中。然后技能让 Codex 逐一检查这些日志，并与源码进行对比： • 阅读示例的源码和注释 • 推断预期的执行流程 • 打开对应的日志 • 将预期行为与实际的 stdout 和 stderr 进行比较 • 对每个成功运行的示例都这样做，而不只是抽检一个 这比把正确性编码为固定的脚本级断言更准确也更灵活。成功的退出码有用，但对于调用真实 API、使用工具或产生结构化输出的示例来说是不够的。通过先记录实际输出，再仔细对照源码检查，我们可以根据每个示例的真实意图来验证它。 在 JavaScript 仓库中，还有第二层：独立的 integration tests 技能。这个工作流不止于在仓库内运行源码示例。它把包发布到本地 Verdaccio 注册中心，然后在多种环境中测试安装和运行，包括 Node.js、Bun、Deno、Cloudflare Workers 和 Vite React 应用。这抓的是另一类问题：不是“示例在仓库里能不能跑”，而是“包在经过发布、安装和运行时集成之后，行为是否仍然正确”。 合在一起看，就能理解为什么技能、脚本和模型判断的组合管用。脚本让运行可重复、捕获证据、覆盖手动检查起来繁琐的安装路径。Codex 则利用这些证据，做出比简单的脚本通过/失败检查更细致的对比。 增加发布检查 发布准备是这个模式特别合适的另一个场景。 两个仓库中的发布审查工作流从查找上一个发布标签开始，将其与最新的 main 分支进行 diff，然后要求 Codex 检查该差异中的： • 公共 API 和面向用户的 SDK 行为中的向后兼容性问题 • 回归问题，包括预期行为的细微变化 • 需要迁移说明或发布说明更新但尚未添加的变更 根据这些发现，技能做出整体的发布就绪性判断。 一个具体的例子是 openai/openai agents python 2480 [23] ，在这次发布审查中，整体结论是绿灯放行，同时指出了 Python 3.9 支持的移除以及它所需的发布说明跟进： Code block Plain Text Release readiness review (excerpt) Release call: 🟢 GREEN LIGHT TO SHIP. Minor version bump includes expected breaking change (Python 3.9 drop) with no concrete regressions found. Scope summary: 38 files changed (+1450/ 789); key areas touched: , , , , , . Python 3.9 support removed Risk: 🟡 MODERATE. Users pinned to Python 3.9 will be unable to install the 0.9.0 release. Evidence: now sets and drops the Python 3.9 classifier; CI skip logic for 3.9 was removed. Action: Ensure release notes clearly call out the Python 3.9 drop and that packaging metadata remains . 技能还定义了关卡决策的方式。审查从“可以安全发布”出发，只有当差异中出现了真实问题的具体证据时才切换为阻止发布。每个阻止决定都必须附带具体的解除阻止清单。这让输出更易使用：绿灯意味着差异中未发现阻止发布的问题，红灯意味着存在真实问题且有明确的下一步。 这比泛泛的“请审查一下这次发布”要有用得多。它迫使模型基于具体的差异进行推理，并用可操作的术语解释结果。如果发布是安全的，就直接说安全。如果不安全，就指出确切的证据和确切的后续步骤。 在 CI 中运行工作流 当一个技能在本地验证有用之后，Codex GitHub Action [6] 可以轻松地把同一个工作流自动化到 CI 中。最好等本地工作流稳定了再上 CI，因为手动跑才是调试指令、打磨脚本、发现边界情况的过程。 对于公开仓库，触发器的设计和技能本身同样重要。GitHub Action 安全清单 [24] 建议限制谁能启动工作流、优先使用可信事件或显式审批、对来自 PR、提交、issue 或评论的 prompt 输入进行清理、用 drop sudo 或非特权用户保护 OPENAI API KEY ，以及把 Codex 作为任务中的最后一步运行。 如果一个工作流具有写权限且接受不可信的公开输入，风险通常出在技能周围的触发器设计、输入处理和运行时权限上。 在 PR 审查中使用 Codex 技能是这些仓库效率提升的一部分。Codex GitHub PR 自动审查 [25] 是另一部分。 自从 Codex GitHub PR 自动审查上线以来，Codex 在这些仓库的大多数代码变更审查中都有帮助。我们把它当常规审查环节，不是特殊工具。 对于直接的程序错误、回归和缺失的测试，把 Codex 作为必要的审查路径在实践中已经足够可靠。它能始终如一地反复检查同样的正确性模式，并消除了小修复和日常改进的一个主要瓶颈。 人工审查依然重要，但针对的是另一类变更。 当核心问题不是“这段代码正确吗”而是“在多个合理的方案中我们该选哪个，以及该如何发布”时，人工审查仍然不可或缺。这包括： • API 或架构变更，存在多个合理的设计方案，维护者需要做出明确选择 • 行为变更，影响产品预期、向后兼容性承诺或发布策略 • 命名、迁移和发布沟通决策，难点在于选择对用户和贡献者最清晰的方案 • 需要维护者或团队间对齐的变更，比如确定范围、排列优先级，或决定哪些内容现在发布、哪些以后再说 Codex 在所有这些场景中仍然能提供有用的贡献，但它们仍然需要人类决策者和直接讨论。 AGENTS.md 也可以编码这种分工：仓库可以告诉 Codex 在正确性审查中什么是重要的，Codex 就能持续一致地应用这些指导。 这也是效率提升的重要贡献者。重复性的审查和验证工作不再需要为每个低风险变更等待稀缺的审查者时间，而维护者可以专注于需要他们判断力的高上下文审查。这种转变帮助我们更快地处理了积压的 bug 和小规模的功能改进。 写在最后 在 OpenAI Agents SDK 仓库中，技能在融入仓库的日常工作配置时效果最好。 AGENTS.md 告诉 Codex 哪些工作流是必需的。 description 告诉它何时路由到这些工作流。 scripts/ 处理确定性的部分。模型处理需要上下文的部分。而当一个工作流在本地稳定之后，Codex GitHub Action [6] 可以把同样的流程带入 CI。 这让这些仓库中的日常工程工作变得更明确、更可靠。小改进的发布也更快了，验证、发布审查和 PR 交接都走同一套流程。 更好的写法（实际使用的描述）： 简短版本已经告诉了 Codex 技能做什么，但没有说明它何时适用、哪类变更应该触发它、以及这些检查是否可选。更具体的版本把这三点都说清楚了。 同样的模式也出现在 pr draft summary 上。 太笼统： 更好的写法（实际使用的描述）： 同样，真正的描述就是路由元数据。它告诉 Codex： • 这是一个任务结束时的技能 • 它适用于实质性变更，而不是每次对话 • 输出是一个可直接用于 PR 的结构化块，而不仅仅是一段文字摘要 这些仓库的经验是：在 description 上花时间。如果路由感觉不可靠，先修描述，再加代码。 把机械性操作放进脚本 接下来的问题是：什么该留在模型里，什么该下沉到脚本中。 一个可靠的划分原则是： • 解读、对比和报告留给模型 • 确定性的、重复的 shell 操作放进 scripts/ 这与公开的指导一致。Codex 自定义文档 [8] 把技能描述为一种方式，让 Codex 获得更丰富的指令、脚本和参考资料来执行可重复的工作流，同时不会一开始就撑大上下文。这适合以模型为先的架构：让 Codex 处理依赖上下文的部分，只在需要时引入脚本处理确定性的部分。Skills in OpenAI API cookbook [22] 也建议把技能脚本设计成微型 CLI：从命令行运行、输出确定性的 stdout、出错时显式报错，需要时把输出写入已知的文件路径。 在 Agents SDK 仓库中，我们尽量把模型用在它的智能真正有价值的地方，例如： • 阅读源码以推断预期行为 • 将日志与预期行为进行对比 • 判断一个发布差异中是否存在真正的兼容性风险 • 生成维护者可以据此行动的解释 脚本则负责这些工作周围的机械性操作，例如： • 按固定顺序运行仓库要求的验证命令 • 启动示例运行、收集每个示例的日志、为失败的示例生成重试文件 • 在发布就绪性审查之前获取上一个发布标签 • 暴露诸如 start 、 stop 、 status 、 logs 、 tail 、 collect 和 rerun 之类的辅助命令，让同一个工作流可以方便地反复运行 分工原则：模型负责解读对比判断，脚本负责执行收集重复 如果模型每次都要重新发现同一套 shell 脚本流程，那通常意味着这套流程应该变成一个脚本。如果任务取决于上下文、权衡或解释，那部分就该留在模型里。 自动化集成测试 两个仓库中最有用的工作流领域之一是自动化集成测试。这里有两个相关的层次：在两个仓库中自动验证仓库内的示例，以及在 JavaScript 仓库中单独验证发布的包在用户实际的安装方式下是否仍能正常工作。 在这套配置之前，验证示例大多靠手动。你可以运行示例，但最后一公里往往取决于肉眼检查日志或凭经验判断输出是否正确。对一个示例来说还能应付，但在一个不断增长的 SDK 仓库中就难以为继了。 第一层是 examples auto run ，但技能是在运行器之后才出现的。要实现示例验证的自动化，我们首先得在两个仓库中构建非交互式示例执行的底层支持。这意味着让示例脚本能够在自动模式下运行，包括那些通常需要用户输入或审批的示例。 这些基础工作包括： • 自动回答常见的交互式提示 • 在运行器支持的范围内，自动通过人工审核环节（HITL）、MCP、 apply patch 和 shell 操作 • 把仍不适合自动化的示例放在跳过列表中，例如需要额外运行时配置的 Realtime 或 Next.js 应用示例 • 为每次示例运行编写结构化日志 • 生成重试文件，这样失败时无需重新运行所有内容 基础就位后，我们把它组织成了一个技能，让工作流变得可复用且易于调用。在 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 保存到逐示例的日志中。然后技能让 Codex 逐一检查这些日志，并与源码进行对比： • 阅读示例的源码和注释 • 推断预期的执行流程 • 打开对应的日志 • 将预期行为与实际的 stdout 和 stderr 进行比较 • 对每个成功运行的示例都这样做，而不只是抽检一个 这比把正确性编码为固定的脚本级断言更准确也更灵活。成功的退出码有用，但对于调用真实 API、使用工具或产生结构化输出的示例来说是不够的。通过先记录实际输出，再仔细对照源码检查，我们可以根据每个示例的真实意图来验证它。 在 JavaScript 仓库中，还有第二层：独立的 integration tests 技能。这个工作流不止于在仓库内运行源码示例。它把包发布到本地 Verdaccio 注册中心，然后在多种环境中测试安装和运行，包括 Node.js、Bun、Deno、Cloudflare Workers 和 Vite React 应用。这抓的是另一类问题：不是“示例在仓库里能不能跑”，而是“包在经过发布、安装和运行时集成之后，行为是否仍然正确”。 合在一起看，就能理解为什么技能、脚本和模型判断的组合管用。脚本让运行可重复、捕获证据、覆盖手动检查起来繁琐的安装路径。Codex 则利用这些证据，做出比简单的脚本通过/失败检查更细致的对比。 增加发布检查 发布准备是这个模式特别合适的另一个场景。 两个仓库中的发布审查工作流从查找上一个发布标签开始，将其与最新的 main 分支进行 diff，然后要求 Codex 检查该差异中的： • 公共 API 和面向用户的 SDK 行为中的向后兼容性问题 • 回归问题，包括预期行为的细微变化 • 需要迁移说明或发布说明更新但尚未添加的变更 根据这些发现，技能做出整体的发布就绪性判断。 一个具体的例子是 openai/openai agents python 2480 [23] ，在这次发布审查中，整体结论是绿灯放行，同时指出了 Python 3.9 支持的移除以及它所需的发布说明跟进： 技能还定义了关卡决策的方式。审查从“可以安全发布”出发，只有当差异中出现了真实问题的具体证据时才切换为阻止发布。每个阻止决定都必须附带具体的解除阻止清单。这让输出更易使用：绿灯意味着差异中未发现阻止发布的问题，红灯意味着存在真实问题且有明确的下一步。 这比泛泛的“请审查一下这次发布”要有用得多。它迫使模型基于具体的差异进行推理，并用可操作的术语解释结果。如果发布是安全的，就直接说安全。如果不安全，就指出确切的证据和确切的后续步骤。 在 CI 中运行工作流 当一个技能在本地验证有用之后，Codex GitHub Action [6] 可以轻松地把同一个工作流自动化到 CI 中。最好等本地工作流稳定了再上 CI，因为手动跑才是调试指令、打磨脚本、发现边界情况的过程。 对于公开仓库，触发器的设计和技能本身同样重要。GitHub Action 安全清单 [24] 建议限制谁能启动工作流、优先使用可信事件或显式审批、对来自 PR、提交、issue 或评论的 prompt 输入进行清理、用 drop sudo 或非特权用户保护 OPENAI API KEY ，以及把 Codex 作为任务中的最后一步运行。 如果一个工作流具有写权限且接受不可信的公开输入，风险通常出在技能周围的触发器设计、输入处理和运行时权限上。 在 PR 审查中使用 Codex 技能是这些仓库效率提升的一部分。Codex GitHub PR 自动审查 [25] 是另一部分。 自从 Codex GitHub PR 自动审查上线以来，Codex 在这些仓库的大多数代码变更审查中都有帮助。我们把它当常规审查环节，不是特殊工具。 对于直接的程序错误、回归和缺失的测试，把 Codex 作为必要的审查路径在实践中已经足够可靠。它能始终如一地反复检查同样的正确性模式，并消除了小修复和日常改进的一个主要瓶颈。 人工审查依然重要，但针对的是另一类变更。 当核心问题不是“这段代码正确吗”而是“在多个合理的方案中我们该选哪个，以及该如何发布”时，人工审查仍然不可或缺。这包括： • API 或架构变更，存在多个合理的设计方案，维护者需要做出明确选择 • 行为变更，影响产品预期、向后兼容性承诺或发布策略 • 命名、迁移和发布沟通决策，难点在于选择对用户和贡献者最清晰的方案 • 需要维护者或团队间对齐的变更，比如确定范围、排列优先级，或决定哪些内容现在发布、哪些以后再说 Codex 在所有这些场景中仍然能提供有用的贡献，但它们仍然需要人类决策者和直接讨论。 AGENTS.md 也可以编码这种分工：仓库可以告诉 Codex 在正确性审查中什么是重要的，Codex 就能持续一致地应用这些指导。 这也是效率提升的重要贡献者。重复性的审查和验证工作不再需要为每个低风险变更等待稀缺的审查者时间，而维护者可以专注于需要他们判断力的高上下文审查。这种转变帮助我们更快地处理了积压的 bug 和小规模的功能改进。 写在最后 在 OpenAI Agents SDK 仓库中，技能在融入仓库的日常工作配置时效果最好。 AGENTS.md 告诉 Codex 哪些工作流是必需的。 description 告诉它何时路由到这些工作流。 scripts/ 处理确定性的部分。模型处理需要上下文的部分。而当一个工作流在本地稳定之后，Codex GitHub Action [6] 可以把同样的流程带入 CI。 这让这些仓库中的日常工程工作变得更明确、更可靠。小改进的发布也更快了，验证、发布审查和 PR 交接都走同一套流程。 参考资源 • OpenAI Agents SDK for Python [2] • OpenAI Agents SDK for JS [3] • Skills in Codex [8] • Custom instructions with AGENTS.md [26] • Codex GitHub Action [6] • Use Codex in GitHub [25] • Skills in OpenAI API cookbook [27] • Agent Skills specification [18] • Skills in OpenAI API: operational best practices [22] 引用链接 [1] OpenAI Agents SDK: https://developers.openai.com/api/docs/guides/agents sdk [2] Python: https://github.com/openai/openai agents python [3] TypeScript: https://github.com/openai/openai agents js [4] Realtime API: https://developers.openai.com/api/docs/guides/realtime [5] : https://agents.md/ [6] Codex GitHub Action: https://developers.openai.com/codex/github action [7] Codex for Open Source: https://developers.openai.com/codex/community/codex for oss [8] Codex 自定义文档: https://developers.openai.com/codex/concepts/customization skills [9] openai agents python 中的 .agents/skills: https://github.com/openai/openai agents python/tree/main/.agents/skills [10] openai agents js 中的 .agents/skills: https://github.com/openai/openai agents js/tree/main/.agents/skills [11] AGENTS.md 指南: https://developers.openai.com/codex/guides/agents md layer project instructions [12] openai agents python 的 AGENTS.md: https://github.com/openai/openai agents python/blob/main/AGENTS.md [13] openai agents js 的 AGENTS.md: https://github.com/openai/openai agents js/blob/main/AGENTS.md [14] Changesets: https://github.com/changesets/changesets [15] OpenAI Docs MCP: https://developers.openai.com/resources/docs mcp [16] Docs MCP 快速入门: https://developers.openai.com/resources/docs mcp quickstart [17] 官方 MCP 服务器端点: https://developers.openai.com/mcp [18] Agent Skills 规范: https://agentskills.io/specification [19] Codex 技能文档: https://developers.openai.com/codex/skills [20] Skills in OpenAI API cookbook: https://developers.openai.com/cookbook/examples/skills in api/ what is a skill [21] SKILL.md frontmatter 章节: https://developers.openai.com/cookbook/examples/skills in api/ skillmd frontmatter [22] Skills in OpenAI API cookbook: https://developers.openai.com/cookbook/examples/skills in api/ operational best practices [23] openai/openai agents python 2480: https://github.com/openai/openai agents python/pull/2480 [24] GitHub Action 安全清单: https://developers.openai.com/codex/github action security checklist [25] Codex GitHub PR 自动审查: https://developers.openai.com/codex/integrations/github [26] Custom instructions with AGENTS.md: https://developers.openai.com/codex/guides/agents md [27] Skills in OpenAI API cookbook: https://developers.openai.com/cookbook/examples/skills in api 🔗 原文链接： https://mp.weixin.qq.com/s/xiGwSmmJ... https://mp.weixin.qq.com/s/xiGwSmmJ... 宝玉 宝玉 宝玉AI2026年3月17日 00:01 美国 我们用 Codex 改变了维护 OpenAI Agents SDK [1] 仓库的方式。仓库本地的技能（skills）、 AGENTS.md 文件和 GitHub Actions，让我们把反复出现的工程工作——验证、发布准备、示例集成测试、PR 审查，变成了可重复执行的工作流。即便配置相当简单，也明显提升了这些活跃仓库的开发效率。2025 年 12 月 1 日至 2026 年 2 月 28 日期间，两个仓库共合并了 457 个 PR，而此前三个月（2025 年 9 月 1 日至 11 月 30 日）只有 316 个（Python：182 → 226，TypeScript：134 → 231）。 简单介绍一下背景：该 SDK 提供 Python [2] 和 TypeScript [3] 两个版本。它为构建智能体应用提供了核心组件，也是在 Realtime API [4] 之上构建语音智能体的简洁方案，支持多智能体、工具调用和人工审核环节（HITL）。用的人不少：截至 2026 年 3 月 6 日的近 30 天内，Python 包在 PyPI 上的下载量约为 1470 万次，TypeScript 包在 npm 上的下载量约为 150 万次。 这套配置很简单： • 仓库策略写在 AGENTS.md [5] 里 • 仓库本地技能放在 .agents/skills/ 目录下 • 技能内部可以包含脚本和参考资料 • 当同一个工作流需要在 CI 中运行时，使用 Codex GitHub Action [6] 这套配置让 Codex 对仓库的运作方式有了稳定的上下文，让重复性的工程工作更快、更准。 如果你维护着一个公开的开源项目，可以看看 Codex for Open Source [7] 。符合条件的维护者可以申请带 Codex 的 ChatGPT Pro、API 额度，以及 Codex Security 的有条件访问权限。 Skills 系统四层架构：AGENTS.md 策略层 → 技能层 → 脚本层 → CI 层，附 PR 增长数据 把工作流留在仓库里 在这些仓库中，我们用技能来承载仓库特有的工作流。一个技能就是一小包操作知识：一个 SKILL.md 清单文件，加上可选的 scripts/ 、 references/ 和 assets/ 目录。Codex 自定义文档 [8] 解释了为什么这样做效果好：技能很适合用来承载可重复的工作流，因为它们可以携带更丰富的指令、脚本和参考资料，同时不会一开始就撑大智能体的上下文。 这正好符合技能采用的渐进式披露（progressive disclosure）模型： • 首先只看到 name 和 description 等元数据 • 只有当技能被选中时，才加载 SKILL.md 的完整内容 • 只在需要时才读取参考资料或运行脚本 两个 SDK 仓库都把这些工作流放在代码旁边： • openai agents python 中的 .agents/skills [9] • openai agents js 中的 .agents/skills [10] Python 仓库是更简洁的基础版本： • 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 仓库遵循同样的总体模式，然后针对其 npm monorepo（单仓库）和发布流程增加了几个仓库特有的技能： • changeset validation ——检查变更集和版本升级级别是否真正匹配包的差异。 • integration tests ——将包发布到本地 Verdaccio（本地 npm 包注册中心）注册表，并验证在各支持运行时中的安装和运行行为。 • pnpm upgrade ——协调更新 pnpm 工具链和 CI 中的版本锁定。 比起具体的技能列表，更重要的是这个模式本身。每个技能都有职责明确的契约、清晰的触发条件和具体的输出。 技能渐进式披露模型与技能目录：Python 8 个技能 + JS 3 个专属技能 其中一些最有用的技能并不是硬性关卡。 docs sync 和 test coverage improver 是“先报告再行动”的工作流：它们先检查当前的差异或覆盖率产物，排出优先级，然后在编辑之前征求批准。在 Python 仓库中， docs sync 还把源码中的 docstring 和注释作为生成参考文档的权威来源，而不是手动修补生成的输出。JavaScript 专属的 pnpm upgrade 技能也是窄范围维护工作流的好例子：它把本地 pnpm 版本、 packageManager 字段和工作流中的版本锁定一起更新，而不是退而求其次地做全局搜索替换。 让工作流成为强制要求 技能要真正发挥作用，得在对的时机被强制触发。这就是 AGENTS.md 的用武之地。 AGENTS.md 指南 [11] 把这类文件定义为仓库级别的指令，随代码库一起传递，在智能体开始工作之前生效。指南还建议保持文件精简。在 Agents SDK 仓库中，我们用这个空间来放 Codex 每次都应遵守的规则，并把最重要的规则放在最前面。 实际操作中，两个仓库都使用简短的“如果/则”规则来强制使用技能。在修改运行时或 API 变更之前，先调用 $impleme