Codex Skills 学习手册
从零开始掌握 Codex 技能系统——把重复工作转化为可复用的自动化工作流
生成日期：2026‑07‑01
阅读说明
本书面向已经掌握 Codex 基础操作、希望进一步提升开发效率的读者。全书采用案例驱动方式，每章都包含学习目标、操作案例、练习、检查清单和常见坑。Skills（技能）是 Codex 最强大的功能之一——它让你可以把常用的开发流程、项目规范、测试脚本等内容封装成可重复调用的模块，从此告别重复输入相同指令的烦恼。简单理解：Prompt 只能解决一次问题，而 Skill 可以永久复用解决方案。
总目录
第一部分：认识 Skills
第 1 章：什么是 Codex Skills
第 2 章：Skills 的工作原理——渐进式披露
第二部分：Skills 的结构与存储
第 3 章：Skill 的目录结构
第 4 章：Skill 的存储位置与作用域
第三部分：创建你的第一个 Skill
第 5 章：使用 Skill Creator 创建
第 6 章：手动创建 Skill（推荐方式）
第 7 章：实战：从零创建一个 XSS 漏洞检测 Skill
第四部分：Skills 的调用与使用
第 8 章：显式调用与隐式调用
第 9 章：Skills 的管理与维护
第五部分：高级技巧与最佳实践
第 10 章：编写高质量 SKILL.md 的核心原则
第 11 章：Skill 与 Plugin 的关系
第 12 章：团队协作与知识沉淀
第六部分：常见问题与排障指南
第 13 章：常见问题与排障指南
第一部分：认识 Skills
第 1 章：什么是 Codex Skills
1.1 官方定义
Codex Skill 是一个封装了可复用工作流的文件夹。一个 Skill 可以包含指令、参考资料、脚本、模板文件以及 MCP 工具依赖，然后统一打包给 Codex 使用。
Skills 是模块化的、自包含的文件夹，通过提供专业知识、工作流和工具来扩展 Codex 的能力。可以把 Skills 理解为特定领域或任务的“入职指南”——它们将 Codex 从通用型 Agent 转变为配备程序性知识的专用 Agent。
1.2 Skills 的核心价值
•
扩展能力：为 AI 代理注入特定领域的专业知识
•
提升效率：避免重复劳动，节省时间
•
保持上下文干净：只在需要时加载相关内容，减少 token 消耗
•
标准化输出：确保技能执行结果可复用、可预期
•
团队共享：技能包可上传 Git，全员同步更新，统一开发标准
1.3 Skill 能做什么？
前端开发 Skill 可以包含 Vue 开发规范、Pinia 状态管理规范、Element Plus 组件规范、Git 提交规范。当你对 Codex 说“创建一个用户管理页面”时，它会自动按照团队规范输出代码。
运维 Skill 可以包含 Docker 部署流程、Nginx 配置规范、PM2 启动命令、故障排查步骤。输入“部署 Node 项目”，Codex 即可自动执行对应流程。
检查清单
我理解了 Skill 的本质是“可复用的工作流封装”
我能区分 Skill 与普通 Prompt 的区别（复用 vs 一次性）
我知道 Skill 可以包含脚本、模板、参考文档等资源
常见坑
•
❌ 把 Skill 当成普通文档：Skill 必须放在正确的目录并遵循 YAML 格式，否则不会被识别。
•
❌ 忽略团队共享：个人 Skill 放在用户级目录，团队 Skill 必须放在仓库级 .agents/skills/ 下。
第 2 章：Skills 的工作原理——渐进式披露
2.1 什么是渐进式披露
Codex Skills 采用 渐进式披露（Progressive Disclosure） 机制来优化性能和资源使用：
•
启动阶段：Codex 启动时，仅加载所有技能的名称和描述（即元数据），不加载完整内容。
•
按需加载：当你的任务匹配某个技能时，Codex 才会完整加载其 SKILL.md 文件。
•
高效运行：仅在实际使用时消耗 tokens，保持上下文简洁、响应迅速。
2.2 为什么这种设计很重要
这种机制的核心优势在于——Codex 只注入技能的 name、description 和文件路径到运行时上下文，正文内容始终留在磁盘上。这意味着你可以在技能中写很长的指令，而不会占用宝贵的上下文窗口。
检查清单
我理解了 Skills 不会在启动时全部加载
我知道技能描述（description）是路由的关键
我明白长指令可以放在 SKILL.md 正文，不影响上下文占用
常见坑
•
❌ 认为技能加载越多越慢：实际上只加载元数据，不影响启动速度。
•
❌ 忽略 description 的作用：描述不清晰会导致隐式调用不触发。
第二部分：Skills 的结构与存储
第 3 章：Skill 的目录结构
3.1 标准目录布局
一个标准的 Skill 目录如下：
代码块
Plain Text
my-skill/
├── SKILL.md # 必需：主指令文件
├── scripts/ # 可选：可执行脚本（Python、Shell等）
├── references/ # 可选：参考文档、模板
├── ../assets/ # 可选：图片、配置文件等资源
└── agents/
└── openai.yaml # 可选：UI元数据与依赖声明
3.2 各目录用途说明
| | |
| | |
| | |
| | |
| | |
| | |
3.3 命名规范
Skill 目录名使用小写 kebab-case（如 xss-scanner、react-ts-init）。
检查清单
我的 Skill 目录包含 SKILL.md 文件
目录名符合 kebab-case 规范
如需要，我已创建 scripts/、references/ 等子目录
常见坑
•
❌ 将 SKILL.md 放在错误的位置：必须在 Skill 根目录，不能在子文件夹。
•
❌ 目录名含大写或空格：会导致识别失败。
第 4 章：Skill 的存储位置与作用域
4.1 不同层级的存储路径
Skills 可以存放在多个层级，适用于不同范围的使用场景：
| | |
| | |
| | |
| | |
| | |
| | |
⚠️ 注意：在旧版 Codex 中，Skills 存放在 ~/.codex/skills/ 目录下。新版本遵循 Agent Skills 开放标准，使用 .agents/skills/ 路径。如果两个技能同名，Codex 不会合并它们，两者都会出现在技能选择器中。
4.2 如何启用 Skills
Skills 功能默认处于实验阶段。需要在配置文件中启用：
在 ~/.codex/config.toml 中添加：
代码块
TOML
[features]
skills = true
然后重启 Codex。也可以单次运行时启用：
代码块
Bash
codex --enable skills
检查清单
我已确认 Skills 功能已启用（config.toml 或启动参数）
我知道不同作用域路径的优先级
我选择了适合当前使用场景的存储位置
常见坑
•
❌ 技能放错路径：例如将用户级技能放入仓库级，导致无法跨项目使用。
•
❌ 忘记重启 Codex：配置更改或新增 Skill 后必须重启。
第三部分：创建你的第一个 Skill
第 5 章：使用 Skill Creator 创建
5.1 Skill Creator 是什么
Codex 提供了内置的 Skill Creator 工具，可以通过交互式问答快速创建技能。
5.2 操作步骤
启动 Codex
输入 $，选择 Skill Creator
输入技能名称
输入主指令（instruction）
Codex 会通过交互式问答帮你完善技能结构
⚠️ 注意：如果生成的技能未保存在正确的 Skills 目录下，你需要手动将其移动到对应位置。
检查清单
我尝试使用 Skill Creator 生成了一个简单技能
我知道生成后的文件默认位置
我能手动移动 Skill 到目标目录
常见坑
•
❌ 依赖 Skill Creator 一步到位：生成的技能可能不完善，需要手动调整。
•
❌ 未检查保存路径：可能默认保存在错误的位置。
第 6 章：手动创建 Skill（推荐方式）
6.1 为什么推荐手动创建
手动创建能让你完全掌控技能结构，适合高级用户，也更容易调试。
6.2 步骤一：创建 Skill 目录
根据你的需求选择作用域，例如用户级技能：
代码块
Bash
mkdir -p ~/.agents/skills/my-first-skill
6.3 步骤二：创建 SKILL.md 文件
代码块
Markdown
---
name: my-first-skill
description: 简短描述这个技能做什么，以及什么时候应该使用它（不超过500字符）
---
6.4 SKILL.md 的格式要求
•
必须包含 YAML frontmatter（用 --- 包裹）
•
name：非空，不超过100字符
•
description：非空，不超过500字符
•
正文可以是任意 Markdown 格式
6.5 步骤三：重启 Codex
Codex 会自动检测技能变化。如果更新没有生效，手动重启 Codex。
检查清单
我能够手动创建 Skill 目录和 SKILL.md
我确保 YAML frontmatter 格式正确
我重启 Codex 并验证技能已加载
常见坑
•
❌ YAML 格式错误：比如缺少 --- 或冒号后没有空格。
•
❌ description 超过 500 字符：会被截断，影响路由。
第 7 章：实战：从零创建一个 XSS 漏洞检测 Skill
7.1 需求分析
在日常开发中，你经常需要检查代码中是否存在 XSS（跨站脚本）漏洞。与其每次都手动描述检测规则，不如将其封装成一个 Skill。
触发场景：当用户提到“安全检查”、“XSS”、“漏洞检测”、“代码审计”时，这个 Skill 应该被触发。
7.2 创建 Skill 目录
代码块
Bash
mkdir -p ~/.agents/skills/xss-scanner
cd ~/.agents/skills/xss-scanner
7.3 编写 SKILL.md
代码块
Markdown
【XSS检测报告】
文件：xxx.js
风险等级：高/中/低
问题描述：...
建议修复方案：...
代码块
Plain Text
## 常见 XSS 模式
- `element.innerHTML = userInput` → 高风险
- `document.write(userInput)` → 高风险
- `eval(userInput)` → 高风险
- `element.textContent = userInput` → 安全
- 使用框架（React/Vue）的自动转义 → 默认安全
7.4 验证 Skill
重启 Codex 后，输入 /skills 查看技能列表，确认 xss-scanner 已加载。然后测试：
代码块
Plain Text
请用 xss-scanner 检测当前项目的 XSS 漏洞
检查清单
我成功创建了 XSS 检测 Skill
我验证了技能可以被显式调用
我尝试用隐式触发（如“做安全检查”）测试了自动匹配
常见坑
•
❌ 检测规则过于宽泛：导致大量误报，应聚焦于典型危险模式。
•
❌ 未提供报告格式：输出不结构化，难以后续处理。
第四部分：Skills 的调用与使用
第 8 章：显式调用与隐式调用
8.1 显式调用（Explicit Invocation）
在提示中直接引用技能名称。在 CLI/IDE 中，使用以下方式：
•
输入 $，然后选择要使用的 Skill
•
在消息中使用 $
•
在 TUI 中使用 /skills 命令浏览和插入技能
8.2 隐式调用（Implicit Invocation）
当你的任务与技能的 description 匹配时，Codex 可以自动选择并调用该技能。
由于隐式匹配依赖于 description 字段，编写描述时要清晰界定技能的适用范围和边界。
示例：如果技能描述是“对代码进行XSS跨站脚本漏洞检测。当用户提到安全检查、XSS、漏洞扫描、代码审计时使用此技能”，那么当你说“帮我做一下安全检查”时，Codex 可能会自动调用这个技能。
检查清单
我能够使用 $ 选择器显式调用技能
我理解隐式调用依赖 description 的匹配
我会在描述中明确触发条件
常见坑
•
❌ 过度依赖隐式调用：有时描述不够精准，自动匹配失败，此时应显式调用。
•
❌ 描述写得太泛：导致在不需要的场景也被触发。
第 9 章：Skills 的管理与维护
9.1 查看已安装的 Skills
在 Codex 会话中输入 /skills，会列出所有可用的技能。
9.2 更新 Skill
直接修改 SKILL.md 文件即可。Codex 会自动检测变化。如果变化未生效，重启 Codex。
9.3 删除 Skill
删除对应的 Skill 目录，重启 Codex 即可。
9.4 安装社区 Skill
Codex 社区有大量现成的 Skills 可供使用：
启动 Codex
输入 $，选择 Skill Installer
输入技能名称，或粘贴 GitHub 仓库 URL
Codex 将自动完成安装
重启 Codex（安装完成后务必重启，否则新技能不会生效）
也可以从 GitHub 上的 Skill 仓库（如 awesome-codex-skills）手动下载 Skill 目录，放入对应的 Skills 路径。
检查清单
我掌握了 /skills 查看技能列表
我知道如何更新和删除技能
我会使用 Skill Installer 安装社区技能
常见坑
•
❌ 更新后未重启：部分更新需要重启才能生效。
•
❌ 社区技能未校验安全性：安装前应审查内容，避免恶意代码。
第五部分：高级技巧与最佳实践
第 10 章：编写高质量 SKILL.md 的核心原则
10.1 描述即路由
Skill 的 description 是路由的关键。它不是营销文案，而是决策边界。
每个 SKILL.md 的 description 都应该回答：
•
什么时候应该使用这个技能？
•
什么时候不应该使用这个技能？
好例子：
代码块
Plain Text
description: 对JavaScript/TypeScript代码进行XSS漏洞检测。当用户明确提到安全检查、XSS、漏洞扫描时使用。不适用于其他类型的安全审计。
坏例子：
代码块
Plain Text
description: 一个很棒的安全工具
10.2 保持简洁（Concise is Key）
上下文窗口是公共资源。Skills 与系统提示、对话历史、其他技能的元数据以及用户请求共享上下文窗口。
核心原则：
•
默认假设：Codex 已经很聪明了
•
只添加 Codex 尚未掌握的信息
•
挑战每一条信息：“Codex 真的需要这个解释吗？”
•
优先使用简洁的例子，而非冗长的解释
10.3 设置适当的自由度
根据任务的脆弱性和可变性匹配具体程度：
| | |
| | |
| | |
| | |
10.4 内容分层存放
不要把所有内容都塞进 SKILL.md：
•
SKILL.md：只保留核心的程序性指令和工作流指导
•
references/：存放详细的参考资料、规范、示例
•
../assets/：存放模板、配置文件等
这样 Codex 只在需要时才加载 reference 文件，保持上下文高效。
10.5 添加负面示例减少误触发
在 description 或指令中明确说明“什么时候不应该使用这个技能”，可以有效减少误触发。
检查清单
我的技能描述清晰且明确触发边界
我尽量精简 SKILL.md 正文，将参考资料移入 references/
我根据任务脆弱性设置了合适的自由度
常见坑
•
❌ 描述过于简短或模糊：导致隐式调用失败。
•
❌ 把大量示例写进 SKILL.md：占用上下文，应放到 references/ 按需引用。
第 11 章：Skill 与 Plugin 的关系
11.1 本质区别
很多人容易混淆 Skill 和 Plugin：
| | |
| | |
| | |
11.2 推荐流程
代码块
Plain Text
Skills 是工作流的创作格式，Plugins 是可复用技能和应用的安装分发单元。先用 Skill 设计工作流本身，然后当你想让其他开发者安装时，再将其打包为 Plugin。
检查清单
我能区分 Skill 和 Plugin 的职责
我知道先写 Skill 再打包为 Plugin 的流程
常见坑
•
❌ 直接开发 Plugin 而忽略 Skill 设计：导致工作流未经充分验证。
•
❌ 混淆两者概念：在交流或文档中错误混用术语。
第 12 章：团队协作与知识沉淀
12.1 共享 Skills
Skills 让团队能够沉淀组织内部知识，并将其转化为可复用、可共享的工作流。
仓库级 Skills：将 Skills 提交到 Git 仓库的 .agents/skills/ 目录下，团队成员拉取代码后即可使用。
团队级 Skills 库：建立统一的团队 Skills 仓库，通过 Skill Installer 或 npm 包分发。
12.2 典型团队用例
Skills 帮助 Codex 在用户、仓库和会话之间保持一致的行为——这在你想自动应用标准约定和检查时特别有用。
典型场景：
•
代码审查规范 Skill
•
项目初始化 Skill（统一技术栈和配置）
•
Git 提交规范 Skill
•
部署流程 Skill
检查清单
我了解如何将 Skill 分享给团队成员
我考虑过为团队建立公共 Skill 仓库
我明白统一 Skill 能提高团队一致性
常见坑
•
❌ 未将 Skill 纳入版本控制：导致团队成员各自为政。
•
❌ Skill 缺乏文档：团队成员不知道如何使用或修改。
第六部分：常见问题与排障指南
第 13 章：常见问题与排障指南
13.1 Skills 没有加载
可能原因：
•
未启用 Skills 功能：检查 config.toml 中 skills = true
•
存放路径不正确：确认 Skill 在正确的 .agents/skills/ 或 ~/.codex/skills/ 目录下
•
未重启 Codex
解决方案：检查配置，移动 Skill 到正确位置，重启。
13.2 SKILL.md 格式错误
可能原因：
•
YAML frontmatter 缺失或格式错误
•
name 或 description 字段为空或超长
•
文件编码问题（如 UTF-8 with BOM）
解决方案：检查 SKILL.md 格式，确保以 --- 开头和结尾，修复后重启 Codex。
13.3 隐式调用不生效
可能原因：
•
description 不够清晰，未能匹配用户意图
•
Skill 的 agents/openai.yaml 中 allow_implicit_invocation 设置为 false
解决方案：优化 description，明确触发条件和使用边界。
13.4 Symlink 不被识别
Codex 会跳过符号链接（symlink）。如果 Skills 是符号链接，可能不会被加载。
解决方案：使用实际目录而非符号链接。
13.5 技能加载失败排查清单
技能是否有明确的触发条件和预期结果？
必需的文件是否存在，路径是否有效？
引用的脚本/资源/参考文件是否实际存在于包中？
操作是否默认安全（超时、限制、约束）？
输出格式是否足够明确以供下游使用？
检查清单
我熟悉常见排障步骤
我知道如何查看日志或启用调试模式（如 --debug）
我能够自行诊断大部分加载问题
常见坑
•
❌ 排障时忘记重启：很多问题在重启后自动解决。
•
❌ 未检查配置文件语法：toml 格式错误会导致功能不生效。
本书各章既可顺序学习，也可按需跳读。建议初学者从第 1 章到第 7 章顺序学习，掌握基础后再根据实际需求阅读高级章节。每章末尾的“检查清单”和“常见坑”可以帮助你快速验证学习成果、规避典型错误。