Codex 源码- Skill 系统

当你用 Claude Code 或 Cursor 工作了三个月后，打开聊天记录搜索框，试着找一个三周前用过的复杂提示词------也许是"评审这个 PR 时重点检查 breaking changes、测试覆盖率和变更大小"，或者是"汇总最近 24 小时的 issue，按标签聚类，标出高关注度的"。

你会发现，这类指令散落在无数对话线程中，无法复用、无法版本化，更无法衡量它们消耗了多少上下文窗口。

Codex 团队遇到了同样的问题。他们的解决方案不是"写一份更好的文档"，而是把 AI 的能力编码为可复用的工程资产------这就是 Codex 的 Skill 系统。

场景触发条件：什么情况下 Codex 团队会决定创建一个 skill？

从 Codex 仓库的 git history 中，可以还原出三个真实的触发模式。

模式一：重复工作流固化

2026 年 2 月，Eric Traut 提交了 commit 7e569f1162，引入 babysit-pr skill。Commit message 写得很直白："Add PR babysitting skill for this repo"。这个 skill 让 Codex 在 PR 提交后持续监控 CI、review comments 和 mergeability，自动修复失败、重试 flaky tests、处理 review feedback，直到 PR 可合并。

为什么创建它？因为团队发现，PR 提交后的" babysitting "是一个被反复执行、步骤固定的工作流------同一件事做第 3+ 次时，就值得固化为 skill。

类似的案例还有 codex-issue-digest（#19779）："Maintainers need a shared way to run Codex GitHub issue digests without copying large prompts or relying on manual GitHub page summaries."

模式二：知识分散

2026 年 4 月，pakrym-oai 提交了 513dc28717，引入 code-review skill。Commit message 只有一句话："Adds a skill that centralizes rules used during code review for codex."

关键词是 centralizes。代码评审的规则------比如"检查 breaking changes""变更不要超过 800 行""context 注入不能超过 10K tokens"------之前散落在聊天记录和人类记忆里。当团队对这些规则有了共识，但共识只存在于人脑中时，就需要一个 skill 来集中化。

模式三：复杂 Prompt / 脚本封装

2026 年 4 月，Michael Bolin 提交了 d63ba2d5ec，引入 codex-pr-body skill。这个 skill 定义了 PR body 的更新规范：如何保留作者原有内容、解释 why 在 what 之前、如何处理 Sapling 的 stacked PRs。

这个 skill 只有 59 行，但它的存在意味着：当某个 prompt 虽然不长，但涉及特定工具（Sapling）的特殊工作流时，也值得封装为 skill。

关键判断标准不是"这个任务很重要"，而是**"这个任务被反复执行且存在共享需求"**。

Skill 即代码：磁盘结构与触发机制

Codex 的 skill 不是聊天记录里的一个收藏夹，也不是 README 里的一个段落。它是一个有严格结构的代码单元。

磁盘上的结构是这样的：

bash 复制代码

skill-name/
├── SKILL.md                    # 必需。YAML frontmatter + Markdown body
├── agents/
│   └── openai.yaml             # UI 元数据（display_name, icon, brand_color）
├── scripts/                    # 可执行辅助脚本（Python, Bash 等）
├── references/                 # 按需加载的参考文档
└── assets/                     # 模板、图片、字体等输出资源

SKILL.md 是整个系统的核心。它分为两部分：

YAML Frontmatter （必需）：只有 name 和 description 两个字段。description 是 skill 的触发机制------它会被始终加载到模型上下文中，帮助模型判断何时应该调用这个 skill。
Markdown Body （必需）：详细的指令和工作流。但注意------body 只在 skill 触发后才会被加载。

这个设计本身就是一个关键决策：不要把所有 skill 的完整指令都塞进上下文窗口。

真实仓库中的 skill 全景：12 个案例的格式分析

理论结构讲完了，让我们看看 Codex 仓库里真实存在的 12 个 skill，从中提炼可借鉴的模式。

12 个 skill 的分类清单

Codex 仓库的 .codex/skills/ 目录下目前有 12 个 skill，按复杂度可以分成三层：

简单技能（< 20 行 SKILL.md）

test-tui：TUI 交互测试指南（14 行）
remote-tests：远程执行器测试指南（16 行）
code-review-change-size：变更大小指导，800 行限制（11 行）
code-review-context：模型可见上下文规则，10K tokens 上限（13 行）
code-review-testing：测试编写指导，集成测试优先（15 行）
code-review-breaking-changes：外部集成表面 breaking changes 检查（13 行）

中等技能（20-80 行）

code-review：代码评审 orchestrator，调用所有 code-review-* subagent（15 行）
codex-pr-body：PR body 更新规范，含 Sapling stacked PRs 处理（60 行）
codex-bug：GitHub bug 报告诊断与分类（49 行）

复杂技能（> 80 行）

codex-issue-digest：GitHub issue 汇总，含注意力标记和反应处理（103 行）
babysit-pr：PR 持续监控，含 CI 分类、review 反馈处理、轮询策略（184 行）

格式特征：description 是唯一的触发机制，但写法差异巨大

所有 SKILL.md 都遵循统一的 frontmatter 结构，但 description 的写法揭示了一个关键洞察：description 的长度决定了 skill 被触发的精准度。

极简 description（2-10 词）

yaml 复制代码

name: code-breaking-changes
description: Breaking changes

yaml 复制代码

name: code-review-change-size
description: Change size guidance (800 lines)

这类 description 像关键词标签，依赖 orchestrator（code-review）显式调用。它们自己不承担"判断是否触发"的职责。

中等 description（10-30 词）

yaml 复制代码

name: test-tui
description: Guide for testing Codex TUI interactively

yaml 复制代码

name: codex-pr-body
description: Update the title and body of one or more pull requests.

这类 description 包含明确的动作动词（"Guide"、"Update"）和对象（"Codex TUI"、"pull requests"），让模型在对应场景下有较高的触发概率。

超长 description（> 50 词）

yaml 复制代码

name: babysit-pr
description: Babysit a GitHub pull request after creation by continuously polling review comments, CI checks/workflow runs, and mergeability state until the PR is merged/closed or user help is required. Diagnose failures, retry likely flaky failures up to 3 times, auto-fix/push branch-related issues when appropriate, and keep watching open PRs so fresh review feedback is surfaced promptly. Use when the user asks Codex to monitor a PR, watch CI, handle review comments, or keep an eye on failures and feedback on an open PR.

这个 description 本身就是一份微型需求文档：定义了输入（PR）、行为（polling、diagnose、retry、auto-fix）、终止条件（merged/closed/user help）、使用场景（"Use when..."）。它把"触发条件"直接编码进了 description，因为 babysit-pr 没有 orchestrator 代劳，必须自己判断何时该被激活。

典型案例一：babysit-pr------复杂 skill 的参考模板

babysit-pr 的 SKILL.md 长达 184 行，但它的结构非常清晰，可以作为复杂 skill 的参考模板：

sql 复制代码

Objective（目标与终止条件）
Inputs（输入格式）
Core Workflow（步骤化工作流，15 步）
Commands（脚本命令示例）
CI Failure Classification（失败分类规则）
Review Comment Handling（评论处理策略）
Git Safety Rules（安全约束）
Monitoring Loop Pattern（轮询模式）
Polling Cadence（频率策略）
Stop Conditions（严格停止条件）
Output Expectations（输出规范）
References（引用外部文档）

值得注意的是，babysit-pr 将决策逻辑外置 到了 references/heuristics.md：

CI 分类 checklist（branch-related vs flaky/unrelated）
决策树（fix vs rerun vs stop）
Review comment 处理 criteria
Stop-and-ask conditions

这保持了 SKILL.md 本身的叙事流畅性，同时把需要频繁迭代的规则单独存放。

此外，babysit-pr 有 scripts/gh_pr_watch.py（26KB）和 scripts/test_gh_pr_watch.py（4KB），说明复杂 skill 的 Executable 部分远大于 Readable 部分------SKILL.md 是"指挥手册"，scripts 是"执行部队"。

典型案例二：code-review------subagent 编排的实践样本

code-review 本身只有 15 行，但它展示了一个重要的编排模式：

markdown 复制代码

Use subagents to review code using all code-review-* skills in this repository other than this orchestrator. One subagent per skill. Pass full skill path to subagents. Use xhigh reasoning.

这个 orchestrator 不自己做评审，而是并行 spawn 4 个 subagent ，每个加载一个 code-review-* skill 的 body：

code-review-breaking-changes：检查 API/CLI/配置的 breaking changes
code-review-change-size：检查变更是否超过 800 行
code-review-context：检查上下文注入是否违反 10K tokens 上限
code-review-testing：检查是否添加了集成测试

每个子 skill 都极简（11-15 行），因为它们的职责单一。这种"orchestrator + 专一 subagent"的模式，比写一个巨型全能 prompt 更容易维护和复用。

典型案例三：简单 skill 的共同模式

简单技能虽然内容不同，但结构高度一致：

frontmatter：name + description（description 包含动作+对象）
核心约束 1-3 条：用 bullet 或编号列出不可违背的规则
可选的例外说明："If unit tests are needed..."、"Unless the change is mechanical..."

例如 code-review-testing：

markdown 复制代码

For agent changes prefer integration tests over unit tests.
Features that change the agent logic MUST add an integration test.
If unit tests are needed, put them in a dedicated test file.

三条规则，一层递进：优先集成测试 → 必须添加 → 单元测试的例外处理。这种"原则→强制→例外"的三段式结构，值得在写 skill 时模仿。

可借鉴点 vs 独立思路

维度	Codex 实践	可借鉴性	说明
description 长度梯度	极简（标签）/ 中等（动作+对象）/ 超长（自包含需求）	高	根据 skill 是否有 orchestrator 决定 description 的写法
references/ 外置决策逻辑	babysit-pr 的 heuristics.md	高	把频繁迭代的规则从 SKILL.md 分离
scripts/ 可执行辅助	gh_pr_watch.py、collect_issue_digest.py	高	复杂工作流需要脚本支撑，SKILL.md 只负责编排
subagent 编排模式	code-review orchestrator + 4 个维度 subagent	高	多维度任务拆分为专一 skill，用 orchestrator 并行调用
隐式调用	通过 scripts/ 目录位置或 `cat SKILL.md` 自动触发	中	需要 AI 工具底层支持，不是纯 skill 设计问题
热重载	SkillsWatcher 10 秒节流	中	需要文件系统监听和运行时重载能力
元技能	skill-creator 本身是一个 skill	低	Codex 特有的工程决策，其他项目未必需要
2% 上下文预算	skill metadata 占用 2% 或 8000 字符	低	Codex 特有的资源治理策略，小型项目不需要

核心借鉴：写 skill 的三条原则

从 12 个真实案例中可以提炼出三条普适原则：

description 决定触发：如果你希望 skill 被隐式调用，description 必须包含"Use when..."的场景描述；如果只是被 orchestrator 显式调用，description 可以极简。
单一职责：一个 skill 只做一件事。code-review 被拆成 4 个子 skill 而不是一个巨型 prompt，正是因为"每个维度可以独立迭代"。
SKILL.md 是手册，scripts 是执行：当工作流超过 10 步或需要外部 API 调用时，把逻辑写成脚本，SKILL.md 只描述"何时调用、传什么参数、期望什么输出"。

Skill 系统的整体架构

在深入每个设计决策之前，先看一张整体架构图：

sql 复制代码

用户输入 / Agent 执行命令
       |
       v
+----------------------------------+
|  Skill 加载与去重               |
|  - loader.rs: 扫描 4 个作用域    |
|  - 去重: Repo > User > System    |
+----------------------------------+
       |
       v
+----------------------------------+
|  上下文预算管理                 |
|  - render.rs: 2% 窗口上限       |
|  - 超出预算 → 截断/省略         |
+----------------------------------+
       |
       v
+----------------------------------+
|  触发机制                       |
|  - 显式: $skill-name            |
|  - 隐式: 脚本运行 / 文档读取    |
+----------------------------------+
       |
       v
+----------------------------------+
|  执行与编排                     |
|  - 渐进式披露加载 body          |
|  - 子 Agent 并行编排            |
|  - AGENTS.md 行为准则叠加       |
+----------------------------------+
       |
       v
+----------------------------------+
|  开发体验                       |
|  - SkillsWatcher 热重载         |
|  - skill-creator 元技能         |
+----------------------------------+

这个架构的核心思想是：上下文窗口是公共资源，需要被治理。从加载到触发到执行，每个环节都有明确的预算和策略。

设计决策一：上下文治理------渐进式披露、预算管理与双重优先级

Codex 团队把上下文窗口当作公共资源来管理。skill 系统实现了三层渐进式披露：

层级	内容	大小	加载时机
Metadata	name + description + path	~100 词	始终
Body	完整工作流指令	< 5K 词	触发后
Resources	scripts / references / assets	无上限	按需

这种设计的底层逻辑是：上下文窗口是有限的，而 skill 的数量可能会无限增长。如果不加控制，100 个 skill 的完整指令可能会占满整个上下文窗口。

但渐进式披露只解决了"要不要加载"，还没有解决"加载多少"。Codex 在 codex-rs/core-skills/src/render.rs 中实现了一个精密的预算管理系统：

预算上限 ：skill metadata 占用上下文窗口的 2%，或 8000 字符（取较小值）
超出预算时的降级策略 ：先尝试截断 description （round-robin 字符分配），如果仍超出则直接省略整个 skill

系统会发出显式警告，并记录遥测指标（THREAD_SKILLS_TRUNCATED_METRIC）。Codex 团队在测量和监控 skill 系统对上下文窗口的消耗。

双重优先级体系则解决了"多个作用域的 skill 如何共存"的问题：

去重时 ：Repo > User > System > Admin（本地定制覆盖默认值）
Prompt 排序时 ：System > Admin > Repo > User（基础默认行为优先展示）

这个设计同时满足两个看似矛盾的需求，很少有系统能优雅地处理这一点。

设计决策二：触发与执行------隐式调用与子 Agent 编排

用户可以通过 $skill-name 显式触发 skill，但 Codex 还实现了一种更聪明的机制：隐式调用。

当 agent 执行命令时，系统自动检测该命令是否"属于"某个 skill：

脚本运行检测 ：如果命令是 python scripts/foo.py，系统会检查该脚本是否位于某个 skill 的 scripts/ 目录下
文档读取检测 ：如果命令是 cat SKILL.md，同样自动触发

为什么需要这个设计？因为用户不会每次都记得打 $skill-name。当 agent 自己决定运行某个辅助脚本时，它应该自动获得运行该脚本所需的上下文知识。

子 Agent 编排 则是另一个执行层面的创新。code-review skill 不是单条 prompt，而是分布式执行架构：

父 agent 识别出需要 code review
Spawning 多个 subagent，每个负责一个维度（breaking changes、change size、context、testing）
Subagent 并行执行，独立上下文，最后汇总去重

这不是"写一个好 prompt"，而是把 skill 的执行从单线程变成并行计算。

设计决策三：生态与体验------AGENTS.md 互补、热重载与元技能

Codex 团队区分了两种 AI 指导文件：

Skill：回答"能做什么"（task-specific capabilities）
AGENTS.md：回答"在这个代码库里该怎么表现"（project-wide conventions）

AGENTS.md 的搜索是层级式的：从项目根目录到当前工作目录，深层覆盖高层。这和 skill 的作用域体系形成了互补------Skill 告诉你"怎么 review 代码"，AGENTS.md 告诉你"在这个仓库里，TUI 代码要用 ratatui 的什么 API 风格"。

热重载让 skill 开发体验接近代码开发：

yaml 复制代码

文件系统事件（notify crate）
       |
       v
ThrottledWatchReceiver（10秒节流）
       |
       v
SkillsWatcherEvent::SkillsChanged
       |
       v
订阅者重新加载 changed skills（无需重启 agent）

修改 SKILL.md 后 10 秒内自动生效------如果 skill 是代码，就应该像代码一样支持热重载。

元技能（skill-creator） 则把"创建 skill"这件事本身标准化为 6 步流程：

理解用例
规划资源
初始化（init_skill.py 自动生成模板）
编辑（SKILL.md 控制在 500 行以内）
验证（quick_validate.py）
forward-testing（用 subagent 假装真实用户测试------子 agent 不知道自己在测试，以此验证 skill 的通用性）

为什么不做自动 skill 生成？ skill-creator 的回答是：上下文窗口是公共资源，自动生成的 skill 很难写出精准的 description（唯一触发机制）。只有人类能判断"这段信息 Codex 是不是真的需要"。

这是一个反直觉的洞察：Codex 不追求"AI 自动生成一切"，而是把"人工创建的体验"做到极致。

元技能：人工驱动，但流程极致标准化

Codex 没有做自动 skill 生成。它不会分析聊天记录，发现"你经常做这件事"，然后自动生成一个 skill。相反，它把"创建 skill"这件事本身编码成了一个 skill：skill-creator。

skill-creator 提供了一套 6 步标准化流程：

理解用例：用具体例子确认触发场景
规划资源：分析哪些放 script、哪些放 reference、哪些放 asset
初始化 ：init_skill.py 自动生成模板目录 + frontmatter + agents/openai.yaml
编辑：遵循"Concise is Key"，SKILL.md 控制在 500 行以内
验证：quick_validate.py 检查格式和命名规则
迭代：forward-testing（用 subagent 假装真实用户测试，子 agent 不知道自己在测试）

为什么不做自动化？ skill-creator 的文档已经回答：上下文窗口是公共资源，自动生成的 skill 很难写出精准的 description（这是唯一触发机制）。只有人类能判断"这段信息 Codex 是不是真的需要"。

这是一个反直觉的洞察：Codex 不追求"AI 自动生成一切"，而是把"人工创建的体验"做到极致。这和很多 AI 产品的思路相反。

可学习点

一个工程的开始，从先写 3-5 个最常用的 skill
定义渐进式披露：frontmatter 放触发词，body 放详细步骤，scripts 放可执行辅助
当发现某个指令被反复使用时，不要靠记忆，靠 skill 创建流程固化它
上下文窗口是公共资源：如果你的 AI 应用支持多个 skill，必须有预算管理和降级策略
关键判断标准：不是"这个任务很重要"，而是**"这个任务被反复执行且存在共享需求"**