Codex 的 Skills：怎么写、放哪里、怎么调用

这篇适合谁、读完能做到什么

这篇适合想把自己常做的一套流程固定下来、让 Codex 每次都按同样步骤做的人。读完你应该能写出一个最小的 Skill，知道它该放在哪个目录，会用 $ 或自动匹配两种方式调用它，也知道怎么临时禁用一个 Skill。^[1]

Skill 是什么，和插件有什么区别

Skill 用来给 ChatGPT 和 Codex 增加针对某类任务的能力。一个 Skill 把指令、资源和可选的脚本打包在一起，让产品能稳定地按某个流程执行。Skill 建立在开放的 agent skills 标准之上。^[1]

可以这样理解分工：Skill 是写可复用流程的格式，插件则负责分发。插件通过 ChatGPT 和 Codex 共用的插件目录分发 Skill 和连接器。^[1] 如果只在自己的仓库或本机用，直接放文件夹就够了；要分享给别人、把几个 Skill 打包在一起，或者和某个连接器一起交付，才需要做成插件。^[1]

一个 Skill 的文件结构

Skill 就是一个目录，里面必须有 SKILL.md，并且它的前置信息里要包含 name 和 description。目录里还可以放几类可选内容：^[1]

scripts/：可执行代码。
references/：参考文档。
assets/：模板和其他资源。
agents/openai.yaml：外观和依赖的配置。^[1]

手写一个 Skill 时，SKILL.md 开头是这样的前置块：^[1]

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for ChatGPT or Codex to follow.

前置块后面就是给模型看的指令。

怎么写好 description

模型是否自动选中一个 Skill，主要看 description。因此 description 要简短，写清楚适用范围和边界，把核心用途和触发词放在最前面，这样即使被截断，也还能被匹配到。^[1]

另外，一个 Skill 只做一件事。文档建议优先用指令而不是脚本，除非你需要确定性的行为或依赖外部工具；步骤要写成祈使句，并写明输入和输出。写完后用几条真实的提示词测试，看它会不会在该触发的时候触发。^[1]

如果你不想从零写，可以在 Codex 里输入 $skill-creator。它会问你这个 Skill 做什么、什么时候触发，以及只用指令还是要带脚本。默认是只用指令。^[1]

怎么调用

调用 Skill 有两种方式：^[1]

显式调用：在提示词里直接指定。在 Codex CLI 或 IDE 扩展里，运行 /skills，或者输入 $ 来提到某个 Skill。
隐式调用：任务内容和 Skill 的 description 匹配时，ChatGPT 或 Codex 可以自行选用它。

如果你不希望某个 Skill 被隐式调用，在它的 agents/openai.yaml 里设置 allow_implicit_invocation 为 false。这样 Codex 不会根据用户提示自动调用它，但用 $skill 显式调用仍然有效。allow_implicit_invocation 的默认值是 true。^[1]

Skill 放在哪里

Codex 会从仓库、用户、管理员和系统几个位置读取 Skill。^[1]

仓库：从当前工作目录一直往上，到仓库根目录，每一层目录里的 .agents/skills 都会被扫描。
用户：$HOME/.agents/skills。
管理员：/etc/codex/skills。
系统：Codex 自带的 Skill，包括 skill-creator 和 skill-installer，默认启用。^[1]

有两点要注意。第一，如果两个 Skill 的 name 相同，Codex 不会合并它们，两个都会出现在选择列表里。第二，Codex 支持符号链接形式的 Skill 目录，会跟随链接指向的目标扫描。^[1]

添加 Skill 之后，Codex 会自动检测变化；如果新的内容没有出现，重启 Codex 即可。^[1]

安装现成的 Skill

想给本机的 Codex 加一些官方整理好的 Skill，用 $skill-installer。例如安装 linear 这个 Skill：^[1]

$skill-installer linear

安装器也可以从其他仓库下载 Skill。文档说，这种本地安装适合试验和本机配置；要长期、可复用地分发自己的 Skill，应优先做成插件。^[1]

临时禁用一个 Skill

不想删除某个 Skill、只想让它暂时不生效，可以在 ~/.codex/config.toml 里加一条 [[skills.config]]：^[1]

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

每条记录只能用一种选择器。写绝对路径 path 只匹配那一个 SKILL.md；写 name 则匹配所有同名 Skill。有多条记录匹配时，最后一条生效。^[1]

如果只想在当前项目里关掉所有系统自带的 Skill，就在该项目受信任的 .codex/config.toml 里把 [skills.bundled] 下的 enabled 设为 false。修改配置后要重启 Codex。^[1]

常见问题

改了 Skill，Codex 没反应。 先重启 Codex。Codex 本来会自动检测变化，但如果更新没出现，重启是文档给出的办法。^[1]

两个 Skill 同名。 它们不会合并，两个都会显示在选择器里。要区分，最好改掉其中一个的 name，或者用 [[skills.config]] 禁用其中一个。^[1]

限制

启动时，Codex 的初始 Skill 列表默认最多占用模型上下文窗口的 2%；上下文窗口未知时，上限是 8,000 个字符。Skill 很多时，Codex 会先缩短描述，列表放不下的 Skill 可能被省略，并给出警告。可以用 skills.max_context_tokens 调大这个预算，最多 10,000 个 token。^[1]