Skills
把高频操作封装成可复用的指令，让 Codex 一键执行复杂流程
一份 SKILL.md，按需触发；一次定义，反复生效从零开始
你每次都要教 Codex 怎么完成同一个任务
场景一：写论文引言
"帮我写一段引言，要包含研究背景、问题陈述、贡献点，用学术语气，引用近三年的文献。"
你花了 5 分钟描述格式要求。
场景二：又要写引言
下周写另一篇论文，你又要重新描述一遍同样的格式要求。
第三次。第五次。每次都在重复。
根本原因
AGENTS.md 解决的是"项目规则"，但任务级的操作流程没有被封装。你需要一种机制，把"怎么做某件事"写一次，以后直接调用。
开始之前
适合谁
- 经常让 Codex 做同类任务（写文档、查论文、操作 PR）
- 想把自己的工作流程标准化，减少重复描述
- 想复用社区或团队共享的 Skill 模板
你将学会
- 理解 Skill 的本质与目录结构
- 查阅 内置 System Skills 的能力
- 创建自己的自定义 Skill
- 掌握 Skill 的渐进式加载机制
本章不覆盖
- AGENTS.md（第 02 章）：项目级规则
- Slash Commands（第 03 章）：命令入口
- MCP（第 06 章）：工具扩展
是什么
给 AI 的"工作手册"——在什么场景、按什么规则、用什么工具
一句话定义
Skill 是一个目录，里面有一个 SKILL.md 文件。它告诉 Codex：在什么场景下、按什么规则、用什么工具完成任务。
类似物
- 给新员工的 SOP 操作手册
- 函数库里的 API 文档
- 烹饪食谱——食材、步骤、火候
核心特征
- 按需触发：不是每次加载，而是匹配到场景才激活
- 自包含：指令、脚本、参考文档都在一个目录里
- 可组合：多个 Skill 可以同时生效
Skill vs AGENTS.md
两者互补，不是替代
| 维度 | AGENTS.md | Skill |
|---|---|---|
| 作用域 | 项目级，始终生效 | 任务级，按需触发 |
| 内容 | "你该怎么做事"（规则） | "怎么做这件事"（流程） |
| 加载时机 | 会话启动时全部加载 | 匹配到 description 才加载 |
| 文件格式 | 单个 Markdown 文件 | 目录 + SKILL.md + 资源 |
| 典型例子 | "用 TypeScript，命名用 camelCase" | "review PR 时按这个 checklist 逐项检查" |
目录结构
一个 Skill 就是一个自包含的文件夹
skill-name/
├── SKILL.md # 必需：核心指令文件
│ ├── YAML frontmatter # 必需：name + description
│ └── Markdown body # 必需：具体指令内容
├── agents/ # 推荐：UI 元数据
│ └── openai.yaml
└── Bundled Resources # 可选：辅助资源
├── scripts/ # 可执行脚本
├── references/ # 参考文档
└── assets/ # 模板、图标等SKILL.md 是必需的。其他目录按需添加，让 Skill 从"纯指令"升级为"带工具的工作流"。
SKILL.md 结构
frontmatter 决定触发，body 决定执行
--- 包裹的一段元数据（YAML 格式）。你可以把它理解为这个 Skill 的"身份证"——Codex 不读这里的正文内容，只读这里的字段（如 name、description）来决定"要不要激活这个 Skill"。三条横线下方的正文叫 body，才是 Skill 被激活后真正执行的指令。
---
name: skill-name
description: 一句话描述，决定何时触发此 Skill
---
# Skill 标题
## 使用说明
在这里写具体的操作步骤、注意事项和输出格式。
## 示例
给出一个典型用例，帮助 Codex 理解你的期望。frontmatter 字段
name（必需）：Skill 的唯一标识description（必需）：最关键——Codex 根据这段描述判断何时激活此 Skill
body 内容
- 具体的操作步骤和规则
- 输入输出格式要求
- 引用的脚本或参考文档路径
- $ARGUMENTS 占位符接收用户参数
description 决定触发
写好 description 是 Skill 成功的关键
好的 description
description: 生成或编辑 raster 图片，
适用于封面、插图、去背景等场景。
用户说"画个封面""去背景"时触发。✅ 说明了做什么、什么时候、典型触发词
差的 description
description: 图片工具❌ 太模糊，Codex 不知道何时该用这个 Skill
内置 System Skills
开箱即用，覆盖常见任务场景
| Skill | 一句话用途 | 典型触发词 |
|---|---|---|
| imagegen | AI 生图 / 编辑图片 | "画个封面""去背景" |
| openai-docs | 实时查 OpenAI 文档 | "最新 API""当前定价" |
| github | 操作 PR / Issue | "开 PR""回复 CR" |
| browser | 浏览器自动化 | "打开网页""截图" |
| computer-use | 桌面操控 | "点按键""填表单" |
| documents | Word 文档 | "转 docx""加特征" |
| PDF 读写 | "加水印""转图片" | |
| presentations | PPT 制作 | "做分享""改字帖" |
| spreadsheets | Excel 操作 | "算平均值""加公式" |
| skill-creator | Skill 脚手架 | "新建 skill" |
| plugin-creator | 插件脚手架 | "打包发布" |
按能力分类
Skill 可以归为四大类
🎨 内容创作
- imagegen — AI 生图与图片编辑
- documents — Word 文档处理
- presentations — PPT 制作
- spreadsheets — Excel 操作
- pdf — PDF 读写
🔧 开发工具
- github — PR / Issue 操作
- browser — 浏览器自动化
- computer-use — 桌面操控
- openai-docs — 文档查询
🚀 平台扩展
- skill-creator — Skill 脚手架
- plugin-creator — 插件脚手架
自定义 Skill
在两个位置创建，作用域不同
全局 Skill
~/.codex/skills/
└── my-skill/
└── SKILL.md对所有项目生效，适合个人通用的工作流（如写作风格、代码审查偏好）。
项目 Skill
.codex/skills/
└── my-skill/
└── SKILL.md仅对当前项目生效，适合项目特有的流程（如发布 checklist、部署流程）。
自定义 Skill 示例
一个实际的 commit message 规范 Skill
---
name: commit-message
description: 生成符合 Conventional Commits 规范的
commit message。当用户说"帮我写个 commit message"
或"生成提交信息"时触发。
---
# Commit Message 生成器
## 规则
1. 格式：`<type>(<scope>): <subject>`
2. type 必须是以下之一：
- feat: 新功能
- fix: 修复 bug
- docs: 文档变更
- refactor: 重构
- test: 测试相关
- chore: 构建/工具变更
3. subject 用中文，不超过 50 字
4. 不要加句号
## 输入
$ARGUMENTS（用户的改动描述）
## 输出
直接输出一行 commit message，不要解释。加载机制
渐进式加载，按需激活
第一步：扫描 frontmatter
Codex 启动时扫描所有可用 Skill 目录，只读取 SKILL.md 的 YAML frontmatter（name + description）。这一步很轻量。
第二步：匹配 description
当用户发出请求时，Codex 将请求与各 Skill 的 description 进行语义匹配。匹配度最高的 Skill 被选中。
第三步：加载 body
只有被选中的 Skill 才会加载 Markdown body 内容。未匹配的 Skill 不占用上下文窗口。
第四步：按需加载资源
如果 body 中引用了 scripts/、references/ 或 assets/，这些文件在需要时才被读取。
加载流程
从用户请求到 Skill 激活的完整路径
用户输入
│
▼
┌─────────────────────────────┐
│ 1. 扫描所有 Skill 目录 │
│ 读取 frontmatter │
│ (name + description) │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ 2. 语义匹配 │
│ 用户意图 vs description │
│ 选出最佳匹配 Skill │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ 3. 加载 SKILL.md body │
│ 注入到上下文窗口 │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ 4. 按需加载资源 │
│ scripts/ references/ │
│ assets/ │
└──────────────┬──────────────┘
│
▼
Codex 执行任务最佳实践
写出高质量 Skill 的几个原则
description 要精准
包含做什么、什么时候、典型触发词。这是 Skill 能否被正确触发的关键。
body 要简洁
只写 Codex 不知道的信息。它已经很聪明了，不需要教它基础概念。每多一行，就多占一点上下文。
善用 $ARGUMENTS
用 $ARGUMENTS 接收用户传入的参数，让 Skill 更灵活。不要硬编码具体值。
资源按需引用
大段参考资料放 references/，脚本放 scripts/，不要在 body 里堆砌。
常见误区
避开这些坑，Skill 才能好用
❌ 误区一：description 太宽泛
"处理文件"——Codex 不知道什么时候该用。改成"将 Markdown 转换为符合公司模板的 Word 文档"。
❌ 误区二：body 太长
写了 500 行指令。结果：上下文被撑爆，执行变慢。保持精简，复杂逻辑拆到 scripts/。
❌ 误区三：和 AGENTS.md 混淆
"用 TypeScript" 应该放 AGENTS.md。"按以下流程发布 npm 包" 应该放 Skill。规则 vs 流程。
核心回顾
今天你学到了什么
Skill 本质
Skill = 目录 + SKILL.md。description 决定何时触发，body 决定如何执行。是给 AI 的"工作手册"。
内置 Skills
覆盖生图、文档、PPT、浏览器、PR 操作等场景。开箱即用，按需触发。
自定义 Skill
在 ~/.codex/skills/（全局）或 .codex/skills/（项目）创建目录 + SKILL.md 即可。
渐进式加载
扫描 frontmatter → 匹配 description → 加载 body → 按需加载资源。不会撑爆上下文。
要点清单
下次启动前可以做的事
必做
- 浏览内置 Skills，了解哪些场景已覆盖
- 挑一个最常用的 Skill，看它的 SKILL.md 源码
- 理解 description 的匹配逻辑
建议做
- 为自己高频任务创建一个自定义 Skill
- 用 $ARGUMENTS 让 Skill 更灵活
- 把大段参考资料拆到 references/ 目录
警惕
- 不要把所有规则都塞进 Skill
- description 不要写得太模糊
- body 不要超过 100 行
小结
你已经掌握了 Skills 的核心机制
本章要点
- Skill = 目录 + SKILL.md，description 决定触发，body 决定执行
- 内置 System Skills 覆盖生图、文档、PPT、浏览器、PR 操作等
- 自定义 Skill：在 ~/.codex/skills/ 创建目录 + SKILL.md
- 渐进式加载：按需激活，不撑爆上下文