构建技能 | ChatGPT 学习
来源: https://developers.openai.com/codex/skills 抓取时间: 2026-07-21 16:19:36
使用智能体技能为 Codex 扩展特定任务能力。技能将指令、资源和可选脚本打包在一起，使 Codex 能够可靠地遵循工作流。技能建立在 开放智能体技能标准 之上。
技能是可重用工作流的创作格式。插件将可重用的技能和连接器分发到网页版 ChatGPT 的工作模式，以及 ChatGPT 桌面应用的工作模式和 Codex。Codex CLI 也可以安装插件。使用技能设计工作流本身，然后当您希望工作区中的其他人安装它时，将其打包为 插件。
技能可在 ChatGPT 桌面应用、Codex CLI 和 IDE 扩展中使用。
在 ChatGPT 桌面应用中，打开侧边栏中的 技能 以查看和探索跨项目创建的技能。
技能使用 渐进式披露 来高效管理上下文：Codex 从每个技能的名称、描述和文件路径开始。只有当 Codex 决定使用某个技能时，它才会加载完整的 SKILL.md 指令。
Codex 在上下文中包含可用技能的初始列表，以便它可以为任务选择正确的技能。为了避免挤占提示的其余部分，此列表最多使用模型上下文窗口的 2%，或者当上下文窗口未知时使用 8,000 个字符。如果安装了许多技能，Codex 会首先缩短技能描述。对于大型技能集，Codex 可能会从初始列表中省略一些技能并显示警告。
此预算仅适用于初始技能列表。当 Codex 选择一个技能时，它仍然会读取该技能的完整 SKILL.md 指令。
技能是一个包含 SKILL.md 文件以及可选脚本和参考的目录。SKILL.md 文件必须包含 name 和 description。
- my-skill/
- SKILL.md 必需：指令 + 元数据
- scripts/ 可选：可执行代码
- references/ 可选：文档
- assets/ 可选：模板、资源
- agents/
- openai.yaml 可选：外观和依赖项
Codex 如何使用技能
Codex 可以通过两种方式激活技能：
- 显式调用： 直接在您的提示中包含该技能。在 CLI/IDE 中，运行
/skills或键入$来提及一个技能。 - 隐式调用： 当您的任务与技能
description匹配时，Codex 可以选择该技能。
由于隐式匹配取决于 description，因此请编写简洁的描述，具有明确的范围和边界。将关键用例和触发词放在前面，这样即使描述被缩短，Codex 仍然可以匹配该技能。
创建技能
如果您已经知道工作流，并且展示比描述更容易，请使用 录制和重播。Codex 录制工作流，检查步骤，并从演示中起草一个可重用的技能。
如果您想描述该技能，请使用内置创建器：
$skill-creator
创建器会询问该技能做什么、何时应该触发，以及它应该保持仅指令还是包含脚本。仅指令是默认设置。
您也可以通过创建一个包含 SKILL.md 文件的文件夹来手动创建技能：
---
name: skill-name
description: 准确解释此技能何时应该和不应该触发。
---
Codex 要遵循的技能指令。
Codex 会自动检测技能更改。如果更新没有出现，请重启 Codex。
在哪里保存技能
Codex 从仓库、用户、管理员和系统位置读取技能。对于仓库，Codex 会从当前工作目录向上扫描到仓库根目录中的 .agents/skills。如果两个技能共享相同的 name，Codex 不会合并它们；两者都可以出现在技能选择器中。
| 技能范围 | 位置 | 建议用途 |
|---|---|---|
REPO | $CWD/.agents/skills | |
| 当前工作目录：您启动 Codex 的位置。 | 如果您在仓库或代码环境中，团队可以检入与工作文件夹相关的技能。例如，仅与微服务或模块相关的技能。 | |
REPO | $CWD/../.agents/skills | |
| 当您在 Git 仓库内启动 Codex 时，位于 CWD 上方的文件夹。 | 如果您在具有嵌套文件夹的仓库中，组织可以检入与父文件夹中共享区域相关的技能。 | |
REPO | $REPO_ROOT/.agents/skills | |
| 当您在 Git 仓库内启动 Codex 时，位于最顶层的根文件夹。 | 如果您在具有嵌套文件夹的仓库中，组织可以检入与使用该仓库的每个人相关的技能。这些作为根技能，可供仓库中的任何子文件夹使用。 | |
USER | $HOME/.agents/skills | |
| 检入用户个人文件夹的任何技能。 | 用于策划与用户相关、适用于用户可能工作的任何仓库的技能。 | |
ADMIN | /etc/codex/skills | |
| 检入机器或容器中共享系统位置的任何技能。 | 用于 SDK 脚本、自动化，以及检入机器上每个用户可用的默认管理员技能。 | |
SYSTEM | 由 OpenAI 与 Codex 捆绑在一起。 | 适用于广泛受众的有用技能，如技能创建器和计划技能。每个人在启动 Codex 时都可以使用。 |
Codex 支持符号链接的技能文件夹，并在扫描这些位置时遵循符号链接目标。
这些位置用于创作和本地发现。当您想要在单个仓库之外分发可重用的技能，或者可选地将它们与连接器捆绑在一起时，请使用 插件。
使用插件分发技能
直接技能文件夹最适合本地创作和仓库范围的工作流。如果您想要分发可重用的技能、将两个或更多技能捆绑在一起，或者与连接器一起提供技能，请将它们打包为 插件。
插件可以包含一个或多个技能。它们还可以可选地将应用映射、MCP 服务器配置和展示资源捆绑在一个包中。
安装精选技能供本地使用
要为您自己的本地 Codex 设置添加超出内置功能的精选技能，请使用 $skill-installer。例如，要安装 $linear 技能：
$skill-installer linear
您也可以提示安装程序从其他仓库下载技能。Codex 会自动检测新安装的技能；如果没有出现，请重启 Codex。
将此用于本地设置和实验。对于您自己技能的可重用分发，首选插件。
启用或禁用技能
在 ~/.codex/config.toml 中使用 [[skills.config]] 条目来禁用技能而不删除它：
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
更改 ~/.codex/config.toml 后重启 Codex。
可选元数据
添加 agents/openai.yaml 以配置 ChatGPT 桌面应用 中的 UI 元数据，设置调用策略，并声明工具依赖项，以获得使用技能的更无缝体验。
interface:
display_name: "可选的面向用户的名称"
short_description: "可选的面向用户的描述"
icon_small: "./assets/small-logo.svg"
icon_large: "./assets/large-logo.png"
brand_color: "#3B82F6"
default_prompt: "用于该技能的可选周围提示"
policy:
allow_implicit_invocation: false
dependencies:
tools:
- type: "mcp"
value: "openaiDeveloperDocs"
description: "OpenAI Docs MCP server"
transport: "streamable_http"
url: "https://developers.openai.com/mcp"
allow_implicit_invocation（默认值：true）：当为 false 时，Codex 不会根据用户提示隐式调用该技能；显式 $skill 调用仍然有效。
最佳实践
- 保持每个技能专注于一项任务。
- 优先使用指令而不是脚本，除非您需要确定性行为或外部工具。
- 编写带有明确输入和输出的命令性步骤。
- 针对技能描述测试提示，以确认正确的触发行为。
有关更多示例，请参见 GitHub CI 修复、PDF、Linear、openai/skills 和 智能体技能规范。对于可安装的分发，首选 插件。