Skills 技能：
把反复交代的流程写下来

什么时候值得做成技能

官方给了一条好记的经验：同一段提示词你老在复制，或者同一套流程你老在纠正，它大概就该变成一个技能。官方举的常见例子有：排查日志、写发布说明、按清单审 PR、规划迁移、汇总监控或事故、固定的调试流程。

在 order-admin 里，"新增一个 API 接口"就是这样的活：每次都是建路由、加类型、补两条测试、跑 npm test。这一课把它做成技能 add-api-endpoint，放进仓库，全组共用。

在哪些地方能用

示例内容是为 order-admin 编的；文件夹结构和每一项的用途与官方文档一致。

必填的只有两样：name 是技能的名字；description 写它做什么、什么时候用，Codex 靠这一行判断什么时候该用它（第 4、7 节）。建议文件夹名和 name 写成一样，省得混。

试一试：换一个起点

Codex 从"当前工作目录"往上一层层找 .agents/skills，直到仓库根，不往下找。这个起点在哪：

• 在 App 里，是项目的主文件夹。项目菜单里点 Edit project，指向一个文件夹选 Make primary，就换了主文件夹；新对话都从它开始找。项目里附加的其他文件夹（次要文件夹）能读能改，但里面的技能不会被自动发现。
• 在命令行里，是你运行 codex 的那个目录。

假设同事在 src/api/ 里也放了一个只管接口评审的 api-review，切换起点看看（App 里是换主文件夹，命令行里是换启动目录）：

触发模拟器

order-admin 里装了 3 个技能。对 Codex 说一句话，看它会不会用、用哪个。再把某个技能的"允许自动触发"关掉，试试同一句话。

模拟器用关键词比对来示意。真实的 Codex 是模型读 description 后自己判断的，没有固定的关键词表，所以 description 要写得清楚、具体。

禁止自动触发

在技能文件夹里加一个 agents/openai.yaml，写上：

policy:
  allow_implicit_invocation: false

这个开关默认是 true。改成 false 后，Codex 不会再根据你的话自动选它，但 $commit 点名照样能用。它只管"自动"，不是停用（真要停用见第 9 节）。

装得越多，清单越挤

第 1 层那份初始清单有预算：最多占模型上下文窗口的 2%；不知道窗口多大时，按 8,000 个字符算。超了，Codex 先把描述截短；还放不下，就会有些技能进不了清单，同时给出警告。拖动滑块看看。

数量阈值是示意：真实能放多少个，取决于模型的上下文窗口和各个描述的长短。

画面为教学示意：Codex 说的话、文件内容和测试数量是虚构的；技能放在哪、怎么触发、.agents 受保护这些规则与官方文档一致。

官方的写法要点

1. 说清做什么、什么时候用，也说清什么时候不用。官方模板里 description 的占位文字就是"写清楚这个技能什么时候该触发、什么时候不该"。
2. 放进用户真会说的话。你们平时说"加个接口"，就把"加个接口"写进去。
3. 关键用途和触发词放最前面。技能多了描述会被截短（第 5 节）。
4. 一个技能只做一件事。先从 2 到 3 个具体用例开始，别一上来就想覆盖所有边角情况。
5. 拿真实的提示词测一测。对着 description 试几句你平时会说的话，看它该用时用没用、不该用时有没有乱用。

它们常常一起用：技能里可以写明"用哪个 MCP 工具"；把技能和 MCP 打包在一起就是插件。另外官方有一句好记的话：技能定方法，定时任务定时间（定时任务在第 13 课）。

agents/openai.yaml 全貌

这个文件可选，管三件事：在 App 里怎么显示、能不能自动触发、依赖哪些工具。

interface:
  display_name: "新增 API 接口"
  short_description: "路由、类型、测试一次加齐"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "用 add-api-endpoint 新增一个接口"

policy:
  allow_implicit_invocation: true

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

技能依赖 MCP 时，缺的服务器 Codex 会提示你安装。这个行为由功能开关 features.skill_mcp_dependency_install 控制，已经稳定、默认开着。MCP 本身第 9 课讲。

停用一个技能，但不删它

在 ~/.codex/config.toml 里加一段（config.toml 第 7 课讲），改完重启 Codex：

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

官方示例里 path 写的是 SKILL.md 的路径；配置参考表把它描述成"技能文件夹的路径"。两处说法不同，先照示例写，不生效再改成文件夹路径试试。App 的 Skills 页面里能不能直接开关，以你的 App 为准。

调大或调小初始清单的预算

[skills]
max_context_tokens = 2000

默认是上下文窗口的 2%；自己写的值必须是正整数，最多 10000 个 token。一般不用改，技能太多、清单总被截短时再考虑。

装别人写好的技能

想在自己电脑上加几个官方精选的技能，用内置的 $skill-installer，比如 $skill-installer linear 会装上 $linear 技能；也可以让它从别的仓库下载。装完 Codex 会自动发现，没出现就重启。官方的定位是：这适合自己试用；要把自己的技能分发给别人，优先做成插件。

技能里的脚本也在审批范围里

官方的审批配置里专门列了一类"技能脚本审批"（skill_approval），和沙箱审批、MCP 审批并列。也就是说，技能里的脚本同样可能停下来请你批准。想让某一类提示自动拒绝、其余照常问你，可以用 approval_policy 的 granular 写法，比如 approval_policy = { granular = { skill_approval = false, … } }，false 表示这一类提示直接拒绝（完整示例见官方 Agent approvals & security 页；config.toml 怎么写见第 7 课）。

团队和企业：三条分发路径

三条路互相独立：把技能从一条路挪到另一条，不会带走所有者、共享、角色、安装状态或连接器授权。

常见问题