Skills 是 Codex 的工作流封装格式：把一套可复用的流程打包进 SKILL.md 文件（加上可选的脚本、参考文档、资源），让 Codex 在任务匹配时自动或显式地调用。Skills 遵循渐进式加载，发现阶段只加载元数据，被选中后才加载完整指令，不会白白占用上下文。本文覆盖创建、配置、作用域管理和 Plugin 分发。

OpenAI Codex Skills 指南

Skills 让你用工作流文件扩展 Codex 的能力。一个 Skill 打包了指令、资源和可选脚本，让 Codex 能可靠地遵循某套流程。Skills 基于开放 agent skills 标准。

Skills vs Plugins 的分工：

• Skills 是工作流的创作格式（本地开发和迭代）
• Plugins 是可安装的分发单元（打包后分享给其他开发者安装）

先用 Skill 在本地设计工作流，稳定后打包成 Plugin 分发。

---

Skill 的目录结构

my-skill/
  SKILL.md         # 必须：指令 + 元数据（name + description 必填）
  scripts/         # 可选：可执行脚本
  references/      # 可选：参考文档
  assets/          # 可选：模板、资源
  agents/
    openai.yaml    # 可选：UI 元数据 + 调用策略 + 工具依赖

---

Codex 如何使用 Skills

Codex 通过两种方式激活 Skill：

1. 显式调用：在 Prompt 里直接引用 Skill。CLI/IDE 里运行 /skills 或输入 $ 然后选择 Skill
2. 隐式调用：当你的任务内容与 Skill 的 description 匹配时，Codex 自动选择使用

隐式匹配依赖 description 的质量，因此写好 description 非常关键——要清楚说明这个 Skill 在什么情况下该触发、什么情况下不该触发。

渐进式加载机制：

• Codex 先加载所有 Skill 的元数据（name、description、文件路径）用于发现
• 决定使用某个 Skill 后才加载完整 SKILL.md
• 仅在需要时读取 references 或运行脚本

这样大量 Skills 共存时不会浪费上下文。

---

创建 Skill

推荐方式：用内置的 $skill-creator：

$skill-creator

创建向导会询问：Skill 做什么、什么时候触发、是否需要脚本（默认仅指令，无脚本）。

手动创建：新建一个目录，创建 SKILL.md：

---
name: skill-name
description: 精确描述这个 Skill 应该在什么时候触发，什么时候不该触发。
---

Codex 应该遵循的 Skill 指令。

Codex 会自动检测 Skill 变更。如果更新没有生效，重启 Codex。

---

Skill 的作用域

Codex 从多个位置读取 Skills，每个位置有不同的使用场景：

作用域	路径	建议用途
REPO（CWD）	$CWD/.agents/skills	当前工作目录专属，比如某个微服务或模块特有的流程
REPO（父目录）	$CWD/../.agents/skills	嵌套仓库结构里，适合共享的父目录 Skills
REPO（根目录）	$REPO_ROOT/.agents/skills	整个仓库通用，所有子目录都能用
USER	$HOME/.agents/skills	个人 Skills，适用于所有仓库
ADMIN	/etc/codex/skills	机器或容器级别的系统 Skills
SYSTEM	Codex 内置	OpenAI 提供的通用 Skills，如 skill-creator、plan

Codex 支持符号链接（symlink）的 Skill 目录，会跟随 symlink 扫描实际位置。

同名 Skill 不会合并，两者都会出现在 skill 选择器里。

---

安装社区 Skill

用 $skill-installer 安装精选 Skill，比如安装 $linear Skill：

$skill-installer linear

也可以让安装器从其他仓库下载 Skills。Codex 自动检测新安装的 Skills，如果没出现就重启 Codex。

---

启用/禁用 Skill

在 ~/.codex/config.toml 里可以禁用 Skill 而不删除文件：

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

修改 config.toml 后重启 Codex。

---

可选元数据（agents/openai.yaml）

在 Skill 目录里加 agents/openai.yaml 可以配置 UI 元数据、调用策略和工具依赖：

interface:
  display_name: "用户界面显示名称（可选）"
  short_description: "用户界面显示描述（可选）"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "调用这个 Skill 时的默认 Prompt"

policy:
  allow_implicit_invocation: false  # 设为 false 则只能显式调用

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI 开发者文档 MCP 服务端"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

allow_implicit_invocation（默认 true）：设为 false 后，Codex 不会根据 Prompt 内容自动触发这个 Skill，但 $skill-name 显式调用仍然有效。

通过 dependencies.tools 声明 MCP 依赖后，Codex 会在使用这个 Skill 前自动安装和配置对应的 MCP 服务端。

---

通过 Plugins 分发 Skills

直接共享 Skill 目录适合本地开发和仓库级工作流。如果你想在更大范围分发 Skill（比如给整个团队或外部用户），或者把多个 Skills 打包在一起，应该打包成 Plugin。

Plugins 可以包含：

• 一个或多个 Skills
• 可选的 App 映射
• MCP 服务端配置
• 展示资源

打包成 Plugin 后，其他用户可以直接安装而不需要手动管理文件。

---

最佳实践

• 每个 Skill 只做一件事，不要试图在一个 Skill 里覆盖所有情况
• 优先用指令而不是脚本，除非需要确定性行为或外部工具
• 写清楚步骤，明确指定输入和输出
• 测试 Prompt 与 description 的匹配，确认触发行为符合预期
• 如果同一个 Prompt 反复被使用或反复需要纠正同样的工作流，就该把它做成 Skill

更多示例参考：github.com/openai/skills 和 agent skills 规范。

---

常见问题

Q: 我的 Skill 更新了但 Codex 没有识别到，怎么办？

A: 重启 Codex 即可。Codex 在每次启动时重新扫描 Skill 目录，没有持久化缓存。

Q: 仓库级 Skill 和用户级 Skill 同名了会怎样？

A: 两者都会出现在 Skill 选择器里，Codex 不会合并它们。你可以显式选择要用哪一个，或者通过 allow_implicit_invocation: false 控制哪个不被自动触发。

Q: 什么时候该用脚本，什么时候纯靠 SKILL.md 指令？

A: 大多数情况下，写清楚指令就够了，这也是最容易迭代的方式。只有在需要确定性行为（比如必须严格按特定格式输出）、需要调用外部 CLI 工具、或者需要处理复杂数据变换时，才加入脚本。