说明：本文基于本人日常开发调试总结，不同Codex版本对Skills解析能力存在差异，模板可按需微调，仅供技术研究使用。

前言

使用Codex CLI做本地代码生成时，很多人把精力全部放在Prompt提示词上面，却忽略了Skills这套配置体系。同样的输入提示词，开启Skills和不开启Skills，输出效果差距巨大。

不少开发者直接复制网上零散的Skills片段，运行之后发现完全达不到预期：生成的代码注释泛滥、逻辑残缺、动不动输出伪代码、不遵循项目编码规范，甚至明明要求C#，结果输出大段Python。大部分情况不是模型能力不行，而是Skills配置写得不合理、参数与场景不匹配。

网上能找到完整可落地的Skills模板很少，大多只是简单介绍字段含义。本文结合实际开发场景，拆解Codex‑CLI Skills核心配置逻辑，分享多套经过实测的高精度模板，覆盖工具脚本、模块重构、单元测试、工程代码生成等场景，同时梳理常见配置踩坑点。

什么是Codex CLI Skills

Skills可以理解为CLI层面的角色+约束+Few‑shot示例集合，独立于单次的prompt。可以把编码风格、输出规范、禁止行为、参考示例写在Skills配置文件中，后续每一次调用都会自动加载这套规则，不需要每次在命令行重复粘贴一大段提示。

简单区分Prompt与Skills：

• Prompt：单次任务需求，每次调用可以变化，比如“写一个JSON解析工具”。
• Skills：长期固定的全局约束，编码规范、禁止输出内容、参考示例，全局生效。

很多新手会犯一个错误：把单次业务需求写到Skills配置中。Skills适合放长期不变的规则，业务需求放在调用时的prompt，两者混淆之后，每次调用输出都会出现莫名其妙的偏差。

Skills配置文件一般为yaml格式，主要由几个核心部分组成：

1. description：技能角色描述，定义模型身份与整体能力边界。
2. constraints：硬性约束列表，强制限制输出行为，禁止伪代码、禁止多余解释等。
3. examples：少量高质量示例片段，Few‑Shot引导输出格式，不要堆砌过多示例，避免占用token。
4. parameters：温度、top_p、最大输出token等推理参数，直接在技能文件固化。

关键点：Skills会占用上下文token，示例片段不宜过多，示例越多，留给业务输入的token空间越小，容易触发上下文超限报错。

高频配置错误，导致Skills完全失效

在直接使用模板之前，先梳理平时最容易踩的配置坑，很多人配置写了，但是完全不生效。

1. 示例片段写的太多

不少同学为了让模型学习编码习惯，往examples里面塞几十段大代码。直接导致输入token暴涨，留给业务代码的窗口被挤压，不仅调用成本变高，还容易截断。examples只放2‑4组极简高质量示例即可。

2. 将单次业务需求写入Skills

Skills是全局固定配置，适合编码规范、输出约束。不要写“完成用户的订单模块”这类业务需求，业务逻辑放在调用时的prompt，否则无论你输入什么指令，模型都会偏向这个业务。

3. constraints约束写的模糊

约束不要写模糊描述，例如“写好一点”“代码尽量完善”。需要写明确的强制约束，例如：禁止输出伪代码，禁止省略关键逻辑，不输出自然语言解释，仅输出可直接运行代码。模糊的约束模型几乎不会遵守。

4. temperature参数设置不合理

生成工程代码温度不要过高，很多人直接设置0.8以上，输出天马行空，大量臆造不存在的API。业务代码生成温度建议0.1‑0.4区间。做创意脚本、算法探索时再调高温度。

5. 配置文件没有被CLI正确加载

路径写错、yaml格式缩进错误，CLI静默跳过Skills配置，不会报错，表现就是配置写了完全不生效。排查方式：开启CLI的debug日志，可以看到是否成功读取解析skills文件。

6. 约束之间互相冲突

同时写两条冲突约束，例如“输出详细注释”和“禁止写注释”，模型输出行为就会不稳定，时而有注释时而没有。

多套实战高精度Skills模板

使用说明：保存为skills.yaml，通过codex run --skills skills.yaml加载使用，可以根据自己项目规范微调。

模板一：通用工具脚本生成模板（Python/Shell脚本）

适合：写小工具、数据处理脚本、文件批量处理、运维脚本，追求直接可运行，减少多余文字解释。

description: >
  你是一名熟练的脚本开发工程师，擅长编写简洁可直接运行的工具脚本，注重异常处理，兼容主流运行环境。
constraints:
  - 只输出完整可运行代码，禁止输出伪代码、省略号占位逻辑
  - 减少大段自然语言解释，必要注释写在代码内部
  - 必须增加基础异常捕获，处理文件IO、网络异常
  - 代码遵循PEP8编码规范
  - 不生成未定义的函数与变量
examples:
  - input: "写一个读取csv并导出json的工具"
    output: |
      import csv
      import json

      def csv_to_json(file_path):
          data = []
          try:
              with open(file_path,"r",encoding="utf‑8") as f:
                  reader = csv.DictReader(f)
                  for row in reader:
                      data.append(row)
              return data
          except Exception as e:
              print(f"error:{e}")
              return None
parameters:
  temperature: 0.2
  top_p: 0.3
  max_output_tokens: 1200

模板二：C#工程业务模块生成模板

适合：.NET、WPF、控制台业务类，严格遵循C#编码规范，面向对象写法，适合上位机、后端业务片段生成。

description: >
  资深C#后端与上位机开发工程师，熟悉.NET编码规范，输出健壮的C#业务代码。
constraints:
  - 输出完整可编译C#代码，禁止伪代码，禁止省略方法内部逻辑
  - 使用标准命名规范，类名大驼峰，参数小驼峰
  - 必要的参数非空判断，异常捕获处理
  - 不输出不存在的第三方类库与API
  - 不要输出大段文字说明，注释精简
examples:
  - input: "写一个简单文件读取工具类"
    output: |
      using System;
      using System.IO;

      public class FileHelper
      {
          public static string SafeReadText(string path)
          {
              try
              {
                  if(!File.Exists(path)) return string.Empty;
                  return File.ReadAllText(path);
              }
              catch(Exception ex)
              {
                  Console.WriteLine(ex.Message);
                  return null;
              }
          }
      }
parameters:
  temperature: 0.15
  top_p: 0.25
  max_output_tokens: 1500

模板三：代码重构优化模板

适合：传入已有代码，做性能优化、bug修复、逻辑重构，保留原有业务逻辑，不随意改动原始业务行为。

description: >
  专业代码重构工程师，负责对已有代码做优化，修复潜在bug，提升可读性与性能，不改变原有业务逻辑。
constraints:
  - 保留原有输入输出、业务逻辑，不要擅自修改业务行为
  - 消除潜在空指针、资源泄漏问题
  - 简化冗余逻辑，去除重复代码
  - 输出完整重构后的全部代码，不要只输出片段
  - 禁止修改原有接口入参出参
examples:
  - input: "优化下面的循环逻辑"
    output: |
      //重构之后完整代码，保留原有功能
parameters:
  temperature: 0.1
  top_p: 0.2
  max_output_tokens: 1800

模板四：单元测试生成模板

适合：根据业务代码自动生成单元测试用例，覆盖正常场景、边界条件、异常分支。

description: >
  专职单元测试工程师，针对业务代码编写完整单元测试，覆盖正常、边界、异常场景。
constraints:
  - 输出完整可运行单元测试代码
  - 覆盖正常流程、边界值、异常抛出场景
  - 使用对应语言主流测试框架
  - 不要修改待测试业务逻辑
examples:
  - input: "为工具方法生成单元测试"
    output: |
      #单元测试完整示例代码
parameters:
  temperature: 0.2
  top_p: 0.3
  max_output_tokens: 1400

Skills调优实操技巧

1. 开启Debug模式确认配置加载
   执行调用时带上‑‑debug参数，日志中会打印已加载的skills内容，如果看不到skills相关日志，代表yaml路径错误或者格式错误，配置没有生效。很多配置无效问题都可以通过debug快速定位。

2. temperature参数参考区间
   |场景|temperature参考值|
   | ---- | ---- |
   |业务代码、重构、单元测试|0.1‑0.3|
   |工具脚本、算法实现|0.2‑0.4|
   |创意探索、Demo原型|0.5‑0.7|

业务工程代码温度不要超过0.4，越高越容易臆造API，出现虚假函数。

3. examples示例编写原则
   示例贵在精不在多，2‑4组足够。示例一定要和你的业务场景保持一致，如果要生成C#代码，示例就放C#，不要混杂Python示例，会严重干扰模型输出。

4. constraints约束要可验证
   尽量写可被执行检验的硬性规则，避免主观形容词，少写“优雅、高质量”这类模糊描述。换成“禁止伪代码”“增加异常捕获”这类明确指令。

5. 多套技能文件分开维护
   不同场景不要写在同一个skills配置，工具脚本一套、重构一套、单元测试一套，调用的时候指定不同yaml文件，便于维护。

常见现象与对应处理方案

现象1：经常输出伪代码，大量省略号占位

排查：constraints没有明确禁止伪代码，或者温度参数过高。
处理：在constraints增加强制约束，调低temperature，examples加入完整可运行的简短示例。

现象2：明明要求C#，输出Python代码

排查：examples混入其他语言示例，或者描述没有明确限定编程语言。
处理：description明确语言，示例全部统一为目标语言。

现象3：输出大量文字解释，代码很少

排查：约束没有限制多余自然语言输出。
处理：增加约束，禁止多余的文字讲解，仅保留代码内部注释。

现象4：Skills配置写完，调用完全不生效

排查：yaml缩进错误，文件路径不对，没有正确指定‑‑skills参数。
处理：开启debug日志，确认CLI成功读取配置文件。

现象5：输入代码稍大，直接上下文超限

排查：examples示例片段太大，占用大量token。
处理：精简examples，示例尽量短小，删减不必要的大段示例。

总结

很多开发者使用Codex CLI只看重单次prompt，忽略Skills配置带来的巨大提升。Skills相当于给CLI设置一套长期生效的编码规则，不用每次调用重复写大量约束。

想要配置生效，核心是：约束明确不模糊、示例精简高质量、推理参数和场景匹配、确认配置文件真正被加载。不要堆砌示例，不要把单次业务需求写入技能配置。

上面四套模板覆盖脚本、C#业务、重构、单元测试，实际项目可以直接复制使用，根据自己团队编码规范微调约束条件，能够明显改善Codex‑CLI代码输出不准、跑偏的问题。