OpenAI Codex 技能指南 | 创建、组织与复用智能体技能

使用智能体技能可以给 Codex 注入任务级能力。一个技能会把指令、参考资料和可选脚本打包在一起，让 Codex 可以更稳定地遵循某个工作流。Codex 的技能建立在开放智能体技能标准之上。

技能是“可复用工作流”的创作格式；插件则是“可安装分发单元”。如果你想先设计工作流本身，请从技能开始；当你希望让其他开发者能够安装使用，或希望和应用一起分发时，再把它打包成插件。

Codex CLI、IDE 扩展和 Codex App 都支持技能。

Codex 使用“按需展开”来管理上下文：启动时只读取技能的元数据，例如 name、description、文件路径以及可选的 agents/openai.yaml 元数据；只有在 Codex 决定实际使用这个技能时，才会把完整 SKILL.md 指令加载进上下文。

一个技能就是一个目录，里面至少要有 SKILL.md，还可以按需添加脚本和参考资料。SKILL.md 必须声明 name 和 description。

my-skill/
├── SKILL.md          # 必需：指令与元数据
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：文档参考
├── assets/           # 可选：模板与资源
└── agents/
    └── openai.yaml   # 可选：展示信息与依赖声明

Codex 如何使用技能

Codex 有两种触发技能的方式：

显式调用：例如在 CLI / 应用中使用 /skills 选择，或者在提示词中写 $skill-name
隐式调用：Codex 根据 description 判断是否适合使用某个技能

因为隐式匹配依赖 description，所以技能描述必须写清楚触发边界：什么时候该用，什么时候不该用。

创建技能

优先使用内置创建器：

$skill-creator

创建器会询问这个技能做什么、在什么场景下触发，以及它是“纯指令”还是“带脚本”型。默认推荐先做纯指令技能。

你也可以手动创建，只要建立一个目录并放入 SKILL.md：

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

Skill instructions for Codex to follow.

Codex 会自动检测技能变更；如果更新后没有生效，重启 Codex 即可。

技能的保存位置

Codex 会从仓库、用户、管理员和系统四类位置读取技能。对于仓库级技能，Codex 会从当前工作目录开始，一路向上扫描到仓库根目录中的 .agents/skills。如果两个技能使用了同一个 name，Codex 不会合并它们，它们会分别出现在可选技能列表中。

技能范围	位置	推荐用途
REPO	`$CWD/.agents/skills`	当前工作目录对应的小范围技能，例如某个微服务或模块专属技能。
REPO	`$CWD/../.agents/skills`	当你在 Git 仓库的子目录中启动 Codex 时，可让父目录中的共享技能自动生效。
REPO	`$REPO_ROOT/.agents/skills`	仓库级共享技能，适合面向整个仓库的团队规范或工作流。
USER	`$HOME/.agents/skills`	用户自己的全局技能，适用于任意仓库。
ADMIN	`/etc/codex/skills`	机器或容器级共享技能，常用于默认运维脚本、SDK 自动化或管理员统一下发的技能。
SYSTEM	OpenAI 随 Codex 内置	面向广泛用户的通用技能，例如 `skill-creator` 和规划相关技能。

Codex 支持通过符号链接组织技能目录；扫描时会跟随链接目标继续读取。

这些路径主要用于本地创作和本地发现。如果你要把技能作为可复用产物分发到仓库之外，或者希望和应用一起打包，应该使用插件。

用插件分发技能

直接在 skills/ 目录下维护技能，最适合本地开发和仓库范围工作流。

如果你希望：

分发一个可复用技能
把多个技能组合在一起发布
把技能和应用集成一起交付

那么更适合把它们打包成插件。

插件可以包含一个或多个技能，也可以同时携带应用映射、MCP 服务端配置和展示资源。

在本地安装精选技能

如果你想在本地 Codex 环境中安装内置之外的精选技能，可以使用 $skill-installer。例如安装 $linear 技能：

$skill-installer linear

你也可以让安装器从其他仓库下载技能。Codex 会自动发现新安装的技能；如果没有立即出现，可以重启 Codex。

这个流程更适合本地试验和个人使用。对于你自己希望复用和分发的技能，优先考虑插件。

启用或停用技能

你可以通过 ~/.codex/config.toml 中的 [[skills.config]] 条目，在不删除技能的前提下将其停用：

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

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

可选元数据

如果你希望在 Codex App 中配置界面元数据、设置调用策略，并声明工具依赖，以获得更顺畅的技能使用体验，可以在技能目录中加入 agents/openai.yaml：

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

最佳实践

让每个技能聚焦在一项明确工作上。
除非你确实需要确定性行为或外部工具，否则优先使用指令而不是脚本。
步骤尽量写成祈使句，并明确输入与输出。
用真实提示词去测试 description，确认它会在正确场景触发，也会在不该触发时保持沉默。

最近搜索

推荐搜索

技能