最近 Codex 的 Skills 功能讨论度非常高。很多人装好了 Codex CLI 之后第一反应是“下一步装什么 Skills”但打开 GitHub 一搜仓库又多又杂有的是纯前端方向有的是测试专用有的是论文写作向根本不知道哪些值得装。这篇文章我从社区高频出现的 Codex Skills 里筛选了 8 个方向逐个验证了安装方式、目录规范、实际使用效果也整理了安装过程中最常遇到的几个报错。内容偏实战适合已经装了 Codex、正准备折腾 Skills 的开发者如果你还没装 Codex也可以先从第 2 章的环境准备开始看。需要提前说明的是Skills 生态更新很快不同版本 Codex 的加载机制和配置项名称可能略有差异。本文会尽量以稳定的目录结构为例但遇到版本差异时请以官方仓库和官方文档为准。1. 为什么 Codex Skills 值得单独研究先用一个通俗的方式理解 Skills它相当于给 Codex 准备的“岗位说明书”或“操作手册”。平时我们用 Codex 写代码是直接给一句话指令比如“帮我写一个登录接口”。模型会依据自己的训练知识和当前仓库上下文来生成代码。但如果你希望 Codex 每次写登录接口时都强制遵循团队规范、先写参数校验、再写异常处理、最后补单元测试那每一次都要在提示词里重复这些要求非常不稳定。Skills 解决的就是这个问题。它把一套固定的工作流、规则、代码风格、检查清单打包成一个目录放在 Codex 能读取到的位置。当 Codex 判断当前任务和某个 Skill 匹配时就会主动读取对应的 SKILL.md 文件并按照里面的步骤来执行任务。从实际使用来看Skills 和普通 Prompt 的核心区别有三点对比项普通 PromptSkills触发方式每次手动编写自动匹配或手动指定复用性复制粘贴容易遗漏固定目录统一维护内容复杂度适合短指令可以包含多步骤、检查清单、代码模板团队协作各写各的仓库共享统一规范也就是说Skills 真正解决了“让 AI 稳定按规范干活”的问题。对于个人开发者可以把自己的高频工作流沉淀成 Skills对于团队可以把代码规范、测试规范、发布规范全部通过 Skills 固化下来减少重复沟通成本。2. 环境准备安装 Codex CLI 并确认 Skills 目录在安装 Skills 之前先把 Codex 环境准备好。下面以最常见的 npm 安装方式为例。2.1 安装 Codex CLInpm install -g openai/codex安装完成后确认版本codex --version如果命令行提示command not found说明 npm 全局 bin 目录没有加入系统 PATH需要手动把 npm 全局目录导出到 PATH或者重新设置 Node.js 环境。2.2 登录账号codex login登录成功后Codex 会生成对应的认证配置。不同版本可能使用不同的登录方式有的是浏览器 OAuth有的是 API Key 配置具体以当前版本提示为准。2.3 VSCode 插件如果你习惯在 VSCode 中使用 Codex可以在扩展市场搜索 “Codex” 官方扩展。安装后VSCode 会直接调用本机已经装好的 Codex CLI。这里有一个高频报错是unable to locate the codex cli binary. set codex cli path or ensure the elec...这个报错的意思是桌面端或插件找不到 codex 命令行工具的路径。解决办法是在插件的设置项里把codex_cli_path显式指定为本机 codex 的绝对路径。which codex # 例如输出 /usr/local/bin/codex就把这个路径填入配置2.4 确认 Skills 目录Codex 读取 Skill 的通用目录是~/.codex/skills/每个 Skill 是一个独立的子目录目录名就是 Skill 名称目录内必须包含一个SKILL.md文件。~/.codex/skills/ └── my-skill/ └── SKILL.md如果你的电脑上还没有这个目录可以手动创建mkdir -p ~/.codex/skills需要注意的是不同版本对 Skills 目录的支持程度可能不同。老版本 Codex 可能只能通过codex exec显式指定 skill新版本则支持自动匹配。建议先确认当前版本的官方文档中 Skills 章节的说明。3. SKILL.md 目录格式与最少示例在安装第三方 Skills 之前先理解 SKILL.md 的写法这样后面排错时不会一头雾水。一个最简单的 SKILL.md 通常包含三部分--- name: demo-skill description: 当需要生成示例代码时使用此技能。 --- # Demo Skill ## 执行步骤 1. 先确认需求。 2. 再生成代码。 3. 最后补充测试用例。 ## 注意事项 - 代码必须添加注释。 - 命名遵循项目现有风格。关键点在于description。Codex 会根据描述判断当前任务是否匹配这个 Skill所以描述写得越具体自动触发就越准确。写好之后把它放在~/.codex/skills/demo-skill/SKILL.md然后启动 Codex输入一个和描述相关的任务观察它是否自动加载了这个 Skill。如果 Codex 没有识别到可以从三个方向排查目录名和 SKILL.md 中的name是否一致。description是否足够明确避免过于宽泛。当前版本是否开启了 Skills 自动发现功能。4. 实测 8 个必装 Skills下面进入正题。这 8 个 Skills 覆盖了全栈开发、前端、测试、学术研究、文本处理、技能发现、自定义开发、模型接入等场景是我从社区高频项目和个人实践中筛出来的组合。4.1 Superpowers Skills综合开发效率增强Superpowers Skills 是社区讨论度很高的一套 Skills 合集核心思路是给 Codex 增加一套“工作流增强”能力。安装方式是把仓库克隆到 Skills 目录cd ~/.codex/skills git clone superpowers仓库地址 superpowers克隆完成后检查目录内是否包含SKILL.md。如果包含的是多个子技能的聚合结构那么需要在~/.codex/skills下再确认 Codex 是否能递归加载。实测感受是它最大的价值不是让 Codex “写更多代码”而是让 Codex 在做任务之前先拆解步骤、定义完成标准、规划文件变更范围。对于比较大的重构任务效果尤其明显。适用人群后端、全栈开发者经常用 Codex 做跨文件重构的开发者。4.2 前端开发 Skills组件生成与代码规范统一前端是 Codex 使用频率最高的场景之一。社区里以“前端开发 Skills”命名的项目不少其中以 Matt Pocock 系列最典型它对 TypeScript、React、Next.js 的支持比较深入。这类 Skills 通常包含TypeScript 类型规范React 组件结构模板常用 UI 库的使用约定样式方案约束安装方式和上面类似克隆到~/.codex/skills即可。重点验证的用法是让 Codex “按项目现有规范生成一个用户列表组件”。装好 Skills 后它会先读取 SKILL.md再依据其中的约定输出组件而不是凭空发挥。适用人群React/Vue 前端开发者、TypeScript 项目维护者。4.3 自动化测试 Skills结合 Playwright 做端到端测试测试类 Skills 在社区里的热度上升很快。很多人用 Codex 生成单元测试觉得效果不错但端到端测试一直比较难落地因为涉及浏览器操作、选择器定位、等待策略等细节。装上测试 Skills 后可以约束 Codex 按照固定模式生成 Playwright 测试脚本比如统一使用test.describe分组每个用例包含明确的test.step选择器优先使用>model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY配置完成后执行export DEEPSEEK_API_KEY你的密钥 codex exec 根据当前目录的 demo-skill 生成一个示例这里想强调的是不同模型对 SKILL.md 的遵循能力不同。实测中模型越强对多步骤指令的执行就越完整如果你用的是轻量模型SKILL.md 写得再规范模型也可能忽略某些步骤。因此装 Skills 的同时尽量选一个上下文窗口大、指令遵循能力强的模型。5. 常见报错与排查思路这一部分把社区里高频出现的 Codex Skills 相关报错整理成表格方便你对照排查。问题现象常见原因解决思路unable to locate the codex cli binary桌面端或插件找不到 codex 可执行文件执行which codex获取路径在插件设置中填写codex_cli_pathSkills 没有自动触发SKILL.md 的 description 描述太宽泛将 description 写得更具体包含触发关键词或手动指定 Skill克隆 Skills 仓库后 Codex 不识别目录层级不正确确保目录结构为~/.codex/skills/技能名/SKILL.md提示某个模型不受支持例如 the xxx model is not supportedconfig.toml 中的模型名与模型服务不支持之间不一致检查 config.toml 中model和model_provider是否匹配换成模型服务支持的标识cc switch local proxy failed while handling codex endpoint /responses本地 API 网关转发 Codex 请求时失败检查本地网关监听端口、config.toml 中的 base_url 是否一致确认模型名可用使用第三方模型时回复格式不对模型不支持 Codex 的 responses 协议优先选择兼容 OpenAI responses 协议或具备兼容层的服务SKILL.md 中引用的脚本没有生效脚本路径不对或没有执行权限在 SKILL.md 中使用相对路径并检查脚本的权限必要时在命令行手动执行验证其中一个值得展开的是cc switch local proxy failed这类问题。很多开发者会使用本地网关类工具统一管理多个模型服务的 API Key 和 Base URL这类工具会监听本机某个端口然后把请求转发到真实模型服务。当你在网关中切换模型服务后Codex 仍然使用旧的 URL 或模型名就会导致/responses接口请求失败。排查顺序是确认本地网关正常启动端口可访问。查看config.toml中base_url是否指向网关监听的地址。确认当前选中的模型服务支持 Codex 使用的接口格式。切换模型后重启 Codex 进程。6. 最佳实践与工程建议6.1 不要一次性装太多 SkillsSkills 数量一多Codex 自动匹配时可能选中错误的技能。建议每个阶段只保留正在使用的 5 到 10 个核心 Skills其余放到备份目录需要时再启用。6.2 描述要具体职责要单一SKILL.md 中的description直接决定了自动匹配的准确率。写得越具体触发越精准。同时一个 Skill 最好只负责一种任务。把“写代码”和“写测试”放在同一个 Skill 里往往两个任务都做不好。6.3 对第三方 Skills 做安全审查Skills 本质上是可执行的指令集个别仓库可能包含恶意指令。安装后第一件事不是运行而是打开 SKILL.md 通读一遍确认没有要求上传敏感文件、执行来源不明的脚本等危险操作。6.4 把 SKILL.md 纳入版本管理团队的 Skills 应该和代码一起版本管理放在独立仓库中。这样新成员入职后只需要 clone 一次就能获得和团队一致的 AI 工作流。6.5 定期更新与清理Skills 的作者会不断修复 bug、更新适配版本。建议每隔一段时间回到仓库拉取最新代码同时删除已经不再使用的技能避免目录变得臃肿。6.6 自己写 Skill 时尽量加入检查清单好的 SKILL.md 不只是告诉 AI “做什么”还要告诉它“什么时候算做完”。在文档末尾增加检查清单能显著提升输出质量。例如## 完成检查 - [ ] 代码不包含未使用的变量 - [ ] 所有错误分支都有处理 - [ ] 已补充最小测试用例7. 总结与下一步这篇文章从 Codex Skills 的运行机制讲起给出了 8 个值得安装的 Skills 方向包括综合开发增强、前端规范、自动化测试、学术研究、自然语言处理、技能管理、自定义模板、模型接入配置并整理了安装和运行过程中的高频报错。对刚开始接触 Skills 的读者建议先按第 2 章准备好环境然后从第 4.1 节 Superpowers 或第 4.2 节前端 Skills 开始尝试。装好之后不需要刻意记住每个 Skill 的细节只需要在真实任务中观察 Codex 是否按照预期工作再逐步调整。如果你已经用了一段时间下一阶段可以重点研究自定义 Skills 开发把团队规范和个人工作流固化成 SKILL.md这才是 Skills 功能的长期价值所在。
最近 Codex 的 Skills 功能讨论度非常高。很多人装好了 Codex CLI 之后第一反应是“下一步装什么 Skills”但打开 GitHub 一搜仓库又多又杂有的是纯前端方向有的是测试专用有的是论文写作向根本不知道哪些值得装。这篇文章我从社区高频出现的 Codex Skills 里筛选了 8 个方向逐个验证了安装方式、目录规范、实际使用效果也整理了安装过程中最常遇到的几个报错。内容偏实战适合已经装了 Codex、正准备折腾 Skills 的开发者如果你还没装 Codex也可以先从第 2 章的环境准备开始看。需要提前说明的是Skills 生态更新很快不同版本 Codex 的加载机制和配置项名称可能略有差异。本文会尽量以稳定的目录结构为例但遇到版本差异时请以官方仓库和官方文档为准。1. 为什么 Codex Skills 值得单独研究先用一个通俗的方式理解 Skills它相当于给 Codex 准备的“岗位说明书”或“操作手册”。平时我们用 Codex 写代码是直接给一句话指令比如“帮我写一个登录接口”。模型会依据自己的训练知识和当前仓库上下文来生成代码。但如果你希望 Codex 每次写登录接口时都强制遵循团队规范、先写参数校验、再写异常处理、最后补单元测试那每一次都要在提示词里重复这些要求非常不稳定。Skills 解决的就是这个问题。它把一套固定的工作流、规则、代码风格、检查清单打包成一个目录放在 Codex 能读取到的位置。当 Codex 判断当前任务和某个 Skill 匹配时就会主动读取对应的 SKILL.md 文件并按照里面的步骤来执行任务。从实际使用来看Skills 和普通 Prompt 的核心区别有三点对比项普通 PromptSkills触发方式每次手动编写自动匹配或手动指定复用性复制粘贴容易遗漏固定目录统一维护内容复杂度适合短指令可以包含多步骤、检查清单、代码模板团队协作各写各的仓库共享统一规范也就是说Skills 真正解决了“让 AI 稳定按规范干活”的问题。对于个人开发者可以把自己的高频工作流沉淀成 Skills对于团队可以把代码规范、测试规范、发布规范全部通过 Skills 固化下来减少重复沟通成本。2. 环境准备安装 Codex CLI 并确认 Skills 目录在安装 Skills 之前先把 Codex 环境准备好。下面以最常见的 npm 安装方式为例。2.1 安装 Codex CLInpm install -g openai/codex安装完成后确认版本codex --version如果命令行提示command not found说明 npm 全局 bin 目录没有加入系统 PATH需要手动把 npm 全局目录导出到 PATH或者重新设置 Node.js 环境。2.2 登录账号codex login登录成功后Codex 会生成对应的认证配置。不同版本可能使用不同的登录方式有的是浏览器 OAuth有的是 API Key 配置具体以当前版本提示为准。2.3 VSCode 插件如果你习惯在 VSCode 中使用 Codex可以在扩展市场搜索 “Codex” 官方扩展。安装后VSCode 会直接调用本机已经装好的 Codex CLI。这里有一个高频报错是unable to locate the codex cli binary. set codex cli path or ensure the elec...这个报错的意思是桌面端或插件找不到 codex 命令行工具的路径。解决办法是在插件的设置项里把codex_cli_path显式指定为本机 codex 的绝对路径。which codex # 例如输出 /usr/local/bin/codex就把这个路径填入配置2.4 确认 Skills 目录Codex 读取 Skill 的通用目录是~/.codex/skills/每个 Skill 是一个独立的子目录目录名就是 Skill 名称目录内必须包含一个SKILL.md文件。~/.codex/skills/ └── my-skill/ └── SKILL.md如果你的电脑上还没有这个目录可以手动创建mkdir -p ~/.codex/skills需要注意的是不同版本对 Skills 目录的支持程度可能不同。老版本 Codex 可能只能通过codex exec显式指定 skill新版本则支持自动匹配。建议先确认当前版本的官方文档中 Skills 章节的说明。3. SKILL.md 目录格式与最少示例在安装第三方 Skills 之前先理解 SKILL.md 的写法这样后面排错时不会一头雾水。一个最简单的 SKILL.md 通常包含三部分--- name: demo-skill description: 当需要生成示例代码时使用此技能。 --- # Demo Skill ## 执行步骤 1. 先确认需求。 2. 再生成代码。 3. 最后补充测试用例。 ## 注意事项 - 代码必须添加注释。 - 命名遵循项目现有风格。关键点在于description。Codex 会根据描述判断当前任务是否匹配这个 Skill所以描述写得越具体自动触发就越准确。写好之后把它放在~/.codex/skills/demo-skill/SKILL.md然后启动 Codex输入一个和描述相关的任务观察它是否自动加载了这个 Skill。如果 Codex 没有识别到可以从三个方向排查目录名和 SKILL.md 中的name是否一致。description是否足够明确避免过于宽泛。当前版本是否开启了 Skills 自动发现功能。4. 实测 8 个必装 Skills下面进入正题。这 8 个 Skills 覆盖了全栈开发、前端、测试、学术研究、文本处理、技能发现、自定义开发、模型接入等场景是我从社区高频项目和个人实践中筛出来的组合。4.1 Superpowers Skills综合开发效率增强Superpowers Skills 是社区讨论度很高的一套 Skills 合集核心思路是给 Codex 增加一套“工作流增强”能力。安装方式是把仓库克隆到 Skills 目录cd ~/.codex/skills git clone superpowers仓库地址 superpowers克隆完成后检查目录内是否包含SKILL.md。如果包含的是多个子技能的聚合结构那么需要在~/.codex/skills下再确认 Codex 是否能递归加载。实测感受是它最大的价值不是让 Codex “写更多代码”而是让 Codex 在做任务之前先拆解步骤、定义完成标准、规划文件变更范围。对于比较大的重构任务效果尤其明显。适用人群后端、全栈开发者经常用 Codex 做跨文件重构的开发者。4.2 前端开发 Skills组件生成与代码规范统一前端是 Codex 使用频率最高的场景之一。社区里以“前端开发 Skills”命名的项目不少其中以 Matt Pocock 系列最典型它对 TypeScript、React、Next.js 的支持比较深入。这类 Skills 通常包含TypeScript 类型规范React 组件结构模板常用 UI 库的使用约定样式方案约束安装方式和上面类似克隆到~/.codex/skills即可。重点验证的用法是让 Codex “按项目现有规范生成一个用户列表组件”。装好 Skills 后它会先读取 SKILL.md再依据其中的约定输出组件而不是凭空发挥。适用人群React/Vue 前端开发者、TypeScript 项目维护者。4.3 自动化测试 Skills结合 Playwright 做端到端测试测试类 Skills 在社区里的热度上升很快。很多人用 Codex 生成单元测试觉得效果不错但端到端测试一直比较难落地因为涉及浏览器操作、选择器定位、等待策略等细节。装上测试 Skills 后可以约束 Codex 按照固定模式生成 Playwright 测试脚本比如统一使用test.describe分组每个用例包含明确的test.step选择器优先使用>model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY配置完成后执行export DEEPSEEK_API_KEY你的密钥 codex exec 根据当前目录的 demo-skill 生成一个示例这里想强调的是不同模型对 SKILL.md 的遵循能力不同。实测中模型越强对多步骤指令的执行就越完整如果你用的是轻量模型SKILL.md 写得再规范模型也可能忽略某些步骤。因此装 Skills 的同时尽量选一个上下文窗口大、指令遵循能力强的模型。5. 常见报错与排查思路这一部分把社区里高频出现的 Codex Skills 相关报错整理成表格方便你对照排查。问题现象常见原因解决思路unable to locate the codex cli binary桌面端或插件找不到 codex 可执行文件执行which codex获取路径在插件设置中填写codex_cli_pathSkills 没有自动触发SKILL.md 的 description 描述太宽泛将 description 写得更具体包含触发关键词或手动指定 Skill克隆 Skills 仓库后 Codex 不识别目录层级不正确确保目录结构为~/.codex/skills/技能名/SKILL.md提示某个模型不受支持例如 the xxx model is not supportedconfig.toml 中的模型名与模型服务不支持之间不一致检查 config.toml 中model和model_provider是否匹配换成模型服务支持的标识cc switch local proxy failed while handling codex endpoint /responses本地 API 网关转发 Codex 请求时失败检查本地网关监听端口、config.toml 中的 base_url 是否一致确认模型名可用使用第三方模型时回复格式不对模型不支持 Codex 的 responses 协议优先选择兼容 OpenAI responses 协议或具备兼容层的服务SKILL.md 中引用的脚本没有生效脚本路径不对或没有执行权限在 SKILL.md 中使用相对路径并检查脚本的权限必要时在命令行手动执行验证其中一个值得展开的是cc switch local proxy failed这类问题。很多开发者会使用本地网关类工具统一管理多个模型服务的 API Key 和 Base URL这类工具会监听本机某个端口然后把请求转发到真实模型服务。当你在网关中切换模型服务后Codex 仍然使用旧的 URL 或模型名就会导致/responses接口请求失败。排查顺序是确认本地网关正常启动端口可访问。查看config.toml中base_url是否指向网关监听的地址。确认当前选中的模型服务支持 Codex 使用的接口格式。切换模型后重启 Codex 进程。6. 最佳实践与工程建议6.1 不要一次性装太多 SkillsSkills 数量一多Codex 自动匹配时可能选中错误的技能。建议每个阶段只保留正在使用的 5 到 10 个核心 Skills其余放到备份目录需要时再启用。6.2 描述要具体职责要单一SKILL.md 中的description直接决定了自动匹配的准确率。写得越具体触发越精准。同时一个 Skill 最好只负责一种任务。把“写代码”和“写测试”放在同一个 Skill 里往往两个任务都做不好。6.3 对第三方 Skills 做安全审查Skills 本质上是可执行的指令集个别仓库可能包含恶意指令。安装后第一件事不是运行而是打开 SKILL.md 通读一遍确认没有要求上传敏感文件、执行来源不明的脚本等危险操作。6.4 把 SKILL.md 纳入版本管理团队的 Skills 应该和代码一起版本管理放在独立仓库中。这样新成员入职后只需要 clone 一次就能获得和团队一致的 AI 工作流。6.5 定期更新与清理Skills 的作者会不断修复 bug、更新适配版本。建议每隔一段时间回到仓库拉取最新代码同时删除已经不再使用的技能避免目录变得臃肿。6.6 自己写 Skill 时尽量加入检查清单好的 SKILL.md 不只是告诉 AI “做什么”还要告诉它“什么时候算做完”。在文档末尾增加检查清单能显著提升输出质量。例如## 完成检查 - [ ] 代码不包含未使用的变量 - [ ] 所有错误分支都有处理 - [ ] 已补充最小测试用例7. 总结与下一步这篇文章从 Codex Skills 的运行机制讲起给出了 8 个值得安装的 Skills 方向包括综合开发增强、前端规范、自动化测试、学术研究、自然语言处理、技能管理、自定义模板、模型接入配置并整理了安装和运行过程中的高频报错。对刚开始接触 Skills 的读者建议先按第 2 章准备好环境然后从第 4.1 节 Superpowers 或第 4.2 节前端 Skills 开始尝试。装好之后不需要刻意记住每个 Skill 的细节只需要在真实任务中观察 Codex 是否按照预期工作再逐步调整。如果你已经用了一段时间下一阶段可以重点研究自定义 Skills 开发把团队规范和个人工作流固化成 SKILL.md这才是 Skills 功能的长期价值所在。
到视图(VIEW)的灵活运用)
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
