Skills 技能

使用 agent skills 为 Codex 扩展任务专用能力。一个 skill 会打包指令、资源和可选脚本，让 Codex 能够可靠地遵循某个工作流。Skills 基于 open agent skills standard。

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

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

Skills 使用 progressive disclosure 来高效管理上下文：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。

• Directorymy-skill/

  • …
• SKILL.md 必需：指令 + 元数据
• Directoryscripts/ 可选：可执行代码

  • …
• Directoryreferences/ 可选：文档

  • …
• Directoryassets/ 可选：模板、资源

  • …
• Directoryagents/

  • …
• openai.yaml 可选：外观和依赖项

Codex 如何使用 skills

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

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

因为隐式匹配依赖 description，所以请编写简洁的描述，并清楚说明范围和边界。将关键使用场景和触发词放在前面，这样即使描述被缩短，Codex 仍然可以匹配到该 skill。

创建 skill

如果您已经了解该工作流程，且演示比描述更简单，请使用“记录与回放”（Record & Replay）。Codex 会记录该工作流程、检查相关步骤，并根据演示起草一项可重复使用的技能。

如果您想改为描述该技能，请使用内置的创建器：

$skill-creator

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

你也可以通过创建一个带有 SKILL.md 文件的文件夹来手动创建 skill：

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

Skill instructions for Codex to follow.

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

skills 保存在哪里

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

Skill 作用域	位置	建议用途
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/skills 提交到机器或容器上的共享系统位置中的任何 skills。	用于 SDK 脚本、自动化，以及提交默认管理员 skills，使机器上的每个用户都可使用。
SYSTEM	由 OpenAI 随 Codex 捆绑。	对广大用户有用的 skills，例如 skill-creator 和 plan skills。用户启动 Codex 时即可使用。

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

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

使用 plugins 分发 skills

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

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

为本地使用安装精选 skills

要为你自己的本地 Codex 设置添加内置 skills 之外的精选 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 app 中配置 UI 元数据，设置调用策略，并声明工具依赖项，从而获得更顺畅的 skill 使用体验。

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

最佳实践

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

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