很多人在第一次装好 Codex 之后都会有一个类似的困惑它确实能写代码但一旦遇到真实项目里的复杂任务就开始“自由发挥”。让它查一个 bug它给你输出十种可能原因让它做个代码审查它点评了一堆风格问题却没指出真正会出事的逻辑缺陷。问题不一定出在模型本身而在于你只给 Codex 装了一个光秃秃的“大脑”却没有给它可复用的“工作方法”。Skills 就是用来补上这一层的。简单来说Skill 是一个带说明、规则、脚本和示例的任务包。你可以把它理解成一份给 AI 实习生看的《部门工作手册》复杂任务来了它不再临场乱猜而是先翻手册再按流程执行。Codex 还是同一个 Codex但有了 Skills 之后它的输出稳定性、专业度和团队适配度会明显上一个大台阶。这篇文章会从真实项目中最常被调用的高频场景出发梳理 8 个值得优先配置的 Codex Skills并讲清楚每个 Skill 解决什么痛点、适合谁、怎么装、怎么写。文末还会给出常见报错排查和安全建议建议先收藏再看。1. 为什么 Codex Skills 突然值得关注编程工具的竞争已经从“谁的模型更强”进入到了“谁能把模型能力稳定地落地到工程流程里”的阶段。Codex 本身是一个非常强的编码 Agent但 Agent 和“稳定产出”之间还隔着一层东西任务流程。没有 Skills 的 Codex像一个能力很强但没人带的新同事。你告诉它“帮我修一下这个模块”它会写代码但它不知道你的团队要求单元测试覆盖率是多少、不知道接口返回格式必须统一、不知道数据库操作必须走什么规范。它只能凭训练数据里的“通用最佳实践”来猜。Skills 解决的是这个问题把团队的规范、项目的约定、特定任务的执行步骤沉淀成 Agent 可以反复读取和执行的“行为包”。从最近的搜索热度也能看出趋势。“codex skills”“skills 推荐”“superpower skills 安装”“codex 使用教程”这些词被大量搜索说明已经有很多开发者从“观望 Codex”进入到了“实际配置 Codex”的阶段。与此同时另一个高频搜索词也很说明问题unable to locate the codex cli binary. set codex cli path or ensure the executable is in your PATH这说明大量用户在安装和配置阶段就遇到了问题。Codex 的使用门槛已经从“会不会用 AI”转移到了“会不会搭环境、会不会配置 Skills、会不会排查运行错误”。这篇文章要做的就是帮你把这条路的坑先踩平。2. Codex Skills 核心概念Skill 不是普通 Prompt在进入推荐清单之前有必要先把概念对齐。很多初学者会把 Skill 理解成“一段更长的 Prompt”这是最大的误解。2.1 什么是 AgentAgent 是能够自主完成任务的智能体。在编程场景里它不只是“生成一段代码”就结束而是可以读取项目文件、执行命令、运行测试、根据结果修复代码循环往复直到完成目标。Codex 就是这样一个编码 Agent。它有能力做很多事但能力不等于稳定性。2.2 什么是 SkillSkill 是一个结构化的任务包通常由一个目录组成skills/ └── pr-check/ ├── SKILL.md └── scripts/ └── check_pr.py其中SKILL.md是核心文件它用固定格式描述这个 Skill 的用途、触发条件、执行步骤和注意事项。Agent 在执行任务时会读取这个文件按照里面的说明来行动。scripts/目录存放辅助脚本。Skill 不是只能“给模型讲道理”它还能让模型调用真实工具、执行真实检查这就比普通 Prompt 强非常多。2.3 SKILL.md 的结构下面是一个最小可用的SKILL.md结构示例--- name: pr-check description: 在提交 Pull Request 之前对变更内容执行团队规范检查。 --- # PR 检查清单 当用户要求检查 Pull Request 时按以下步骤执行 1. 获取变更文件列表。 2. 逐个检查变更内容。 3. 调用 scripts/check_pr.py 检查硬编码密钥和调试输出。 4. 输出检查结果按“严重问题 / 建议改进 / 通过”分级。注意SKILL.md不是给人看的文档而是给模型读的“操作规程”。它的name和description字段尤其重要因为 Agent 在接到任务时是靠description来判断“这个任务应该用哪个 Skill”的。2.4 普通 Prompt、Skill、插件的区别维度普通 PromptSkill插件本质一次性指令可复用的行为包代码层面的能力扩展是否包含脚本通常没有可以包含脚本本身就是程序复用性低每次重新写高可沉淀、可版本化高维护成本低中等较高典型用途临时问答、简单生成审查、测试、重构、规范检查接入外部系统、扩展编辑器能力理解了这个区别你就明白了为什么大家都在找“好用的 Skills”而不是“更长的 Prompt”。Skills 是把一次性经验变成长期资产的关键。3. 环境准备与 Codex 基础安装在装 Skills 之前先确保 Codex 本身能跑起来。很多网友反馈的“找不到 CLI”问题实际就发生在这个阶段。3.1 前置条件安装 Codex 通常需要以下条件Windows、macOS 或主流 Linux 发行版Node.js 运行环境具体版本以 Codex 官方要求为准可用的模型 API 配置例如 OpenAI 官方服务或者兼容 OpenAI 协议的模型服务命令行终端以及基础的 Git 使用经验。需要注意我没有列出具体版本号是因为不同版本的 Codex 对 Node.js 版本要求不同。更稳妥的做法是去官方文档确认当前版本要求而不是盲目安装最新 Node.js。3.2 安装与验证Codex CLI 的安装方式以官方文档为准通常可以通过官方安装脚本或包管理器完成。安装完成后在终端中验证codex --version如果这个命令能正常输出版本号说明 CLI 已经安装成功。如果你使用的是 ChatGPT 桌面版中的 Codex 功能启动时遇到下面的报错unable to locate the codex cli binary. set codex cli path or ensure the executable is in your PATH原因通常是系统里只安装了桌面客户端没有安装 Codex CLI或者 CLI 安装了但可执行文件不在 PATH 中。解决思路是确认 Codex CLI 是否安装成功执行codex --version验证找到 Codex CLI 的实际安装路径在桌面客户端设置中将codex_cli_path指向这个路径或者把 Codex 可执行文件所在目录加入系统 PATH然后重启客户端。3.3 配置模型服务Codex 默认连接固定模型服务但根据社区反馈很多用户会配置兼容 OpenAI 协议的模型服务比如 DeepSeek。这类配置通常需要修改 Codex 的配置文件核心思路是设置 API 请求地址base_url设置 API Key 环境变量指定模型名称。具体字段名和格式要以你安装的 Codex 版本官方文档为准不要照抄网络上的旧配置。如果配置之后报错比如提示模型不支持首先要检查base_url是否可用、API Key 是否有效、模型名称是否在当前服务商的支持列表中。3.4 找到 Skills 目录Codex 会从特定目录扫描 Skills。不同版本约定可能不同但常见做法有两种全局目录存放个人所有项目通用的 Skills项目目录跟随具体项目例如放在项目根目录下的.codex/skills或类似路径。进入项目目录后可以查看 Codex 的配置说明确认它扫描哪个目录。后面安装和自建 Skill都要放到正确的位置才会生效。4. 8 个必装 Skills 推荐清单下面进入本文的核心部分。我梳理了 8 个在真实项目中出场率最高的 Skills 方向。每个 Skill 都会从痛点、工作流、适合谁三个角度展开。4.1 代码审查 Skill解决痛点人工 Code Review 容易疲劳。一个几十行的小改动Reviewer 可能只看到格式问题而漏掉真实的逻辑风险。Codex 的优势是“永远有耐心”可以逐行对比改动并且不会被时间压力影响判断。典型工作流输入变更集比如 Git diff 或 PR 链接按严重程度输出问题列表每个问题给出代码位置、风险说明和修复建议最后给出“是否建议合并”的结论。适合谁团队负责人、开源项目维护者、喜欢在提交前做自检的开发者。建议Codex Review 适合做第一轮检查和兜底但不要把合并决策完全交给它。尤其是涉及架构取舍、业务规则的问题人工仍然要保留最终决定权。4.2 单元测试生成 Skill解决痛点大多数项目测试覆盖率不高不是因为开发者不重视测试而是因为写测试确实枯燥。更麻烦的是很多边界条件——空值、超长输入、并发冲突——如果没有经验根本想不到要覆盖。典型工作流输入源码文件或函数分析输入输出、依赖关系和边界条件生成测试文件说明每个用例覆盖的场景。适合谁后端开发者、正在做重构的团队、刚接手没有测试的旧项目的开发者。建议让 Codex 生成测试之后一定要在真实环境中跑一遍。生成测试的价值是“快速补上覆盖率”而不是“生成完就算完事”。一个跑不通的测试比没有测试更危险。4.3 前端开发 Skill解决痛点前端开发大量工作集中在组件实现、样式调整、响应式适配。这类任务重复性高而且细节极多很容易出现“功能对了但样式在不同屏幕宽度下崩了”的情况。典型工作流输入需求描述或设计稿说明输出组件代码、样式方案和关键交互实现列出响应式适配和边界处理注意事项。适合谁前端工程师、全栈开发者、需要快速搭建页面的团队。建议从热度来看“前端开发 skills” 是搜索量非常高的方向说明前端同学的实际需求很大。但要注意Codex 生成的组件代码要放进项目的设计体系里检查不要直接全盘接受。尤其是样式方案必须符合团队已有的设计规范。4.4 代码重构 Skill解决痛点接手旧项目时面对一坨几百行的函数你不敢轻易重构怕一动就出问题。Codex 可以帮你分析现有代码结构提出重构方案并且给出验证思路。典型工作流指定要重构的文件或模块说明重构目标可读性、性能、还是结构拆分输出重构前后的代码对比给出验证步骤和风险清单。适合谁接手遗留系统的开发者、做技术债务治理的团队。铁律重构之前必须有测试兜底。没有测试的重构和蒙眼换零件没有区别。建议先让“单元测试生成 Skill”把测试补上再执行重构。4.5 性能分析 Skill解决痛点接口慢、慢 SQL、内存占用过高这类性能问题定位成本很高。因为问题可能出现在应用代码、数据库、缓存策略、甚至硬件资源多个层面。典型工作流输入 profiling 结果、慢查询日志或接口耗时数据分析瓶颈可能出现的层级输出定位结论和优化建议列出可以快速验证的指标和命令。适合谁后端开发、运维工程师、负责系统优化的开发者。重要提醒涉及生产环境数据时必须先脱敏。不要让 Codex 直接操作线上数据库。最优的做法是在测试环境复现问题或者把日志导出到本地分析。4.6 技术调研 Skill解决痛点写技术方案、做技术选型时最耗时间的是“穷尽候选方案”这一步。人工调研很容易漏掉某个新兴方案或者因为信息茧房而偏好自己熟悉的旧技术。典型工作流输入调研主题输出候选方案对比表每个方案说明优缺点、适用条件、社区活跃度给出推荐结论和验证建议。适合谁架构师、技术经理、准备写技术方案的开发者。延伸场景从社区搜索热度看“学术研究”“agent skills 赋能人文社科研究” 这类词汇也在快速增长。说明 Skills 的应用范围已经超出了纯编码领域资料检索、调研对比、归纳整理这类知识型任务同样可以受益。4.7 文档与注释生成 Skill解决痛点大多数开发者讨厌写文档但项目又离不开文档。更常见的问题是代码更新了注释和 README 还停留在三个月前给后人留下一堆误导信息。典型工作流输入源码文件或变更记录输出 README、API 文档、代码注释建议或 CHANGELOG高亮标注“文档与代码可能不一致”的地方。适合谁开源项目维护者、团队知识库管理者、需要做项目交接的开发者。建议生成文档后必须经过一次人工审校。AI 生成的文档整体质量不低但它不真正理解业务上下文你需要在关键描述上做修正尤其是“为什么这么做”这类只有人才知道的信息。4.8 团队规范检查 Skill自定义 Skill 入口解决痛点团队规范往往靠文档和人传人。新人来了看一遍规范文档真要写代码时还是会忘。如果能把规范变成 Agent 的真实检查步骤效果会好很多。典型工作流把团队的编码规范、提交规范、安全红线写进 SKILL.md让 Codex 在提交前、Code Review 时、或生成代码后自动执行检查输出“通过/不通过”清单。适合谁所有团队尤其是规范多、迭代快的团队。这个 Skill 也是从“使用 Skill”跨到“开发 Skill”的桥。社区里很多成熟的 Skills 集合本质上就是把优秀团队的工作方式打包成了可复制的 Skill。下一章我会讲如何安装这类第三方 Skills。4.9 8 个 Skills 汇总对比推荐方向解决痛点适合谁落地建议代码审查Review 疲劳、漏掉风险团队负责人、开源维护者人工保留最终决策权单元测试生成覆盖率低、边界遗漏后端、重构团队生成后必须跑通再合入前端开发组件和样式细节多前端、全栈对齐团队设计体系代码重构旧项目不敢动遗留系统维护者先补测试再重构性能分析问题定位成本高后端、运维生产数据先脱敏技术调研方案对比不全面架构师、技术经理结合真实业务验证文档生成文档缺失、过期开源、交接场景人工审校关键描述团队规范检查规范靠人传人所有团队从最小检查项开始5. 安装第三方 Skills 的正确姿势社区里已经有大量现成的 Skills 可以直接安装搜“codex skills”就能找到不少。常见的如 superpower skills、mattpocock skills、hermes skills hub 等都是一些开发者或社区整理的能力集合。安装步骤并不复杂但有几个细节容易踩坑。5.1 找到并下载 Skills从 GitHub 或社区仓库找到你需要的 Skill 仓库后把它克隆到本地或者直接下载相关文件夹。不要一次性安装一个几百个 Skill 的“全家桶”。Skill 太多Agent 匹配起来反而不精确还会增加上下文负担。建议先挑选 3 到 5 个和日常工作最相关的。5.2 放入正确目录把 Skill 文件夹放到 Codex 扫描的目录中。如果是项目级使用放在项目根目录下对应的 skills 目录里如果是全局使用放在全局配置目录下。目录结构示例.codex/ └── skills/ ├── pr-checklist/ │ ├── SKILL.md │ └── scripts/ │ └── check_pr.py └── test-generator/ ├── SKILL.md └── templates/ └── test_template.py放好之后通常需要重启 Codex或者重新加载配置Skills 才会被扫描到。5.3 安全审计这是很多人忽略的一步。第三方 Skill 本质上是可执行代码。你把它下载到本地Codex 就会在执行任务时调用里面的脚本。如果 SKILL.md 里写着“删除所有日志文件”或者脚本里有可疑的网络请求你直接使用就等于把危险操作交给了 Agent。在运行任何第三方 Skill 之前至少要做三件事通读 SKILL.md确认它的行为符合你的预期检查 scripts 目录下的脚本看有没有高危操作第一次运行时先在一个测试项目的环境里跑不要直接在主线分支或生产环境跑。5.4 安装后验证安装完成后用一个最小的测试任务验证 Skill 是否被加载。比如安装的是代码审查 Skill就手动构造一个包含明显错误的 diff看它是否按 SKILL.md 的步骤输出检查结果。如果 Skill 没有被触发优先检查两件事目录是否在扫描路径中SKILL.md 的description是否足够明确。6. 手写一个 Skill从 0 到 1 的完整示例与其到处找第三方 Skills不如动手写一个自己的。很多团队最后的做法都是基于社区 Skills 做二次开发把团队自己的规范加进去。下面用一个“团队规范检查 Skill”作为例子完整演示从目录创建到运行验证的过程。6.1 场景设定假设团队成员经常犯这几个问题在代码里硬编码密码或密钥提交代码时残留console.log调试输出代码里遗留 TODO 但没有关联任务编号。我们希望 Codex 在代码审查时自动执行这些检查输出结构化结论。6.2 创建目录结构首先在 skills 目录下创建team-pr-check文件夹mkdir -p .codex/skills/team-pr-check/scripts6.3 编写 SKILL.md文件路径.codex/skills/team-pr-check/SKILL.md--- name: team-pr-check description: 当用户要求检查 Pull Request 或提交的代码变更时执行团队规范检查。 --- # 团队 PR 规范检查 收到 PR 审查请求后必须按以下顺序执行 1. 获取变更文件列表和变更内容。 2. 调用 scripts/check_pr.py传入变更内容文件路径。 3. 根据脚本输出整理检查结果。 4. 输出结论时按以下格式 - [严重] 需要阻塞合并的问题 - [建议] 建议修改但不阻塞的问题 - [通过] 无明显问题 5. 如果脚本无法执行明确报告错误不要编造结果。注意 SKILL.md 里的几个关键设计description写清楚了触发条件方便 Agent 匹配正文用了“必须”“不要编造结果”这类强指令而不是“建议”“尽量”这类模糊词明确告诉模型脚本执行失败时要报告错误而不是自己硬编一个结果。6.4 编写检查脚本文件路径.codex/skills/team-pr-check/scripts/check_pr.py#!/usr/bin/env python3 import re import sys def read_diff(path): with open(path, r, encodingutf-8) as f: return f.read() def check_diff(diff_text): issues [] hardcoded_secret re.search( r(password|api_key|secret|token)\s*\s*[\][^\][\], diff_text, re.IGNORECASE, ) if hardcoded_secret: issues.append((严重, 疑似硬编码密钥或口令请改为环境变量)) if console.log in diff_text: issues.append((建议, 存在 console.log 调试输出请清理)) todo_without_ticket re.findall( rTODO\s*(?!\[), diff_text ) if todo_without_ticket: issues.append((建议, 存在未关联任务编号的 TODO请补充)) return issues def main(): if len(sys.argv) 2: print(用法: python check_pr.py diff文件路径) sys.exit(1) diff_path sys.argv[1] diff_text read_diff(diff_path) issues check_diff(diff_text) if not issues: print(PASS: 未发现明显问题) return print(FAIL: 需要处理以下问题) for level, message in issues: print(f - [{level}] {message}) if __name__ __main__: main()这个脚本有几个设计点用sys.argv[1]接收 diff 文件路径方便 Codex 调用检查逻辑分成“严重”和“建议”两个等级脚本可以独立运行方便本地调试不依赖 Codex。如果需要让脚本直接执行记得添加权限chmod x .codex/skills/team-pr-check/scripts/check_pr.py6.5 编写一个测试 diff为了验证效果创建一个包含问题的测试文件。文件路径test-diff.txtconst password 123456; console.log(debug); // TODO: 优化这个函数6.6 手动运行脚本验证先不通过 Codex手动运行脚本确认脚本本身逻辑正确python3 .codex/skills/team-pr-check/scripts/check_pr.py test-diff.txt预期输出FAIL: 需要处理以下问题 - [严重] 疑似硬编码密钥或口令请改为环境变量 - [建议] 存在 console.log 调试输出请清理 - [建议] 存在未关联任务编号的 TODO请补充如果这一步输出正确说明脚本本身没问题。接下来再验证 Codex 能不能正确调用它。7. 运行效果验证与常见误判很多人在配置 Skills 之后会凭“感觉”判断是否生效。比如看到 Codex 的回答看起来更规范了就以为 Skill 起作用了。这其实不够严谨。7.1 如何确认 Skill 真正生效建议按下面的清单检查Codex 的日志中是否能找到“已加载 Skill xxx”的记录执行任务时Codex 是否提取了 SKILL.md 里的步骤而不是自由发挥是否真的调用了 scripts 目录下的脚本输出结果是否包含了 SKILL.md 里定义的格式或分级。有一次调试时我发现 Codex 的回答看起来完全按 SKILL.md 的格式输出了但脚本其实没有执行。原因是模型根据训练经验“猜”出了可能的结果直接照着格式编了一段。这提醒我判断 Skill 是否真正生效不能只看最终回答要看执行过程中有没有实际调用脚本、有没有读取文件。7.2 验证命令在 Codex 中可以用类似下面的方式要求它执行检查codex 请对 test-diff.txt 中的变更执行 team-pr-check正确触发时Codex 会先读取 SKILL.md然后执行脚本最后按脚本输出整理结果。如果没有触发它会表现为自己分析文本直接给出回答没有调用脚本的迹象。7.3 常见误判场景误判场景真实状态进一步确认方式回答格式很规范看起来像 Skill 生效可能只是模型学会了格式检查日志确认是否执行脚本没有输出“FAIL/PASS”标记Skill 依赖的脚本没有执行手动运行脚本确认路径和权限输入任务后没有任何反应Skill 没有被加载检查目录路径和 SKILL.md 格式脚本报错但 Codex 没有报告SKILL.md 里没写“报错”指令在 SKILL.md 中明确要求报告错误8. 常见问题与排查思路使用 Codex Skills 的过程中有几类问题出现频率最高这里整理成一张排查表。问题现象可能原因排查方式解决方案启动时提示找不到 codex cli binaryCLI 未安装或 PATH 未配置执行codex --version确认命令可用安装 CLI或在桌面端设置codex_cli_pathSkill 完全没有被触发目录放错、description 不明确检查 Codex 配置中的 skills 路径移动目录到正确位置优化 SKILL.md 的 descriptionSKILL.md 解析失败YAML front matter 格式错误查看 Codex 启动日志修正 front matter删除特殊符号和多余空格脚本执行提示权限不足文件没有可执行权限执行ls -l scripts/查看权限chmod x scripts/*.pyCodex 输出了结果但看起来是编造的脚本没被调用模型自己生成了结果检查日志中是否有脚本调用记录在 SKILL.md 中强制要求“必须调用脚本否则报告错误”接入 DeepSeek 等模型服务时报错base_url、API Key 或模型名配置不正确查看接口返回的状态码和错误信息按官方文档重新配置模型服务商参数Skills 装太多之后匹配变慢或混乱Skill 之间 description 重叠检查每个 Skill 的 description 是否唯一精简 Skills 数量重写模糊的 description其中最值得补充说明的是模型服务配置问题。很多用户希望让 Codex 接入 DeepSeek 这类兼容 OpenAI 协议的模型服务但不同版本的 Codex 配置方式有差异。遇到报错时第一件事是看返回错误而不是盲目改配置。如果是模型不支持的报错优先去模型服务商官网核对模型名和 API 规格。9. 最佳实践与安全建议Skills 用起来不难但要用好、用稳、用安全需要一点工程化思维。9.1 把 Skills 当成代码来管理建议把 Skills 目录纳入 Git 仓库管理。Skills 会随着团队规范、项目结构、模型能力的变化而变化必须像代码一样走版本管理、review 和回滚。团队可以维护一个独立的 skills 仓库每个人用git pull更新。新成员入职时只需要拉取一次仓库就能获得团队沉淀下来的完整工作流。9.2 命名与描述要精确SKILL.md 里的name和description决定了 Agent 能不能在正确的时候找到它。description不要写“用于代码检查”这种模糊表达要写“当用户要求审查 Pull Request 或检查代码变更时执行”。好的 description 通常包含三要素触发场景、输入内容、输出格式。9.3 SKILL.md 中使用强指令模型对“可以”“建议”这类词的执行力度远低于“必须”“禁止”“先做 A再做 B”。写 SKILL.md 时尽量用明确的操作指令减少模糊空间。比如## 执行规则 1. 必须读取变更文件不允许跳过。 2. 必须调用 scripts/check.py 获取检查结果。 3. 如果脚本执行失败必须报告错误禁止自行编造结果。9.4 权限最小化这是安全底线。Skills 脚本不要使用高权限账号运行不要在 SKILL.md 或脚本中写死 API Key、密码等敏感信息改用环境变量对包含删除、覆盖、网络请求等敏感操作的脚本必须经过二次 review第一次使用第三方 Skill 时先在隔离的测试项目中运行。9.5 从 3 到 5 个 Skill 起步不要一次性把所有热门 Skill 都装上。Skill 越多Agent 的匹配负担越重你也越难判断某个问题到底出在哪个 Skill 上。更务实的路线是先装 3 到 5 个和日常工作最相关的比如代码审查、测试生成、文档生成。跑通之后再根据实际需求慢慢增加。9.6 核心建议如果你现在只记一句话那就记这句Codex 的能力边界并不只由模型决定更由你提供给它的 Skills 决定。安装现成的 Skills 只是第一步真正有价值的是把你所在团队的工作规范、你个人踩过的坑、你熟悉的工程流程沉淀成自己的 Skill。一个好的 SKILL.md本质上就是把“你会怎么做”写成了“Agent 能照着执行”的操作手册。这件事的回报会随着你写过的 Skill 越多而越来越大。下一步的实践路径很清晰先确认 Codex 能正常运行安装两个最常用的 Skills用真实项目跑一遍然后选一个团队里重复性最高、规则最明确的任务动手写自己的第一个 Skill。跑通之后你会发现 Codex 从一个偶尔惊艳的“代码生成器”变成了真正熟悉你项目规则和团队习惯的开发伙伴。