中文 | English

使用 agent skills，可以为 Codex 扩展面向特定任务的能力。一个 skill 会打包说明、资源以及可选脚本，从而让 Codex 能更可靠地遵循某个工作流。Skills 建立在 open agent skills standard 之上。

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

Skills 可用于 Codex CLI、IDE 扩展以及 Codex app。

Skills 使用 渐进式披露 来高效管理上下文：Codex 起初只会看到每个 skill 的元数据（name、description、文件路径，以及来自 agents/openai.yaml 的可选元数据）。只有当 Codex 决定要使用某个 skill 时，它才会加载完整的 SKILL.md 说明。

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

Codex 如何使用 skills

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

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

由于隐式匹配依赖于 description，因此请用清晰的范围与边界来编写 description。

创建 skill

请先使用内置的创建器：

$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 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/skills 位于机器或容器中的共享系统位置。	用于 SDK 脚本、自动化，以及管理员提供给机器上每个用户的默认 skills。
SYSTEM	由 OpenAI 随 Codex 一同内置。	适用于广泛用户群体的实用 skills，例如 skill-creator 和 plan skill。所有人启动 Codex 时都可用。

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

这些位置用于编写与本地发现。当你想把可复用的 skills 分发到单个仓库之外，或可选地与 app 集成一起打包时，请使用 plugins。

使用 plugins 分发 skills

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

Plugins 可以包含一个或多个 skills。它们还可以在同一个包中可选地包含 app 映射、MCP server 配置以及展示资源。

为本地使用安装精选 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 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 description 的触发行为是否正确。

如需更多示例，请参阅 github.com/openai/skills 与 the agent skills specification。