1. 先搞清楚 Codex 的 Skill 到底是个什么东西很多人第一次接触 Codex 的 Skill 体系时脑子里冒出来的第一个问题就是这跟插件有什么区别我直接写提示词不行吗我刚开始也是这么想的直到我把同一套任务分别用纯提示词和 Skill 跑了一遍才发现两者的差距不在功能上而在稳定性和复用性上。Skill 的本质是把一段经过验证的、结构化的能力封装成一个可被反复调用的单元。你可以把它理解成厨房里的预制菜包——不是说你不能从零切菜配料而是当你每天都要做同一道菜的时候有一个配比固定、步骤明确的料包出品的稳定性会高出一大截。纯提示词的问题在于每次你都要重新描述一遍上下文、约束条件、输出格式稍微漏掉一个细节结果就跑偏了。Skill 把这些东西固化下来你只需要关心输入是什么。那 Codex 的 Skill 具体能干什么从实际使用来看它主要解决三类问题第一类是基础能力补齐比如让 Codex 稳定地按照某种代码规范输出、按照固定格式生成文档第二类是效率提升比如批量处理重复性任务、自动化一些手工操作第三类是业务逻辑封装把某个特定领域的知识和工作流打包成一个可复用的模块。适合谁来参考这篇内容如果你是刚装好 Codex、面对一堆 Skill 不知道从哪下手的新手这篇就是写给你的。如果你已经用了一段时间但 Skill 装了不少却感觉没发挥出应有的效果也可以对照着看看是不是分层没做对。我下面会按照基础层、提效层、业务层这三个层次把每一层该装什么、为什么这么装、装完之后怎么验证一步步拆开讲。提示不要一上来就追求装得多Skill 装太多但互相冲突比只装三个基础 Skill 的体验还要差。分层的目的就是让你知道什么阶段该装什么。2. 三层分类法的底层逻辑为什么不是按功能分而是按层次分2.1 按功能分类的陷阱市面上很多 Skill 推荐清单是按功能分的代码类、文档类、数据分析类、图像处理类。这种分法看起来清晰但实际用起来有个很大的问题——你很难判断两个功能不同的 Skill 之间会不会打架。举个例子你装了一个代码格式化的 Skill又装了一个代码审查的 Skill。单独用都没问题但当你让 Codex 审查一段代码并自动修复时两个 Skill 可能同时对输出格式提出要求一个说要按 PEP8 缩进另一个说要保留原始风格只改逻辑。结果就是 Codex 在两边反复横跳输出变得不稳定。按层次分就不一样了。基础层的 Skill 只负责让 Codex 能正常工作提效层的 Skill 只负责让 Codex 工作得更快业务层的 Skill 只负责让 Codex 懂某个领域的规矩。层次之间有明确的优先级基础层不满足提效层装了也白装提效层没跑通业务层就是空中楼阁。2.2 三层各自的职责边界我把这三层的职责边界整理成了一张表方便你对照理解层次核心职责典型 Skill 类型不装的后果装多了的后果基础层保证 Codex 能稳定理解指令、输出可用结果环境适配、编码规范、输出格式约束结果随机性大每次都要手动纠正约束过多Codex 变得死板稍微超纲就不会处理提效层减少重复劳动把常见操作自动化批量处理、模板生成、快捷指令大量时间花在重复输入上自动化流程互相嵌套出问题很难排查业务层让 Codex 理解特定领域的术语和流程行业术语库、业务流程模板、领域知识包输出内容外行需要大量人工修改领域知识过时或冲突导致输出错误且难以发现这张表的核心信息是每一层都有不装和装多两个方向的坑。新手最容易犯的错误是只看到不装的坑于是拼命装结果掉进装多的坑里。2.3 三层之间的依赖关系三层不是并列的而是有明确的依赖顺序。基础层是地基提效层是框架业务层是装修。地基没打好就搭框架框架会歪框架没搭好就搞装修装修会裂。我自己的经验是基础层的 Skill 数量控制在 3 到 5 个就够了提效层 5 到 8 个业务层根据你实际涉及的领域来定通常 2 到 4 个。这个数量不是拍脑袋定的而是根据 Codex 在处理单个任务时能同时激活的 Skill 数量上限来反推的。超过这个数量Skill 之间的干扰概率会显著上升。注意如果你现在只装了一两个 Skill 就觉得够用了那大概率是你还没遇到真正复杂的任务。等你遇到一个需要同时处理代码、文档和业务逻辑的任务时就会发现基础层和提效层的缺失有多要命。3. 基础层 Skill 怎么挑先让 Codex 能干活3.1 环境适配类 Skill 的选择标准环境适配类 Skill 解决的是Codex 能不能在你的机器上正常工作的问题。这类 Skill 通常跟你的操作系统、编程语言版本、项目结构有关。以 Python 项目为例你需要一个能识别你当前虚拟环境的 Skill。为什么这个很重要因为 Codex 默认可能使用系统级的 Python 解释器而你项目实际跑在 venv 或者 conda 环境里。如果不装这个 SkillCodex 生成的代码可能在你机器上跑不起来报一堆模块找不到的错误。选择这类 Skill 的标准有三条第一它要能自动检测当前工作目录下的环境配置文件比如pyproject.toml、requirements.txt、.python-version第二它要能在生成代码时自动带上正确的解释器路径第三它要能在环境切换时给出明确的提示而不是默默用错环境。我实测下来满足这三条的 Skill 不多但一旦找到就非常省心。你可以这样验证在一个 venv 环境里让 Codex 生成一段需要第三方库的代码看它会不会自动提示你安装依赖以及安装命令里用的 pip 是不是当前环境的 pip。3.2 编码规范类 Skill 的取舍编码规范类 Skill 是最容易被过度安装的一类。很多人看到Google Python Style Guide装一个PEP8装一个Black 格式化再装一个结果三个 Skill 同时生效时Codex 不知道该听谁的。我的建议是同一时间只激活一个编码规范类 Skill。如果你团队用的是 Black那就只装 Black 相关的 Skill把其他的禁用掉。如果你没有强制规范那就装一个最通用的、只约束基本格式缩进、命名、注释风格的 Skill不要装那种连变量名长度都要管的。这里有个实操技巧你可以在 Skill 的配置里设置优先级。比如把 Black 的 Skill 优先级设为高把通用的 PEP8 Skill 优先级设为低。这样当两者冲突时Codex 会优先遵循 Black 的规则。但说实话与其花时间调优先级不如直接只留一个省事得多。3.3 输出格式约束类 Skill 的配置要点输出格式约束类 Skill 解决的是Codex 返回的结果能不能直接用的问题。比如你让 Codex 生成一个 API 文档它默认可能返回一大段 Markdown但你需要的是可以直接导入 Swagger 的 JSON。这时候一个输出格式约束 Skill 就能派上用场。配置这类 Skill 时重点看三个参数输出格式JSON、YAML、Markdown、纯文本、字段映射你的字段名和 Codex 默认字段名的对应关系、错误处理当 Codex 无法按格式输出时是报错还是降级为纯文本。我踩过的一个坑是有些输出格式 Skill 默认开启严格模式只要 Codex 的输出有一点点不符合格式就整个报错导致你拿不到任何结果。实际使用中建议把严格模式关掉改成尽力而为模式先拿到结果再手动微调比反复重试效率高得多。3.4 基础层 Skill 的验证清单装完基础层 Skill 后不要急着装下一层先花十分钟做一轮验证。验证清单如下让 Codex 生成一段包含第三方库调用的代码检查它是否使用了正确的解释器路径让 Codex 格式化一段故意写得很乱的代码检查输出是否符合你预期的规范让 Codex 输出一个结构化数据比如一个包含五个字段的 JSON检查字段名和格式是否正确切换到一个不同的项目目录重复上述操作检查 Skill 是否能自动适配新环境这四步都通过了基础层才算搭好。任何一步出问题都先解决基础层的问题不要往下走。4. 提效层 Skill 怎么配把重复劳动交给机器4.1 批量处理类 Skill 的适用场景批量处理类 Skill 的核心价值是一次配置多次执行。最典型的场景是你有二十个格式相同的文件需要做同样的修改手动改要半小时用 Skill 可能两分钟就搞定了。但批量处理类 Skill 有个前提条件你的任务必须是高度重复且规则明确的。如果你的二十个文件每个都有不同的结构那批量处理反而会增加你的配置成本。判断标准很简单如果你能用一句话描述清楚对每个文件做什么那就适合用批量处理 Skill如果你需要针对每个文件说不同的话那就不适合。我常用的一个批量处理 Skill 是按模板生成文件。比如我需要为十个不同的模块生成单元测试文件每个文件的测试逻辑不同但结构相同。我会先写好一个模板然后用 Skill 批量生成最后手动填充每个文件的具体测试逻辑。这样比从零写十个文件快得多又比完全自动生成可控。4.2 模板生成类 Skill 的参数调优模板生成类 Skill 的关键在于模板本身的质量。一个糟糕的模板会让生成结果千篇一律且难以修改一个好的模板应该做到结构固定但内容灵活。调优模板时重点调整三个地方占位符的粒度、默认值的设置、条件分支的处理。占位符粒度太粗生成的结果需要大量手动修改粒度太细配置起来又很麻烦。我的经验是占位符的数量控制在 5 到 10 个之间比较合适。默认值的设置也很关键。比如你生成一个函数模板默认参数是None还是空字符串会直接影响生成代码的可读性。条件分支的处理则决定了模板能不能应对稍微复杂一点的场景比如如果项目使用 TypeScript 则生成类型定义否则生成 JSDoc 注释。4.3 快捷指令类 Skill 的冲突排查快捷指令类 Skill 让你可以用简短的命令触发复杂的操作。比如你设置一个/review指令Codex 就会自动执行读取当前文件、检查代码规范、生成审查报告这一整套流程。这类 Skill 最容易出的问题是指令冲突。你装了两个不同的 Skill都定义了/review指令Codex 就不知道该执行哪一个。排查方法是在 Codex 的配置里查看所有已注册的指令列表把重复的指令重命名或者禁用掉。另一个常见问题是指令嵌套过深。比如/deploy指令内部调用了/test指令/test又调用了/lint一旦中间某个环节出错你很难定位是哪个指令的问题。我的建议是快捷指令的嵌套层级不要超过两层超过两层就拆成独立的指令手动按顺序执行。4.4 提效层 Skill 的效果评估方法装完提效层 Skill 后你需要一个客观的方法来评估它到底有没有提升效率。我的做法是记录三个指标单次任务耗时、手动干预次数、结果返工率。单次任务耗时很好理解就是完成一个典型任务需要多少时间。手动干预次数是指在整个过程中你需要手动修改或补充多少次。结果返工率是指生成的结果需要完全重做的比例。一个合格的提效层 Skill 应该让单次任务耗时下降至少 30%手动干预次数下降至少 50%返工率控制在 10% 以内。如果装了之后这三个指标没有明显改善那要么是 Skill 本身不适合你的场景要么是你的配置方式有问题。提示不要只看最快的一次有多快要看最慢的一次有多慢。提效类 Skill 的价值在于稳定地节省时间而不是偶尔爆发一次。5. 业务层 Skill 怎么落地让 Codex 懂你的行业5.1 业务术语库的构建方法业务层 Skill 的核心是术语库。你所在的行业一定有自己的一套黑话和缩写Codex 默认是不懂的。比如在电商领域SKU、SPU、动销率这些词如果你不告诉 Codex 它们的确切含义生成的内容就会很外行。构建术语库的方法有两种一种是手动整理把你日常工作中高频出现的术语列出来给每个术语写一句准确的定义另一种是从现有文档中提取比如从你的产品需求文档、API 文档、数据库设计文档中把术语抽出来。我推荐两种方法结合使用。先手动整理一批核心术语大概 20 到 30 个保证覆盖你 80% 的日常场景。然后再从文档中提取补充把遗漏的术语补上。术语库不需要一次建完可以在使用过程中逐步完善。5.2 业务流程模板的设计原则业务流程模板是把你的工作流固化下来。比如你每次做需求评审都要经过理解需求、检查技术可行性、评估工作量、输出评审意见这四个步骤那就可以把这四个步骤做成一个流程模板。设计流程模板时要遵循三个原则步骤可跳过、输出可追溯、异常可处理。步骤可跳过是指某些步骤在特定情况下可以省略比如紧急需求可以跳过工作量评估。输出可追溯是指每个步骤的输出都要有记录方便后续回溯。异常可处理是指当某个步骤无法完成时流程能给出明确的提示而不是直接崩溃。5.3 领域知识包的更新策略领域知识包是最容易过时的一类 Skill。你所在行业的知识在更新你的知识包如果一直不更新Codex 就会用旧知识来处理新问题结果可想而知。更新策略取决于你所在领域的知识更新速度。技术领域可能每个月都要更新一次传统行业可能每季度更新一次就够了。更新的内容主要包括新增的术语、修改的定义、废弃的流程、新增的规范。我自己的做法是设置一个日历提醒每月的最后一周花半小时检查一下知识包是否需要更新。更新的时候不要大改每次只改确实需要改的地方改完做一轮验证确保没有引入新的冲突。5.4 业务层 Skill 的验证与迭代业务层 Skill 的验证比前两层更复杂因为它涉及到对领域知识的理解是否正确。我的验证方法是找三个你熟悉的业务场景分别用 Codex 处理一遍然后对照你手动处理的结果看差异在哪里。如果差异主要在格式上那说明基础层或提效层还有问题。如果差异主要在内容上比如 Codex 用错了术语或者搞错了流程那说明业务层的 Skill 需要调整。迭代的时候优先修正那些高频且影响大的问题。比如一个术语用错了如果这个术语在你日常工作中出现频率很高那就优先修正如果只是偶尔出现可以放到下一轮迭代再处理。6. 实操从零开始搭建你的第一套 Skill 组合6.1 安装前的环境检查在装任何 Skill 之前先确认你的 Codex 版本和运行环境。打开终端运行以下命令查看版本信息codex --version如果版本低于你需要的 Skill 所要求的最低版本先升级 Codex。升级命令根据你的安装方式不同而不同如果是通过包管理器安装的用对应的升级命令即可。然后检查你的工作目录结构。Codex 的 Skill 通常会读取当前目录下的配置文件所以你需要确保配置文件在正确的位置。常见的配置文件包括.codex/config.json、codex.config.js等具体取决于你的 Codex 版本和安装方式。6.2 基础层 Skill 的安装与配置基础层我建议从三个 Skill 开始环境适配、编码规范、输出格式。安装方式通常有两种通过命令行安装和通过配置文件声明。命令行安装的示例codex skill install env-adapter codex skill install code-style codex skill install output-format配置文件声明的方式是在.codex/config.json中添加{ skills: [ { name: env-adapter, enabled: true, priority: 1 }, { name: code-style, enabled: true, priority: 2, config: { style: black, lineLength: 88 } }, { name: output-format, enabled: true, priority: 3, config: { strict: false, defaultFormat: markdown } } ] }配置完成后重启 Codex 使配置生效。然后按照 3.4 节的验证清单做一轮检查。6.3 提效层 Skill 的逐步接入提效层不要一次全装上建议一个一个来。先装一个批量处理 Skill用一周时间熟悉它的用法确认没有冲突后再装下一个。以模板生成 Skill 为例安装后的第一步是创建你的第一个模板。模板文件通常放在.codex/templates/目录下。一个简单的函数模板示例--- name: function-template description: 生成标准函数结构 variables: - name: functionName description: 函数名称 - name: params description: 参数列表 - name: returnType description: 返回类型 --- def {{functionName}}({{params}}) - {{returnType}}: TODO: 添加函数说明 pass创建好模板后用/template function-template指令测试一下看生成的结果是否符合预期。6.4 业务层 Skill 的定制化配置业务层 Skill 通常需要你自己定制因为每个行业的术语和流程都不一样。定制的方式有两种一种是基于现有的通用 Skill 修改配置另一种是从零创建一个新的 Skill。从零创建 Skill 的基本结构如下{ name: my-domain-knowledge, version: 1.0.0, description: 我的领域知识包, terms: { 术语A: 术语A的准确定义, 术语B: 术语B的准确定义 }, workflows: { 需求评审: [ 理解需求背景, 检查技术可行性, 评估工作量, 输出评审意见 ] } }把这个文件放在.codex/skills/目录下然后在配置中启用它。6.5 三层 Skill 的联调测试三层都装好后做一次联调测试。找一个你实际工作中的任务完整地跑一遍观察三个层次的 Skill 是否都能正常发挥作用。联调测试的重点是检查层次之间的衔接。比如基础层的输出格式约束会不会影响提效层的模板生成提效层的批量处理会不会触发业务层的术语检查如果发现层次之间有冲突优先调整基础层的配置因为基础层是其他两层的基础。7. 常见问题与排查技巧实录7.1 Skill 装了不生效怎么办这是最常见的问题。排查顺序如下第一检查 Skill 是否已启用。有些 Skill 安装后默认是禁用状态需要在配置中手动开启。第二检查优先级设置。如果两个 Skill 的优先级相同且功能冲突Codex 可能随机选择一个执行。把优先级区分开。第三检查配置文件的位置。Codex 可能读取的是全局配置而不是项目配置或者反过来。确认你的配置写在了正确的位置。第四查看日志。Codex 通常会在日志中记录 Skill 的加载情况日志文件一般在.codex/logs/目录下。7.2 Skill 之间冲突的典型表现Skill 冲突的表现有很多种我整理了一个速查表表现可能原因解决方法输出格式忽变两个格式约束 Skill 同时生效禁用其中一个或调整优先级指令无响应快捷指令重名重命名冲突的指令生成结果不完整某个 Skill 的严格模式拦截了输出关闭严格模式执行速度明显变慢Skill 嵌套过深拆解嵌套减少层级术语使用混乱多个业务层 Skill 定义了同一术语合并术语库统一来源7.3 性能下降的排查思路如果你发现装了 Skill 之后 Codex 的响应速度明显变慢先别急着卸载。按以下步骤排查第一步禁用所有提效层和业务层的 Skill只保留基础层看速度是否恢复。如果恢复了说明问题出在提效层或业务层。第二步逐个启用提效层的 Skill每启用一个测一次速度找到导致变慢的那个。第三步检查这个 Skill 的配置看是否有不必要的计算或过大的数据加载。比如一个术语库如果包含了几千个术语每次调用都要全量加载速度自然会慢。这时候可以把术语库拆分成多个小文件按需加载。7.4 版本更新后的兼容性处理Codex 本身会更新Skill 也会更新。更新之后经常出现的问题是新版本不兼容旧配置。处理方法是更新前先备份你的配置文件。更新后如果发现 Skill 不工作先查看更新日志中是否有破坏性变更的说明。如果有按照说明修改配置。如果没有尝试回滚到上一个版本等 Skill 作者发布兼容版本后再更新。我自己的习惯是Codex 主版本更新后先等一周再更新看看社区有没有反馈兼容性问题。这一周的时间差可以帮你避开很多坑。7.5 新手最容易踩的五个坑第一个坑一次性装太多 Skill。前面已经说过这里再强调一遍分层逐步接入是唯一正确的方式。第二个坑忽略基础层直接装业务层。结果就是业务层的输出格式乱七八糟根本没法用。第三个坑不写配置注释。过了一个月你自己都不记得每个 Skill 是干什么的更别说排查问题了。第四个坑从不更新术语库。用半年前的术语库处理今天的任务输出内容会显得很过时。第五个坑遇到问题就卸载重装。很多时候问题出在配置上卸载重装解决不了根本问题反而会丢失你之前的配置。提示每次修改 Skill 配置后都做一次快速验证生成一段简单代码或文档确认没有引入新问题。这个习惯能帮你省下大量排查时间。8. 我个人的一些使用体会装 Skill 这件事说到底跟收拾工具箱是一个道理。新手总想把所有工具都塞进箱子里结果箱子重得拎不动真要用的时候还找不到想要的。老手则只带最常用的几件需要什么再临时加。我现在的配置是基础层三个、提效层五个、业务层两个总共十个 Skill。这个数量用了大半年期间只做过微调没有大改。我的建议是你先按照这篇内容把三层框架搭起来然后在使用过程中慢慢调整。不要追求一步到位也不要看到别人推荐什么就装什么。另外说一个我踩过的坑有段时间我为了追求自动化把很多手动步骤都做成了 Skill结果后来发现有些步骤手动做反而更快因为自动化的配置和维护成本比手动执行还高。所以装 Skill 之前先问自己一句这个操作我一周会做几次如果少于三次手动做就行了不值得为它专门配一个 Skill。最后分享一个小技巧给你的每个 Skill 写一句什么时候用它的说明放在配置文件的 description 字段里。过一段时间你回头看这句话能帮你快速判断这个 Skill 还有没有保留的必要。没有这句话你大概率会一直留着一些根本用不上的 Skill白白增加冲突的风险。