古法编程

这页解决 OpenAI Codex Skills 的创建、发现、安装、启用/禁用和分发问题。Skills 会先只加载 name、description 和路径，匹配后才读取完整 SKILL.md；要在 ~/.codex/config.toml 禁用某个 Skill，或用 agents/openai.yaml 配置 allow_implicit_invocation、MCP 依赖和界面元数据，可以按这里操作。

OpenAI Codex Skills 创建与安装教程

Use agent skills to extend Codex with task-specific capabilities. A skill packages instructions, resources, and optional scripts so Codex can follow a workflow reliably. Skills build on the open agent skills standard。

Skills 是可复用工作流的创作格式。Plugins 是 Codex 里可安装的分发单元。先用 Skills 设计工作流，再在需要让其他开发者安装时打包成 plugin。

Skills 可在 Codex CLI、IDE extension 和 Codex app 中使用。

Skills 采用 progressive disclosure 管理上下文：Codex 先只看每个 skill 的名称、description 和文件路径，只有决定使用某个 skill 时，才会加载完整的 SKILL.md 指令。

Codex 会把可用 skills 的初始列表放进上下文，方便挑选合适的 skill。为了避免挤占提示词，这个列表的上限大约是模型上下文窗口的 2%，如果不知道上下文窗口大小，则上限为 8,000 个字符。安装的 skills 很多时，Codex 会优先缩短 skill 描述；如果 skill 数量特别大，部分 skills 可能不会出现在初始列表里，Codex 会显示警告。

这个预算只影响初始 skills 列表。Codex 选中某个 skill 后，仍会读取该 skill 的完整 SKILL.md 指令。

一个 skill 本质上是一个目录，里面包含 SKILL.md，以及可选的 scripts 和 references。SKILL.md 必须包含 name 和 description。

my-skill/
  SKILL.md
  scripts/
  references/
  assets/
  agents/
    openai.yaml

Codex 如何使用 Skills

Codex 可以用两种方式激活 skills：

  1. 显式调用：在提示词中直接包含 skill。在 CLI/IDE 中，运行 /skills 或输入 $ 来提及一个 skill。
  2. 隐式调用：当任务与 skill 的 description 匹配时，Codex 可以自行选择这个 skill。

因为隐式匹配依赖 description，所以 description 要简短、边界清晰。把关键用例和触发词放在前面，哪怕后续描述被截短，Codex 也还能匹配到。

创建 Skill

先用内置 creator：

$skill-creator

creator 会询问这个 skill 做什么、什么时候应该触发，以及它是只放指令还是要带脚本。默认是 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。对于 repository，Codex 会从你当前工作目录开始，一直向上扫描到 repository root 的每一层目录中的 .agents/skills。

如果两个 skill 的 name 相同，Codex 不会合并它们；两个都会出现在 skill selector 里。

Skill Scope Location Suggested use
REPO $CWD/.agents/skills
Current working directory: where you launch Codex.		 如果你在某个仓库或代码环境里工作，可以把只适用于某个工作目录的 skill 检入这里，比如只适用于某个 microservice 或 module。
REPO $CWD/../.agents/skills
A folder above CWD when you launch Codex inside a Git repository.		 如果仓库里有嵌套目录，可以把适用于共享父目录的 skill 放在这里。
REPO $REPO_ROOT/.agents/skills
The topmost root folder when you launch Codex inside a Git repository.		 如果你希望整个仓库都能用同一组 skill，可以放在仓库根目录，这些 root skills 对仓库任意子目录都可用。
USER $HOME/.agents/skills
Any skills checked into the user’s personal folder.		 适合个人常用 skills，对用户工作过的任何 repository 都生效。
ADMIN /etc/codex/skills
Any skills checked into the machine or container in a shared, system location.		 适合 SDK scripts、automation，以及给机器上每个用户提供默认 admin skills。
SYSTEM Bundled with Codex by OpenAI. 适合广泛用户群的通用 skills，例如 skill-creator 和 plan。所有人启动 Codex 时都可用。

Codex 支持 symlinked skill folders，扫描这些位置时会跟随 symlink target。

这些位置用于本地创作和发现。如果你要把 reusable skills 分发到单个 repo 之外，或者想把它们和 app integrations 一起打包，就用 plugin。

通过 Plugins 分发 Skills

直接放 skill 文件夹最适合本地编写和 repo 级工作流。如果你要分发 reusable skill、把两个或多个 skills 打包在一起，或者把 skill 和 app integration 一起发布，就把它们打包成 plugin。

Plugins 可以包含一个或多个 skills，也可以选择性地打包 app mappings、MCP server 配置和 presentation assets。

安装精选 Skills 到本地

如果想在本地 Codex 里添加内置之外的 curated skills，可以用 $skill-installer。例如安装 $linear skill：

$skill-installer linear

你也可以让 installer 从其他 repository 下载 skills。Codex 会自动检测新安装的 skills；如果没有出现，重启 Codex。

这适合本地安装和试验。若要把你自己的 reusable skills 分发给别人，优先用 plugins。

启用或禁用 Skills

可以在 ~/.codex/config.toml 里添加 [[skills.config]]，在不删除文件的情况下禁用某个 skill：

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

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

可选元数据

在 skill 目录中添加 agents/openai.yaml，可以为 Codex app 配置 UI metadata、调用策略，并声明工具依赖，让使用这个 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 不会根据用户提示词自动调用这个 skill，但显式的 $skill 调用仍然有效。

最佳实践

  • 每个 skill 只负责一件事。
  • 能用指令就优先用指令，除非你确实需要确定性行为或外部工具。
  • 用命令式步骤写清输入和输出。
  • 用 prompt 测试 skill description，确认触发行为符合预期。

更多示例可参考 github.com/openai/skills 和 the agent skills specification。

常见问题

OpenAI Codex Skills 更新后为什么没生效？

重启 Codex。Codex 会在启动时重新扫描 skill 目录。

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

Codex 不会合并同名 skill，两个都会出现在 skill selector 里。你可以手动选中要用的那个。

什么时候该用脚本，什么时候只写 SKILL.md 指令？

大多数情况下只写 SKILL.md 指令就够了，也更容易迭代。只有在需要确定性行为、必须调用外部 CLI 工具，或者要处理复杂数据变换时，才加入脚本。