跳到正文

ChatGPT 技能：把重复工作写成可复用的流程

技能的目录结构、渐进式披露如何影响 description 的写法、Codex 从哪些位置加载技能、如何用 skill-creator 创建，以及什么时候该改用插件分发。

当前有效最后核验

适用平台

  • ChatGPT 桌面应用
  • Codex CLI
  • Codex IDE 扩展
  • ChatGPT 网页版与手机端（通过插件捆绑的技能）

官方文档怎么说

  • 技能建立在开放的 agent skills 标准之上。

    Build skills

  • 独立技能在 ChatGPT 桌面应用、Codex CLI 和 IDE 扩展中可用；捆绑在插件里的技能还可以在网页版、桌面版和手机端的 Chat 与 Work 中使用。

    Build skills

  • 一个技能是一个包含 SKILL.md 文件的目录，可选附带 scripts、references、assets 和 agents 目录；SKILL.md 必须包含 name 和 description。

    Build skills

  • 技能使用渐进式披露：ChatGPT 和 Codex 先只看到每个技能的名称和描述，决定使用某个技能时才加载完整的 SKILL.md 指令。

    Build skills

  • 在 Codex 中，初始技能列表最多占用模型上下文窗口的 2%，上下文窗口未知时为 8000 字符；技能太多时 Codex 会先缩短描述，必要时省略部分技能并给出警告。

    Build skills

  • 显式调用方式为：在 ChatGPT 中输入 @ 选择技能，在 Codex CLI 或 IDE 扩展中运行 /skills 或输入 $ 提及技能。

    Build skills

  • 隐式调用依赖 description 匹配，因此官方要求写简洁、范围与边界清晰的描述，并把关键用例和触发词前置。

    Build skills

  • 内置创建器在 ChatGPT Work 中通过 @skill-creator 调用，在 Codex 中通过 $skill-creator 调用；默认是仅指令（instruction-only）。

    Build skills

  • Codex 从仓库、用户、管理员和系统四类位置读取技能；仓库位置是从当前工作目录向上到仓库根目录的每一级 .agents/skills 目录。

    Build skills

  • 两个技能同名时 Codex 不会合并它们，两个都可能出现在技能选择器里。

    Build skills

  • 可以用 ~/.codex/config.toml 中的 [[skills.config]] 条目在不删除技能的情况下禁用它，修改后需重启 Codex。

    Build skills

  • agents/openai.yaml 中的 allow_implicit_invocation 默认为 true；设为 false 时 Codex 不会基于用户提示隐式调用该技能，但显式 $skill 调用仍然有效。

    Build skills

  • 官方定义技能是打包某个任务或工作流的指令与配套资源，插件是可安装的捆绑包，可以包含技能和 MCP servers。

    Skills & Plugins

技能的本质：把"你已经会做的事"写下来

官方对技能的定义是：一个技能打包指令、资源和可选脚本，让 ChatGPT 或 Codex 可靠地遵循某个工作流。它建立在开放的 agent skills 标准 之上。

更实用的一句在另一页：技能可以捕捉你已经在用的做法，让产品在这类任务出现时都按同一套流程走。

所以判断"值不值得写成技能"的标准不是难度，而是重复性 + 一致性要求。官方给的例子是：准备每日简报、审阅文档、制作演示文稿、应用团队写作规范，或者每周从同一批已连接的工具里收集信息。

目录结构

一个技能就是一个目录，里面有一个 SKILL.md，加上可选的其他部分：

my-skill/
  SKILL.md      必需：指令 + 元数据
  scripts/      可选：可执行代码
  references/   可选：文档
  assets/       可选：模板、资源
  agents/
    openai.yaml 可选：外观与依赖

SKILL.md 必须包含 name 和 description。最小可用形态就是：

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

Skill instructions for ChatGPT or Codex to follow.

注意官方在这个模板里给 description 写的示范文本本身就是一条建议：说清楚这个技能什么时候该触发、什么时候不该触发。下一节解释为什么。

渐进式披露：为什么 description 决定成败

技能用渐进式披露来管理上下文：ChatGPT 和 Codex 一开始只看到每个技能的名称和描述，决定使用某个技能时才加载完整的 SKILL.md 指令。

这带来两个直接后果。

第一，隐式调用完全依赖描述匹配。 官方因此要求：写简洁、范围与边界清晰的描述，并把关键用例和触发词前置——理由是即使描述被缩短，host 仍然能匹配到这个技能。

第二，技能多了会挤占预算。 在 Codex 中，初始列表还包含每个技能的文件路径，而这个列表最多占模型上下文窗口的 2%，上下文窗口未知时为 8000 字符。技能装多了，Codex 会先缩短描述；对于很大的技能集，可能会省略部分技能并给出警告。

好消息是这个预算只作用于初始列表——技能一旦被选中，完整的 SKILL.md 仍然会被完整读取。

两种调用方式

  • 显式调用 —— 在 ChatGPT 里输入 @ 选择技能；在 Codex CLI 或 IDE 扩展里运行 /skills 或输入 $ 提及技能。
  • 隐式调用 —— ChatGPT 或 Codex 在你的任务匹配技能 description 时自行选择。

创建：三条路

用创建器（推荐） —— 在 ChatGPT Work 中 @skill-creator，在 Codex 中 $skill-creator。创建器会问这个技能做什么、什么时候该触发、以及应该保持仅指令还是包含脚本。默认是仅指令。

录一遍 —— 如果你已经知道流程，而且演示比描述更容易，用 Record & Replay：录制器捕捉工作流、检查步骤，并从这次演示中起草一个可复用的技能。

手写 —— 建目录、写 SKILL.md。Codex 会自动检测技能变化；如果更新没出现，重启 Codex。

官方给出的"好的第一个技能"参考：每周更新、活动简报、会议纪要跟进，或者任何步骤和格式都该保持一致的任务。

Codex 从哪里加载本地技能

| 范围 | 位置 | 用途 | |---|---|---| | REPO | $CWD/.agents/skills | 只与某个工作目录相关的技能，比如某个微服务或模块 | | REPO | $CWD/../.agents/skills | 在 Git 仓库内启动时，上层目录里与某个共享区域相关的技能 | | REPO | $REPO_ROOT/.agents/skills | 仓库根目录，面向所有使用该仓库的人 | | USER | $HOME/.agents/skills | 跨仓库通用的个人技能 | | ADMIN | /etc/codex/skills | 机器或容器上共享的系统级位置，适合 SDK 脚本、自动化和默认管理员技能 | | SYSTEM | 由 OpenAI 随 Codex 内置 | skill-creator、plan 这类广泛适用的技能 |

两个细节值得记住：Codex 支持软链接的技能目录并会跟随软链接目标；两个技能同名时 Codex 不会合并它们，两个都可能出现在技能选择器里。

关掉一个技能而不删除它

两种方式，作用不同：

完全禁用 —— 在 ~/.codex/config.toml 里加：

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

改完重启 Codex。

只禁用隐式调用 —— 在 agents/openai.yaml 里设 policy.allow_implicit_invocation = false（默认是 true）。这样 Codex 不会根据你的提示自动调用它，但显式 $skill 调用仍然有效。适合那些做对了很有用、做错了代价很高的技能。

agents/openai.yaml 还能配置桌面应用里的 UI 元数据（显示名、简短描述、图标、品牌色、默认提示）以及声明工具依赖，让使用体验更顺。

最佳实践，以及什么时候该换成插件

官方列的四条最佳实践：

  • 每个技能只聚焦一件事。
  • 优先用指令而不是脚本，除非你需要确定性行为或外部工具。
  • 写祈使句式的步骤，明确输入和输出。
  • 拿提示词对着技能描述测试，确认触发行为符合预期。

关于分发，官方的分界很清楚：直接的技能目录适合本地创作和仓库范围的工作流。想把一个可复用技能分发出去、把两个以上技能打包在一起、或者让技能和连接器一起发布，就该打包成插件。

实际操作

  1. 选一个你已经在重复做的任务，记下你通常从什么开始（文件、链接、笔记）以及做完是什么样子。
  2. 描述工作流：在 ChatGPT 中用 @skill-creator，在 Codex 中用 $skill-creator，说明目标、步骤、期望格式，以及必须包含或必须避免的东西；有模板或好例子就一并给它。
  3. 审阅草稿，用一个真实请求测试它，如果结果漏步骤或偏离格式就继续调整。
  4. 安装并复用；工作区设置允许时可以分享给同事。
  5. 也可以手动创建：建一个目录，写一个含 name 和 description 的 SKILL.md。
  6. 需要 UI 元数据、调用策略或工具依赖时，添加 agents/openai.yaml。

Windows 步骤

  1. Windows 版 ChatGPT 桌面应用支持技能，侧边栏的 Skills 同样可以查看跨项目创建的技能。
  2. Codex 读取技能的位置在 Windows 上遵循同一套规则，用户级位置对应 $HOME/.agents/skills，配置文件对应 ~/.codex/config.toml——在 Windows 上即 %USERPROFILE% 下的对应路径。
  3. 官方建议优先用指令而不是脚本，除非你需要确定性行为或外部工具；这条建议在 Windows 上尤其值得听，因为跨平台脚本更容易出问题。

手机步骤

  1. 手机端不能创作技能，但可以使用它们：官方说明捆绑在插件里的技能在网页版、桌面版和手机端的 Chat 与 Work 中可用。
  2. 独立技能（直接放在文件系统里的技能目录）不在手机端可用，它们限于桌面应用、Codex CLI 和 IDE 扩展。

使用案例

  • 把每周更新、活动简报、会议纪要跟进这类步骤和格式都该保持一致的任务固化下来。
  • 把团队的写作规范或评审标准变成 ChatGPT 每次都会遵守的流程。
  • 配合定时任务使用：用技能定义动作、提供工具和上下文，用定时任务决定何时执行。

常见错误

  • description 写得含糊。隐式调用完全依赖描述匹配，描述不清就等于这个技能只能靠手动调用。
  • 一个技能塞进多件事。官方的第一条最佳实践就是让每个技能只聚焦一件事。
  • 一上来就写脚本。官方建议优先用指令，除非确实需要确定性行为或外部工具。
  • 装了一堆技能之后奇怪某些技能没被选中。Codex 的初始技能列表有上下文预算，技能太多时会先缩短描述，必要时省略部分技能并给出警告。
  • 改完 ~/.codex/config.toml 不重启 Codex。

常见问题

技能和插件有什么区别？
官方的划分是：技能是打包某个任务或工作流的指令与配套资源；插件是可安装的捆绑包，可以包含技能和 MCP servers。选择标准也很直接——需要一个聚焦任务的可复用指令时用技能；需要一个能把指令和已连接服务或其他工具组合起来的可安装包时用插件。
渐进式披露具体是怎么回事？
ChatGPT 和 Codex 一开始只看到每个技能的名称和描述，决定使用某个技能时才读取该技能完整的 SKILL.md 指令。在 Codex 中初始列表还包含每个技能的文件路径，并且这个列表最多占模型上下文窗口的 2%（上下文窗口未知时为 8000 字符）。这个预算只作用于初始列表——技能一旦被选中，完整的 SKILL.md 仍然会被完整读取。
Codex 会从哪里加载本地技能？
四类位置。REPO：当前工作目录的 .agents/skills、启动 Codex 时在 Git 仓库内则包括上层目录的 .agents/skills、以及仓库根目录的 .agents/skills。USER：$HOME/.agents/skills。ADMIN：/etc/codex/skills。SYSTEM：由 OpenAI 随 Codex 内置。Codex 支持软链接的技能目录并会跟随软链接目标。
怎么在不删除的情况下关掉一个技能？
在 ~/.codex/config.toml 里加一个 [[skills.config]] 条目，把该技能 SKILL.md 的 path 设进去并写 enabled = false，然后重启 Codex。另一种是在 agents/openai.yaml 里把 policy.allow_implicit_invocation 设为 false——那样 Codex 不会根据你的提示自动调用它，但显式 $skill 调用仍然有效。
已经知道怎么做，但懒得写出来怎么办？
用 Record & Replay。官方说明它可以录制工作流、检查步骤，并从这次演示中起草一个可复用的技能。

官方来源

这些是本教程对照核验的官方页面。需要厂商的原始措辞时请直接查阅。

来源状态