Skills 深度解析：什么时候该把 Codex 工作流沉淀为可复用能力
TL;DR
Skill 是 Codex 的可复用工作流单元，不是更长的提示词收藏夹。官方文档把 Skill 定义为一个包含 SKILL.md 的目录，目录里可以放脚本、参考资料、模板资产，以及面向 Codex app 的 agents/openai.yaml 元数据。Codex 在初始上下文里先看到技能名、描述和路径，只有判断某个技能适合当前任务时才读取完整说明；官方还给初始技能列表设置了上下文预算：最多使用模型上下文窗口的 2%，未知窗口时最多 8000 个字符。这个设计说明 Skill 的价值不是“塞更多背景”，而是把稳定、重复、边界清楚的工程流程做成按需加载的操作手册。
一句话判断：如果某个 Codex 用法已经被同一团队重复执行多次、输入输出可描述、失败原因可分类、需要携带模板或脚本，并且不应该常驻每次会话上下文，那它适合做成 Skill。反过来，一次性探索、项目常规约束、权限策略、团队价值观、需要实时授权的数据连接，都不该被硬塞进 Skill。
读者定位
本文面向已经在真实代码库里使用 Codex 的中高级开发者、技术负责人、研发效能团队和平台工程师。你应该已经理解 AGENTS.md、Codex CLI 或 app 的基本交互方式，也知道一次 Codex 任务会受到上下文、工具权限、沙箱、网络和审批策略影响。本文不讲“如何写一个漂亮提示词”，而讲团队怎样把个人经验沉淀为可复用资产，同时避免把工作流资产做成维护负担。
如果你的团队还处在“大家随便试试 Codex”的阶段，先不要急着建 Skill 库。先用普通 prompt 把高频场景跑通，记录成功案例、失败案例和必要命令。等流程开始稳定，再考虑抽取 Skill。过早封装会把还没想清楚的判断固定下来，后续每一次调整都要付治理成本。
问题：Prompt、AGENTS.md 和 Skill 的边界为什么容易混
团队使用 Codex 一段时间后，最常见的痛点不是“不会写 prompt”，而是重复经验散落在不同人的聊天记录、仓库说明和临时脚本里。一个资深工程师会在 PR review 前要求 Codex 先看 diff、再看迁移文件、最后按安全、兼容、测试缺口排序；另一个工程师会在发布前让 Codex 检查配置变更、CI 状态、回滚方案和文档更新。两套流程都有效，但如果每次都复制一大段 prompt，团队无法版本化，也无法让新人稳定复用。
把这些内容放进 AGENTS.md 也不总合适。AGENTS.md 是仓库级或目录级的常驻指导，适合放项目结构、构建命令、测试要求、代码风格、安全边界和提交约定。它会在对应范围内持续影响 Codex 的工作方式。如果把“发版检查步骤”“安全 review rubric”“季度依赖巡检模板”全写进 AGENTS.md，每个普通 bug 修复任务都会背着一堆无关流程，主上下文会变重，模型也更容易被不相关规则干扰。
Skill 解决的是第三类问题：某个流程不是所有任务都需要，但一旦触发，就需要稳定的步骤、参考资料、脚本和输出格式。它位于“临时 prompt”和“常驻仓库规则”之间。用得好，Skill 会让团队把成熟工作流复用起来；用得差，它会变成一堆模糊触发的长文档，让 Codex 频繁加载错误上下文。
心智模型：Skill 是按需加载的工程操作手册
可以把 Codex 的上下文表面分成五层。
第一层是当前 prompt。它处理一次性目标、限制、临时输入和本轮验收标准。它应该短、具体、贴近当前任务。
第二层是 AGENTS.md。它处理仓库长期规则。官方 AGENTS.md 指南强调，Codex 会查找并合并适用范围内的指导文件，离目标文件更近的指导会覆盖或细化上层规则。这里适合写“本仓库总是怎样构建、测试、命名、提交、处理安全边界”。
第三层是 Skill。它处理可复用但不常驻的任务流程。官方 Skills 文档说明，Skill 使用渐进披露：Codex 先拿到名字、描述和路径，选中后才读取完整 SKILL.md。这意味着 Skill 正文可以比普通 prompt 长，也可以引用参考文件，但触发描述必须足够精确。
第四层是 MCP、连接器、浏览器、shell、计算机控制等工具。它们提供动作和数据入口。Skill 可以告诉 Codex 在某个流程里怎样使用这些工具，但不应该替代工具权限设计。
第五层是 Automation、SDK、GitHub Action 等运行入口。它们决定什么时候运行、在哪个环境运行、如何把结果送回系统。Skill 可以被这些入口显式调用，但 Skill 本身不是调度器。
这个分层能帮你避免两个误判。第一个误判是把 Skill 当成“更高级的 AGENTS.md”。Skill 不应该承载全局规则，否则会重复、冲突，并且触发成本高。第二个误判是把 Skill 当成“自动化脚本”。Skill 定义的是工作流知识；自动化定义的是触发时机和运行环境。一个发布检查 Skill 可以先由人手动调用，等结果稳定后再放进 Codex app Automations 或 codex exec 管道。
官方机制：Codex 怎样发现和使用 Skills
截至 2026-06-22，官方 Skills 文档给出的关键机制有几条。第一，Skill 是一个目录，最小要求是 SKILL.md，该文件必须包含 name 和 description。目录可选包含 scripts/、references/、assets/ 和 agents/openai.yaml。第二，Skills 可在 Codex CLI、IDE extension 和 Codex app 中使用。第三，Codex 会在初始上下文里加入可用技能列表，但这个列表有预算限制；当技能很多时，Codex 会先缩短描述，仍然过长时可能省略部分技能并显示警告。第四，选中某个技能后，Codex 仍会读取完整 SKILL.md，所以完整执行步骤不必塞进描述。
这些机制会直接影响 Skill 设计。name 应该短、稳定、可被用户显式调用。description 是路由入口，不是宣传语。它要写清使用条件、排除条件和交付物。SKILL.md 正文要像操作手册，告诉 Codex 在什么顺序下读什么、跑什么、检查什么、输出什么。references/ 放长规则、rubric、领域背景；scripts/ 放确定性动作；assets/ 放模板和素材；agents/openai.yaml 放 app 里的展示元数据、调用策略和工具依赖。
官方文档还提到可以用 $skill-installer 安装 curated skills；本地实验可以这样做，但如果你要把团队技能分发给多人，官方建议优先用 plugin 作为安装分发单元。换句话说，Skill 是作者格式，plugin 更像分发包。团队内部早期可以直接维护 Skill 目录；跨团队、跨机器、带依赖分发时，再考虑插件化。
什么时候应该创建 Skill
第一个判断标准是重复性。流程至少被人工跑过三次，且每次的步骤和输出高度相似。一次成功不代表流程稳定；第一次往往还在探索真实边界。比如“为这个新服务设计缓存策略”不适合立刻做 Skill，因为问题开放；“检查 Node 服务发布前配置、环境变量、迁移和回滚文档”更适合，因为动作重复。
第二个判断标准是触发边界。你能写出“何时使用”和“何时不要使用”。例如“Use when reviewing a pull request for correctness, security, tests, and compatibility. Do not use for general code explanation.” 这样的描述可路由；“Improve code quality” 不可路由。边界越模糊，误触发越多。
第三个判断标准是证据链。Skill 运行后应该产生可检查输出，而不是“感觉更好”。PR review Skill 应输出按严重程度排序的 findings，并引用文件和原因；依赖巡检 Skill 应输出受影响包、风险来源、建议动作和无法确认项；文档发布 Skill 应输出链接检查、目录一致性、截图需求和人工复核点。
第四个判断标准是资源需求。流程需要随身携带 rubric、模板、示例、脚本、检查清单或领域资料时，Skill 比 prompt 更适合。否则你可能只是需要一个 prompt snippet。
第五个判断标准是上下文稀疏性。流程只在特定场景有用，不应该污染所有任务。安全审计、发布检查、PR triage、合规文档写作、特定框架迁移、内部平台排障，都属于这种类型。
第六个判断标准是维护责任。Skill 一旦进入团队库，就需要有人 review、更新、废弃。没有维护人的 Skill 会慢慢失真，尤其是依赖脚本、工具、内部路径和外部服务时。
真实工作流案例：把发布前检查沉淀成 Skill
假设一个后端团队每周发布两次服务。资深工程师通常会让 Codex 做四件事：读取本次 diff，找出配置和数据库变更；检查迁移是否有回滚策略；确认测试、CI 和文档是否覆盖关键路径；输出发布风险摘要。这个流程一开始可以用普通 prompt：
请检查当前分支的发布风险。先读 diff，再检查 migrations、config、docs 和 CI 配置。输出阻塞项、非阻塞风险、需要人工确认的问题和建议发布顺序。
跑过几次后，你会发现稳定部分很多：读取范围、风险分类、输出格式、回滚检查、环境变量检查、测试命令。于是可以创建 release-readiness/ Skill：
release-readiness/
SKILL.md
references/
risk-rubric.md
rollout-checklist.md
scripts/
collect-release-diff.sh
assets/
release-report-template.md
SKILL.md 的 frontmatter 可以写：
---
name: release-readiness
description: Use when checking a branch or pull request before release for config changes, migrations, rollback, tests, and docs. Do not use for general code review or feature planning.
---
正文再规定步骤：先确认目标分支和发布范围；读取 diff、迁移、配置和部署文件；必要时运行只读检查脚本；按阻塞项、可接受风险、人工确认项输出；如果权限不足或脚本失败，保留失败原因并改用手工文件检查。这样做的好处是，新人不需要记住资深工程师的完整 prompt；Codex 也不会在普通 bug 修复任务中加载发布检查 rubric。
等这个 Skill 稳定后，可以把它放进 Automation：每周发布日前一天自动检查候选分支，把发现送到 Triage。这里 Skill 定义“怎么查”，Automation 定义“什么时候查、在哪个 worktree 查、结果去哪”。两者分开，后续调试会清楚很多。
操作清单：从个人流程到团队 Skill
- 记录三次真实执行。保留原始 prompt、输入范围、运行命令、失败原因和最终输出。
- 抽取稳定步骤。把每次都一样的动作写进 Skill，把仍需人工判断的部分写成“确认点”，不要伪装成确定流程。
- 写
description。用真实用户说法触发，例如“review PR”“check release risk”“triage failing CI”，并加入排除条件。 - 拆分资源。执行主线放
SKILL.md，长规则放references/，确定性动作放scripts/，报告模板放assets/。 - 设计失败路径。写清脚本不存在、权限不足、网络不可用、仓库状态异常时怎样降级。
- 建最小评测集。至少准备 5 个应该触发的请求和 5 个不应该触发的请求，记录路由结果。
- 找维护人。每个团队 Skill 都要有人负责版本更新、废弃和迁移。
- 再考虑自动化。只有手动调用稳定后，才把 Skill 放进 Automation、SDK 或 CI。
权衡与风险
Skill 会降低重复描述成本，但会增加治理成本。团队 Skill 多到一定程度后，命名、触发描述、版本兼容、依赖安装和废弃策略都会变成问题。官方的初始技能列表有上下文预算限制，技能过多时可能有描述被缩短或技能被省略；这不是理论问题，而是团队技能库膨胀后的真实约束。
Skill 也会制造“流程幻觉”。文档写得很完整，不代表流程在当前仓库、当前权限、当前工具版本下可运行。尤其是脚本类 Skill，必须写清输入、输出、依赖和失败码。不要让 Codex 猜测脚本会做什么。
安全上，Skill 不应该绕过沙箱和审批。一个 Skill 可以说明“需要读取 GitHub PR”“需要运行测试”“需要调用 MCP”，但真正的授权仍由 Codex 的工具、连接器、审批策略和运行环境控制。团队不应把“这个 Skill 是安全的”当成开放高权限的理由。
组织上，Skill 会把个人经验变成团队资产，也会暴露流程分歧。不同资深工程师对 review 严重程度、发布门禁、测试覆盖的理解可能不同。把 Skill 合并进团队库前，最好先让相关 owner review rubric，而不是由某个人把自己的习惯直接写成全队规则。
常见误区
误区一：把第一次成功的 prompt 直接做成 Skill。正确做法是先跑多次，确认稳定步骤和可变输入。
误区二：description 写得像愿景。Codex 需要路由条件，不需要口号。描述要贴近用户会说的话。
误区三：把所有背景都塞进 SKILL.md。这样会让选中后的上下文变重。长背景应放在 references/，并在正文里写明何时读取。
误区四：把 Skill 当权限边界。权限由沙箱、审批、连接器和工具配置控制。Skill 只能说明工作流，不是安全机制。
误区五：没有反例评测。只测“应该触发”的请求，会让 Skill 变成到处误触发的通用大网。
误区六：创建后无人维护。路径、命令、模型、官方能力和团队流程都会变化。Skill 需要像代码一样 review。
团队治理细节：Skill 库要像轻量产品一样维护
当团队只有一两个 Skill 时，维护通常靠作者自觉；当数量到十几个，治理就会成为实际问题。一个健康的 Skill 库至少需要四类元信息：负责人、适用仓库、最近验证日期、废弃条件。负责人不是名义 owner，而是当脚本失败、官方能力变化、团队流程变更时能做决定的人。适用仓库能避免一个为后端服务写的 Skill 被文档仓库误用。最近验证日期提醒团队哪些 Skill 已经长时间没在真实任务里跑过。废弃条件说明什么时候应该删掉或合并，而不是让旧流程长期存在。
命名也要治理。建议团队按“领域-动作”命名，而不是按作者或抽象目标命名。release-readiness、ci-failure-triage、docs-link-audit 比 alice-helper、quality-master、general-review 更容易理解。名字不宜频繁变更，因为用户、Automation 和文档可能显式引用 $skill-name。如果职责发生根本变化，新建 Skill 往往比改旧名字更稳。
版本记录要关注行为变化，而不是只写“更新说明”。例如“收窄 description，避免解释代码时误触发 PR review”“把回滚检查移动到 references，减少默认上下文”“脚本失败时改为手工 diff 检查”。这些记录能帮助后续排查：某个误触发是不是由 description 改动引入，某个执行失败是不是由脚本路径调整造成。
团队还要设置入口规则。个人 Skill 可以放在个人目录，团队共享 Skill 必须经过 review。review 不需要很重，但至少看四件事：触发边界是否清楚，是否有反例，是否声明权限和脚本副作用，是否有 owner。没有这些信息的 Skill 不应进入共享库，因为它会影响其他人的 Codex 行为。
Skill 的废弃同样重要。一个过期 Skill 比没有 Skill 更危险，因为它给人一种流程仍有效的错觉。废弃可以分三步：先在 description 或正文开头标注 deprecated，并指向替代 Skill；再从团队默认安装或可见列表中移除；最后删除目录。对已经被 Automation 或 SDK 调用的 Skill，删除前要先搜索引用，避免后台任务静默失败。
设计判断：哪些内容留在 Skill 外
很多团队在写 Skill 时会把“相关内容”全部带上，但相关不等于适合。下面这些内容通常应留在 Skill 外。
第一，仓库全局规则。构建命令、测试命令、目录约定、提交格式、安全禁区，属于 AGENTS.md 或仓库文档。Skill 可以引用这些规则，但不应复制一份。复制会造成规则分叉：仓库命令改了，Skill 里的旧命令还在。
第二，实时事实。当前负责人、当前发布窗口、今天失败的 CI、某个 PR 的状态，应来自用户输入、工具或授权系统。Skill 只定义怎样查询和怎样判断，不应写死事实。
第三，敏感凭据和私有地址。Skill 不能保存 token、密钥、内部临时链接、生产账号。需要访问外部系统时，用 MCP、连接器、环境配置或平台授权完成，并在 Skill 中说明依赖和失败处理。
第四，开放式决策。架构取舍、组织优先级、产品方向不适合被一个 Skill 固化。Skill 可以提供评审框架，但最终决策应回到负责人和现有流程。
第五，模型价格和账户权益。模型可用性、价格、套餐和功能成熟度变化很快，文章和 Skill 中应引用官方文档或团队当前配置，而不是写死长期承诺。
这个“留在外面”的清单能帮助 Skill 保持窄而可靠。一个 Skill 越像“在特定场景执行一套流程”，越容易维护；越像“把所有背景都塞给 Codex”，越容易变成上下文负担。
采用节奏：先让一个 Skill 变好，再扩展数量
团队很容易在第一次尝到复用收益后快速创建大量 Skill。更稳的节奏是先把一个高频 Skill 打磨到可依赖，再复制方法。比如先做 ci-failure-triage：收集真实请求，写 description，跑正反例，处理脚本失败，观察一周输出是否被开发者采纳。等这套流程跑通，再做 PR review、发布检查和依赖巡检。
衡量一个 Skill 是否“变好”，不要只看触发次数。要看它是否减少了重复解释，是否让新人也能得到接近资深工程师的检查顺序，是否能诚实报告无法验证项，是否在失败时给出可接手路径。如果用户每次还要补充大量背景，说明 Skill 没把稳定信息沉淀好；如果用户经常要纠正它“不该用这个流程”，说明 description 需要收窄。
Skill 数量扩展也要控制粒度。两个流程如果输入、步骤和输出高度相似，可以合并成一个 Skill，并在正文里按场景分支；两个流程如果触发词相似但产出不同，应拆开并写清排除条件。不要为了每个小习惯创建 Skill，也不要把所有工作流做成一个“万能工程助手”。前者会让技能库膨胀，后者会让路由失效。
最后，团队要允许 Skill 退出。某个 Skill 三个月没人用、owner 离开、脚本长期失败、官方能力变化后不再需要，都应进入废弃流程。复用资产只有在被维护时才是资产，没人维护时就是隐藏风险。
一个实用信号是“用户是否愿意显式调用”。如果团队成员开始主动在任务里写 $ci-failure-triage 或 $release-readiness，说明这个 Skill 的边界和价值已经被理解。如果大家总是绕开它，宁愿复制旧 prompt，说明它要么触发不准，要么输出不够可信，要么流程和真实工作不贴合。采用数据要和访谈结合，不能只看文件是否存在。
另一个信号是“新成员是否能用”。如果只有作者本人能得到好结果，Skill 仍然只是个人习惯的包装；如果新人也能按相同入口得到可检查输出，它才真正变成团队资产。
这条标准能防止团队把个人经验误当作组织能力。
延伸阅读
GitHub 原文：31-skills-introduction.md