如果你最近在项目里重度使用 Codex，应该能明显感觉到：它比单纯聊天强得多，但也不是开箱就神。尤其换到一个别人维护了很久的老仓库，代码还没看几行就给出方案，方向可能没错，细节却常常全歪。我过去几个月的经验是，这种“飘”的本质，是模型缺少一套可复用的操作规范——也就是今天要说的 skill。把成熟的做事方法打包成文件，让 Codex 在对应场景下自动切换到老手模式，这才是 skill 真正值得收藏的原因。
我不跟你扯概念，直接给一份我筛了无数轮、目前实际高频在用的 15 个 skill 清单。每个都会说清楚：它解决什么问题、关键约束是什么、落地时哪里容易翻车。不管用的是 Codex CLI、桌面版，还是其他支持类似机制的 AI 编程工具，这份清单都可以直接参考；刚入门的读者也能从里面搞明白 skill 到底怎么改变 Codex 的干活方式。
1. 先把 skill 的机制搞懂，后面的清单才看得明白
1.1 skill 和普通提示词的根本区别
假设你让 Codex 审查最近的一段改动。直接问它会怎样？大概率得到一堆正确但没什么用的废话：注意边界条件、补充单元测试、提升可读性。每句都对，可你合上屏幕还是不知道下一步该干嘛，因为它没有一套可执行的判断流程。
skill 解决的就是这个问题。它本质是一段结构化的操作手册，里面写清楚触发条件、执行顺序、检查清单、输出格式、禁止事项。模型看到之后，不再是“临时想怎么回答”，而是“按手册执行”。同一个任务，让新人随便看代码，和给新人一本带 check list 的评审手册，效果当然完全不同。这就是有没有 skill 的差别。
再说直白一点。普通提示词是一次性的，用完就没了；skill 是可复用、可版本化、可以跨项目带走的资产。你完全可以把一套团队评审规范写在 skill 里提交到仓库，新同事拿到项目就拿到了这套规范，Codex 行为也跟着稳定。我在团队里推行 skill 之后，最明显的感觉不是 Codex 变得更“聪明”，而是它变得更“稳”，不会今天这个风格明天那个风格。
1.2 一个最小可用的 SKILL.md 长什么样
抛开不同工具在元信息字段上的差异，一个 skill 本质上就是一个带说明的 Markdown 文件。我常用的最小模板是：
--- name: code-review description: 针对改动做代码审查，侧重影响面与风险 --- 当用户说“审查代码”“帮我 review”时，按下面流程执行： 1. 收集本次改动文件列表，确定和基线分支的差异 2. 按检查清单逐项核对 3. 输出分级结论：阻塞 / 建议 / 非阻塞 4. 不修改代码，只输出审查意见 ## 检查清单 - 是否引入新的依赖？是否必要？ - 异常分支是否被吞掉？有没有只 catch 不处理？ - 是否存在明显的风险，比如把密钥写进代码？ - 改动是否会影响其他模块的兼容性？这个文件放在技能目录里，Codex 在遇到匹配场景时就会把它加载进来。不同工具的目录位置略有区别，我自己常用的方式是把技能目录放在用户配置下，团队项目里再用 AGENTS.md 去声明全局规则，这样个人技能和团队规范能分开管理，不会互相打架。
目录结构大概是这样：
~/.codex/skills/ code-review/ SKILL.md crash-trace/ SKILL.md在项目根目录的 AGENTS.md 里，再写清楚项目语境、技术栈、惯用代码风格。个人技能负责“这类任务该怎么做”，AGENTS.md 负责“这个项目有什么特殊性”，两者配套使用，比单一方案更顺。
1.3 别什么都想做成 skill
有人一接触 skill 就很兴奋，恨不得把每个操作都固化成技能。我的建议是反过来：先做减法。只有那些重复发生三次以上、有明确步骤、且经验可沉淀的任务，才值得做成 skill。探索性问题、一次性提问，直接对话更快。判断方法很简单：同一件事你一个月干三回，就值得固化；干一回就忘的事，写了 skill 也是在落灰。
2. 15 个值得收藏的 skill 全名单
2.1 先看总表，方便按图索骥
| 编号 | skill 名称 | 解决的核心问题 | 建议使用频次 |
|---|---|---|---|
| 01 | code-review | 合并前没人细看代码 | 几乎每天 |
| 02 | crash-trace | 线上报错不知道怎么查 | 几乎每天 |
| 03 | refactor-helper | 代码烂但不敢动手 | 每周 |
| 04 | test-writer | 核心逻辑没有用例兜底 | 每周 |
| 05 | doc-writer | README 和接口文档长期欠债 | 每周 |
| 06 | git-trace | 某个提交把功能改坏了 | 按需 |
| 07 | dependency-audit | 依赖升级心里没底 | 按需 |
| 08 | sql-review | 慢查询和表结构不合理 | 按需 |
| 09 | api-review | 接口联调来回扯皮 | 按需 |
| 10 | repo-map | 新仓库、新同事上手太慢 | 按需 |
| 11 | security-scan | 密钥和漏洞藏进了代码 | 每周 |
| 12 | perf-profiler | 接口慢、内存涨、CPU 高 | 按需 |
| 13 | a11y-review | 无障碍细节不被重视 | 按项目 |
| 14 | pipeline-debug | CI 一直红，不知道从哪查 | 按需 |
| 15 | skill-creator | 想写新技能但不会搭框架 | 按需 |
这 15 个我按使用场景分成了三批：第一批偏日常编码，几乎每天都碰；第二批偏工程协作，多出现在中大型项目；第三批看着冷门，但关键时刻能救命。下面逐一讲。
2.2 我筛选这 15 个的标准
这 15 个不是按“看起来高级”选的。标准就三条：第一，任务边界要清楚，能说清楚输入是什么、输出是什么，不会让 Codex 自由发挥；第二，调用频率足够高，值得沉淀；第三，输出结果容易验证，生成的内容可以被人快速检查。
举个例子就明白了。code-review 的输入是改动，输出是结论，边界非常清晰；crash-trace 的输入是日志，输出是根因和证据链，结果可以对着日志核验。反过来，像“帮我做一个完整项目”这种事就不适合做成 skill，因为太开放了，再好的技能模板也救不了模糊需求。筛选 skill 时，宁可范围小一点、具体一点，也不要贪大求全。
3. 第一批 5 个：每天写代码都会用到
3.1 code-review：先看影响面，再看代码风格
code-review 是我清单里翻牌率最高的技能。它最大的价值不是替代人来审查，而是让 Codex 在合并前先做一轮高性价比的扫描，把明显问题拦下来，人工 reviewer 只需要看它标出来的重点和少数漏网之鱼。
我在 skill 里会对 Codex 提四个要求。第一，先列改动文件清单和改动之间的依赖关系，从影响面讲起，而不是一上来逐行挑刺。第二，结论分三档：阻塞项、建议项、非阻塞项，阻塞项写清楚为什么必须改，建议项给出改法。第三，禁止直接改代码，只输出审查意见，否则改动很容易越滚越大。第四，项目无关的规则不要提，不能用项目里根本不存在的规范去要求别人。
实际用下来，这个技能最大的收益反而是“沉淀”。项目里哪些历史问题反复出现、哪些区域代码风险最高，都可以逐步追加到 skill 的检查清单里，让 Codex 越用越像一个熟悉这个项目的资深同事。
3.2 crash-trace：从日志到根因的推理链路
线上环境一出问题，大家第一反应是翻监控、找日志。crash-trace 要做的，就是把“从原始日志到根因定位”这条推理链路固化下来，防止 Codex 一上来就天马行空地猜测。
我给这个 skill 定的流程是：先输入错误日志或堆栈片段，要求它按时间线整理出关键事件，而不是一下子跳到结论；然后做根因假设，每个假设必须对应一条日志证据；最后给出验证方法、最小复现思路和修复建议。输出格式我要求它包含“证据链”这一栏，理由很简单——很多线上问题是因为信息不足被误判的，让 Codex 把证据写出来，你一眼就能看出它的判断成不成立。
踩坑提示：日志少的时候，Codex 很容易编一个“看起来合理”的原因。我后来强制要求它在信息不足时直接说“需要更多数据”，并列出还需要哪些日志，而不是硬给答案。这个约束加进去之后，可用性高了一个档次。
3.3 refactor-helper：行为不变是铁律
重构最大的难点不是改代码，而是怕改出行为差异，尤其是老项目，一个函数被十来处调用是常有的事。refactor-helper 的能力重心放在“安全地改”，而不是“炫酷地改”。
技能里必须写死的第一条铁律是：重构不得改变对外行为，除非需求明确要求改变。第二条是：动手前先让 Codex 找出所有调用点，评估影响面；改动范围越大，越要建议先补测试。第三条是：一次只做一种重构，这轮只拆分函数、下轮只消除重复代码，不要把多个目的混在一次改动里。
另一个值得收藏的原因是可以和 test-writer 配合：先让 Codex 给待重构模块生成一组基线测试，跑绿之后再动刀，最后再跑一遍测试确认行为没变。这种“测试先行”的流程，是重构类 skill 能真正落地的关键。光靠模型自己声称“代码逻辑没变”，远远不够。
3.4 test-writer：不是为了覆盖率好看
让 Codex 写测试，是目前回报率很高的场景，但也是最容易出现“表面繁荣”的场景。默认情况下它喜欢生成一堆覆盖 happy path 的测试，覆盖率数字好看，关键分支和异常路径却没人管。
test-writer 这个 skill 我会重点约束三点：第一，优先覆盖核心业务逻辑和经常出问题的分支，而不是为了凑覆盖率去测试 getter/setter；第二，mock 策略必须明确，外部依赖能 mock 的 mock，但不要把所有东西都 mock 掉，否则测了个寂寞；第三，输出要符合项目已有的测试风格，用项目现有的测试框架和命名习惯，不能另起炉灶。
实际效果上，它做批量生成很快，尤其是表驱动测试，几秒钟就能把一组输入输出枚举出来。这个技能适合在提测前批量跑一轮，专门盯“异常分支建用例了没有”，远比让人手工从零写效率高。
3.5 doc-writer：文档即契约
程序员不爱写文档是常态，结果就是 README 过期、接口文档失联。doc-writer 让 Codex 直接从代码读文档：入口参数、返回值、异常、调用示例，全部抽取整理成统一格式。
我在技能里会强制要求它标明“信息来源”，避免出现代码里根本不存在的内容。比如写完接口文档，每个字段都要能对应到代码里的真实定义，不允许脑补。另外要规定输出结构：对 README，至少包含快速开始、本地开发、部署上线、常见问题；对外部接口，至少包含请求示例、响应示例、错误码表。
用下来最有价值的地方是，它能把多年没更新的老模块文档一次性补齐，而且格式统一，后续维护成本低。需要注意一个细节：让 Codex 生成完文档后，把不明确的信息标记为 TODO，而不是自己编一个看似合理的说法，这一点对文档质量影响很大。
4. 第二批 5 个：团队协作和工程化场景的高频 skill
4.1 git-trace：哪个提交把功能改坏了
版本回溯往往比想象中麻烦。git-trace 这个技能专门解决“某个功能本来是好的，现在坏了，到底是谁、哪个提交改坏的”。我之前手工做这件事，最常做的就是复制粘贴git log、git blame、git bisect这一套命令，还要对着输出反复分析。有了 skill，Codex 可以一步到位：输入功能名和大概发现问题的版本区间，让它自动跑命令、缩小嫌疑提交范围、再对比改动内容给出结论。
skill 里要给它定好边界：第一，允许执行只读 Git 命令，但禁止任何可能改变仓库状态的操作，比如 reset、checkout 覆盖文件；第二，结论要附带证据链，即哪个提交的哪一行导致了行为变化；第三，如果没有定位到，不要强行推荐“回滚”这种高风险操作，而是给出需要进一步排查的方向。这一条对线上环境尤其重要。
4.2 dependency-audit：升级前先看清风险
每次升级依赖，我都会有那么一瞬间不想管了。dependency-audit 解决两个问题：一是这个依赖能不能升，升了影响什么；二是有没有已知的高危问题。技能入口可以是package.json、requirements.txt、pom.xml或go.mod，Codex 读完之后输出一份简洁的变更影响报告。
我要求的输出结构是：当前版本、目标版本、版本差异摘要、可能的破坏点、升级建议。破坏点要具体到代码层面，比如“某函数签名变了，项目里有三处调用需要同步改”，而不是笼统地写一句“注意兼容性”。另一个要点是让它优先关注跨大版本升级和带安全公告的版本，小版本升级不用花太多篇幅。
虽然 Codex 不一定实时掌握最新的安全情报库，但它能结合项目代码语义，把“升级后哪些地方可能编译失败、测试可能挂”分析得比较透彻。这份报告比直接翻 release notes 快很多，尤其适合依赖很多的老项目。
4.3 sql-review：慢查询和表结构的事前体检
数据库相关的 skill 我犹豫过要不要单独列出来，因为大多数后端项目都有这个痛点，但并不是每天碰。最后留下来了，因为一旦用上，收益特别大。sql-review 可以做两类事：一类是审查已有的慢查询，输入执行计划和 SQL，让它指出索引问题和可优化点；另一类是审查表结构设计变更，输入建表语句或 ORM 模型，让它评估字段、索引、外键设计的合理性。
我建议在 skill 里加一条强制要求：涉及生产数据的建议，必须标注风险等级和执行代价，不能只说“建议加索引”这种空话；同时明确它不能直接在数据库上执行变更，只能输出审查意见。实际用的时候，把慢查询日志的一段丢进去，它能快速给出“这里全表扫描了”“这段 JOIN 关联字段缺索引”之类的定位，人再判断要不要采纳，整体效率高很多。
4.4 api-review：联调前的接口契约体检
接口设计的问题往往在联调阶段集中爆发：字段命名不一致、错误码语义模糊、缺少幂等设计、分页参数没统一。api-review 就是在接口文档或接口定义产出后，先把这些坑按经验检查一遍。
我会让 Codex 审查几个固定维度：请求与响应结构、必填与选填字段、错误码覆盖、鉴权方式、兼容性、幂等性。输出格式也是固定的：问题清单按严重程度排序，每个问题给出修改建议和受影响方。这个技能特别适合团队里有多个后端服务、几个人同时定义接口的场景。评审意见足够具体的话，开发可以先自己消化一轮，联调会议就不用开得那么累。
4.5 repo-map：新仓库和新同事的快速上手工具
repo-map 的核心目标是让 Codex 在进入一个新仓库时，先产生全局认知，而不是上来就改代码。具体落地方式是把技能绑定在“分析仓库结构”这个场景上：入口在哪、模块怎么划分、测试怎么跑、部署脚本在哪个目录、代码风格有什么特殊约定，全部扫一遍之后，生成一份仓库地图。
这份地图有几个用处。第一，直接补充到项目根目录的 AGENTS.md 里，后续所有 Codex 会话都能共享；第二，作为新人的 onboarding 文档，配合 doc-writer 生成的 README，基本能把“上手成本”从以天计降到以小时计；第三，当仓库结构变化时，定期重跑这个 skill 维护地图，避免文档和代码脱节。
实际上我自己很多项目第一次用 Codex 时，都会先跑一次 repo-map，让 Codex 自己把 AGENTS.md 建起来。后面不管开多少个会话，它的上下文一致性会好很多。这也是我强烈建议先收藏的一个 skill。
5. 第三批 5 个：平时不起眼，关键时刻能救场的 skill
5.1 security-scan：密钥、硬编码与常见风险的日常扫雷
安全审查不是只给安全团队用的。日常要检查的事情其实很具体：代码里是不是不小心提交过密码、token、云厂商密钥；接口是不是少了权限校验；是否拼接了用户输入去执行命令或查询数据库。security-scan 就是把这类高频检查做成技能，让 Codex 在改动合并前自动扫一遍。
我在 skill 里给出的检查项包括：硬编码密钥、路径穿越、注入风险、越权访问、反序列化风险。每一项都要求输出位置、风险等级和修复建议。最有效的一个用法是配合 CI，把 security-scan 的输出直接贴进合并请求评论，让开发者提交代码时就能看到风险提示，而不是上线后被扫出来再紧急修复。
需要提醒的是，别把它当成专业的安全审计工具，它更适合做第一轮粗筛。真正的高危场景，还是要人工审计加专业扫描工具配合。用它至少能拦住最粗心的那类问题，比如把所有环境变量一次性提交到公开仓库。
5.2 perf-profiler：用证据找性能瓶颈
性能优化的坑在于，凭直觉猜瓶颈通常不准。perf-profiler 这个技能强调“先拿数据，再下结论”。你可以把 profiler 输出、慢接口的调用链路、或者一段 CPU 占用数据丢给它，让它按热点函数、内存分配、锁竞争等维度拆解，找出最值得动手的部分。
关键约束是要求 Codex 区分“观测到的现象”和“推测的原因”。现象必须来自你提供的数据，推测原因必须标注出需要进一步验证。因为性能问题最容易出现“改错地方”的情况，改了三天发现瓶颈根本不在那儿。输出报告我会要求包含三块：热点排名、可能原因、验证方案。可以据此按优先级去压测验证，效率高很多。
5.3 a11y-review：被忽视的无障碍细节
无障碍审查在大多数团队里优先级都不高，但这又是真实用户需要的东西。a11y-review 让 Codex 扫描前端代码里的无障碍问题：图片有没有 alt、表单控件有没有 label、按钮能不能用键盘操作、颜色对比度是否足够、焦点有没有清晰的可见状态。
这个技能绑定在组件代码和页面代码上，输入一段 JSX 或 Vue 模板就可以开始查。Codex 对常见无障碍规则的掌握比较扎实，能给出很具体的修改建议。做这一项不需要专门配人，我通常会在组件库升级或页面改版后跑一轮，成本低，又能在不影响功能的情况下提升可用性。
5.4 pipeline-debug：CI 一直红的时候，别再人肉翻日志
CI/CD 流水线坏了，最痛苦的不是改配置，而是从一堆日志里找失败原因。pipeline-debug 就是把流水线的失败日志喂给 Codex，让它按阶段定位：是编译失败、依赖下载问题、测试超时、部署权限不足，还是配置语法错误。
我的建议是让技能先输出“失败阶段定位”，再输出“最可能的失败原因”和“修复步骤”，并且明确要求它说明每个结论对应的日志证据。常见问题就那么几类，Codex 识别的准确率相当高。真正的高价值场景是，它不只告诉你哪里错了，还能结合项目情况给出修复方案，节省大量人肉排查时间。
5.5 skill-creator：用 Codex 自己写新 skill
最后一个压轴技能，是创造一个“技能生成器”。它的输入是你的需求描述——“我想要一个 skill，用来检查代码里是否有被硬编码的超时时间”，输出就是一个可以直接导入的 SKILL.md，包含元信息、执行步骤、检查清单、输出模板和禁止事项。
我为什么把它放进名单里？因为 skill 这东西最大的门槛不是用，而是写。技能生成器能把“把经验固化成文件”这个过程的成本降到很低。我实际使用时的提示词很简单：描述任务目标、说明使用频率、列出已知的坑，然后让 skill-creator 生成第一版；我再审一遍，往往只要改几处就能投入使用。这也让前面的 14 个技能可以持续扩展，而不是一份固定死清单。
6. 实操心得：我写 skill 踩过的 6 个坑
6.1 把 skill 写成了作文，没有写检查清单
我第一次写 skill 时，洋洋洒洒写了一大段“请仔细审查代码，确保代码质量高、可读性好”之类的话。给 Codex 用了之后，输出和普通提示词提问没区别。后来才意识到，skill 里最有价值的部分是具体到能“逐个打勾”的检查项。比如“确认是否捕获了异常且没有写日志”，一条顶十句空话。写 skill 时，动笔的顺序应该是先列检查清单，再补流程说明。
6.2 只让 Codex 做什么，没有告诉它不能做什么
模型有一个特点：没有明确禁区时，它喜欢按自己理解自由发挥。比如 code-review 没写“不要修改代码”，它就真的会顺手帮你改；安全扫描没写“不要执行带副作用的命令”，它就可能尝试改动环境。后来我在所有 skill 尾部都加了一个“禁止事项”区块，把绝对不能做的一一列清楚，行为立刻稳定了很多。
6.3 缺少输出模板，结论五花八门
没有格式约定时，同一个 skill 两次输出可能结构完全不同，有时给表格，有时给长文，看着累。我在所有高频 skill 里都要求固定输出模板，比如结论分级、证据链、风险等级这些字段必须出现。格式定了，人对输出结果的检查速度会快非常多。
6.4 一个技能里塞了太多场景
最初习惯把一个目录相关的所有问题写进同一个技能，结果它反而不知道该按哪套流程来。比如把“重构、格式化、加注释”塞在一起，触发时行为很混乱。后来拆成单一职责：一个技能只做一件事，相关的动作通过调用其他技能完成。这也是我给清单里每个技能都用非常具体名字的原因。
6.5 只有步骤，没有退出标准
步骤定义了做事的顺序，退出标准定义了什么时候算完成。没有退出标准，Codex 容易一直列不完，或者自行扩大范围，把“审查一下改动”变成“顺手帮你重构了整个文件”。我在写 skill 时会明确写上“完成判定”，例如审查完所有文件、每个问题都给出结论分级、不再输出新问题时即结束。这个字段看起来不起眼，实际作用极大。
6.6 没有纳入版本管理
skill 文件是经验资产，和代码一样会演进。我以前图省事，只存在本地目录，结果某次换电脑，发现自己辛辛苦苦调校过的 skill 全没了。现在我会把通用技能放到一个独立的配置仓库里，团队项目相关的则放在项目目录下随代码走。这样既能跨设备同步，又能通过 review 来迭代技能，一举两得。
7. 常见问题与实践建议
7.1 高频问题速查表
| 问题 | 答案 |
|---|---|
| skill 和普通 prompt 有什么区别？ | 普通 prompt 是一次性的，skill 是可复用、结构化的操作手册，包含检查清单和输出格式。 |
| skill 会显著拖慢 Codex 吗？ | 一般不会，它只是上下文里多了一段规范文本；反而因为输出更聚焦，后续返工更少。 |
| 技能文件应该放哪？ | 个人通用技能放用户配置目录，团队相关放项目目录，并通过 AGENTS.md 加强项目级约束。 |
| 多个 skill 之间会冲突吗？ | 尽量保持单一职责，触发词和场景别重叠；出现冲突时，优先项目级规则。 |
| 所有 skill 都要从零写吗？ | 不用。可以先让 Codex 用 skill-creator 生成初版，再人工修改迭代。 |
| Codex 每次都会自动加载所有 skill 吗？ | 通常是根据意图和描述匹配加载，不会全部加载；简洁清晰的 description 能提高匹配准确率。 |
7.2 用三个问题决定要不要写 skill
以后你再遇到一个“想做成 skill”的想法，先问自己三个问题：这件事是不是每个月都会发生三次以上？输入输出边界是否清楚？结果能不能被快速验证？如果三个答案都是是，那就值得写；如果有一个不满足，先放一放，等真正痛了再说。这样做的目的是防止技能库膨胀成一个什么都有一点、但什么都不可靠的大杂烩。
最后分享一点我的体会。skill 这个东西，上手第一周最容易犯的错误是贪多，一口气配完 15 个，结果很多技能根本不会被触发，还会让加载和匹配变混乱。我的做法是先从每天都要用的 3 个开始：code-review、crash-trace、repo-map。稳定跑顺之后，再根据真实遇到的重复问题，用 skill-creator 一个一个补进来。你收藏的永远不会是这份清单本身，而是清单背后那一套“把经验固化下来”的习惯。等到你开始主动整理第二个、第三个 skill 的时候，这套工作方式就已经是你的了。
