从零开始学习 Codex Skill

原创

我们经常会重复向 Codex 提出相似的要求，例如整理会议记录、检查代码规范，或者按照固定模板生成文档。如果每次都重新描述完整流程，不仅麻烦，输出格式也容易发生变化。Codex Skill 可以把一套常用的工作方法保存下来，让 Codex 在遇到合适的任务时重复使用。本文以一个名为 summarize-notes 的 Skill 为例，介绍 skill 的基本构造和使用。

1. 什么是 Codex Skill

Skill 可以理解为一份提供给 Codex 的“任务说明书”。类似于你跟 GPT 日常对话提供的 prompt，它包含了各种信息，例如这个这个 Skill 适合处理什么任务，什么时候该使用它，如何使用等等。例如，我们可以创建一个 summarize-notes Skill，专门把零散笔记整理成以下内容：

• 简短摘要；
• 关键要点；
• 待办事项；
• 待确认问题。

以后只要告诉 Codex“帮我整理下面的会议笔记”，Codex 就可以按照这套固定流程工作。如上所述，Skill 和普通提示词的区别在于：普通提示词通常只在当前对话中使用，而 Skill 是可以保存、复用和共享的工作流程。

2. 一个 Skill 由哪些文件组成

一个常见的 Skill 目录如下：

summarize-notes/
├── SKILL.md  # 必须有
├── agents/
│   └── openai.yaml
├── scripts/
├── references/
└── assets/

各文件和目录的用途如下：

文件或目录	是否必需	用途
SKILL.md	是	定义 Skill 的名称、触发场景和具体工作流程
agents/openai.yaml	否	配置界面名称、简介、默认提示词、调用策略和工具依赖
scripts/	否	保存需要稳定、重复执行的脚本
references/	否	保存规范、API 文档和领域资料等参考内容
assets/	否	保存模板、图片、字体等输出资源

3. 创建第一个 Skill

Codex 内置了 skill-creator，可以在 Codex CLI 或 IDE 扩展中输入下面的内容，让它帮助我们创建 Skill，在对话中输入 $skill-creator 然后描述自己的需求：

请创建一个 summarize-notes Skill，把零散笔记整理成摘要、要点、待办和待确认问题。

上面这个方法比较简单，还有第二个方法就是手动创建。如下琐事

cd ~/Downloads/output
mkdir -p summarize-notes/agents

创建完成后的目标结构是：

~/Downloads/output/summarize-notes/
├── SKILL.md
└── agents/
    └── openai.yaml

SKILL.md 是整个 Skill 的核心文件。一个最小的 SKILL.md 必须在开头包含 YAML Front Matter，并定义 name 和 description：

---
name: summarize-notes
description: 将零散的会议、学习或访谈笔记整理成摘要、要点、待办和待确认问题。用户要求整理、清理、总结笔记或提取行动项时使用；翻译文本或润色已经成型的文章时不要使用。
---

# 整理笔记

读取用户提供的全部笔记，然后按照以下流程处理：

1. 找出笔记的主题和主要结论。
2. 合并重复内容，但保留重要的人名、日期、数字和限制条件。
3. 提取负责人、截止时间和具体行动，组成待办事项。
4. 将缺少负责人、时间或必要信息的内容放入待确认问题。
5. 按照规定格式输出结果。

不要补充原始笔记中不存在的事实。如果某部分没有内容，写“无”。

## 输出格式

### 摘要

用一段简短文字概括笔记。

### 关键要点

- 要点一
- 要点二

### 待办事项

- [ ] 任务；负责人：姓名或待确认；截止时间：日期或待确认

### 待确认问题

- 问题一

• name 是 Skill 的调用名称。显式调用时应该输入：$summarize-notes。建议名称只使用小写字母、数字和连字符，并尽量做到简短、明确。目录名最好和 name 保持一致，减少安装和排查问题时的困惑。
• description 的作用：不只是写给人看的简介，也是 Codex 判断是否应该自动使用这个 Skill 的重要依据。一个比较好的 description 应该同时说明：

• Skill 能做什么；
• 哪些用户表达应该触发它；
• 哪些相似任务不应该触发它。

Codex 首先看到 Skill 的名称和描述，决定使用后才会读取完整的 SKILL.md。因此，description 应该简洁，但不能省略关键的触发条件。例如，只写下面这句话就比较模糊：

# 不清楚的表达
description: 用来处理笔记。

# 清晰的表达
description: 将零散的会议、学习或访谈笔记整理成摘要、要点、待办和待确认问题。用户要求整理、清理、总结笔记或提取行动项时使用；翻译文本或润色已经成型的文章时不要使用。

编写 agents/openai.yaml

agents/openai.yaml 是可选文件，主要用于配置 Skill 的界面信息和调用策略。我们的示例可以写成：

interface:
  display_name: "笔记摘要"
  short_description: "把零散的会议、学习与访谈笔记整理成摘要、要点、待办和待确认问题"
  default_prompt: "使用 $summarize-notes 将下面的零散笔记整理为摘要、要点、待办事项和待确认问题。"

policy:
  allow_implicit_invocation: true

各字段的含义如下：

字段	含义
display_name	展示给用户看的名称，例如 Skill 列表中的“笔记摘要”
short_description	展示给用户看的简短功能说明
default_prompt	用户选择该 Skill 时可使用的默认起始提示词
allow_implicit_invocation	是否允许 Codex 根据用户请求自动选择该 Skill，默认值为 true

这里最容易混淆的是 display_name 和 SKILL.md 中的 name：

display_name: 笔记摘要       # 展示名称
name: summarize-notes       # 调用名称

因此应该使用 $summarize-notes 调用，而不是 $笔记摘要。

4. 安装 Skill

安装为用户级 Skill

如果希望这个 Skill 在自己的不同项目中都可以使用，可以把整个目录复制到用户级 Skill 目录：

mkdir -p ~/.agents/skills
cp -R ~/Downloads/output/summarize-notes ~/.agents/skills/

安装为项目级 Skill

如果某个 Skill 只适用于一个代码仓库，可以将它放到仓库的 .agents/skills 目录：

cd /path/to/your-project
mkdir -p .agents/skills
cp -R ~/Downloads/output/summarize-notes .agents/skills/

项目成员可以把这个目录提交到 Git，从而共享同一套工作流程。Codex 会从当前工作目录开始向仓库根目录扫描 .agents/skills。因此，Skill 放在不同层级时，可以分别服务于某个子目录或整个仓库。

5. 查看和调用 Skill

查看 Skill

Codex 通常会自动检测 Skill 的新增和修改。如果列表没有更新，可以重新启动 Codex，再打开一个新会话检查。输入 /skills

显式调用

显式调用就是直接在提示词中写出 Skill 名称：

$summarize-notes 请整理下面的会议笔记：

新版功能计划下周五上线。小王负责测试，小李整理发布文档，测试完成后再确定具体发布时间。

这种方式最明确，适合测试 Skill，或者必须保证使用某个 Skill 的场景。

自动触发

如果 allow_implicit_invocation 没有设置为 false，Codex 可以在用户请求符合 description 时自动选择 Skill。此时不需要写 $summarize-notes，直接描述任务即可：

帮我把下面的会议记录整理成摘要、关键要点、待办和待确认问题：

……

自动触发由 Codex 根据语义判断，并不等于每次都强制触发。如果需要稳定复现，仍然建议显式写出 $summarize-notes。

如果不希望 Codex 自动调用，可以修改 agents/openai.yaml：

policy:
  allow_implicit_invocation: false

关闭后，显式使用 $summarize-notes 仍然有效。

本文由 Yonghui Wang 创作，采用 知识共享署名4.0 国际许可协议进行许可
本站文章除注明转载/出处外，均为本站原创或翻译，转载前请务必署名
最后编辑时间为: Aug 15, 2026 02:38 pm