Codex Agent Skills 技能系统

Agent Skills（代理技能）是一种开放的技能组织格式，可以将任务指令、脚本和参考资料整理成可复用的技能，让 AI Agent 按照指定流程完成工作。

在 Codex 中，我们可以通过 Skills 扩展它的工作能力。例如，让 Codex 按照固定规范审查代码、生成测试、编写技术文档或者处理数据文件。

与每次手动输入一大段提示词不同，Skills 可以将经常使用的操作流程保存下来，在需要时重复使用。

一个 Skill 本质上是包含 SKILL.md 文件的目录。这个文件负责描述技能的用途、适用场景以及具体执行步骤。

例如，一个简单的 Skill 目录可以是：

my-skill/
├── SKILL.md           # 必需：技能说明与执行指令
├── scripts/           # 可选：Python、Shell 等脚本
├── references/        # 可选：参考文档
└── assets/            # 可选：模板、图片等资源

其中，只有 SKILL.md 是必需的。对于简单任务，只需要这个文件就可以创建一个 Skill。

什么是 Agent Skills？

Skills 可以理解为提供给 AI Agent 的一套可复用操作说明。

例如，我们希望 Codex 在检查 Python 代码时，始终按照以下要求执行：

• 检查代码语法及潜在运行错误。
• 识别可能存在的安全问题。
• 检查代码可读性和维护性。
• 给出修改建议，并说明原因。
• 未经允许，不直接修改源文件。

如果没有 Skill，可能每次都需要重复输入这些要求。

创建一个代码审查 Skill 后，就可以直接告诉 Codex：

使用 python-code-review 技能，检查当前项目的 Python 代码。

Codex 会读取相关技能说明，并按照定义的规则执行任务。

Skills 可以用于 Codex CLI、IDE 扩展和支持技能的桌面应用。部分技能也可以通过 Plugins 打包，在其他受支持的 ChatGPT 环境中使用。

需要注意，Skill 本身主要提供操作指令和相关资源，并不意味着它自动获得额外权限。真正能够执行哪些操作，仍取决于 Codex 当前可使用的工具和运行环境。

Skills、MCP 与 Plugins 的区别

在使用 Codex 时，经常会同时遇到 Skills、MCP 和 Plugins 三个概念。

例如，一个生成销售报告的 Skill 可以规定如何分析数据、绘制图表和整理结果；MCP 可以提供访问业务数据库的工具；Plugin 则可以将这些能力打包分发。

三者可以配合使用，但一个简单的 Skill 并不需要同时配置 MCP 和 Plugin。

查看 Codex Skills

在支持 Skills 管理功能的 Codex 客户端中，可以查看已安装技能，也可以使用内置创建工具编写新技能。

Codex 提供了 skill-creator，可以通过对话方式创建或修改 Skill。

创建完成后，可以在技能列表中查看对应的技能。

Skills 的工作原理

Codex 可以同时安装多个 Skills，但不会在每次任务开始时都读取所有技能的完整内容。

为了减少上下文占用，Codex 使用渐进式加载（Progressive Disclosure）机制。

渐进式加载

技能加载通常分为以下几个阶段：

1. 发现技能：Codex 读取技能的名称、描述和文件路径等信息。
2. 选择技能：根据用户显式指定的技能，或者当前任务与技能描述的匹配情况，决定使用哪个 Skill。
3. 读取指令：加载对应的 SKILL.md 文件。
4. 读取资源：根据任务需要访问相关的脚本、参考文档或模板。
5. 执行任务：按照技能指令，使用当前环境中可用的工具完成工作。

例如，安装了 20 个 Skills，并不代表 Codex 每次都会将这 20 个技能的完整内容放入模型上下文。

Codex 的初始技能列表有上下文预算限制：最多使用模型上下文窗口的约 2%；无法确定上下文窗口大小时，使用 8,000 字符的预算。

当技能数量较多时，Codex 可能缩短描述，必要时省略部分初始列表中的技能并给出警告。

这个限制主要针对初始技能列表，不表示被选中的 Skill 只能使用这么少的内容。

技能调用方式

Codex 支持显式调用和隐式匹配两种主要方式。

1、显式调用

显式调用是指用户明确指定要使用哪个 Skill。

在 Codex CLI 或 IDE 扩展中，可以使用 /skills 查看或选择技能，也可以通过 $ 引用技能。

例如：

$python-code-review 检查当前项目的代码

这里的 $python-code-review 是 Codex 对话中的技能引用，不是终端中的普通 Shell 命令。

2、隐式匹配

隐式匹配是指用户没有明确指定技能，但 Codex 根据当前任务和 Skill 的 description 判断某个技能是否适用。

例如，用户输入：

帮我检查这个 Python 项目有没有安全问题。

如果安装了适用于 Python 代码审查的 Skill，Codex 可能自动选择该技能。

隐式匹配并不保证每次都会触发，因此 description 应该清楚地描述技能适用于哪些任务，以及哪些情况不应该使用。

Skills 目录结构

一个完整的 Skill 可以包含指令文件、执行脚本、参考资料和其他资源。

my-skill/
├── SKILL.md
├── scripts/
│   └── check.py
├── references/
│   └── coding-rules.md
├── assets/
│   └── report-template.md
└── agents/
    └── openai.yaml

各个文件和目录的作用如下：

对于初学者，建议先从一个 SKILL.md 文件开始。只有确实需要执行代码或使用参考资料时，再添加其他目录。

创建第一个 Skill

创建 Skill 可以通过内置的 skill-creator 完成，也可以手动编写。

方法一：使用 skill-creator

在 Codex 对话中输入：

然后说明希望创建的技能，例如：

帮我创建一个 Python 代码审查 Skill。

要求：
1. 检查代码语法和潜在错误。
2. 检查常见安全问题。
3. 提出可读性和性能方面的建议。
4. 输出包含文件位置、问题和修改建议的报告。
5. 不要自动修改源文件。

创建器会根据任务描述生成技能文件，并可以帮助完善描述和执行步骤。

创建完成后，需要检查生成的 SKILL.md 是否符合预期，并使用实际任务测试调用效果。

方法二：手动创建 Skill

如果希望更清楚地了解 Skills 的结构，可以手动创建。

下面以 Python 代码审查为例。

第一步：创建目录

进入需要使用 Skills 的项目目录，创建技能文件夹：

mkdir -p .agents/skills/python-code-review

目录结构如下：

project/
└── .agents/
    └── skills/
        └── python-code-review/
            └── SKILL.md

第二步：编写 SKILL.md

在技能目录中创建 SKILL.md 文件，写入以下内容：

其中，文件开头的 --- 区域是 YAML 元数据：

• name：技能名称，通常使用简洁的英文标识。
• description：技能的用途和适用条件，也是隐式匹配的重要依据。

后面的 Markdown 正文则定义技能的执行步骤、输出格式和限制条件。

第三步：调用技能

在项目目录启动 Codex 后，可以通过以下提示词调用：

$python-code-review 检查当前项目的 Python 代码。

也可以使用普通任务描述测试隐式匹配：

请对当前 Python 项目进行代码审查，
重点检查安全漏洞和潜在运行错误。

如果技能能够正确加载，Codex 就会参考 SKILL.md 中定义的规则执行审查。

第四步：测试技能

建议分别测试以下情况：

• 明确引用 Skill，检查是否能够正常调用。
• 仅描述 Python 代码审查任务，观察是否自动匹配。
• 要求编写普通 Python 程序，检查是否出现不必要的技能调用。
• 检查最终输出是否包含文件位置、问题描述和修改建议。

通过测试可以进一步调整 description 和具体指令。

建议在项目中保留测试样例，便于以后更新 Skill 时进行回归检查。

Skills 存储位置

Codex 可以从多个位置发现 Skills，包括仓库级、用户级、管理员级和系统内置技能。

常见路径如下：

对于 Git 仓库，Codex 可以从当前工作目录向上扫描到仓库根目录，查找各级 .agents/skills 文件夹。

例如：

project/
├── .agents/
│   └── skills/
│       └── project-review/
└── backend/
    └── .agents/
        └── skills/
            └── api-check/

项目根目录下的技能适合整个项目共享，子目录中的技能则可以用于更具体的模块。

如果两个 Skill 使用相同的 name，Codex 不会自动合并它们，可能会在选择器中同时显示。因此，建议为技能使用清晰且不重复的名称。

如何选择安装位置？

如果技能只用于某个项目，建议保存在项目的 .agents/skills/ 中，并通过 Git 进行版本管理。

如果技能适用于所有项目，例如通用的 Python 代码审查或文档编写规范，可以保存到用户级目录：

~/.agents/skills/

这样不需要在每个项目中重复创建同一个 Skill。

Skills 配置说明

启用与禁用技能

对于本地 Codex，可以通过 ~/.codex/config.toml 中的 [[skills.config]] 配置禁用指定技能。

其中，path 应填写技能对应 SKILL.md 文件的实际路径。

设置 enabled = false 后，可以在不删除技能文件的情况下禁用该技能。

修改配置后，通常需要重启 Codex。

配置技能显示信息

除了 SKILL.md，还可以使用可选文件 agents/openai.yaml 配置技能显示信息及调用策略。

例如：

常见配置项如下：

allow_implicit_invocation 默认允许隐式调用。设置为 false 后，Codex 不会仅根据任务描述自动选择该技能，但仍可以显式引用。

例如，如果某个 Skill 涉及敏感操作，可以选择只允许显式调用。

注意：禁用隐式调用并不等于限制工具权限。涉及删除文件、修改数据库等操作时，仍然需要使用独立的权限和审批机制。

声明 MCP 工具依赖

如果 Skill 需要使用外部 MCP 服务，还可以在 agents/openai.yaml 中声明工具依赖。

例如：

该配置用于声明技能对 MCP 工具的依赖，不应理解为它会自动完成所有 MCP 服务器的安装、授权和连接。

实际使用时，仍需确认运行环境中对应的 MCP 服务可用，并具备所需的访问权限。

安装与分发 Skills

安装精选技能

Codex 提供 skill-installer，用于安装精选技能或从其他仓库获取技能。

例如，在 Codex 对话中输入：

该示例表示调用技能安装器，请求安装名为 linear 的技能。

同样需要注意，这属于 Codex 的技能调用方式，而不是普通终端命令。

技能安装完成后，如果没有出现在技能列表中，可以尝试重新启动 Codex。

从 GitHub 安装技能

除了安装精选技能，还可以从其他代码仓库获取 Skills。

例如，可以使用 skill-installer 按照提示安装指定仓库中的技能，也可以手动将技能目录复制到本地的 .agents/skills/ 或 ~/.agents/skills/ 目录。

安装第三方 Skill 前，建议先检查：

• SKILL.md 中的指令是否清楚，是否包含不必要的操作要求。
• scripts/ 中是否包含未经审查的命令或可执行代码。
• 是否要求访问敏感文件、密钥或其他个人数据。
• 是否需要连接外部服务器，以及这些服务器是否可信。

Skill 中的指令可能影响 Agent 的行为，因此不应将不可信的第三方技能直接用于具有高权限的环境。

使用 Plugins 分发

对于本地使用或项目内共享，直接保存 Skill 目录通常就足够了。

如果需要将技能分发给更多用户，或者同时打包多个技能、MCP 服务和其他资源，可以使用 Plugins。

例如，一个插件可以包含：

my-plugin/
├── plugin.json
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   └── test-generator/
│       └── SKILL.md
└── mcp.json            # 可选：MCP 配置

这里展示的是可移植 Agent Plugins 的基本目录结构。根目录中的 plugin.json 用于描述插件信息。

Plugins 还支持可选的展示资源和其他扩展配置，具体格式以相应版本的官方文档为准。

因此，可以将 Skill 理解为任务能力的定义，而 Plugin 更侧重这些能力的打包、安装与分发。

编写 Skills 的最佳实践

一个好的 Skill 不在于内容写得多，而在于任务边界明确、操作步骤清楚，并且能够稳定复用。

编写时建议注意以下几点：

1. 明确适用范围：说明 Skill 在哪些任务中使用，哪些任务不应该使用。
2. 保持职责清晰：尽量让一个 Skill 围绕一类相关任务，不要混入大量无关功能。
3. 步骤具体：说明需要读取哪些信息、执行哪些操作，以及如何检查结果。
4. 按需使用脚本：确定性计算、批量处理等操作可以使用脚本，简单流程优先使用文字指令。
5. 控制上下文占用：将较长的参考资料放入 references/，仅在需要时读取。
6. 明确输出格式：规定结果中需要包含的内容，例如问题清单、文件路径和修改建议。
7. 进行实际测试：测试显式调用、隐式匹配以及不应该触发技能的情况。

如何编写 description？

description 是 Skill 中非常重要的字段，直接影响 Codex 判断技能适用范围的能力。

例如，下面的描述比较模糊：

description: Helps with Python.

它没有说明技能具体处理哪些任务。

更明确的写法是：

description: Review Python code for bugs,
security issues, and maintainability.
Use when the user requests a Python code review.
Do not use for unrelated programming tasks.

实际编写 YAML 时，如果需要使用多行文本，建议使用 YAML 的折叠文本语法：

description: >-
  Review Python code for bugs, security issues,
  and maintainability. Use when the user requests
  a Python code review. Do not use for unrelated
  programming tasks.

好的 description 应尽量包含三个方面：技能负责什么、什么时候使用，以及什么时候不使用。

常见问题

1、技能创建后没有显示？

首先检查技能是否位于 Codex 能够发现的目录中，以及是否包含文件名正确的 SKILL.md。

然后检查 YAML 元数据是否包含 name 和 description。

如果文件结构没有问题，可以尝试重启 Codex。

2、Skill 为什么没有自动触发？

隐式匹配通常根据技能描述和当前任务进行判断，并不保证每次都触发。

可以优化 description，明确技能用途、触发条件和不适用场景。

如果希望确保使用指定技能，可以通过 $技能名称 显式引用。

3、两个 Skill 名称相同怎么办？

Codex 不会自动将同名技能合并，两个技能可能同时出现在选择器中。

建议为不同技能使用明确、唯一的名称，避免选择时产生混淆。

4、Skill 可以执行 Python 脚本吗？

可以。Skill 可以将 Python、Shell 等脚本放在 scripts/ 目录中，并在 SKILL.md 中说明如何使用。

不过，脚本能否真正执行仍取决于 Codex 的运行环境、文件权限和安全限制。

5、Skill 和 AGENTS.md 有什么区别？

AGENTS.md 通常用于提供项目或目录范围内的持续性工作约定，例如编码规范、测试命令和项目说明。

SKILL.md 则用于定义可以按需调用的特定任务流程，例如代码审查、生成测试或发布检查。

简单来说，AGENTS.md 更偏向项目的通用规则，Skill 更偏向可复用的专项工作流程。两者可以同时使用。

6、一个 Skill 可以包含多个文件吗？

可以。除了必需的 SKILL.md，还可以增加脚本、参考文档和模板等资源。

建议将核心执行要求保留在 SKILL.md 中，详细资料则单独存放，避免单个文件过长。

7、什么时候使用 Skill，什么时候使用 Plugin？

如果只是希望在当前项目中复用一套工作流程，使用 Skill 即可。

如果需要安装、发布或分发包含多个技能和其他集成能力的软件包，可以考虑使用 Plugin。

总结

Codex Skills 提供了一种将任务指令、脚本和资源组织为可复用能力的方式。

创建一个简单的 Skill，只需要准备一个包含 name、description 和执行说明的 SKILL.md 文件。

对于初学者，建议从一个具体的小任务开始，例如 Python 代码审查、测试生成或技术文档整理。先确保 Skill 能被正确调用，再逐步加入脚本、参考资料和外部工具。

通过 Skills，可以把重复使用的提示词和操作规范整理成长期维护的工作流程，让 Codex 在不同任务中按照相对一致的方式执行操作。

更多资料：

• Codex 与 ChatGPT Skills 官方文档
• Agent Skills 开发文档
• Plugins 打包与分发文档
• OpenAI Skills GitHub 仓库