No.7

原文：Using skills to accelerate OSS maintenance
发布日期：2026-03-09
作者：Kazuhiro Sera

概述

OpenAI 团队分享了他们如何使用 Codex 和技能（Skills）来维护 OpenAI Agents SDK 仓库。通过仓库本地的技能、AGENTS.md 配置文件和 GitHub Actions，他们将重复性的工程工作（如验证、发布准备、集成测试和 PR 审查）转化为可重复的工作流程。

效果显著：2025年12月1日至2026年2月28日期间，两个仓库合并了 457 个 PR，相比前三个月的 316 个 PR 有明显提升（Python: 182→226, TypeScript: 134→231）。

核心设置

简单的三件套：

AGENTS.md - 仓库策略文件
.agents/skills/ - 仓库本地技能
Codex GitHub Action - 在 CI 中运行相同工作流

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

技能（Skills）是什么

技能是一个小型的操作知识包：

SKILL.md 清单文件
可选的 scripts/、references/、assets/

渐进式披露模型：

首先看到元数据（name 和 description）
只有在选择技能时才加载 SKILL.md
只在需要时读取引用或运行脚本

实际技能示例

Python 仓库的技能

code-change-verification - 运行格式化、lint、类型检查和测试
docs-sync - 审计文档与代码库的一致性
examples-auto-run - 自动模式运行示例并记录日志
final-release-review - 比较发布标签检查发布准备情况
implementation-strategy - 在编辑前决定兼容性边界
openai-knowledge - 通过官方 Docs MCP 拉取当前 OpenAI API 文档
pr-draft-summary - 准备分支名、PR 标题和草稿描述
test-coverage-improver - 运行覆盖率并提出高影响力测试

TypeScript 仓库的额外技能

changeset-validation - 检查 changesets 和版本号是否匹配包差异
integration-tests - 发布到本地 Verdaccio 并验证跨运行时安装行为
pnpm-upgrade - 协调更新 pnpm 工具链和 CI 配置

AGENTS.md 的作用

AGENTS.md 是仓库级别的指令文件，在代理开始工作前应用。两个仓库使用简短的 if/then 规则来强制使用技能：

## 强制技能使用

- 编辑运行时或 API 更改前使用 `$implementation-strategy`
- 代码、测试、示例或构建行为变更时运行 `$code-change-verification`
- OpenAI API 或平台工作使用 `$openai-knowledge`
- 实质性代码工作准备好审查时使用 `$pr-draft-summary`

验证规则示例

Python 仓库：

make format
make lint
make typecheck
make tests

TypeScript 仓库：

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

技能编码了仓库对"已验证"的定义，AGENTS.md 使这个定义可执行。

写好技能描述

description 字段是路由契约的一部分，因为它是启动时加载的元数据。

不够好的描述：

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.

更具体的版本告诉模型：

技能做什么
何时应用
哪些变更应触发它
检查是否可选

脚本 vs 模型判断

可靠的分工：

解释、比较和报告 → 留给模型
确定性、重复的 shell 工作 → 放入 scripts/

模型擅长的工作：

读取源代码推断预期行为
比较日志与预期行为
判断发布差异是否包含兼容性风险
生成维护者可操作的解释

脚本处理的机械工作：

按固定顺序运行验证命令
启动示例运行、收集日志、写入重新运行文件
获取上一个发布标签
暴露 start、stop、status、logs 等辅助命令

自动化集成测试

示例自动运行

examples-auto-run 技能的基础工作包括：

自动回答常见交互提示
自动批准 HITL、MCP、apply_patch 和 shell 操作
为每个示例运行写入结构化日志
生成重新运行文件以便失败重试

验证流程：

读取示例源代码和注释
推断预期流程
打开匹配的日志
比较预期行为与实际 stdout/stderr
对每个成功的示例都这样做

TypeScript 的集成测试

integration-tests 技能更进一步：

将包发布到本地 Verdaccio 注册表
在多个环境中测试安装和运行（Node.js、Bun、Deno、Cloudflare Workers、Vite React）
捕获不同类别的问题："包在发布、安装和运行时集成后是否仍然正常工作？"

发布检查

发布审查工作流：

找到上一个发布标签
与最新 main 进行差异比较
检查差异中的：
- 公共 API 和用户面向 SDK 行为的向后兼容性问题
- 回归，包括预期行为的小变化
- 需要迁移说明或发布说明更新的变更

决策逻辑：

从"安全发布"开始
只有在差异显示具体问题证据时才切换到阻止状态
每个阻止调用必须附带具体的解除阻止清单

在 CI 中运行工作流

一旦技能在本地有用，Codex GitHub Action 可以轻松在 CI 中自动化相同的工作流。

安全检查清单：

限制谁可以启动工作流
优先使用可信事件或显式批准
清理来自 PR、提交、问题或评论的提示输入
使用 drop-sudo 或非特权用户保护 OPENAI_API_KEY
将 Codex 作为作业的最后一步运行

在 PR 审查中使用 Codex

Codex GitHub PR 自动审查已成为这些仓库中大多数代码变更的常规审查部分。

Codex 擅长的审查：

程序错误
回归
缺失的测试
一致性检查

仍需人工审查的情况：

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

这种分工显著提高了吞吐量：重复性审查和验证工作不再等待稀缺的审查者时间，维护者可以专注于需要判断的高上下文审查。

关键要点

技能最适合可重复的工作流 - 它们可以携带更丰富的指令、脚本和引用，而不会预先膨胀上下文
AGENTS.md 使工作流强制执行 - 通过 if/then 规则告诉 Codex 何时必须使用哪些技能
好的描述是路由元数据 - 花时间写清楚 description，说明技能做什么、何时应用、触发条件
脚本处理机械工作，模型处理判断 - 确定性工作放入脚本，解释和比较留给模型
本地先稳定，然后自动化到 CI - 在本地调试指令和脚本，然后用 GitHub Action 自动化
Codex 审查释放人工审查时间 - 让 Codex 处理正确性检查，人工专注于设计决策和对齐

使用技能加速开源软件维护

AI 核心摘要

概述