Codex配置Skill实现步骤详解

一、Codex Skills 是什么

先说一个核心概念：Codex Skills 是 OpenAI Codex（CLI/IDE 袋里）的可复用工作流技能包。简单来说，就是把「任务指令 + 脚本 + 参考资料」打包成一个标准化模块，让 AI 能稳定执行特定开发任务。这相当于给 Codex 写好的SOP 作业流程。

• 本质：可复用、可共享、可版本化的自动化任务单元
• 核心价值：一次定义，随处调用；减少重复提示词，降低 token 消耗，提升结果一致性

二、Skill 结构（标准格式）

每个 Skill 其实就是一个文件夹，里面必须包含一个 SKILL.md 文件，其他脚本、参考资料、资源文件都是可选的，按需添加即可。来看一个典型的目录结构：

my-skill/
├── SKILL.md       # 必选：名称、描述、触发条件、步骤、输入输出
├── scripts/       # 可选：辅助脚本（bash/python 等）
├── references/    # 可选：文档、示例、规范
└── assets/        # 可选：配置文件、模板

下面是一个 SKILL.md 的示例，采用 YAML 头信息加正文的格式，直接复制就能用：

---
name: systematic-debugging
description: 系统化调试：复现问题→缩小范围→定位根因→验证修复
---

## 触发条件
用户提到 bug、报错、异常、调试、定位问题时自动调用

## 执行步骤
1. 确认复现步骤与环境
2. 二分法缩小问题范围
3. 定位根因（日志/堆栈/依赖）
4. 给出修复方案并验证

三、调用方式（3 种）

1. 显式调用（手动）
   • 前缀 $：$.systematic-debugging
   • 命令 /skills：列出所有可用技能，直接选择
2. 隐式调用（自动）
   • 当你的需求和 Skill 的 description 或触发条件匹配时，Codex 会自动识别并调用，你完全无需手动指定
3. 手动配置（搭配下面五中的手动创建skill）
   • 找到系统中的 .codex 目录
     • mac 通常在：/Users/账户名/.codex
     • Windows 通常在：C:Users你的用户名.codex
   • 找到目录下的 skills 目录，cd 进去
   • 创建工程目录，工程目录可以和 SKILL.md 的 name 不一样（推荐一致）
   • 创建或把现有的 SKILL.md 放在创建的工程目录下
   • 在 Codex 中创建新的对话框，这一步很重要，旧的对话框由于缓存等原因，是读取不到新添加的 SKILL 的
   • 新对话框中可以直接对话触发生效：后续在 project 项目中默认使用 project-sensitive-guard skill

四、常用内置 / 推荐 Skill（2026）

• systematic-debugging：系统化调试（最优先安装，减少无效修改）
• deep-research：深度调研（权威源→比对时间→整理结论）
• coding-agent：并行协作（主线 + 旁路任务拆分，提升效率）
• create-plan：任务拆解（大需求拆成可执行小步骤）
• find-skills：技能发现（自动匹配当前任务所需技能）

五、创建 Skill（3 种方法）

1. Prompt-to-Skill（快速）

   直接对 Codex 说：

   请创建一个 Skill，以后我给你网页项目时，先检查移动端排版、按钮样式、文字层级、颜色规范，最后输出修改文件和结果。

2. 固化流程（推荐）

   先手动跑通一次完整流程，满意后说：

   把刚才的流程固化成一个 Skill，命名为 xxx，按标准格式生成 SKILL.md 和文件夹结构。

3. 手动创建（看情况）

   手动创建 SKILL.md 文档，比如：

   ---
   name: project-sensitive-guard
   description: 在 project 项目中保护敏感配置和凭据文件。
   
   ---
   
   # project 敏感信息保护
   
   在 `project` 项目中工作时，严格遵守以下规则：
   
   - 不读取 `project/env/**`
   - 不读取 `.env` 或 `.env.*`
   - 搜索仓库时排除敏感路径
   

六、核心特性

• 渐进式加载：启动时只加载名称和描述，真正调用时才加载完整内容，省 token、响应快
• 多范围存储：
  • System：系统内置
  • User：个人全局
  • Repo：项目共享（团队协作）
• 沙盒执行：独立环境运行，支持多技能并行，互不干扰
• 生态兼容：遵循 Open Agent Skills 标准，可在 Claude、Copilot 等工具间复用

七、和 Custom Prompts 的区别

• Custom Prompt：一次性 / 会话级，上下文丢失就失效，长提示词消耗大量 token
• Skill：持久化 / 模块化，可版本控制、共享、复用，按需加载更高效