最后核验：2026-10-23
先看结论
Skill 把一段你反复在做的工作流程打包成可复用的单元，让 ChatGPT 和 Codex 每次遇到同类任务都按同一套步骤和格式来做，不用你每次重新粘贴提示词。要点：
- 结构很简单：一个目录，里面有
SKILL.md（必须包含name和description），再加可选的脚本和参考资料。 - 渐进式披露：一开始只把每个 skill 的名称和描述（Codex 里还有文件路径）放进上下文，Codex 决定用某个 skill 时才去读它完整的
SKILL.md。所以description就是触发的依据。 - 一个 skill 只做一件事；能用文字指令说清的，就不要写脚本。
- 从你已经在重复做的任务开始，而不是先造一个庞大的 skill 库。
本文整理自 OpenAI 官方文档和开发者博客，核验日期 2026-10-23；界面与默认值以你当前版本为准。
先分清：AGENTS.md、Skill、Plugin 各管什么
官方最佳实践把“把常驻规则塞进提示词，而不是放进 AGENTS.md 或 skill”列为新手常见错误。三者的分工可以这样理解（其中对 AGENTS.md 与 skill 的对比是编者的归纳）：
- AGENTS.md：每次都该遵守的常驻规则，如仓库结构、构建测试命令、工程约定，见AGENTS.md 怎么写才有用；
- Skill：某一类任务的可复用流程，用到才载入；
- Plugin：分发层。官方说法是，skill 是编写可复用流程的格式，plugin 用来把 skill 和连接器分发给别人。
一个经验判断（编者归纳）：如果一条规则“无论做什么任务都要遵守”，放 AGENTS.md；如果它“只在做某一类事时才需要”，做成 skill。
什么任务值得做成 Skill
官方建议：把一个你已经在重复做的任务，变成一份聚焦的“作业手册”。官方列出的适合做第一个 skill 的例子，是步骤和格式需要保持一致的任务，比如每周更新、活动方案、会议跟进。
放到开发场景里（编者归纳），常见候选有：
- 按固定格式写发布说明、迁移说明；
- 按团队的清单做一次代码审查或安全检查；
- 修复 CI 失败的固定排查流程；
- 生成固定结构的故障复盘或周报。
官方 openai/skills 仓库里有一些现成示例，如修复 GitHub CI、PDF、Linear 等，可以先读一读别人怎么写。
五步做出第一个 Skill
- 选一件具体的事：记下你通常以什么开始（文件、链接、笔记），以及做完的样子应该是什么。
- 用内置的创建器描述它：在 Codex 里输入
$skill-creator（在 ChatGPT 里是@skill-creator）。说明目标、步骤、期望格式，以及“一定要包含”和“一定要避免”的内容；手头有模板或好的样例就一并给它。创建器会问你：这个 skill 做什么、什么时候触发、是只含指令还是还要带脚本。默认只含指令。 - 审阅并用真实请求试一试：检查草稿指令，用一个现实的请求测试，漏步骤或格式跑偏就改。
- 启用并复用：启用之后，Codex 会在相关请求里使用它，你也可以显式点名；工作区设置允许时还能分享给队友。
- （可选）用 Record & Replay：如果这个流程“演示比描述更容易”，官方的 Record & Replay 会记录你的操作、检查每一步，再起草出一份可复用的 skill。
也可以手工创建：建一个文件夹，放一个 SKILL.md，格式是官方给出的：
---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---
Skill instructions for ChatGPT or Codex to follow.
Codex 会自动检测 skill 的变化；如果更新没出现，重启 Codex。
description 怎么写（最关键的一步）
隐式触发（也就是你没点名、Codex 自己决定要不要用）完全依赖 description。
官方文档的要求：描述要简洁、范围和边界要清楚；把主要用途和触发词放在最前面，这样即使描述被截短，宿主仍然能匹配。
OpenAI 开发者博客（面向 API 的 Skills，原理相通）进一步建议：
- 把 description 当成路由逻辑，不要当成宣传文案。它应该回答：什么时候用？什么时候不用？输出和成功标准是什么？
- 可以直接在描述里写一个简短的“适用 / 不适用”块，保持具体：输入、涉及的工具、预期产物；
- 补上反例和边界情况：博客提到，让 skill 可用之后，正确触发率一开始反而可能下降；写上几条明确的“遇到……时不要调用这个 skill”（以及改用什么），能让路由更干净，在有多个看起来相近的 skill 时尤其重要。博客以早期客户 Glean 为例：基于 skill 的路由一度让目标评测里的触发率下降约 20%，加入反例和边界情况之后恢复。
下面是一个编者自拟的对比示例，用来说明写法，不是官方原文：
差：帮助写发布说明。
好：在需要根据已合并的 PR 生成面向用户的发布说明时使用。
输入：版本区间。输出：按“新增、改进、修复”分组的条目。
不要用于：内部变更记录、回滚说明（这两类请直接说明需求）。
放在哪里
Codex 会从仓库、用户、管理员和系统几个位置读取 skill。官方列出的位置：
- 仓库（REPO）：
$CWD/.agents/skills（你启动 Codex 的当前目录）、$CWD/../.agents/skills（Git 仓库里上一层目录）、$REPO_ROOT/.agents/skills（仓库根）。Codex 会从当前工作目录一路向上扫描到仓库根的每个.agents/skills； - 用户（USER）：
$HOME/.agents/skills，放你个人、适用于所有仓库的 skill； - 管理员（ADMIN）：
/etc/codex/skills，放机器或容器上共享的默认 skill； - 系统（SYSTEM）：随 Codex 一起提供，例如 skill-creator 和 plan 技能。
几点细节：
- 同名的两个 skill 不会被合并，两个都可能出现在选择器里，所以请起不同的名字；
- 支持符号链接的 skill 文件夹，会跟随链接目标扫描；
- 官方建议：只与某个微服务或模块相关的 skill，放到对应目录；对整个仓库都有用的放仓库根；个人偏好放用户目录。想分发给更多人，用 plugin。
怎么调用，怎么关掉
- 显式调用：在 Codex CLI 或 IDE 扩展里运行
/skills，或输入$来点名 skill；桌面应用侧边栏里有 Skills 入口可以查看；ChatGPT 里输入@； - 隐式调用：Codex 根据你的任务是否匹配某个 skill 的
description来选； - 要确定性就点名：OpenAI 博客的建议是，当你要在一个有明确约定的生产流程里“确定而不是聪明”，直接说“Use the
<skill name>skill.”，把模糊的路由变成明确的约定； - 不想被隐式触发：在 skill 的
agents/openai.yaml里设置policy.allow_implicit_invocation: false（默认true）。设为false之后，Codex 不会根据提示词隐式调用它，但显式的$skill仍然可用； - 临时停用而不删除：在
~/.codex/config.toml里加[[skills.config]]条目，改完需重启 Codex：
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
另外，$skill-installer 可以装官方精选的 skill，例如 $skill-installer linear；也可以让它从其他仓库下载。
内容里放什么
官方最佳实践的四条：
- 每个 skill 只做一件事；
- 优先写指令，只有在需要确定性行为或外部工具时才写脚本；
- 步骤用祈使句，并写明输入和输出；
- 用提示词对照
description测试，确认触发行为正确。
OpenAI 博客还有一条很实用：把模板和示例放进 skill 里。它们只在 skill 被调用时才加载，不会给无关的请求增加 token；而塞在系统提示词里，每次都要付出成本。博客提到，Glean 报告说这种做法带来了他们在生产里最大的质量和延迟收益之一。
别装太多：上下文预算
官方文档里有个容易被忽略的细节：
- Codex 一开始的 skill 列表（含名称、描述和文件路径），默认最多占用模型上下文窗口的 2%；上下文窗口未知时是 8,000 字符；
- skill 很多时，Codex 会先缩短描述；skill 集合很大时，可能会从初始列表里省略一部分，并显示警告；
- 可以用
skills.max_context_tokens设置不同的预算，上限 10,000 个 token； - 这个预算只管初始列表；选中某个 skill 时，仍会读取它完整的
SKILL.md。
由此带来的实践（编者归纳）：skill 不是越多越好；描述先写关键用途和触发词；很少用的 skill 可以按上文停用，而不是都装着。
排错：没触发、乱触发、没出现
下面是按官方机制推出的排查思路，具体做法是编者的建议：
- 没触发：把
description改成“用途和触发词在前”，补上典型的请求说法；需要确定性时直接点名$skill； - 乱触发：在描述里补“不要用于……”和反例；仍然误触发就关闭隐式调用；
- 在列表里看不到：先重启 Codex；确认目录在上面列出的某个位置、
SKILL.md里有name和description；skill 太多时留意是否出现了预算警告； - 同名冲突：Codex 不会合并同名 skill，改名区分。
安全：装之前先读
OpenAI 博客在 API 托管容器的语境下提醒：skill 加开放的网络访问，是数据外泄的高风险组合；若要联网，请把白名单收到最小，并把工具输出当作不可信内容。
对本地的 Codex，编者的建议是：装来自其他仓库或不熟悉来源的 skill 之前，先读它的 SKILL.md 和其中的脚本，弄清它会运行什么、访问什么；来源不明的不要装。
从 Skill 到 Plugin
当你想把 skill 分发给别人、把两个以上的 skill 放在一起，或者让 skill 和连接器一起发布时，官方的建议是打包成 plugin。Plugin 可以包含一个或多个 skill，还可以选择性地捆绑已注册的 MCP 服务器连接和展示素材。本地创作和仓库范围的流程，用目录形式的 skill 就够了。
检查清单
- 这个 skill 只做一件事吗？它只在某一类任务里才需要，还是其实应该放进
AGENTS.md？ description里写了什么时候用、什么时候不用吗？关键词在最前面吗？- 模板和示例放进 skill 里了吗？有没有为了小事写了不必要的脚本？
- 用一条该触发的请求和一条不该触发的请求测过吗？
- 放在了正确的位置（仓库 / 个人），名字有没有冲突？
- 装来源不明的 skill 之前读过它的内容吗？
下一步读什么
- Codex 新手常见的 8 个错误：规则该放提示词、AGENTS.md 还是 skill
- AGENTS.md 怎么写才有用：常驻规则的写法与验证
- Codex 长任务工作流：把 Skills 放进可恢复、可审查的长任务流程
官方来源
- Build skills：结构、创建、存放位置、调用、
agents/openai.yaml、预算与最佳实践 - Skills & Plugins：什么任务适合做成 skill，创建的四个步骤
- Record & Replay：把演示变成 skill
- Best practices：常见错误与 skill 的定位
- Shell + Skills + Compaction: Tips for long-running agents：description 当路由逻辑写、反例、模板放进 skill、安全提醒
- openai/skills：官方 skill 示例仓库
核验日期：2026-10-23。
