跳转到内容
ChatGPT 文档中文镜像

构建技能

身份 非官方简体中文镜像
翻译状态 AI 翻译 / AI 审校
来源版本 官方未提供
同步日期 2026-07-26
官方原文 learn.chatgpt.com

使用 Agent 技能，为 ChatGPT 和 Codex 扩展特定任务的能力。技能将指令、资源和可选脚本打包在一起，使任一产品都能可靠地执行工作流。技能基于开放 Agent 技能标准。

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

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

在 ChatGPT 桌面应用中，打开侧边栏中的 Skills，即可查看和探索在各个项目中创建的技能。

Skills picker showing available skills in the ChatGPT desktop app

技能使用渐进式披露来高效管理上下文。ChatGPT 和 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          # 可选：外观和依赖项

ChatGPT 和 Codex 如何使用技能

Section titled “ChatGPT 和 Codex 如何使用技能”

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

  1. 显式调用： 在提示词中直接包含该技能。在 ChatGPT 中，输入 @ 以选择技能。在 Codex CLI 或 Codex IDE extension 中，运行 /skills 或输入 $ 来提及技能。
  2. 隐式调用： 当任务符合技能的 description 时，ChatGPT 或 Codex 可以选择使用该技能。

由于隐式匹配取决于 description，请编写简洁且范围和边界清晰的描述。将关键使用场景和触发词放在前面，这样即使描述被缩短，宿主仍能匹配该技能。

创建技能

Section titled “创建技能”

如果你已经了解工作流，并且演示比描述更容易，请使用 Record & Replay。记录器会捕获工作流、检查各个步骤，并根据演示草拟一个可复用的技能。

如果你希望描述技能，则可以使用内置创建器。在 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 从哪里加载本地技能

Section titled “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 捆绑提供。 适用于广大用户的技能，例如 skill-creator 和 plan 技能。用户启动 Codex 时即可使用。

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

这些位置用于编写技能和进行本地发现。如果你希望将可复用的技能分发到单个仓库之外，或选择将其与连接器捆绑，请使用插件。

使用插件分发技能

Section titled “使用插件分发技能”

直接使用技能文件夹最适合本地编写以及仓库范围内的工作流。如果你希望分发可复用的技能、将两个或更多技能捆绑在一起，或将技能与连接器一同发布，请将它们打包为一个插件。

插件可以包含一个或多个技能。它们还可以选择在单个软件包中捆绑已注册的 MCP server 连接、捆绑的 MCP server 配置和演示文稿资源。

安装精选技能供本地使用

Section titled “安装精选技能供本地使用”

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

Terminal window
$skill-installer linear

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

将此功能用于本地设置和实验。若要分发自己创建的可复用技能，建议使用插件。

启用或禁用本地 Codex 技能

Section titled “启用或禁用本地 Codex 技能”

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

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

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

可选元数据

Section titled “可选元数据”

添加 agents/openai.yaml，即可在 ChatGPT 桌面应用 中配置 UI 元数据、设置调用策略，并声明工具依赖，从而更顺畅地使用技能。

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 仍然有效。

最佳实践

Section titled “最佳实践”
  • 让每个技能专注于一项工作。
  • 除非需要确定性行为或外部工具，否则优先使用指令而不是脚本。
  • 使用明确输入和输出的祈使步骤。
  • 使用测试提示词检查技能描述，确认触发行为正确。

更多示例请参阅GitHub CI repair、PDF、Linear、openai/skills 和agent skills specification。如需可安装的分发方式，建议使用插件。