OpenAI Codex Skills规范详解：目录结构与官方文档未记载的细节

如果你在运行 OpenAI 的 Codex，并想确切了解 skill 系统做了什么，以及文档在哪里停止，以下是格式、它扫描的目录以及我们无法确认的缺口的完整演练。

Codex skills 是 OpenAI 编程智能体在请求匹配文件夹用途时加载的指令文件夹。每个文件夹包含一个 SKILL.md 文件，以及任务需要的可选脚本、参考文档和模板。OpenAI 的文档称 skills 为可重用工作流的创作格式，plugins 为分发方式。

该格式并非 Codex 特有。它是 Agent Skills 标准，最初由 Anthropic 开发并作为开放标准发布，agentskills.io 上的客户端展示列出了 ChatGPT 和 Codex 在读取相同 SKILL.md 文件的产品中。

本页涵盖 Codex 实际读取的内容、它扫描的确切目录、从 Claude skill 转移过来的是什么和什么没有转移、如何在几分钟内添加一个 skill、团队在多人依赖同一 skill 时必须做出的决定，以及 OpenAI 未文档化的部分。

Publisher: Skills Board. Published August 15, 2026. Last checked August 16, 2026.

Codex skill 是一个包含 SKILL.md 文件的目录：YAML frontmatter 包含名称和描述，然后是 Markdown 指令。Codex 在启动时列出名称、描述和文件路径，并在选择该 skill 时读取完整文件。

That loading order is the point of the format. OpenAI calls it progressive disclosure: ChatGPT and Codex start from each skill's name and description, then load the full SKILL.md instructions when they decide to use that skill. Bundled scripts, references, and assets are read only when the instructions call for them, so a folder of installed skills costs very little context until one of them is relevant.

Codex 可以通过两种方式访问一个 skill。你可以在 Codex CLI 和 IDE 扩展中通过 /skills 显式调用它，或者通过输入 $ 并在 ChatGPT 中输入 @ 来提及 skill。Codex 也可以在你的任务匹配 skill 描述时隐式选择一个 skill，这就是为什么描述必须同时说明 skill 做什么以及何时应该触发——使用人们实际会输入的词语。

Codex 查找 skills 的位置

Codex 从 repository、user、admin 和 system 位置读取 skills。对于从其他智能体过来的用户来说，repository 范围令人惊讶：Codex 在当前工作目录到仓库根目录的每个目录中扫描名为 .agents/skills 的目录。

名称不会跨位置合并。OpenAI 文档说明如果两个 skills 共享相同名称，Codex 不会合并它们，两者都可以出现在 skill 选择器中。这与其他智能体应用的优先级规则真正不同，意味着一个个人 skill 和一个 repository skill 如果同名则会共存，而不是其中一个被静默覆盖。

Symlinked skill folders work. Codex follows the symlink target when it scans these locations, which is how one checked-out copy of a skill can serve several repositories without being duplicated in each of them.

The initial list is budgeted. In Codex the startup list includes each skill's name, description, and file path, and it is capped at 2% of the model's context window, or 8,000 characters when the context window is unknown. If many skills are installed, Codex shortens descriptions first, and for large skill sets it may leave some skills out of the initial list and show a warning. The budget applies only to that list: once Codex selects a skill, it still reads the full SKILL.md.

你可以关闭一个 skill 而不删除它。~/.codex/config.toml 中的 [[skills.config]] 条目接收包含 SKILL.md 的 skill 文件夹路径和一个 enabled 标志，config 参考文档记录了这两个键。更改文件后重启 Codex。

Codex 自动检测 skill 变更，OpenAI 在更新未显示时的说明是重启 Codex。这同样适用于刚安装的 skills。

Codex skills 和 Claude skills：实际转移的内容

文件转移了。周围的设置没有。两个产品都实现了相同的 Agent Skills 标准，因此为一个产品编写的 SKILL.md 通常可以被另一个产品读取，但目录、调用语法以及标准之外的每个字段都是产品特定的。

保持在规范内，文件就可以转移。Agent Skills 规范定义了六个 frontmatter 字段：name 和 description 是必需的，license、compatibility、metadata 和 allowed-tools 是可选的。Anthropic 文档说明 Claude Code 接受自己的额外字段，只有六个规范字段在 Claude Code 之外有效。OpenAI 的 Codex 文档描述了 name 和 description 以及自己的 agents/openai.yaml 文件，但没有文档化 Codex 对四个可选规范字段的处理方式。

可移植性关乎格式，而非结果。相同的指令可以在两个产品中加载，但仍然产生不同的工作，因为工具、沙箱和周围指令不同。在告诉队友它在某处工作之前，在每个智能体实际运行的技能中测试该技能。

For the same walkthrough from the Claude side, including the frontmatter table and the surfaces skills run on, see Claude skills: what they are and how to use them.

如何向 Codex 添加 skill，分步说明

有三种有文档记录的方式可以最终获得 Codex 可以使用的 skill：自己编写文件夹、从 Codex 内部安装精选的一个，或安装捆绑 skills 的 plugin。手动方式是值得首先学习的方式，因为其他两种方式会产生相同的结果。

决定 skill 属于哪个范围

每个在仓库中工作的人都应该拥有的 skill 放在仓库根目录的 .agents/skills 中。只有一个服务有意义的 skill 放在该服务目录内的 .agents/skills 中，因为 Codex 扫描从工作目录到根目录的每个级别。仅属于你自己的 skill 放在 $HOME/.agents/skills 中。

创建文件夹和 SKILL.md 文件

创建一个以 skill 命名的目录，并在其中放置一个 SKILL.md 文件。frontmatter 需要 name 和 description。规范要求名称与父目录名称匹配，最多 64 个字符，并使用小写字母、数字和单个连字符。

为触发器编写描述，而不是为读者

description 是 Codex 用于匹配请求的内容，也是安装许多 skills 时被缩短的部分。OpenAI 的指导是编写具有清晰范围和边界的简洁描述，并前置关键用例和触发词，以便在描述被缩短时主机仍能匹配该 skill。

将步骤放在正文，将详细内容放在单独文件中

正文是纯 Markdown，没有格式限制。规范建议将 SKILL.md 保持在 500 行以下，并将详细参考资料移至单独的文件中，因为一旦 skill 激活，整个正文会被读取，而引用文件仅在指令要求时加载。

首次显式调用

在 Codex CLI 或 IDE 扩展中运行 /skills 并选择该 skill，或输入 $ 并按名称提及它。显式调用确认 Codex 找到了文件夹。之后，将其交给隐式匹配，看看你的描述是否在你预期的请求上实际触发。

仅在需要时添加可选元数据

skill 文件夹内的 agents/openai.yaml 文件可以设置显示名称、短描述、图标、品牌颜色和在 ChatGPT 桌面应用中显示的默认提示，声明工具依赖项（如 MCP 服务器），并设置 allow_implicit_invocation 为 false，以便 skill 仅在你显式调用时运行。

或者完全跳过编写

在 Codex 内部，$skill-creator 通过询问 skill 的作用、何时应该触发以及是否需要脚本来起草一个 skill。Record and Replay 捕获你演示的工作流并从中起草一个 skill。$skill-installer 加上精选 skill 名称安装 OpenAI 的一个，并可以提示从其他仓库下载 skills。

SKILL.md 起点

---
name: release-notes
description: Draft release notes from merged pull requests. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
---

## Steps

1. List the merged pull requests since the last tag.
2. Group them into features, fixes, and internal changes.
3. Write one line per user visible change, in plain language.
4. Leave internal refactors out unless they change behavior.

## Output

A Markdown section titled with the version and date.

团队如何在 Codex 和其他智能体中保持一致的推荐

两个问题藏在一个词背后

分发是把文件送到每位队友的机器上。推荐是知道哪个 skill 适合哪个任务、以及为什么选择那个。这两件事 Codex 都有答案——第一个。第二个根本不是 Codex 的问题。

单仓库场景

如果团队使用的所有 skill 都放在大家都在工作的同一个仓库里，答案很简单：把它们提交到仓库根目录的 .agents/skills，Codex 会自动识别，无需额外工具。这是单一仓库团队的最佳方案，没有共享库能做得更好。本页没有任何内容会让你改变这个认知。

分发问题变复杂的时候

但当 skill 来自别人的仓库、当它们在多个仓库中都有用、或者队友使用不同的 agent 时，这就够用了。分发就变得复杂了：OpenAI 的方案是插件，发布到 ChatGPT 和 Codex 共用的插件目录，或者提交到 $REPO_ROOT/.agents/plugins/marketplace.json，或保存在个人目录 ~/.agents/plugins/marketplace.json，然后用 codex plugin marketplace add 添加。Anthropic 的方案是自己的插件系统。两家的打包格式互不兼容。

推荐层

推荐层通常无处安放。团队最终选定了哪个 skill、为什么选它，往往只存在于聊天记录、书签或某一个人的记忆里。Skills Board 就是为这一层设计的共享库：团队推荐使用的 skill 集合，放在一个可搜索的地方，每个条目的原始来源都可见，不强制要求队友使用哪个 agent。

打开原始来源：每个保存的 skill 都记录了它来自哪个仓库和路径，队友可以在把它放到任何地方之前先阅读 SKILL.md。

复制安装命令：适用于命令适合其安装方式的队友。这只是几种选择之一，不是唯一路径。

下载 ZIP：来自源站的最新 skill 文件（在下载时），给那些更喜欢自行放置文件夹的人用，包括放到 .agents/skills。

通过 MCP 连接 agent：经过认证的 MCP 端点让兼容的 agent 搜索同一个团队库并获取安装命令，在授予相应权限后还能保存 skill 和组织集合。登录在浏览器中完成，无需复制 API key。

保存的 skill 是团队推荐，不是安全审查、不是审批、也不是兼容性认证。

Skills Board 跟随保存的源站中的最新版本。它不会固定或保留历史版本。

它不在 Codex 内部安装或运行 skill，也不声称某个 skill 在团队使用的每个 agent 中行为一致。

它不是 .agents/skills 的替代品。文件仍然需要放到 Codex 扫描的路径中，通过每位队友各自选择的方式。

托管产品永久免费，代码采用 MIT 许可证，可以阅读或自行托管全部内容。

实际运营版本（每个 agent 有一个规范来源和经过测试的安装路径）见 Manage skills across Claude Code, Codex, and Cursor。

限制和开放问题

有些大家期望有文档的内容其实没有。以下是我们核查 OpenAI 当前文档时发现的空白，忠实列出而非猜测。

可选规范字段在 Codex 中没有文档

Agent Skills 规范将 license、compatibility、metadata 和 allowed-tools 定义为可选字段，并将 allowed-tools 标记为实验性的，支持程度因实现不同而异。OpenAI 的 Codex skills 文档只描述了 name 和 description 以及它自己的 agents/openai.yaml 文件，对另外四个字段在 Codex 中的行为只字未提。对它们在 Codex 中的行为，请视为未验证。

Codex 文档未提及读取 .claude/skills

文档中记录的位置有：从工作目录到仓库根目录的 .agents/skills、$HOME/.agents/skills、/etc/codex/skills 以及 Codex 捆绑的 skills。没有列出另一个 agent 使用的目录，因此同时服务两个 agent 的仓库需要两个路径都存在，无论是通过复制文件夹还是通过符号链接。

独立 skill 列出了三个接入面

OpenAI 将独立 skill 描述为在 ChatGPT 桌面应用、Codex CLI 和 IDE 扩展中可用，并将插件中捆绑的 skills 描述为在 ChatGPT 网页、桌面和移动端的 Chat 和 Work 中也可用。其他 Codex 接入面没有列出独立 skill，所以不要假设笔记本上的文件夹会在 Codex 运行的任何地方都存在。

两个官方来源指向不同的仓库

Codex skills 文档链接了 openai/skills 作为示例，开源页面将其列为 ChatGPT 和 Codex 可复用 skills 的家园。仓库本身打开后有一个通知标记其为已废弃，并指向 OpenAI plugins 仓库作为当前 Codex skill 和插件示例的所在地。两个页面在上述日期都已核查。

安装多少 skills 没有文档化的上限

初始 skill 列表被限制为模型上下文窗口的 2%，或未知时为 8000 字符，Codex 会缩短描述并可能省略超出部分的 skills，同时发出警告。能够容纳的 skills 数量取决于模型和你描述的长度，所以实际限制是观察出来的而非查出来的。

常见问题

什么是 Codex skill？ Codex skill 是一个包含 SKILL.md 文件的文件夹，文件有 YAML frontmatter 和 Markdown 说明。frontmatter 需要 name 和 description。Codex 在启动时加载 name、description 和文件路径，然后当你的请求匹配 description 或你调用该 skill 时读取整个文件。

Codex CLI 的 skills 放在哪里？ Codex 扫描从工作目录到仓库根目录的每一级目录中的 .agents/skills，所以仓库级 skill 放在拥有它的那个层级的 .agents/skills。个人 skills 放在 $HOME/.agents/skills，机器级 ones 放在 /etc/codex/skills。Codex 也自带捆绑的 skills。

Claude skills 在 Codex 中能用吗？ 文件通常可以。两个产品都从 Agent Skills 标准读取相同的 SKILL.md 格式。位置不同：Claude Code 读取 .claude/skills 和 ~/.claude/skills，Codex 读取 .agents/skills 和 $HOME/.agents/skills。标准六个字段之外的 frontmatter，以及任何 agent 特定的身体语法，不会沿用过去。

如何在 Codex 中安装 skill？ 三条有文档的路径。自己创建文件夹并在其中放入 SKILL.md，放在 Codex 扫描的位置。在 Codex 内部运行 $skill-installer 然后跟一个策展 skill 名称。或者安装捆绑了 skills 的插件。Codex 会自动检测新的 skills，OpenAI 说如果没出现就重启它。

Codex skill 和 AGENTS.md 有什么区别？ AGENTS.md 始终是指导：Codex 启动时从 Codex 主目录到工作目录构建一条指令链，每个任务都携带它。skill 是按需加载的，只有当请求匹配其 description 或你调用它时才加载，所以只在相关时才消耗上下文。

参考链接

OpenAI: build skills for ChatGPT and Codex：skill 目录布局、渐进式披露和初始列表预算、显式和隐式调用、四个位置作用域、符号链接支持、重复名称、skill 创建器和安装器、[[skills.config]] 开关，以及 agents/openai.yaml。

OpenAI: Codex config reference：skills.config 数组及其 path 和 enabled 键，以及让 Codex 提示安装 skill 缺失的 MCP 依赖的功能开关。

Agent Skills specification：六个 frontmatter 字段及其约束、命名规则、可选脚本、references 和 assets 目录，以及渐进式披露和文件大小建议。

Agent Skills: overview and client showcase：该格式作为 Anthropic 最初开发的开放标准，以及列出 ChatGPT 和 Codex 等读取该格式的产品的展示入口。

Claude Code: skills documentation：Claude Code 从哪里加载 skills、斜杠命令调用、符号链接的 skill 文件夹，以及哪些 frontmatter 字段在 Claude Code 之外也能工作。

OpenAI: package your plugin：插件清单和 skills 目录、ChatGPT 和 Codex 共用的插件目录、仓库和个人 marketplace 文件，以及 codex plugin marketplace 命令。

OpenAI: custom instructions with AGENTS.md：Codex 启动时如何从 Codex 主目录到工作目录构建指令链，并合并它找到的文件。

OpenAI: Codex open source components：Codex 的哪些部分是开源的，包括 openai/codex 的 CLI，以及 skills 和插件的列出仓库。

openai/skills on GitHub：策展、实验和系统 skill 文件夹、$skill-installer 用法示例、每个 skill 的许可协议，以及标记该仓库已废弃而推荐 openai/plugins 的通知。

Claude skills: what they are and how to use them

Cursor skills: what they are and how to use them

Manage skills across Claude Code, Codex, and Cursor

How to share AI agent skills with your team

A shared MCP skill library for teams

Originally published at skillsboard.sh/codex-skills.

For further actions, you may consider blocking this person and/or reporting abuse