19. Skills技能系统

本节目标：理解 Skill 是什么、它怎么省上下文、两种触发方式、技能放哪、怎么创建和安装、怎么禁用。

Skill 是什么

你跟 Codex 干活，总有几套流程是反复交代的。比如每次让它提交代码，你都要叮嘱「先跑测试、commit 信息用中文、前缀按 feat: / fix: 来」。这种「说明书级别」的重复，就是 Skill 该接管的。

Skill 就是把一套固定步骤打包成 Codex 的「专项本事」。你把步骤写进 SKILL.md，以后这套流程就成了 Codex 随手能调的一个动作。

Skill 和斜杠命令的区别：斜杠命令是你主动喊才动；Skill 可以不喊—Codex 看你这活儿对得上某个 Skill 的描述，自己就把它调出来了。

Note

Skill 是「编写格式」，Plugin 是「分发格式」。先用 Skill 把工作流设计好，要给别人装时再打包成 Plugin。ChatGPT 桌面 App、Codex CLI 和 IDE 扩展都支持技能。

技能目录结构

一个 Skill 就是一个目录，里面至少要有 SKILL.md，还可以按需添加脚本和参考资料：

my-skill/
├── SKILL.md          # 必需：指令与元数据
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：文档参考
├── assets/           # 可选：模板与资源
└── agents/
    └── openai.yaml   # 可选：展示信息与依赖声明

SKILL.md 是核心，包含 YAML frontmatter（前置元数据）和正文指令：

---
name: skill-name
description: 说明这个技能该在什么时候触发、什么时候不触发。
---

供 Codex 遵循的技能指令写在这里。

frontmatter 必须有 name 和 description 两个字段。name 是技能的名字（也是你用 $ 喊它时的名字），description 告诉 Codex 这个技能干啥的、啥时候该用。下面的正文是 Codex 真正调用时照着做的步骤说明。

Warning

官方没有 trigger 这个字段，触发靠的是 description 的语义匹配。有些老教程写了 trigger 字段，别被带歪了。

渐进式披露：省上下文的秘密

Skill 凭什么能装一大堆却不撑爆上下文？答案就是渐进式披露（Progressive Disclosure）。

Codex 启动时，只读取每个技能的 name、description 和文件路径。只有当它决定使用某个技能时，才会把完整 SKILL.md 指令加载进上下文。

打个比方：自助餐厅每道菜前面只立一块小牌子—菜名加一句话描述。你扫一眼就知道有什么，但牌子背后的详细做法，没轮到这道菜你根本接触不到。等你真夹了这道菜，后厨的详细做法才展开给你。

这个初始清单有字符预算：最多占模型上下文窗口的约 2%，或上下文窗口未知时上限为 8000 个字符。如果装了很多技能，Codex 会先缩短技能描述。对于极大的技能集合，部分技能可能被省略并显示警告。

Tip

这个预算只管初始清单。Codex 选中某个技能后，照样会完整读它的 SKILL.md。所以你的 description 要把核心用例和触发词放在最前面—万一描述被压缩，前置的关键词还能保住。

两种触发方式

显式调用：你点名喊它

在提示词里用 $ 符号直接引用技能：

$commit

打一个 $，会弹出可选的技能列表。也可以用 /skills 命令选择。显式调用时 Codex 不做任何匹配判断，直接加载完整 SKILL.md 照着干—你说要哪个就是哪个，最稳妥。

Warning

显式调用用的是 $ 符号，不是 @。有些教程写成 @skill-name，跟官方不一致。

隐式调用：它按描述自己匹配

你压根不提技能名，正常说需求，Codex 拿你的话去比对每个技能的 description，对上了就自动调出来。

这是 Skill 最舒服的地方：描述写得好，需求一说它自己就接住了。但隐式准不准全压在 description 上。

Tip

写 description 的诀窍：把用户真会说出口的话写进去。比如「总结未提交的改动并标出风险。当用户问『改了啥』『想要提交信息』『帮我看看 diff』时使用」。这不是写给人看的简介，是写给匹配算法的钩子。

维度	显式调用（`$` / `/skills`）	隐式调用（按描述匹配）
怎么触发	你打 `$` 点名	正常说需求，Codex 自己匹配
Codex 做不做判断	不做，点名即用	做，拿你的话比对 description
准不准取决于	你点对没有	description 写得好不好

技能放哪

Codex 从仓库、用户、管理员和系统四个层级读取技能。仓库级技能会从当前工作目录一路向上扫描到仓库根目录中的 .agents/skills。

作用范围	存放路径	适用场景
REPO	`$CWD/.agents/skills`	当前模块或微服务专属技能
REPO	`$REPO_ROOT/.agents/skills`	整个仓库共享的团队技能
USER	`$HOME/.agents/skills`	你个人的全局技能，任何仓库都能用
ADMIN	`/etc/codex/skills`	机器或容器级共享，管理员统一下发
SYSTEM	OpenAI 随 Codex 内置	通用技能，如 `skill-creator`

Warning

自己手写的技能放 .agents/skills，不是 ~/.codex/skills/。~/.codex/ 是放 config.toml 这类配置的地方。但 $skill-installer 安装的精选技能会放在 ~/.codex/skills/ —那是安装器自己的行为，别去手动碰它。

如果两个技能同名，Codex 不会合并，两个都会出现在技能选择器里。所以不同作用范围之间别用相同的技能名，免得选的时候分不清。

创建技能

用 $skill-creator 快速生成

最快的方式是使用内置创建器：

$skill-creator

它会问你三个问题：

这个技能做什么？
什么时候该触发？
纯指令就够还是要带脚本？（默认推荐纯指令）

答完它就把目录骨架和 SKILL.md 给你生成好。然后再改细节就行。

手动创建

也可以手动建目录和文件：

mkdir -p ~/.agents/skills/my-skill

然后写 SKILL.md：

---
name: my-skill
description: 说明这个技能该在什么时候触发、什么时候不触发。
---

技能指令写在这里。

Codex 会自动检测技能文件的变更。如果更新后没生效，重启 Codex 即可。

Tip

除非你确实需要确定性行为或调外部工具，否则优先用指令而不是脚本。让 Codex 照着自然语言步骤干，比硬塞一个脚本更灵活。

安装精选技能

用 $skill-installer 可以安装内置之外的精选技能：

$skill-installer linear

也可以让安装器从其他仓库下载技能。安装后 Codex 一般自动发现，没出现就重启。

Note

$skill-installer 的定位是「本地试用和实验」。要是你想把自己写的技能正经分发给别人，走 Plugin 那条路。

启用和禁用技能

某个技能暂时不想用，又不想删文件，可以在 ~/.codex/config.toml 里禁用：

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

改完 config.toml 后需要重启 Codex。

可选元数据：agents/openai.yaml

想在 Codex App 里配界面元数据、关掉隐式触发、声明工具依赖，可以在技能目录里放一个 agents/openai.yaml：

interface:
  display_name: "面向用户的显示名称"
  short_description: "面向用户的简短描述"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "使用该技能时的默认提示词"

policy:
  allow_implicit_invocation: false

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

allow_implicit_invocation 默认是 true。设成 false 后，Codex 不再根据提示词隐式触发这个技能，但显式的 $技能名 调用照样有效。

Tip

| 什么时候关隐式触发？有副作用、你想亲手掐时机的技能（比如「发布上线」），不希望 Codex 自作主张触发—给它 allow_implicit_invocation: false，锁成只能 $ 点名。

最佳实践

原则	说明
一个技能只做一件事	保持职责单一，别让一个技能承担太多不相关的任务
指令优先于脚本	能用指令说清的别写脚本，除非需要确定性行为或调外部工具
步骤用祈使句	明确每个步骤的输入和输出
前置核心触发词	把关键用例和触发词放在 `description` 最前面
测试 description	用真实提示词测试是否正确触发，该触发时触发、不该触发时沉默

小结

你想干啥	用什么	在哪
快速造一个新技能	`$skill-creator`	CLI / App 里直接打
装别人现成的技能	`$skill-installer <名字>`	CLI / App 里直接打
手动创建	建目录 + `SKILL.md`	`.agents/skills` 或 `$HOME/.agents/skills`
临时禁用	`[[skills.config]]`	`~/.codex/config.toml`
关掉隐式触发	`allow_implicit_invocation: false`	技能目录的 `agents/openai.yaml`
查看可用技能	`/skills`	CLI / App 里直接打

Skill 让 Codex 不再是张白纸，而是带着一身能按需调出的专项本事上岗。渐进式披露保证装再多也不撑上下文，两种触发方式让你在「省心」和「精准」之间灵活选。记住几个坑：手写的放 .agents/skills 不是 ~/.codex/skills、显式调用用 $ 不是 @、字段没有 trigger、description 把核心触发词前置。

下一章讲 Plugins 插件开发—怎么把技能打包成分发给别人的可安装包。