构建技能

身份非官方简体中文镜像

翻译状态 AI 翻译

来源版本官方未提供

同步日期 2026-07-31

如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加 .md 来获取 URL。

使用 Agent 技能来扩展 ChatGPT 和 Codex 的任务专用能力。一个技能会打包说明、资源和可选脚本，使任一产品都能可靠地遵循工作流。技能基于开放的 Agent 技能标准。

技能是可复用工作流的创作格式。插件通过通用插件目录分发可复用技能和连接器，该目录由和 ChatGPT 共享 Codex。插件可在 Web 上通过 ChatGPT Work 使用，可在 ChatGPT Work 和 Codex 桌面应用中通过 ChatGPT 使用，也可通过 Codex CLI使用。先使用技能来设计工作流本身，然后在你希望其他人安装时，将其打包为插件。

独立技能可在 ChatGPT 桌面应用、 Codex CLI和 IDE 扩展中使用。插件中捆绑的技能也可通过受支持的插件界面使用，包括 Web 上的 ChatGPT Work 。

在 ChatGPT 桌面应用中，打开侧边栏中的技能以查看和探索在你的项目中创建的技能。

交互内容： CodexScreenshot 的动态演示请参阅页面顶部的官方原文链接。

技能使用 渐进式披露 来高效管理上下文。 ChatGPT 和 Codex 会先读取每个技能的名称和描述，然后在决定使用该技能时加载完整 SKILL.md 说明。

在 Codex中，初始列表还包括每个技能的文件路径。为避免挤占提示词的其余部分，该列表最多使用模型上下文窗口的 2%，或在上下文窗口未知时使用 8,000 个字符。如果安装了许多技能， Codex 会先缩短技能描述。对于大型技能集合， Codex 可能会从初始列表中省略部分技能并显示警告。

此预算仅适用于初始技能列表。当 Codex 选择某个技能时，它仍会读取该技能的完整 SKILL.md 说明。

技能是一个目录，其中包含一个 SKILL.md 文件，以及可选的脚本和参考资料。该 SKILL.md 文件必须包含 name 和 description。

交互内容： FileTree 的动态演示请参阅页面顶部的官方原文链接。

如何 ChatGPT 和 Codex 使用技能

ChatGPT 和 Codex 可以通过两种方式激活技能：

显式调用： 在提示词中直接包含该技能。在 ChatGPT中，输入 @ 以选择技能。在 Codex CLI 或 IDE 扩展中，运行 /skills 或输入 1. **显式调用：** 在提示词中直接包含该技能。在 ChatGPT中，输入 @以选择技能。在 Codex CLI 或 IDE 扩展中，运行/skills` 或输入来提及某个技能。
隐式调用： ChatGPT 或 Codex 可以在你的任务与技能 description匹配时选择某个技能。

由于隐式匹配依赖于 description，因此请编写简洁的描述并明确范围和边界。将关键用例和触发词前置，这样即使描述被缩短，宿主也仍能匹配该技能。

创建技能

如果你已经了解工作流，并且演示比描述更容易，请使用录制与重放。录制器会捕获工作流、检查步骤，并根据演示起草一个可复用技能。

如果你想改为描述该技能，请使用内置创建器。在 ChatGPT Work 中，将其调用为 @skill-creator。在 Codex中，将其调用为：

$skill-creator

创建器会询问该技能的用途、何时应触发，以及它应仅包含说明还是包含脚本。默认是仅包含说明。

你也可以手动创建技能：创建一个包含 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 会自动检测技能变更。如果更新没有出现，请重启 Codex。

本地技能由 Codex 从何处加载

Codex 会从仓库、用户、管理员和系统位置读取技能。对于仓库， Codex 会扫描 .agents/skills 从当前工作目录到仓库根目录之间每个目录中的内容。如果两个技能共享同一个 name， Codex 不会合并它们；二者都可能出现在技能选择器中。

技能范围	位置	建议用途
`REPO`	`$CWD/.agents/skills` 当前工作目录：启动 Codex的位置。	如果你在仓库或代码环境中，团队可以检入与某个工作文件夹相关的技能。例如，仅与某个微服务或模块相关的技能。
`REPO`	`$CWD/../.agents/skills` 启动 CWD 时位于 Codex 上方的某个文件夹，且在 Git 仓库内。	如果你在包含嵌套文件夹的仓库中，组织可以在父文件夹中检入与共享区域相关的技能。
`REPO`	`$REPO_ROOT/.agents/skills` 在 Git 仓库内启动 Codex 时的最顶层根文件夹。	如果你在包含嵌套文件夹的仓库中，组织可以检入与所有仓库使用者相关的技能。这些技能作为根技能，可供仓库中的任何子文件夹使用。
`USER`	`$HOME/.agents/skills` 检入到用户个人文件夹中的任何技能。	用于整理与某个用户相关、并适用于该用户可能处理的任何仓库的技能。
`ADMIN`	`/etc/codex/skills` 检入到机器或容器上共享系统位置中的任何技能。	用于 SDK 脚本、自动化，以及检入可供机器上每个用户使用的默认管理员技能。
`SYSTEM`	由 Codex 随 OpenAI捆绑。	适用于广泛受众的有用技能，例如 skill-creator 和 plan 技能。每个人启动 Codex时都可使用。

Codex 支持符号链接的技能文件夹，并在扫描这些位置时跟随符号链接目标。

这些位置用于创作和本地发现。当你想要在单个仓库之外分发可复用技能，或选择性地将其与连接器捆绑时，请使用插件。

通过插件分发技能

直接技能文件夹最适合本地创作和仓库范围的工作流。如果你想分发可复用技能、将两个或更多技能捆绑在一起，或随连接器一起发布技能，请将它们打包为插件。

插件可以包含一个或多个技能。它们还可以选择性地将已注册的 MCP 服务器连接、捆绑的 MCP 服务器配置，以及展示资产打包到单个软件包中。

安装精选技能以供本地使用

若要在你自己的本地 Codex 设置中添加内置项之外的精选技能，请使用 $skill-installer。例如，要安装 $linear 技能：

$skill-installer linear

你也可以提示安装器从其他仓库下载技能。 Codex 会自动检测新安装的技能；如果某个技能没有出现，请重启 Codex。

将此用于本地设置和实验。若要可复用地分发你自己的技能，请优先使用插件。

启用或停用本地 Codex 技能

使用 [[skills.config]] 中的 ~/.codex/config.toml 条目来停用技能，而无需删除它：

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

更改 Codex 后请重启 ~/.codex/config.toml。

可选元数据

添加 agents/openai.yaml 以配置 UI 桌面应用中的 ChatGPT 元数据、设置调用策略，并声明工具依赖项，从而在使用该技能时获得更顺畅的体验。

interface:
  display_name: "Optional user-facing name"
  short_description: "Optional user-facing description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt to use the skill with"

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 repair、 PDF、 Linear、 openai/skills以及 Agent 技能规范。对于可安装分发，请优先使用插件。