Codex 的 skills 话题最近真的是肉眼可见地热起来了，社区仓库、个人博客、开发者群里到处都在转发各种技能包。我这个人的习惯是，先观望，等大家把坑踩得差不多了再动手。上个月我终于抽出整段时间，把 GitHub 上几个主流的 skills 列表、第三方汇总仓库、官方文档全部过了一遍。不看不知道，真的打开了一个新世界，但同时也是个一言难尽的货架：能用的好东西不少，挂羊头卖狗肉的更多。
今天这篇就写两个事：一是告诉你我翻完几百个技能之后，真正留在手里的到底有哪几个，它们解决了什么实际问题；二是把我从下载安装到跑通、再到踩坑的全过程完整记录下来。尤其那种"装上去以为完事，结果 Codex 根本不理你"的情况，我会把排查路径一步步写出来，省得你再走一遍弯路。
1. 动手之前：先理清 Codex Skills 到底是什么
在讲我留下的技能之前，得先把这个机制说透，不然很多操作你会怎么都想不通。
1.1 Skills 和普通提示词的本质区别
Codex 本身是一个大而全的编程代理，你给它一句话，它能帮你改代码、跑命令、看报错，能力很强。但"强"和"听话"是两回事。默认状态下，你让它改前端，它可能直接输出一段代码就完事，不会主动去看你的配置文件、不会检查构建链路、不会考虑你项目里已有的技术栈约束。
Skills 本质上是一套打包好的指令集：一个 SKILL.md 文件（里面写了这个技能的定义、适用场景、执行步骤、输出格式），有时候还附带脚本、模板、参考文档。把它们放进 Codex 能扫描到的技能目录之后，代理在执行任务时就能读到这些说明，按照你预设的流程工作。
用大白话说：默认 Codex 像一位名校毕业但刚入职的实习生，很有能力但需要你事无巨细地交代；Skill 则是给他的一份"岗位 SOP 手册"，把怎么做、做到什么程度、先做什么后做什么都写清楚，他照着执行，结果就稳定很多。
1.2 我翻技能货架时用的筛选标准
把社区里流传的几份大清单打开之后，说实话第一反应是眼花缭乱。什么"一键部署 skill"、"UI 生成 skill"、"论文写作 skill"、"分镜 skill"，甚至还有各种以开发者个人名字命名的"全家桶"。数量估计快两百个了，真一个个装肯定不行，光启动时加载就够呛。
我给自己定了几条筛选标准，也是我劝大家下载技能前先想清楚的问题：
- 解决的是不是高频真实痛点。那些听着炫酷但平时根本用不上的技能，装完就是吃灰。
- 指令是否有明确的执行路径和边界。好的技能会写清楚"第一步检查什么、第二步判断什么、第三步输出什么"，而不是一堆抽象原则。
- 能否低成本修改和维护。技能一定得自己能改，很多技能包作者不维护了，你得能自己接盘。
- 依赖尽量少。动不动就要求额外配置 API 密钥、专门写脚本做数据清洗的，我一般直接放弃。
- 是否容易被误触发。描述写得含糊的技能，会在完全不相干的对话里跳出来干扰判断，这种坚决不要。
带着这些标准再看那个货架，很多花架子很快就筛掉了。剩下来而且我真正每天在用的，集中在四个方向：前端工程、系统性排错、安全基线审计、代码审查。
2. 我真正留在手里的四个核心技能
2.1 前端工程架构：从"写组件"到"管工程"
市面上叫"前端开发 skills"的包我看了不下十个，大部分只是在提示词里写"你是资深前端工程师，遵循最佳实践"，这在我看来没有任何信息增量。我留下的这个技能，强在它把前端专家平时不会明说的隐性操作全部显性化了。
它会按顺序执行一套比较完整的流程：先读package.json，确认依赖版本和脚本命令；再看tsconfig.json里的路径别名、编译目标；接着检查 Tailwind/PostCSS 或者其他 CSS 方案配置；最后结合src/目录的结构，判断新组件应该放哪个位置、要不要抽公共模块、事件处理要不要做防抖等等。
做一个对比你就明白了。我之前让原始 Codex 开发一个筛选表格组件，它直接给我一个"看起来差不多"的东西，样式变量写死、状态随手放在组件内部、按钮逻辑没有防重复点击。后来我让加载了这个技能之后的 Codex 再做同一件事，它会先问我这个项目是偏内部后台还是对外展示、要不要做列表缓存、主题变量想用哪一套。这完全是两个层级的产物。
这个技能的实际使用体验，最舒服的是它输出代码之前会先给一份"改动计划清单"，列清楚动了哪些文件、为什么这么做，我看一眼没问题再让它继续。代码审查环节等于前置了，不用等写完再 debug。
我当时本来想把这个技能拆成"只处理 React"或者"只处理 Vue"的窄版本，后来发现它做得好的地方就是对前端工程通用问题的覆盖面广，反而没必要自我阉割。
2.2 系统性排错：把"猜"变成"假设-验证"闭环
写代码的人都会遇到这种时刻：改了一行配置，重启之后整条链路开始报错，报错信息晦涩难懂，而且连个准确定位都给不出来。我以前经常被这种问题拖出两三个小时，靠经验和感觉去试。
我留下的这个排查技能，本质上是把资深工程师的 debug 方法论固化了下来。遇到报错时它会这样工作：先让我提供触发操作、报错信息、改动时间线；然后列出一个假设清单，按概率排序；接着针对第一个假设，先通过日志、命令、配置查询来低成本验证；验证失败就排除，继续下一个。全程不会像默认模型那样，看到一段报错就跳进代码里乱翻。
举个例子，有次我的 Codex 环境里某条功能请求链路莫名其妙全挂了，报错显示是某个本地网络转发服务在拦截 Codex 的 API 请求，而我又不确定到底是配置问题还是服务本身的问题。换做以前，我可能会随手去改一堆开关，试一回挂一回。这次我先让技能介入，它把相关日志导出来做了先后的比对，判断出是环境变量加载顺序有变化，导致转发服务的地址在 Codex 启动时被配置成了错误的值。整个过程十分钟不到，关键是它每一步都有根据。
我最喜欢这个技能的一点，是它会强制 Codex 区分"事实、假设、待验证项"三种信息。默认状态下模型经常把假设当结论说出来，这个技能能按住它的不确定性，逼着先验证再下结论。
2.3 本地安全基线审计：不是"挖洞"而是兜底
当时看到热搜里带"自动挖洞 skills"这个词，我就知道这是社区里一个比较野的方向。我这边实际留下的安全相关技能，定位完全不同：它不找漏洞去打，而是做基线审计，也就是在经过授权的本地项目里，检查常见的风险配置和代码缺陷，输出一份可执行的问题清单。
这个技能的工作范围包括检查暴露的调试接口、硬编码密钥、越权的接口设计思路、危险依赖版本、缺失输入校验等。它产出的是修复建议，不是利用过程。我团队里每个接手的老项目，我都会先用它跑一遍基线，相当于给代码做个体检。
有一次检查一个内部系统，它发现某个后台接口的鉴权判断居然放在了参数解析之后，导致如果传入一个畸形数据格式，鉴权逻辑会被跳过，直接走数据库查询。这种问题手动审很难发现，因为它不报错、不崩溃，只有带着审计清单逐条核对才能露馅。
这里必须强调一句：安全技能的使用边界一定要清楚，只对自己有权限的项目做审计。任何越权的、主动攻击性质的操作都不在我的讨论范围内，也不建议任何人去碰。我把这个技能留下来，就是因为它是防御视角，和那些放在 GitHub 上声明"仅限技术交流"的漏洞利用工具完全是两回事。
2.4 代码审查与重构验收：MR 阶段的好帮手
第四个我留下的技能是代码审查用的。平时自己在 MR（Merge Request）里看代码，最烦的就是看了一大段，结果只挑出几个命名问题和换行风格。真正影响代码质量的东西——循环里的重复查询、组件的状态耦合、事务边界异常、异常被吞掉——这些问题不靠经验和嗅觉很难发现。
这个技能使用时，我会直接把它接在 diff 之后，让它按照几个维度做检查：逻辑正确性、边界条件、性能隐患、数据结构合理性、可测试性、以及和现有代码风格的兼容性。输出格式是我比较喜欢的：严重问题单独列，次要问题按严重程度排序，每条都标注涉及文件和具体行号，并给出修改示例。
它在团队协作中最大的价值不是抓 bug，而是当"第二双眼睛"。我自己编码时容易陷入惯性，觉得自己写的没问题，但它经常能从另一个角度给出质疑。有好几次，它发现的隐患确实让我冒了冷汗，比如一个列表组件删除 key 的时候没做确认、一个批量更新接口没有对空列表做拦截，这些我根本不可能全部靠人眼盯出来。
如果你做的项目很小，可能感受不到这个技能的威力；但只要你的 MR 是面向团队、要给别人 review 的，这个技能基本等于把初级 review 员的活给包了，你只需要处理剩下的架构级讨论。
3. 安装与配置：完整路径和我踩过的坑
选好了技能，接下来就是实际动手安装。这一步看着简单，但坑是真不少。
3.1 三个存放位置和它们的加载逻辑
Codex 技能有一套约定好的目录结构，不同版本可能有细微差别，核心逻辑是你把这个技能包放到指定的 skills 目录下，启动时它就会被扫描到。
常用方法是这样的，直接在本地建目录：
# 全局技能，任何项目下都能用 mkdir -p ~/.codex/skills/frontend-engineering mkdir -p ~/.codex/skills/debugging-method # 可以把技能包里的 SKILL.md 和其他文件都放进来 # 比如 ~/.codex/skills/frontend-engineering/SKILL.md还有一种用法是项目级技能，放在当前项目的.codex/skills/目录下面：
# 项目级技能，只有在这个仓库里才会被加载 mkdir -p .codex/skills/security-baseline mkdir -p .codex/skills/code-review你可能会好奇两种方式到底怎么选。我的习惯是：通用能力放全局，比如排错方法和代码审查；和具体技术栈强绑定的技能放项目级，比如前端工程架构。这样做的好处是你在 A 项目加载的技能不会跑到 B 项目里误触发，避免上下文被一些没用的描述占用。
技能加载之后，不是每个技能都会自动跑。真正会"主动跳出来"的技能，通常在 SKILL.md 的 description 里写了很明确的触发条件，Codex 会判断当前场景是否匹配。匹配不到或者描述模糊的技能，你得在对话里显式提一下技能名字，它才会开始执行。这本来就是合理的设计，不然几十个技能同时输出，上下文早就爆了。
3.2 从压缩包安装时容易忽略的目录结构问题
社区里不少技能打包下载后是一个 zip 或者从 GitHub 直接 clone 下来。很多人把仓库 clone 下来之后直接塞到~/.codex/skills/下面，结果发现完全加载不上。我也栽过。
原因很简单：很多技能仓库的根目录是 README 和 LICENSE，SKILL.md 在某个子目录里。如果你把整个仓库塞进~/.codex/skills/foo/，Codex 又在这个目录下找了一级foo/SKILL.md，会发现找不到。正确的做法是把仓库里的某个子目录（也就是真正装着 SKILL.md 的那一层）放到~/.codex/skills/下，或者干脆把你需要的那一层作为一个新的独立目录。
有个快速验证的方法：装完之后用文件管理器看一眼目标技能的绝对路径，确认是~/.codex/skills/xxx/SKILL.md，不要多一层嵌套，不然百分之百加载不了。
3.3 那几个让人血压升高的报错和排查过程
装技能的过程中我遇到过高频报错，这里直接按"症状-原因-解决"的方式拆开讲。
"codex is ignoring 1 unrecognized configuration setting. check for typos"
这个报错最容易出现在你从别人那里复制技能包时，技能里夹带了一个老的config.toml片段，或者技能作者在文档里让你往全局配置里加某个键，但你的 Codex 版本根本还没支持这个键。解决办法是先找到 Codex 的配置文件（一般在~/.codex/config.toml），把报错提示的那个键注释或者删掉，然后再启动。别指望那个技能作者会很快更新，很多包半年都不动一次。
环境里某个本地网络转发服务导致 Codex 请求全部失败
这个非常隐蔽，因为报错信息看起来和技能毫无关系，但确实是在我刚加载一批技能后出现的。症状是 Codex 请求 API 端点时返回失败，日志里能看到本地转发链路相关的报错，而技能本身根本没有网络功能。后来查下来，是环境变量里配置的转发地址在加载某个技能的命令脚本时，被意外覆盖成无效值了。
这算是第三方技能的一个风险点：技能包里的脚本会执行命令，可能会改动环境变量或者写临时配置文件。所以你下载技能时一定要长个心眼，下载后先打开脚本和 SKILL.md 看一眼，尤其是带 install.sh、setup.sh 这种动不动就改写环境的包，直接绕过。
"the 'gpt-5.6-sol' model is not supported when using codex"
这个报错的经验同样是：Skills 解决不了模型支持的问题。技能只能改变 Codex 的执行流程和输出规范，底层的模型选择、权限范围还是受账号和版本限制。有人从某些第三方渠道拿到了非常规的模型名称，填到配置里，结果当然不认。这个问题的处理方式很简单，回到配置里把模型名改成当前版本官方支持的 ID 就行，别指望任何 skill 能“解锁”模型能力。
"codex 无法加载组织设置"
这类问题一般不是技能造成的，而是登录状态或者网络链路异常。我遇到一次，是本地网络环境切换后，Codex 没重新走一遍登录流程，导致它拉取组织列表失败。处理方式也很朴素：退出登录、重新认证一次。如果还不行，就把技能目录暂时改名成备份，等确认基础功能恢复再逐个加回来。这一步是很好的隔离方法，能快速区分是技能本身的问题还是环境的问题。
你把这些排查过程串联起来看，会发现很多报错不是技能的问题，而是技能暴露出了环境里本来就存在的毛病。所以排查的优先级一定是从环境到技能，而不是反过来一开始就怀疑技能目录。
4. 把技能接入真实工作流之后，我的体会完全不同了
4.1 一个前端改造任务的实测对比
我拿一个真实案例来说明。我这边有个老项目，是 React + TypeScript + Vite 的技术栈，组件划分混乱，样式命名完全靠心情。任务是给用户列表页加筛选和分页功能。
加载技能之前，Codex 的输出非常"顺滑"：写一个UserList组件，里面放几个 useState，接一个 fetch，render 到表格里。看起来一切正常，但实际上它完全没有意识到这个项目的筛选条件和分页状态需要和 URL 参数同步，而这正是这个页面最核心的交互要求。结果做出来的东西能用，但一刷新页面就丢状态，体验非常初级。
加载技能之后，它先给我了一个计划：检查路由配置、看看这个页面是怎么被调用的、有没有全局状态管理、现有接口对分页参数怎么约定的。然后它说，URL 参数同步就做在列表页这个组件里，不用动全局状态。最后输出的代码里，从useSearchParams读取状态、筛选条件变化时更新 URL、分页页码同步到 query，全部串起来了。
我做的只是触发了一次技能，后面它自主完成的步骤比我以前手动给 Codex 反复强调三遍还要细致。最重要的是，它输出的结构让我一眼就能看懂，改动范围小、匹配现有代码风格，不用事后大改。
4.2 技能工作流下我的角色转变
用技能用了一个多月之后，最明显的变化不是"让 Codex 帮你写更多代码"，而是我的工作流位置变了。以前我把大部分时间花在描述需求、补充约束、纠正代码方向上，简单说就是花大力气当"翻译官"，把人类需求翻译成模型听得懂的话。现在有了技能，大部分约束条件已经内置了，我需要做的只是判断产出、给出方向、处理边界情况。
我现在基本不会让 Codex 直接对着空编辑器"给我做一个功能"，而是先让技能跑一遍项目分析，拿到它的分析结果后，我再像 check-in 一样确认哪些能做、哪些不能做。产出之后，审查环节也有代码审查技能帮我过滤掉低质量问题。
所以如果你问，"有技能之后是不是啥事都不用干，直接给它派活就行"，我的回答是恰恰相反：你需要把精力从重复劳动的细节上撤出来，放在更有判断价值的审查和决策上。这才是技能真正让你工作效率变高的方式——不是让你躺着，而是让你把时间用在刀刃上。
4.3 不要囤技能：维护成本和误触发都得算进去
我在翻技能货架那段时期，也经历了所有新手的通病：看到什么都想装。今天看到一个部署技能感觉能用，明天看到一个数据库优化技能也觉得不错，一个星期下来装了十几个。
结果是什么呢？第一，每次打开 Codex，技能描述占掉大量上下文窗口，真正干活时模型反而被无关指令干扰；第二，几个描述写得模糊的技能会互相抢触发，我明明只是想让它改个变量名，结果它莫名其妙跑了一遍安全审计流程，浪费时间和额度；第三，技能作者更新版本之后，如果我不跟踪，出问题的技能还得自己修。
后来我痛下决心，按之前说的标准把技能砍到四个，世界清爽了。我的原则是：装新技能之前，必须强制自己在未来两周内找到三个真实场景要用它，找不到就不装。装上之后如果两周没碰一次，就删掉或者移出目录备份。技能不是收藏品，是工具，是工具就得常用常新。
4.4 自己动手改技能，才是最值的部分
用了一段时间之后，我开始不满足于直接用别人的技能，而是尝试修改里面不满意的地方。我自己改得最多的，是给前端工程架构技能加了一个项目特有的"禁用清单"：这个项目不能使用某些旧的样式写法，新代码必须走指定的组件库入口。这些写在技术文档里没人看，写进技能里，Codex 每次跑都能遵守。
改技能的过程也不复杂，就是编辑 SKILL.md 里的对应段落，把约束条件加上去。如果你想自己做一个新技能，甚至可以直接复制一个最简结构：
--- name: example-skill description: 这个技能用于处理某类任务，只有出现"XX"关键词时才触发 --- 技能目标： 1. 先检查 XX 文件 2. 再执行 XX 操作 3. 最后输出 XX 格式的结论写完之后放到~/.codex/skills/或.codex/skills/下，就能在会话里加载。你会发现，自己动手写的技能往往比从网上抄来的好用得多，因为它是真正贴合你的项目场景的。
5. 给想入坑的朋友几句掏心窝的话
最后总结几条实际经验吧，都是我"翻完货架"走到现在觉得最值得讲的东西。
第一，在技能市场里找技能，永远不要先下载再看。正确顺序是：先明确你工作中最烦的三件事，列出高频重复的场景，然后找对应的技能包，再打开看它到底怎么实现的。我淘汰掉的绝大多数技能，都是因为没有站在真实需求的角度去筛选。
第二，对于下载来的第三方技能，一定要养成"先看代码再运行"的习惯。SKILL.md 和脚本文件本质上是代码，是有执行逻辑的。你要看它会不会做无害读取以外的操作，会不会读取密钥、修改全局配置、写外部文件。安全底线一定要自己守住。
第三，学会用代码审查技能审视技能本身。我自己就是这么干的：把某个技能包的 SKILL.md 丢给代码审查技能，让它列出这个技能的指令有没有歧义、有没有边界不清晰的地方、会不会被误触发。这个组合打法的杀伤力很强，基本上能帮你过滤掉大量粗制滥造内容。
说到底，技能机制给我最大的一个感受是：AI 编程工具的差距，正在从模型能力转移到"你对工具的驾驭能力"上。模型本身已经很强，怎么把它嵌进你自己的工程体系，才是真正拉开效率差距的地方。这四个技能就是我目前摸索出来的最优组合，以后多半还会变，但方法论不会变：少而精、可维护、贴合场景。如果你正打算翻一翻 Codex 的技能货架，先从这四个入手，应该不会让你失望。
