codex的skill机制允许你把常见任务打包成可复用的指令单元，Codex会在合适的时机自动调用它们。不过在Windows上配置skill和在macOS或Linux上有一些差异，主要是路径分隔符、文件编码和终端环境这几个方面容易出问题。这篇文章会把Windows下从零配置一个skill的完整流程走一遍，并附上常见的坑和排查方法。
skill到底是什么，存放在哪个目录
简单来说，一个skill就是一个文件夹，里面至少包含一个SKILL.md文件，用来描述这个技能做什么、什么时候触发。Codex启动时会扫描skills目录，把这些描述信息加载进上下文，当你的请求命中某个技能的适用场景时，它就会按照SKILL.md里定义的流程执行。
skill文件的位置有两个层级。全局配置放在用户主目录下的C:\Users\你的用户名\.codex\skills文件夹中，对所有项目生效；项目级配置则放在项目根目录的.codex\skills下，只对当前项目生效，优先级高于全局配置。建议把通用技能放全局，和具体项目绑定的技能放项目内，这样团队协作时通过git就能共享。
可以用PowerShell快速创建目录并确认路径是否正确：
# 创建全局skills目录 New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex\skills" # 进入该目录 cd "$env:USERPROFILE\.codex\skills" # 确认.codex目录是否存在配置文件 ls "$env:USERPROFILE\.codex"
如果你之前没运行过Codex，.codex目录可能不存在，手动创建也没问题，Codex启动时会自动识别。
编写第一个SKILL.md文件
SKILL.md由两部分组成：frontmatter元信息和使用说明正文。frontmatter用两行三个短横线包围，里面的字段告诉Codex这个技能的名称和描述；正文部分则是详细的执行指引，写得越具体，Codex执行得越准确。
下面是一个代码审查技能的完整示例。在C:\Users\你的用户名\.codex\skills\code-review目录下新建一个名为SKILL.md的文件（注意文件名必须全大写，扩展名是小写的md），内容如下：
--- name: code-review description: 对代码变更进行审查，检查潜在bug、命名规范和性能问题。当用户要求review代码或提交PR前检查时使用此技能。 --- # 代码审查流程 执行代码审查时按以下步骤操作： 1. 查看当前变更：运行 git diff --stat 了解改动范围 2. 逐文件审查 git diff 的输出内容 3. 按以下维度给出意见： - 逻辑正确性：是否有空指针、越界、资源泄漏 - 命名规范：变量名和函数名是否表意清晰 - 性能：循环内是否有不必要的重复计算 4. 每条意见标注严重程度：阻断、警告、建议 5. 最后输出汇总表格 输出格式要求：使用中文，按文件分组列出问题。
description字段非常关键，Codex主要根据它来判断什么时候触发这个技能。写description时要包含触发场景的关键词，比如上面的例子中写明了“review代码”“提交PR前检查”这类常见说法，命中率会明显提高。
这里有个Windows特有的坑要特别注意：SKILL.md必须保存为UTF-8编码。如果你用记事本编辑后保存成了GBK或带BOM的编码，中文内容可能乱码，导致Codex解析失败或技能不生效。建议用VS Code编辑，右下角确认编码为UTF-8后再保存。
验证skill是否加载成功并排查常见问题
写完SKILL.md后，打开PowerShell或CMD，进入任意一个项目目录，启动codex，然后直接输入类似“帮我review一下代码”的指令。如果skill生效，你会看到Codex的响应中体现了SKILL.md里定义的流程，比如按文件分组、标注严重程度等。也可以在Codex里直接问它当前加载了哪些skills来确认。
如果技能没有被识别，按下面几个方向排查：
- 目录层级错误：SKILL.md必须直接位于技能文件夹内，不能多套一层或少一层。正确路径是
C:\Users\你的用户名\.codex\skills\code-review\SKILL.md，而不是C:\Users\你的用户名\.codex\skills\SKILL.md。 - 文件名大小写：Windows文件系统本身不区分大小写，但如果文件被同步到其他系统或工具按严格匹配读取，
skill.md可能不被识别，统一写成SKILL.md最保险。 - frontmatter格式：name和description后面必须跟英文冒号加空格，三个短横线必须独占一行，多余的空格会导致解析异常。
- 编码问题：用PowerShell执行
Get-Content .\SKILL.md -Encoding UTF8查看内容是否正常，乱码就重新保存。
另一个常见问题是升级Codex后skills失效，这通常是因为新版本调整了目录约定。可以运行codex --version确认版本，再查阅对应版本的官方说明，必要时把skills目录迁移到新路径下。
进阶技巧：让skill携带脚本和模板
skill文件夹不只能放SKILL.md，还可以放脚本、模板等辅助文件。比如你可以做一个生成组件的skill，在里面放一个模板文件：
# 目录结构示例 # C:\Users\你的用户名\.codex\skills\gen-component\ # SKILL.md # template.vue New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex\skills\gen-component" New-Item -ItemType File -Path "$env:USERPROFILE\.codex\skills\gen-component\template.vue"
在SKILL.md的正文里说明“生成组件时读取本目录下的template.vue作为基础模板，替换其中的占位符后写入目标位置”。这样Codex执行时会把模板内容一并读取，生成的结果风格统一，比纯靠提示词描述稳定得多。
需要注意路径引用的写法。在SKILL.md里描述辅助文件位置时，建议用相对描述（比如“本技能目录下的template.vue”），不要写死绝对路径，否则换机器或换用户名后会失效。如果你的skill需要调用系统命令，Windows下推荐明确指定用PowerShell执行，避免Codex默认调用bash导致找不到命令。
配置好skill之后，日常使用中的重复性工作，比如代码审查、生成注释、规范格式化，都可以沉淀成一个个技能文件，随着积累越来越多，Codex对你的项目会越来越熟悉，输出质量也会稳步提升。