用 Skills 复用能力

使用 agent skills 可以给 Codex 扩展 task-specific capabilities（面向具体任务的能力）。一个 skill 会打包

使用 agent skills 可以给 Codex 扩展 task-specific capabilities（面向具体任务的能力）。一个 skill 会打包 instructions（指令）、resources（资源）和可选 scripts（脚本），让 Codex 能稳定地遵循某个工作流。

Skills 基于 open agent skills standard：

https://agentskills.io

Skills 是 reusable workflows（可复用工作流）的 authoring format（编写格式）。Plugins 是 Codex 中可安装的分发单元，用来分发 reusable skills 和 apps。

你应该先用 skills 设计工作流本身；当你希望其他开发者安装时，再把它打包成 plugin：

https://developers.openai.com/codex/plugins/build

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

Skills 使用 progressive disclosure（渐进披露）来高效管理上下文：Codex 一开始只知道每个 skill 的 name、description 和 file path。当 Codex 决定使用某个 skill 时，才会加载完整的 SKILL.md 指令。

Codex 会把初始可用 skills 列表放进上下文，以便为任务选择合适 skill。为了避免挤占 prompt 其余部分，这个列表被限制在模型上下文窗口的大约 2%，或者在上下文窗口未知时限制为 8,000 字符。

如果安装了很多 skills，Codex 会先缩短 skill descriptions。对于非常大的 skill sets，有些 skills 可能会从初始列表中省略，Codex 会显示 warning（警告）。

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

一个 skill 是一个目录，包含必需的 SKILL.md 文件，以及可选 scripts 和 references。SKILL.md 文件必须包含 name 和 description。

my-skill/
  SKILL.md        Required: instructions + metadata
  scripts/        Optional: executable code
  references/     Optional: documentation
  assets/         Optional: templates, resources
  agents/
    openai.yaml   Optional: appearance and dependencies

Codex 如何使用 skills

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

Explicit invocation（显式调用）：在 prompt 里直接包含 skill。CLI / IDE 中可以运行 /skills，或者输入 $ 来提及某个 skill。
Implicit invocation（隐式调用）：当你的任务匹配 skill 的 description 时，Codex 可以主动选择这个 skill。

因为隐式匹配依赖 description，所以 description 要简洁，并且清楚说明范围和边界。把核心使用场景和 trigger words（触发词）放在前面。这样即使 descriptions 被缩短，Codex 仍然有机会正确匹配。

创建 skill

优先使用内置 creator：

$skill-creator

Creator 会询问这个 skill 做什么、什么时候触发，以及它应该只包含指令，还是也包含 scripts。默认是 instruction-only（仅指令）。

你也可以手动创建 skill：新建一个文件夹，并放入 SKILL.md：

---
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 会从 repository、user、admin 和 system 位置读取 skills。

对于 repositories，Codex 会从当前工作目录一路向上扫到 repository root，在每一层寻找 .agents/skills。如果两个 skills 使用同一个 name，Codex 不会合并它们；两者都可能出现在 skill selectors（技能选择器）里。

Skill Scope	Location	Suggested use
`REPO`	`$CWD/.agents/skills` 当前工作目录，也就是启动 Codex 的地方。	如果你在仓库或代码环境中，团队可以把与某个工作目录相关的 skills 提交进去。例如只和某个 microservice 或 module 有关的 skills。
`REPO`	`$CWD/../.agents/skills` 在 Git 仓库内启动 Codex 时，CWD 上层的某个文件夹。	如果仓库有嵌套目录，组织可以把与父级共享区域相关的 skills 提交到上层文件夹。
`REPO`	`$REPO_ROOT/.agents/skills` 在 Git 仓库内启动 Codex 时，最顶层 root folder。	如果仓库有嵌套目录，组织可以把每个使用该仓库的人都相关的 skills 放在这里。这些是 root skills，可供仓库内任意子目录使用。
`USER`	`$HOME/.agents/skills` 用户个人目录中的 skills。	用于整理对某个用户有用、且适用于该用户可能参与的任意仓库的 skills。
`ADMIN`	`/etc/codex/skills` 机器或容器中的共享系统位置。	用于 SDK scripts、automation，以及给这台机器上每个用户提供默认 admin skills。
`SYSTEM`	OpenAI 随 Codex 打包。	面向广泛用户的有用 skills，例如 skill-creator 和 plan skills。启动 Codex 时每个人都可用。

Codex 支持 symlinked skill folders（软链接 skill 文件夹），扫描这些位置时会跟随 symlink target（软链接目标）。

这些位置用于 authoring（编写）和 local discovery（本地发现）。如果你想把 reusable skills 分发到单个 repo 之外，或者可选地把它们和 app integrations 打包在一起，请使用 plugins：

https://developers.openai.com/codex/plugins/build

用 plugins 分发 skills

直接使用 skill folders 最适合 local authoring 和 repo-scoped workflows。如果你想分发一个 reusable skill、把两个或多个 skills 打包到一起，或者把 skill 和 app integration 一起发布，请把它们打包成 plugin：

https://developers.openai.com/codex/plugins/build

Plugins 可以包含一个或多个 skills。它们也可以把 app mappings、MCP server configuration 和 presentation assets 放在同一个 package（包）里。

安装 curated skills 到本地

如果你想给自己的本地 Codex 设置添加 built-ins 之外的 curated skills，可以使用 $skill-installer。

例如安装 $linear skill：

$skill-installer linear

你也可以提示 installer 从其他 repositories 下载 skills。

Codex 会自动检测新安装的 skills；如果某个 skill 没有出现，重启 Codex。

这个方式适合本地设置和实验。如果要分发你自己的 reusable skills，优先使用 plugins。

启用或禁用 skills

在 ~/.codex/config.toml 中使用 [[skills.config]] entries，可以禁用某个 skill，而不删除它：

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

修改 ~/.codex/config.toml 后，需要重启 Codex。

可选 metadata

添加 agents/openai.yaml 可以配置 Codex app 中的 UI metadata、设置 invocation policy（调用策略），并声明 tool dependencies，让 skill 使用体验更顺滑。

Codex app：

https://developers.openai.com/codex/app

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 不会根据用户 prompt 隐式调用这个 skill；显式 $skill 调用仍然有效。

Best practices

让每个 skill 专注于一个任务。
除非需要 deterministic behavior（确定性行为）或 external tooling（外部工具），否则优先写 instructions，而不是 scripts。
用 imperative steps（命令式步骤）写清楚 inputs 和 outputs。
用测试 prompts 对照 skill description，确认它能在正确场景触发。

更多示例见：

On this page