最近在本地环境里集中验证了一批 Codex Skills踩了不少安装、加载和调用上的坑。网上的资料大多是零散片段有的讲安装方法有的只给 SKILL.md 模板缺少一份“装上之后到底能干什么、实际效果怎么样”的完整记录。所以这篇文章我准备用一套可复现的流程把 8 个值得装的 Codex Skills 从作用、适用场景、安装方式到实测结果挨个拆开讲清楚。无论你是刚接触 Codex CLI 的新手还是已经在用 Skills 但想找更好用的方案这篇都能给你一份直接能照着操作的清单。本文涉及的内容包括Skills 解决了什么问题以及它和普通提示词的区别。Codex CLI 环境准备与 Skills 加载机制。8 个实测可用的 Skills 清单与详细拆解。从零编写一个自定义 Skill 的完整示例。常见报错排查比如unable to locate the codex cli binary、模型不支持等。生产环境的工程规范建议。1. 什么是 Codex Skills为什么值得装1.1 Skills 解决的核心问题Codex 本身是一个能理解需求并生成代码的 AI 编程助手但要让它稳定输出高质量结果有一个很现实的问题模型不会自动知道你的项目规范、测试命令、代码风格、文档模板和工具链偏好。每换一个项目你就得在对话里重新解释一遍“我们的代码规范是什么”“测试怎么跑”“构建命令是什么”。这种重复沟通不仅浪费时间还会因为上下文表述不完整导致输出质量波动。Skills 的作用就是把这类“项目级、团队级或任务级的执行知识”固化成一个可复用的指令包。它不再是临时对话里的一句话而是一个包含任务说明、使用步骤、示例、脚本和约束条件的结构化文件。你可以把 Skills 理解为给 Codex 准备的“岗位说明书”。一套可复用的任务 SOP。一个能被自动加载的增强指令集。它解决的问题简单说就是让 AI 在正确的时间用正确的方法做正确的事。1.2 Skills 与 Prompt、插件的区别很多人第一次接触 Skills 时会混淆几个概念这里先做一个简单区分名称本质特点Prompt一次性指令每次都要重新写不持久插件/扩展独立程序功能强但需要单独安装维护Skills结构化指令包可复用、可共享、可版本管理随 Codex 按需加载一个 Skill 通常由 Markdown 文档、可选脚本、示例文件组成。当 Codex 识别到当前任务匹配某个 Skill 时会把这个 Skill 里的指令作为上下文的一部分从而在生成代码、执行命令、输出文档时遵循预设规则。1.3 Skills 的典型应用场景在实际工作中我会把 Skill 用在下面这些场景代码审查统一审查维度从安全、性能、可读性三个角度输出问题清单。前端开发让 Codex 按指定组件库和样式规范生成页面。自动化测试把 Playwright 等测试框架的指令封装成 Skill避免每次重新描述测试流程。文档生成按固定格式输出 README、接口文档和变更日志。数据库操作约束 SQL 写法强制带上 WHERE 条件、事务和回滚语句。研究辅助按学术论文的格式整理资料、生成综述。这 8 个方向基本覆盖了日常开发中重复度最高、最需要稳定的工作。2. 环境准备与版本说明2.1 安装或确认 Codex CLISkills 依赖 Codex CLI 运行所以第一步是确保本地已经安装了可用的 Codex 环境。打开终端执行codex --version如果提示命令找不到或者出现类似下面的报错unable to locate the codex cli binary. set codex_cli_path or ensure the electron binary exists说明 Codex CLI 没有正确安装或者 IDE/桌面端没有找到 CLI 路径。关于这类报错的排查第 5 章会专门展开。如果你需要通过 IDE 插件使用注意插件设置里一般有一个codex_cli_path配置项用来指定可执行文件路径。建议在安装完成后把 codex 可执行文件的绝对路径填进去避免插件找不到 CLI。版本方面需要根据你的项目实际情况调整。不同版本的 Codex CLI 对 Skills 目录结构和加载规则可能存在差异本文示例以常见环境为例重点演示配置思路。2.2 查看 Skills 目录位置Codex CLI 安装完成后需要确认 Skills 目录在哪里。常见的方式是使用命令行查看或者直接进入对应的用户目录。以个人开发环境为例常见的 Skills 目录可能位于~/.codex/skills你可以在终端执行ls -la ~/.codex/skills如果目录不存在就手动创建mkdir -p ~/.codex/skills如果你的 Codex 使用项目级配置也可以在项目根目录下创建.codex/skills目录具体以你当前版本支持的加载路径为准。2.3 查找可用的 Skills社区中有多种方式获取 Skills从 GitHub 上搜索codex skills关键词。使用类似find skills的命令行工具检索本地或远程 Skills。手动克隆社区整理的 Skills 集合仓库。自己按模板编写。在下载任何第三方 Skills 前务必检查以下几点是否要求执行任意脚本。是否包含敏感操作。是否符合项目自身的规范和授权要求。这一点在安全部分会再次强调因为 Skills 本身带有指令和脚本能力错误使用会造成不可控的副作用。3. 实测 8 个值得安装的 Codex Skills下面进入全文核心按开发任务类型逐个拆解 8 个值得装的 Skills。每个 Skill 我会从“解决问题、适用场景、使用方法、实测感受”四个维度来说明。3.1 代码审查助手 Code Review Assistant这个 Skill 在我日常开发中使用频率最高。它把“审查代码”这件事拆成了固定维度不会漏掉关键点。解决的问题平时让 AI 看代码经常只会说“看起来很完美”这种空话。缺少安全、性能、可读性的结构化判断。典型指令使用代码审查 Skill 审查 src/main/java/com/example/service 下的所有 Java 文件Skill 会指示 Codex先读取每个文件的职责。按安全性、性能、可维护性三个维度分别审查。每个问题给出文件路径、行号和具体修改建议。按严重程度等级输出例如严重、一般、建议。实测后它对危险 API 调用、缺少空指针判断、循环内重复查询数据库这类问题的发现率明显高于不加载 Skill 的普通对话。3.2 前端组件开发 Skill前端开发人员会很喜欢这个 Skill因为它能约束 Codex 按照既定的组件库规范生成代码。解决的问题不同项目使用不同组件库例如 Element Plus、Ant Design、Tailwind。没有规范时AI 可能随意混用样式方式。生成的代码不够“符合团队习惯”。Skill 内容一般会包含组件文件命名规范。样式隔离规则。事件命名的统一方式。必须包含的类型定义或接口声明。示例组件代码。实测中加载这个 Skill 后再让 Codex 写 Vue 或 React 组件代码风格明显更统一。比如让它生成一个表格组件它会自动带上 loading 状态、空数据占位和分页参数而不是只输出一个简单的静态表。3.3 自动化测试执行 Skill自动化测试 Skill 是测试开发方向最实用的一个。它把“写测试、跑测试、修测试”串成闭环。解决的问题每次都要重复描述测试框架和运行命令。AI 生成的用例缺少断言。运行失败后不知道如何自动修复。常见内容测试文件存放目录。使用的测试框架比如 Jest、Vitest、Playwright。运行单测和 E2E 测试的命令。断言风格要求。失败时的截图、日志输出规范。实测时我用它编写了一段 Playwright 测试用例Skill 会自动补充等待元素出现、失败截图保存目录、重试策略等细节这是普通对话很难一次生成的。3.4 学术研究与论文写作辅助 Skill这个 Skill 适合做调研、写技术博客、整理技术文档也适合有学术写作需求的人。解决的问题让 AI 按学术规范整理参考文献。避免生成无来源支撑的结论。统一论文结构。Skill 会指示 Codex先提取任务关键词。列出检索式或搜索策略。对文献按时间线或主题分类。输出带有引用标注的综述草稿。要注意的是AI 生成的内容只是辅助草稿。真正做学术研究和论文写作时必须对事实、数据和引用来源做人工核对不能直接依赖模型输出。3.5 数据库 SQL 优化 Skill开发中写 SQL 是高频操作但很多问题只有在数据量上来后才暴露。这个 Skills 的作用是在代码生成阶段就帮你避开常见的 SQL 性能陷阱。解决的问题SELECT *滥用。缺少 WHERE 条件的危险更新或删除。索引失效的隐式转换。大批量操作缺少分批处理。它的典型约束包括-- 禁止没有 WHERE 条件的 UPDATE/DELETE UPDATE user SET status 1 WHERE id 100; -- 分页查询建议使用覆盖索引 SELECT id, name FROM user WHERE status 1 ORDER BY create_time DESC LIMIT 20;实测中让 Codex 生成一个统计报表 SQL它会主动考虑索引、分页、避免SELECT *并提醒是否需要加事务。这对生产环境维护来说非常关键。3.6 Python 工程重构 Skill如果你维护 Python 项目这个 Skill 能帮你统一代码风格减少低级错误。解决的问题函数过长、命名不规范。异常处理不完整。文件读写没有关闭上下文。魔法值散落各处。Skill 通常会约束 Codex使用类型注解。使用with管理文件资源。每个函数只做一件事。异常捕获要精确禁止裸except。命名遵循snake_case。实测中让它对一段旧代码做重构它会主动拆分超过 50 行的函数并把重复逻辑提取成公共方法同时保留原有函数签名兼容性。3.7 文档与 README 生成 Skill文档 Skill 适合需要长期维护项目的开发者。它让 Codex 生成的不再是“为了凑字数”的文档而是结构清晰、可执行的文档。解决的问题README 写得过于简单缺少安装步骤和示例。接口文档没有参数说明。变更日志没有规范化。它会约束输出项目简介。技术栈列表。安装与本地运行命令。环境变量说明。常见问题。实测中这个 Skill 能显著减少“文档到手但不知道怎么启动项目”的问题。生成的说明文件可以直接交给同事或者开源社区用户阅读。3.8 多步骤 Agent 工作流 Skill最后一个 Skill 偏向高阶用法适合把复杂任务拆成多个步骤。社区里常见的superpower skills、agent skills本质上就是在做这件事。解决的问题单次指令无法完成复杂任务。Codex 经常只做“当前这一步”缺少全局规划。任务中断后无法自动衔接下一步。这类 Skill 通常包含任务拆解模板。每一步的验收标准。上下文记录方式。失败回退策略。实测中我把“完成一个前后端分离的用户管理模块”这个任务交给 Codex它按顺序完成了接口设计、数据库建表、后端代码、前端页面和测试用例。虽然不是每个步骤都能直接运行但整体流程已经非常接近真正开发的节奏。4. 从零编写一个自定义 Codex Skill如果你觉得现成的 Skills 不够贴合项目完全可以自己写一个。下面用一个“代码审查”类型的 Skill 示例完整演示编写、加载和验证流程。4.1 创建目录结构与元数据首先创建一个独立的目录命名要清晰建议使用kebab-case或snake_case例如~/.codex/skills/code-review/ ├── SKILL.md ├── examples/ │ └── review-example.md └── scripts/ └── check_rules.pySKILL.md是这个 Skill 的入口文件Codex 会优先读取它。4.2 编写 SKILL.md文件内容分为两部分元信息开头和任务说明正文。下面是一个最小可用的SKILL.md示例--- name: code-review description: 用于对代码进行结构化审查按安全性、性能、可读性输出报告。 version: 1.0.0 --- # 代码审查 Skill ## 任务目标 当用户要求“审查代码”或“review code”时使用本 Skill 规定的流程执行。 ## 审查维度 1. 安全性是否存在注入、越权、敏感信息泄露风险。 2. 性能是否存在循环内查询、N1 问题、未分页查询。 3. 可读性命名是否清晰函数是否过长是否有重复代码。 ## 输出格式 按以下格式输出审查结果 ### 问题清单 | 严重程度 | 文件路径 | 行号 | 问题描述 | 修改建议 | | --- | --- | --- | --- | --- | ## 约束 - 没有发现问题时明确说明“未发现明显问题”。 - 不要修改源码只输出审查意见。这个文件的核心价值在于把审查标准写死让 Codex 在每次执行时都按同一套规则输出。4.3 给 Skill 绑定辅助脚本有些 Skill 不只是文字指令还能调用脚本。下面是一个简单脚本示例可以用来检查代码中的危险模式# scripts/check_rules.py import re import sys DANGEROUS_PATTERNS [ (rSELECT \*, 避免使用 SELECT *), (rDELETE FROM, 确认 DELETE 是否带 WHERE 条件), (rUPDATE .* SET, 确认 UPDATE 是否带 WHERE 条件), ] def check_source(file_path: str) - list: issues [] try: with open(file_path, r, encodingutf-8) as f: content f.read() except FileNotFoundError: return [文件不存在] for pattern, tip in DANGEROUS_PATTERNS: if re.search(pattern, content, re.IGNORECASE): lines [] for idx, line in enumerate(content.splitlines(), start1): if re.search(pattern, line, re.IGNORECASE): lines.append(idx) issues.append(f第 {,.join(map(str, lines))} 行{tip}) return issues if __name__ __main__: if len(sys.argv) 2: print(请传入源码路径) sys.exit(1) for issue in check_source(sys.argv[1]): print(issue)把脚本放进 Skill 目录后Codex 在执行相关任务时可以调用这个脚本对目标文件做一次扫描再把扫描结果纳入审查报告。4.4 加载与验证保存目录结构后重启 Codex CLI或者重新打开 IDE使配置生效。验证方式codex run 审查当前项目中的 user.py如果 Codex 正确加载了 Skill它会先读取SKILL.md然后按审查维度输出结构化报告而不是简单地“看一眼给个判断”。5. 常见报错与排查思路在实际安装和运行 Skills 的过程中最容易出问题的不是 Skill 本身而是 Codex CLI 和底层环境。下面把高频报错整理成表格再逐个说排查思路。问题现象常见原因解决思路提示找不到 codex cli binaryCodex CLI 未安装或路径未配置检查codex --version配置codex_cli_pathSkill 加载后不生效目录路径错误或未重启确认目录为~/.codex/skills重启 CLI模型不支持某个功能当前模型与功能不匹配检查接口配置和模型参数调用接口时提示代理地址不合法本地配置了不被允许的代理地址检查环境变量中的代理设置确保指向合法地址执行脚本被拦截权限配置限制检查 Skill 目录执行权限和配置白名单5.1 提示 unable to locate the codex cli binary这是 IDE 插件用户最容易遇到的一个报错。完整错误信息一般是ChatGPT failed to start. Unable to locate the codex cli binary. Set codex_cli_path or ensure the electron binary exists.它的意思是插件尝试启动 Codex CLI但找不到可执行文件。排查步骤如下先在终端执行codex --version确认 CLI 是否安装。如果能输出版本号使用which codex查看可执行文件路径。打开 IDE 的插件设置找到codex_cli_path配置项填入完整路径。重启 IDE重新加载。这个报错和 Skills 本身没有关系但如果不解决Skills 也无法运行。5.2 接口调用时提示模型不支持报错可能像这样The gpt-5.6-sol model is not supported when using Codex with a...出现这个问题的原因通常是在 Codex 配置中指定的模型不在当前服务支持范围内。处理思路检查 Codex 配置文件中的模型名。确认模型名与当前使用的 API 能力匹配。如果不确定先使用稳定支持的模型再逐步调整。5.3 代理地址相关报错如果看到类似下面的错误cc switch local proxy failed while handling codex endpoint /responses. provided URL is not an allowed proxy这表示 Codex 在访问接口时本地配置的代理地址没有通过校验。建议处理方式检查系统环境变量或 Codex 配置里的代理设置。确认代理地址格式正确。确认该地址是本地允许使用的合法配置。不需要代理的情况下优先去掉相关配置再测试。需要特别提醒不要在项目中配置来源不明或未经验证的代理服务尤其是涉及账号、密钥、生产环境的时候避免敏感信息被第三方截获。5.4 加载了 Skills 但 Codex 没有响应Skills 目录结构没问题但 Codex 表现和没有装之前一样。这种情况一般有三个原因你没有重启 CLI 或 IDE。SKILL.md里的description没有写清楚Codex 无法匹配任务。当前任务关键字没有触发 Skill 的匹配条件。解决办法是让 Skill 的描述更具体例如description: 当用户要求“审查代码”或“review code”时使用。不要写成description: 代码审查。太短的描述会导致匹配不准确。6. 最佳实践与工程建议Skills 虽然使用起来不难但想在团队里稳定落地还是有一些工程层面的细节要注意。6.1 命名与目录规范每个 Skill 目录建议使用统一命名规则例如业务域-能力.md命名要做到“看到目录名就知道用途”同时避免空格和中文目录名防止跨平台兼容问题。6.2 最小权限原则Skills 可能有执行脚本的权限这带来一个安全问题如果你下载了第三方 Skill而它的脚本里包含恶意操作后果会很严重。建议尽量只安装来源可信的 Skills。下载后先阅读SKILL.md和脚本内容。在隔离的开发环境里验证然后再用到生产项目。限制脚本只能访问项目范围内文件。涉及账号、密钥、Token 时设置环境变量而不写入 Skill 文件。6.3 版本管理与团队共享Skill 应该纳入 Git 管理并记录变更日志。个人使用可以放在~/.codex/skills团队共享则建议单独建一个仓库由负责人统一合并和发布。每次修改 Skills 时记得更新SKILL.md里的版本号避免团队成员无法区分新旧版本。6.4 结合项目和团队规范Skills 不是越通用越好。团队内部更推荐在通用 Skill 基础上做项目级定制。举个例子通用代码审查 Skill 检查安全和性能。项目级 Skill 增加“必须使用团队自定义的日志框架”“错误码必须从统一枚举中取”等约束。这样既不影响通用性又能满足项目落地。6.5 日志与效果度量如果团队想评估 Skills 带来的效率提升建议记录两张表使用记录哪些 Skill 被触发、触发频率、成功次数。失败记录哪些任务触发错误、报错信息、解决方式。有了这些数据才能持续迭代 Skill 内容而不是装完就扔在一边。7. 总结这篇文章主要围绕 Codex Skills 的安装、使用和编写展开具体包括Skills 的本质是结构化、可复用的指令包。8 个实测可用的 Skills 覆盖了代码审查、前端开发、自动化测试、学术研究、SQL 优化、Python 重构、文档生成、Agent 工作流等高频场景。通过一个完整的SKILL.md示例演示了从创建目录到加载验证的全过程。整理了unable to locate the codex cli binary、模型不支持、代理配置等常见报错的排查思路。下一步如果你想继续深入可以从两个方向入手一是研究 Codex 官方文档中关于 Skills 目录和加载机制的细节二是结合自己团队的开发流程把高频重复的指令逐步沉淀成 Skills。实际项目中优先关注安全性和权限问题。对第三方 Skill 保持谨慎对脚本执行权限保持最小化对涉及数据和密钥的操作坚持“先测试、后上线、留备份”的原则。把这几点做好Skills 才会成为真正提升效率的工具而不是新的风险入口。