Skills 概览

使用 agent skills 为 Codex 扩展 task-specific capabilities。Skill 会打包 instructions、resources 和可选 scripts，让 Codex 能可靠地遵循 workflow。Skills 基于开放的 agent skills standard。

Skills 是 reusable workflows 的 authoring format。Plugins 是 Codex 中 reusable skills 和 apps 的可安装分发单元。请用 skills 设计 workflow 本身；当你希望其他开发者安装它时，再把它打包成 plugin 。

Skills 可用于 Codex CLI、IDE extension 和 Codex app。

Skills 使用 progressive disclosure 到 manage context efficiently：Codex starts 使用 each skill’s name, description, 和 file path。Codex loads the full SKILL.md instructions only 当 it decides 到 使用 a skill.

Codex includes an initial 列出 of 可用 skills in context so it can 选择 the right skill for a task。To avoid crowding out the rest of prompt, this 列出 uses at most 2% of the model’s context window, 或 8,000 characters 当 the context window is unknown。如果 many skills are installed, Codex shortens skill descriptions first。For large skill sets, Codex may omit some skills 从 the initial 列出 和 显示 a warning.

This budget applies only 到 the initial skills 列出。当 Codex selects a skill, it still reads the full SKILL.md instructions for that skill.

A skill is a directory 使用 a SKILL.md file plus 可选 scripts 和 references。The SKILL.md file must include name 和 description.

Codex can activate skills in two ways:

Because implicit matching depends on description, 写入 concise descriptions 使用 clear scope 和 boundaries。Front-load the key 使用 case 和 trigger words so Codex can still match the skill 如果 descriptions are shortened.

如果 you already know the workflow 和 it’s easier 到 显示 than describe, 使用 Record & Replay 。Codex records the workflow, inspects the steps, 和 drafts a reusable skill 从 the demonstration.

如果 you want 到 describe the skill instead, 使用 the built-in creator:

$skill-creator

The creator asks what the skill does, 当 it should trigger, 和 whether it should stay instruction-only 或 include scripts。Instruction-only is the 默认.

You can also create a skill manually by creating a folder 使用 a SKILL.md file:

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

Skill instructions for Codex to follow.

Codex detects skill changes 自动。如果 an update doesn’t appear, restart Codex.

Codex reads skills 从 repository, user, admin, 和 system locations。For repositories, Codex scans .agents/skills in every directory 从 your 当前 working directory up 到 repository root。如果 two skills share the same name, Codex doesn’t merge them；both can appear in skill selectors.

Codex supports symlinked skill folders 和 follows the symlink target 当 scanning these locations.

These locations are for authoring 和 local discovery。当 you want 到 distribute reusable skills beyond a single repo, 或 可选ly bundle them 使用 app integrations, 使用 plugins .

Direct skill folders are best for local authoring 和 repo-scoped workflows。如果 you want 到 distribute a reusable skill, bundle two 或 more skills together, 或 ship a skill alongside an app integration, package them as a plugin .

Plugins can include one 或 more skills。They can also 可选ly bundle app mappings, MCP server configuration, 和 presentation assets in a single package.

To 添加 curated skills beyond the built-ins for your own local Codex setup, 使用 $skill-installer。例如, 到 安装 the $linear skill:

$skill-installer linear

You can also prompt the installer 到 download skills 从 other repositories。Codex detects newly installed skills 自动；如果 one doesn’t appear, restart Codex.

使用 this for local setup 和 experimentation。For reusable distribution of your own skills, prefer plugins.

使用 [[skills.config]] entries in ~/.codex/config.toml 到 disable a skill 不使用 deleting it:

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

Restart Codex 之后 changing ~/.codex/config.toml.

添加 agents/openai.yaml 到 配置 UI metadata in the Codex app , 到 设置 invocation policy, 和 到 declare tool dependencies for a more seamless experience 使用 using the 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 won’t implicitly invoke the skill based on user prompt；explicit $skill invocation still works.

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