Codex 技能教程：用 SKILL.md 把常用流程变成一句话就能调用的技能

同一套操作每次都要跟 Codex 重新交代一遍？比如「按团队格式写提交说明」「发版前先跑这几项检查」。Codex 的「技能」（Skills）就是为这种情况准备的：把说明、参考资料和脚本打包成一个文件夹，以后一句话就能调出来。本文按 OpenAI 官方文档，讲清技能是什么、怎么写、放在哪里、怎么调用。

技能是什么

技能是一个文件夹，里面有一份必需的 SKILL.md，写着这项任务该怎么做；还可以附带脚本、参考文档和模板。技能遵循开放的 agent skills 标准，ChatGPT 和 Codex 都能使用：独立技能可以在 ChatGPT 桌面 App、Codex 命令行和编辑器扩展里用。

技能和插件的分工是：技能用来设计可以反复使用的工作流程；插件用来把技能和连接器打包分发给别人安装。自己用、或者只在一个项目里用，直接写技能文件夹就够了。

技能为什么不占地方

Codex 启动时只读取每个技能的 name 和 description，等它决定要用某个技能时，才去加载完整的 SKILL.md。官方把这叫「渐进式披露」。在 Codex 里，启动时的技能清单默认最多占模型上下文窗口的 2%；这个上限可以用 skills.max_context_tokens 调整，最高 10,000 tokens。所以装多几个技能，也不会把对话空间挤满。

第一步：建一个技能文件夹

官方给出的目录结构如下，只有 SKILL.md 是必需的：

my-skill/
├── SKILL.md          # 必需：说明 + 元数据
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考文档
├── assets/           # 可选：模板和资源
└── agents/
    └── openai.yaml   # 可选：外观和依赖

SKILL.md 开头是一段元数据，name 和 description 两项必填，下面写具体步骤：

---
name: commit-message
description: 按团队规范写 Git 提交说明。用户要求写提交说明或提交代码时使用；只改文档时不使用。
---

1. 先运行 git diff --staged 查看改动。
2. 第一行用「类型: 简述」格式，不超过 50 个字。
3. 空一行后列出主要改动，每条一行。

description 决定 Codex 什么时候自动用这个技能。官方建议写清楚什么时候用、什么时候不用，并把关键用途和触发词放在最前面，这样描述被截短时也能匹配上。

第二步：放到合适的位置

Codex 会在这些位置找技能：

• 当前目录：$CWD/.agents/skills，只给当前工作目录用；
• 上一级目录：$CWD/../.agents/skills，给同一父目录下的项目共享；
• 仓库根目录：$REPO_ROOT/.agents/skills，整个仓库的子目录都能用；
• 个人目录：$HOME/.agents/skills，你自己的所有仓库都能用；
• 整台机器：/etc/codex/skills，给同一台机器或容器上的所有人用；
• 系统内置：Codex 自带的技能，例如 skill-creator 和 plan。

两个技能同名时不会合并，选择器里两个都会出现。技能文件夹支持符号链接。Codex 会自动发现新技能，如果没出现，重启 Codex 即可。

第三步：调用技能

• 手动调用：在 Codex 命令行或编辑器扩展里运行 /skills，或者输入 $ 加技能名；在 ChatGPT 里输入 @ 选择技能。
• 自动调用：你的任务和某个技能的 description 对得上时，Codex 会自己选用它。

不想让某个技能被自动触发，可以在它的 agents/openai.yaml 里关掉隐式调用，之后只能用 $技能名 手动调用：

policy:
  allow_implicit_invocation: false

不想手写？让 Codex 帮你写

• 在 Codex 里输入 $skill-creator，描述你想要的流程，它会生成技能；默认只包含说明，需要时可以要求加上脚本。
• 想装现成的技能，用 $skill-installer，例如：

$skill-installer linear

暂时停用某个技能而不删除它，在 ~/.codex/config.toml 里加上下面几行，然后重启 Codex：

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

上手建议

1. 从你最常重复交代的一件事开始，一个技能只管一项任务。
2. 能用文字说明的就不写脚本；需要固定结果或调用外部工具时再加脚本。
3. 步骤用命令式短句，写明输入是什么、输出要什么样。
4. 写完后用几句真实的需求测试一下，看技能是不是在该触发的时候触发。

Codex 用 ChatGPT 账号登录使用。还没有会员的，可以在 BuyBuy代充（buybuytopup.cn） 开通 ChatGPT Plus，登录 Codex 后就能按上面的步骤写出第一个技能。