从代码生成到工程协同:OpenAI Skills 重塑项目维护新范式

然而当 AI 真正深入大型项目维护后，一个更关键的问题浮现出来：

也就是说，AI 编程助手的价值，不应该只停留在"一次性生成代码"。

真正有价值的在于：它能否像一个熟悉项目规范的工程协作者，知道这个仓库该如何修改、如何测试、如何发布、如何交接。

OpenAI 在 Agents SDK 的 Python 和 TypeScript 开源仓库中，实践了一套极具参考价值的方法：通过 Skills、AGENTS.md 和 GitHub Actions，将验证、发布准备、示例集成测试、PR Review 等重复性工程任务，沉淀为稳定、可复用、可验证的工作流。

本文将深入剖析这一做法，以及它对 Codebase、AI IDE 和 Agent 平台建设的启示。

OpenAI 的方案可以归纳为四个核心部分：

这套机制的核心价值在于：

不再每次都依赖人重新告诉 AI "这个项目应该怎么做"，而是将项目规范、验证流程、发布要求和交接格式沉淀到仓库中。

这与传统工程中的 Makefile、CI 配置、贡献指南非常相似。

区别在于，Skills 和 AGENTS.md 是专门为 AI Agent 准备的"操作知识"。

也就是说，仓库中不仅保存代码，还保存了 AI 执行任务时需要遵循的工作方式。

在这个实践中，Skill 可以理解为一个小型"操作知识包"。

它通常包含：

其中：

一个 Skill 不应该大包大揽。

优秀的 Skill 通常具备三个特点：

例如：

这些都是非常适合做成 Skill 的场景。

很多人会把 Skill 理解为"高级提示词"。

但更准确地说，Skill 是一种可复用工作流。

普通 Prompt 通常是这样的：

而 Skill 更像这样：

前者依赖模型临场发挥。后者将流程固定下来，让 Agent 稳定执行。

这就是 Skill 的核心价值：

将"人脑里的经验"转化为"仓库里的流程"。

Skill 只有被正确触发，才有价值。

因此还需要一个地方告诉 Codex：

这个地方就是 AGENTS.md。

可以把它理解为仓库级的 Agent 操作规约。

一个简化版可能长这样：

这类规则如果只存在于人脑中，AI 很容易遗忘。

如果每次都写进 Prompt，又太低效。

放入 AGENTS.md，就能让它成为仓库的一部分。

以代码变更验证为例，一个常见误区是：

只要用了 AI 改代码，就让它每次都跑全量测试。

这听起来稳妥，但实际会拖慢效率。

更好的方式是明确定义触发条件：

这就比"永远跑全量"更合理。

文档-only 改动不需要被过重流程拖慢。但真正影响 SDK 行为的改动，必须完成标准验证。

例如 Python 仓库可以定义：

TypeScript 仓库可以定义：

关键不是命令本身，而是把"什么叫完成"定义清楚。

对 Agent 来说，完成任务不应该只是"代码写完了"，而应该是"代码写完，并且完成了仓库要求的验证"。

AI 编程助手很容易犯一个问题：

凭记忆写 API。

这在平台能力快速变化时尤其危险。

比如 SDK、API 参数、流式接口、工具调用方式、认证机制、部署规范，这些内容都可能变化。

所以 OpenAI 在相关仓库中设置了类似 $openai-knowledge 的 Skill：当任务涉及 OpenAI API 或平台集成时，Codex 不能只凭训练记忆回答，而要查询当前官方文档。

这个思路对企业内部项目也非常重要。

可以类比成：

很多 AI 代码问题，本质不是模型不会写，而是上下文过期。

所以，Agent 必须有能力在关键场景下查最新资料。

很多工程任务真正完成时，还差最后一步：

这些工作不难，但很耗时间，而且容易写得不一致。

所以 OpenAI 把这一步也做成了 Skill。

当一项实质性工作完成后，Codex 会根据真实 diff、测试结果和任务上下文，生成 PR 草稿。

示例格式可以是：

这件事看起来很小，但非常有价值。

因为它把"开发完成后的交接动作"也标准化了。

AI 不只是帮你改代码，也可以帮你把改动整理成可 Review、可合并、可追踪的工程产物。

在 Skill 里，description 不是装饰性文案，而是路由规则的一部分。

因为 Codex 在还没有读取完整 Skill 内容之前，通常会先根据 Skill 的名字和描述判断：

所以 description 不能写得太泛。

比如：

这个描述太宽泛。

更好的写法是：

前者只说了"做什么"。后者说清楚了"什么时候做"。

再比如 PR 草稿 Skill。

不好的写法：

更好的写法：

这个描述告诉 Codex：

一句话：

Skill 的 description 写得越像触发条件，路由越稳定。

这套实践里，一个非常重要的分工是：

不要让模型每次都重新想：

这些确定性动作应该写成脚本。

比如：

而模型更适合做：

这是一条非常实用的 Agent 工程原则：

脚本负责稳定执行，模型负责理解判断。

如果全部交给模型，流程不稳定。如果全部写死脚本，又缺乏灵活判断。

最好的方式是两者配合。

在示例集成测试中，有一个很重要的观点：

命令执行成功，不代表 Agent 行为正确。

很多 example 或集成场景，即使退出码是 0，也可能存在问题：

所以更好的做法是：

这比单纯看退出码更可靠。

对 AI IDE 和 Agent 平台也是一样：

未来的 Agent 系统，需要保存更多过程证据，再基于证据做二次审查。

发布前检查也是很适合做成 Skill 的场景。

一个好的 release review Skill 不应该只是问：

而应该先收集证据：

然后再让模型给出判断：

并说明原因。

这种方式可以让 AI 参与发布准备，但不会变成随口判断。

它的基础仍然是证据：

当某个 Skill 在本地已经稳定可用，就可以通过 GitHub Actions 把它接入 CI。

但顺序很重要：

因为本地阶段更适合调试：

如果流程本身还不稳定，过早接入 CI 只会自动化地产生混乱。

另外，自动化越强，越要重视安全边界。

尤其是公开仓库里的 GitHub Actions，需要注意：

这点对企业内部平台也一样。

自动化不是简单地"让 AI 自己跑"，而是要设计清楚权限、触发器和审批边界。

OpenAI 也在这些仓库中使用 Codex 做 PR Review。

Codex 很适合检查：

这些检查具有高重复性、规则比较明确，非常适合交给 AI。

但人工 Review 仍然非常重要。

人更适合判断：

所以，人和 AI 的关系不是替代，而是分工。

可以这样理解：

这样，Reviewer 可以从大量低价值重复检查中解放出来，把精力放在真正需要判断的地方。

这套实践对 Codebase、Agent 平台建设非常有参考价值。

过去我们做 Codebase，更多关注的是：

这些当然重要。

但 Agent 真正进入开发流程后，还需要理解：

这些不是单纯检索能解决的。

它们更像仓库级 Skills、AGENTS.md 和自动化工作流。

未来的 Codebase 系统，不应该只回答：

还应该帮助 Agent 知道：

这意味着 Codebase 要从"代码检索系统"升级成"Agent 工程上下文系统"。

对内部项目来说，可以把仓库关键规则沉淀到 AGENTS.md：

这样，Agent 不再完全依赖用户每次提醒，而是根据仓库规则工作。

在 Codebase / Agent 场景中，可以优先沉淀这些 Skills：

重点不是 Skill 数量，而是每个 Skill 都要有明确边界。

在我们的系统中，也可以采用同样分工：

这样比"全部交给模型"更稳定，也比"全部写死脚本"更灵活。

适合 Codex / Agent 承担的：

适合人类承担的：

这才是 AI 工程协作更合理的方向。

不是替代人，而是把人从低价值重复劳动中释放出来。

这套实践最值得借鉴的地方，不是某一个具体 Skill，而是一种新的工程化范式：

一句话总结：

AI 编程助手的终点，不是"更会写代码"，而是"更懂工程流程"。

真正可落地的 Agent，不应该每次都靠用户重新讲清楚怎么做。

它应该能从仓库中读取规则、选择技能、运行脚本、验证结果，并在该交给人的地方，把问题、证据和建议整理清楚。

这才是 AI 编程助手从"工具"走向"工程协作者"的关键一步。

本文参考并整理自 OpenAI Developers Blog：

Using skills to accelerate OSS maintenance作者：Kazuhiro Sera 发布时间：2026 年 3 月 9 日 原文链接：https://developers.openai.com/blog/skills-agents-sdk