English
主导航

推荐
API 仪表板

Agent 技能

赋予 Codex 新功能与专长

使用 Agent Skills 来扩展 Codex 的任务特定能力。Skill（技能）将指令、资源和可选脚本打包在一起，使 Codex 能够可靠地遵循工作流。Skills 基于 开放的 Agent Skills 标准.

Skills 是可复用工作流的创作格式。Plugins（插件）是 Codex 中用于安装可复用 Skills 和应用的可分发单元。使用 Skills 来设计工作流本身，然后当你希望其他开发者安装它时，将其打包为 插件 当您希望其他开发者安装它时。

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 and description.

  • my-skill/
    • SKILL.md 必填：指令 + 元数据
    • scripts/ 可选：可执行代码
    • references/ 可选：文档
    • assets/ 可选：模板、资源
    • agents/
      • openai.yaml 可选：外观和依赖项

Codex 如何使用 Skills

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

  1. 显式调用： 在你的提示词中直接包含该 Skill。在 CLI/IDE 中，运行 /skills or type $ to mention a skill.
  2. 隐式调用： 当你的任务与 Skill 匹配时，Codex 可以选择该 Skill description.

由于隐式匹配取决于 description, 撰写简明扼要的描述，界定清晰的适用范围与边界。将核心用例和触发词放在最前面，这样即使描述被缩短，Codex 依然能够匹配到该技能。

创建一个 skill

首先使用内置的创建器：

$skill-creator

创建器会询问 Skill 的功能、触发时机，以及是保持纯指令形式还是包含脚本。纯指令形式是默认设置。

你也可以通过创建一个包含 SKILL.md file:

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

Skill instructions for Codex to follow.

文件的文件夹来手动创建 Skill。Codex 会自动检测 Skill 的更改。如果更新未生效，请重启 Codex。

Skills 的保存位置

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

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，这些 Skills 适用于该用户可能处理的任何仓库。
ADMIN/etc/codex/skills
签入到机器或容器中共享系统位置的任何 Skills。		用于 SDK 脚本、自动化，以及签入可供机器上每位用户使用的默认管理员 Skills。
SYSTEM由 OpenAI 与 Codex 捆绑提供。与广泛受众相关的实用 Skills，例如 skill-creator 和 plan skills。在启动 Codex 时对所有人可用。

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

这些位置用于创作和本地发现。当你希望将可复用 Skills 分发到单个仓库之外，或者有选择地将它们与应用集成捆绑在一起时，请使用 插件.

使用插件分发 Skills

直接的 Skill 文件夹最适合本地创作和仓库范围内的工作流。如果你想分发可复用的 Skill，将两个或多个 Skills 捆绑在一起，或者将 Skill 与应用集成一起发布，请将它们打包为 插件.

插件可以包含一个或多个技能。它们还可以选择将应用映射、MCP 服务器配置和展示资源捆绑在单个包中。

插件可以包含一个或多个 Skills。它们还可以选择将应用映射、MCP 服务器配置和呈现资产捆绑到一个包中。

安装精心策划的 Skills 以供本地使用 $skill-installer。例如，要安装 $linear skill:

$skill-installer linear

要为你自己的本地 Codex 设置添加内置之外的精选 Skills，请使用

你还可以提示安装程序从其他仓库下载 Skills。Codex 会自动检测新安装的 Skills；如果未显示某个 Skill，请重启 Codex。

将此用于本地设置和实验。对于你自己 Skills 的可复用分发，请首选插件。

使用 [[skills.config]] 启用或禁用 Skills ~/.codex/config.toml 中的条目来禁用某个 Skill，而无需删除它：

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

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

可选元数据

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

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

最佳实践

  • 保持每项技能专注于单一任务。
  • 除非需要确定性行为或外部工具，否则请优先使用指令而非脚本。
  • 使用明确的输入和输出编写命令式步骤。
  • 根据技能描述测试提示，以确认正确的触发行为。

For more examples, see github.com/openai/skills and the agent skills specification.