本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/skills

Agent Skills

为 Codex 提供新的能力和专业知识

使用 agent skills 为 Codex 扩展特定任务的能力。一个 skill 会打包指令、资源和可选脚本，使 Codex 能够可靠地遵循某个工作流。Skills 基于开放 agent skills 标准构建。

Skills 是可复用工作流的编写格式。Plugins 是 Codex 中可复用 skills 和应用的可安装分发单元。使用 skills 来设计工作流本身；当你希望其他开发者安装它时，再将其打包为一个 plugin。

Skills 可用于 Codex CLI、IDE 扩展和 Codex 应用。

Skills 使用渐进式披露来高效管理上下文：Codex 初始仅包含每个 skill 的名称、描述和文件路径。只有当 Codex 决定使用某个 skill 时，才会加载完整的 SKILL.md 指令。

Codex 会先在上下文中包含一份可用 skills 的初始列表，以便为任务选择合适的 skill。为了避免挤占提示词其余部分，这个列表被限制在模型上下文窗口的大约 2%，或者在上下文窗口未知时限制为 8,000 个字符。如果安装了很多 skills，Codex 会优先缩短 skill 描述。对于非常大的 skill 集合，某些 skills 可能不会出现在初始列表中，并且 Codex 会显示警告。

这个预算只适用于初始 skills 列表。当 Codex 选择某个 skill 时，它仍然会读取该 skill 的完整 SKILL.md 指令。

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

Codex 如何使用 skills

Codex 可以通过两种方式激活 skills：

显式调用： 在你的提示中直接包含该 skill。在 CLI/IDE 中，运行 /skills 或输入 $ 来提及某个 skill。
隐式调用： 当你的任务匹配 skill 的 description 时，Codex 可以自行选择该 skill。

因为隐式匹配依赖于 description，请编写简洁且范围、边界清晰的描述。把关键用例和触发词放在前面，这样即使描述被缩短，Codex 仍然能够匹配到该 skill。

创建 skill

优先使用内置创建器：

$skill-creator

创建器会询问该 skill 做什么、应在何时触发，以及它应保持为纯指令还是包含脚本。默认是纯指令。

你也可以手动创建 skill：创建一个包含 SKILL.md 文件的文件夹：

---
name: skill-name
description: 准确说明这个 skill 应该在何时触发，以及何时不应触发。
---

Codex 需要遵循的 skill 指令。

Codex 会自动检测 skill 变更。如果更新没有出现，请重启 Codex。

将 skills 保存在哪里

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

Skill Scope	Location	Suggested use
`REPO`	`$CWD/.agents/skills` 当前工作目录：你启动 Codex 的位置。	如果你位于某个仓库或代码环境中，团队可以提交与工作文件夹相关的 skills。例如，仅与某个微服务或模块相关的 skills。
`REPO`	`$CWD/../.agents/skills` 当你在 Git 仓库内启动 Codex 时，位于 CWD 上一级的文件夹。	如果你位于一个包含嵌套文件夹的仓库中，组织可以提交与父文件夹中某个共享区域相关的 skills。
`REPO`	`$REPO_ROOT/.agents/skills` 当你在 Git 仓库内启动 Codex 时，最顶层的根文件夹。	如果你位于一个包含嵌套文件夹的仓库中，组织可以提交与仓库中所有使用者相关的 skills。这些可作为根 skills，供仓库中的任意子文件夹使用。
`USER`	`$HOME/.agents/skills` 提交到用户个人文件夹中的任意 skills。	用于整理与某个用户相关、且适用于该用户可能参与的任何仓库的 skills。
`ADMIN`	`/etc/codex/configuration/skills` 提交到机器或容器中的共享系统位置的任意 skills。	用于 SDK 脚本、自动化，以及提交对机器上每个用户都可用的默认管理员 skills。
`SYSTEM`	随 Codex 由 OpenAI 一同打包提供。	适合广泛用户群体的实用 skills，例如 skill-creator 和 plan skills。任何人在启动 Codex 时都可使用。

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

这些位置用于编写和本地发现。当你希望将可复用 skills 分发到单个仓库之外，或者可选地将它们与应用集成一起打包时，请使用 plugins。

使用 plugins 分发 skills

直接使用 skill 文件夹最适合本地编写和仓库范围的工作流。如果你想分发一个可复用 skill，将两个或更多 skills 打包在一起，或者将 skill 与某个应用集成一同发布，请将它们打包为 plugin。

Plugins 可以包含一个或多个 skills。它们还可以选择性地将应用映射、MCP server 配置和展示资源打包到一个单一 package 中。

为本地使用安装精选 skills

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

$skill-installer linear

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

将其用于本地设置和实验。对于你自己 skills 的可复用分发，优先使用 plugins。

启用或禁用 skills

在 ~/.codex/config.toml 中使用 [[skills.config]] 条目，以便在不删除 skill 的情况下禁用它：

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

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

可选元数据

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

interface:
  display_name: "面向用户的可选名称"
  short_description: "面向用户的可选描述"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "使用该 skill 时可选的外围提示"

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；显式的 $skill 调用仍然有效。

最佳实践

让每个 skill 专注于一项工作。
除非你需要确定性行为或外部工具，否则优先使用指令而不是脚本。
使用祈使式步骤，并明确输入和输出。
针对 skill 描述测试提示，以确认触发行为是否正确。

更多示例请参见 github.com/openai/skills 和agent skills 规范。

Codex 如何使用 skills​

创建 skill​

将 skills 保存在哪里​

使用 plugins 分发 skills​

为本地使用安装精选 skills​

启用或禁用 skills​

可选元数据​

最佳实践​