01 · 技能与插件

两个概念，一句话分清

• 技能（Skill）：一项具体任务或工作流所需的指令和配套资源，打包在一起。
• 插件（Plugin）：可安装的套件，可以包含技能、连接器，或者两者都有。 连接器由 MCP 服务器提供支持，也可以带自定义的 ChatGPT 界面。

先用技能把流程本身设计出来；需要分发给别人，再打包成插件。

什么时候该写技能

判断标准很实在：这件事你已经用同样的方式做过三次以上，而且每次都要重新交代一遍。

比如每周的发布说明、代码审查时那几条固定检查、把某类日志整理成排查报告、 按团队规范写 commit message。技能记录的是「你目前处理这类工作的方式」， 让 Codex 每次遇到都走同一套流程。

不适合写成技能的：一次性的活、每次要求都不一样的活、 以及那些其实该写进 AGENTS.md 的全局约定。

技能长什么样

一个包含 SKILL.md 的目录，可以再放脚本和参考资料。SKILL.md 必须有 name 和 description：

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

Skill instructions for ChatGPT or Codex to follow.

description 这一行比正文更重要——它决定了这个技能什么时候会被自动选中。 写「生成发布说明」不如写「当用户要求根据两个 git tag 之间的提交生成面向用户的发布说明时使用； 不要用于内部变更日志」。

它怎么决定用不用某个技能

技能采用渐进式披露：ChatGPT 和 Codex 先只拿到每项技能的名称和描述， 决定要用了才加载完整的 SKILL.md。

在 Codex 里，这个初始列表还包含每项技能的文件路径。 为了不挤占提示里的其他内容，列表最多占模型上下文窗口的 2%； 上下文窗口大小未知时最多 8000 个字符。装的技能太多，Codex 会先压缩描述， 再多就直接省略一部分并给出警告。

所以：技能不是装得越多越好。装了三十个用不上的，代价是你真正需要的那个可能被挤掉。

两种触发方式：

• 显式：ChatGPT 里输入 @ 选，Codex CLI / IDE 里跑 /skills 或输入 $ 引用。
• 隐式：任务和技能的 description 对上了，它自己选。

三种做法

一、让它帮你写。 在 Codex 里：

$skill-creator

创建器会问你这个技能干什么、什么时候触发、只要指令还是也要脚本（默认只有指令）。

二、演示给它看。 流程复杂到不好描述的时候，用录制与重放： 录一遍你的操作，它检查各步骤，据此起草一个可复用的技能。

三、手写。 建目录、写 SKILL.md，就上面那个格式。 Codex 会自动检测技能变更；没显示出来就重启。

Codex 从哪里加载技能

这张表值得记住，因为它决定了「这个技能对谁生效」：

范围	位置	适合放什么
REPO	$CWD/.agents/skills	只跟当前这个微服务 / 模块有关的技能
REPO	$CWD/../.agents/skills	嵌套目录结构里，共享区域的技能
REPO	$REPO_ROOT/.agents/skills	整个仓库通用，提交进版本库，所有人都能用
USER	$HOME/.agents/skills	你个人的，跨所有仓库
ADMIN	/etc/codex/skills	机器 / 容器级共享，适合 SDK 脚本和自动化
SYSTEM	OpenAI 随 Codex 捆绑	skill-creator、plan 这类内置技能

对于仓库范围，Codex 从当前工作目录一路向上遍历到仓库根，扫描各级的 .agents/skills。 同名技能不会合并，两个都会出现在选择器里——所以命名别撞车。

技能文件夹支持符号链接，扫描时会跟随。

想临时关掉某个技能而不删它：

# ~/.codex/config.toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

装别人写好的技能

$skill-installer linear

也可以让安装器从其他仓库下载。这条路适合本地折腾和试验； 要分发自己的技能，官方建议优先用插件。

什么时候该上插件

技能文件夹解决的是「我和我的仓库」；插件解决的是「别人怎么装上我这套东西」。

需要插件的信号：

• 要把两个以上技能捆一起发
• 技能要连外部服务（GitHub、Google Drive、Slack……），得带连接器
• 想让网页版和移动端的 ChatGPT 也能用——独立技能只能在桌面应用、Codex CLI 和 IDE 扩展里用， 插件里捆的技能才能在网页版、桌面端和移动端的聊天与 Work 里用

ChatGPT 和 Codex 共用同一个插件目录，所以装一次两边都能用。

一条实践建议

技能最容易犯的错是写太大。「代码审查技能」这种范围的东西，最后会变成一篇没人读的长文档， 它也不知道什么时候该用。

拆小：「检查 SQL 注入风险」「检查错误处理是否吞异常」「检查新增依赖的许可证」—— 每个技能一件事，描述写清楚触发条件。它会自己在合适的时候挑合适的那个。

相关官方文档

• 技能与插件
• 构建技能
• 录制与重放
• 插件 · 构建插件