Codex用久了很多人的下一步进阶目标就是Skill。这东西说简单也简单说复杂也复杂简单在于它本质上就是一个文本文件加一个目录结构复杂在于你要真正理解Codex到底是“怎么读到”这个Skill、在什么情况下会激活它以及在多个Skill共存的时候它如何做取舍。这篇文章我不讲Codex怎么安装、怎么跑通第一次对话那些基础篇已经写烂了。这篇专门写给已经在用Codex、但总觉得“每次都要重复交代一堆上下文”的人还有那些想把个人工作习惯沉淀成自动化模板的开发者。Skill能解决的核心问题就一个让AI在特定任务上稳定表现出你想要的工作方式而不是每次从零开始“试探”你的偏好。1. Skill到底是个什么东西先搞清楚底层逻辑1.1 Skill和普通提示词最大的区别很多人接触Skill的第一反应是这不就是预设提示词吗我自己写一段prompt存起来每次粘贴进去不就行了两者的体验差距在“你真去用”之后会非常明显。普通提示词是你告诉Codex“这轮对话你要按这个方式去做”它影响的是当前会话的上下文窗口。一旦会话结束或者话题切到别处这份约束就消失了。Skill则不一样它挂在Codex的“长期能力”目录里Codex在运行过程中会根据当前任务自行发现并加载对应的Skill然后把这个Skill里的指令追加到系统提示里相当于给AI的工作方式加了一层常驻的行为约束。我用一个类比来解释普通prompt是你雇了个临时工每次开工前你都要交代一遍“垃圾怎么分类、工具放哪里、墙面刷几遍”Skill则是给这个工人发了一本《岗位操作手册》他上岗第一天先读手册之后每接到一个任务就会自己翻手册对应的章节来干活。区别不在于谁写得更好而在于“约束是否被主动、即时地加载”。Codex本质上是一个agent形态的工具它会自己拆解任务、自己决定调用什么能力。Skill这套机制的设计初衷就是给agent提供一套工作规程让它不用什么事都来问你。所以Skill的核心价值不是“存了一段话”而是“Codex多了一个判断依据”。它描述的是某个场景下的目标、步骤、边界和输出标准然后由Codex在合适的时机把它激活。1.2 一个Skill的标准目录结构先看一个真实的Skill目录长什么样~/.codex/skills/ └── git-commit-standard/ ├── SKILL.md └── references/ └── commit-conventions.mdSkill目录放在~/.codex/skills/下面一个文件夹代表一个Skill文件夹名字一般用短横线连接的小写单词。每个Skill文件夹里面必须有一个SKILL.md文件这是Codex识别Skill的依据。没有这个文件Codex根本不会认为这是一个Skill哪怕目录名起得再规范也没用。SKILL.md的开头有几行YAML格式的元信息Codex靠这几行字段来索引这个Skill--- name: git-commit-standard description: 在用户要求提交代码时根据 Conventional Commits 规范生成规范的 Git 提交信息。 ---name是Skill的唯一标识description承担的功能可能超出你的直觉——它不只是给人看的说明更是Codex做语义检索的核心依据。Codex会拿你当前任务的自然语言描述和所有Skill的description做匹配匹配度高的那个优先被加载。所以description写得好不好直接决定Skill能不能被正确唤醒。除了SKILL.md你还可以在Skill目录下建references子目录放一些补充材料比如团队规范文档、代码风格样例、API接口文档等。这些附件不会被一次性全部塞进上下文Codex会在需要的时候按需检索。从机制上讲这类似一个轻量级的本地知识库只是检索范围限定在单个Skill目录内。1.3 Skill是怎么被Codex“发现”和激活的搞清楚激活链路才能理解后面所有的调试手段。Skill的激活大致有三条路径显式请求用户直接在对话里说“用git-commit-standard这个Skill来处理”Codex会直接去加载对应Skill。自动匹配Codex根据对话内容结合每个Skill的description做语义匹配。如果某个Skill和当前任务高度相关它就会主动使用。这是最常用、也最考验description质量的路径。本地检索当Codex判断某个任务可能需要额外知识时会在Skill目录里做检索把references文件夹里相关的内容抽取出来动态追加到上下文。不管走哪条路径最终的效果是相同的SKILL.md的内容以及命中的参考文档会被注入到当前会话的系统提示中影响Codex后续的行为决策。这里有个关键点Skill的内容不是“说给你听的建议”而是“写进系统提示的指令”。所以SKILL.md里的措辞应当采用命令式、规则式而不是聊天式的委婉表达。2. 动手写第一个Skill做一个Git提交信息规范Skill2.1 明确需求和设计思路写Skill之前先回答三个问题这个Skill在什么场景下被触发它希望Codex做到什么程度它需要哪些边界约束我用一个最常见的场景来演示很多人都烦AI生成的Git提交信息要么是一句“fix bug”糊弄过去要么洋洋洒洒写一段小作文。我想让Codex在我每次提交代码时按照Conventional Commits规范生成提交信息格式固定为type(scope): subjecttype必须是feat、fix、docs、style、refactor、test、chore中的一个subject用祈使句且不超过50个字符。设计思路是这样的触发场景是“提交代码”这个动作理想输出是一段符合规范的提交信息边界是“只负责生成提交信息不要顺手改动代码”。把这些约束写清楚之后Skill的行为边界就非常分明了。有人会问就这么点事直接每次对话里说一句“用Conventional Commits规范”不就行了行但问题是“提交代码”这个动作分散在多次会话里你这次说了下次还得说。而Skill能保证无论什么时候、哪次会话Codex只要看到提交动作就会自动按规范执行不用你二次提醒。2.2 创建skill目录和SKILL.md文件先建目录mkdir -p ~/.codex/skills/git-commit-standard/references然后创建SKILL.md内容如下--- name: git-commit-standard description: 当用户需要提交代码、生成 Git 提交信息、处理 commit message、执行 git commit 时使用。不要用于其他代码修改场景。 --- # Git 提交信息规范 当用户要求提交代码或生成提交信息时严格按照以下规则执行。 ## 提交信息格式 必须使用以下格式( ):[optional body][optional footer]## type 可选值 - feat: 新功能 - fix: 修复 Bug - docs: 文档变更 - style: 代码格式调整不影响逻辑 - refactor: 重构既不是新功能也不是修复 - test: 新增或修改测试 - chore: 构建过程、辅助工具等变更 ## scope 使用规则 - scope 为可选项表示影响范围如组件名、模块名 - 不确定影响范围时省略 scope不得随意编造 ## subject 使用规则 - 使用祈使句如 fix login bug 而不是 fixed login bug - 不超过 50 个字符 - 不使用句号结尾 ## 操作流程 1. 先运行 git status 查看当前变更文件 2. 根据变更内容推断 type必要时结合 git diff 确认改动细节 3. 生成符合上述规则的提交信息直接输出不要额外解释 ## 禁止事项 - 不要修改任何代码文件 - 不要直接执行 git commit除非用户明确要求 - 不要使用 update、modify、change 这类模糊动词这份文档的写法是有讲究的。开头用description界定触发范围正文用“操作流程”告诉Codex先做什么、再做什么用“禁止事项”划定行为边界。文件命名也用了SKILL.md全大写这是Codex约定好的固定文件名。不要擅自改成skill.md或者README.md否则不会被识别。2.3 测试与调试过程Skill写完之后不是直接就能用的要测。先把Codex会话彻底关闭再重新打开。这一步比很多人想象的更重要因为Skill的加载和索引发生在会话初始化阶段。如果测试的时候发现Codex没按Skill执行第一反应应该是重启会话而不是怀疑Skill写错了。重启后找个测试仓库随便改一个文件然后对Codex说“帮我提交一下代码”。正常情况下Codex应该自动加载git-commit-standard这个Skill然后按“操作流程”先查看git status再生成规范的提交信息。如果Codex没走这个流程优先级最高的排查点是description。Codex做Skill匹配时很大程度上依赖description和当前任务在语义空间上的接近程度。你描述里如果全是“当用户需要提交代码”这类直白表达而用户在真实对话里说的是“帮我commit一下”两者在措辞上有差异这个差异可能导致匹配失败。我调试时会用更口语化的措辞来测试触发效果比如“把改动提交一下”、“生成一条commit message”。如果这些说法都能稳定触发说明description写得足够宽。如果只有“提交代码”这四个字百分百触发那description的覆盖面就太窄了需要补充更多同义表达。3. 进阶技巧让Skill真正地“好用”起来3.1 写好description比写正文还重要这话听起来反直觉但实际操作中我踩过的坑绝大多数都出在description上。Codex做Skill匹配时相当于拿着你的对话内容去和description做语义检索。description写得越精准、覆盖面越广Skill被正确激活的概率就越高。反过来如果description写得太泛比如“这个Skill用于处理代码相关任务”那几乎任何对话都能沾上边Codex反而会在多个Skill之间犹豫甚至加载了错误的那个。好的description有三个原则动词开头明确描述“什么时候用”。比如“当用户需要生成Git提交信息时”比“这是一个提交信息规范”更利于匹配。覆盖同义场景把你实际会脱口而出的说法都写进去。用户不会总说“提交代码”还会说“commit一下”、“帮我写个提交说明”、“push之前的提交信息”。description里覆盖这些说法触发率才会高。写明排除条件什么时候不要用它。比如“不要用于代码修改场景”这样即使对话里出现“git”这个词Codex也能判断当前任务不属于这个Skill的职责范围。我见过有些人写description时只写一句话然后正文写了几百行结果Skill在真实对话里基本处于“半激活”状态——偶尔触发偶尔不触发。原因就在于匹配靠的是description这块“门牌”门牌不够醒目里面的房间装修得再好也白搭。3.2 用追加指令控制Codex行为边界Skill内容进入系统提示之后Codex的行为会受到两方面的引导一是正面指令告诉它该怎么做二是禁止边界告诉它不要做什么。我推荐在SKILL.md里单独开一个“禁止事项”小节。很多人在写Skill时只写“应该怎么做”不写“不能怎么做”结果Codex会自由发挥出一些非常离谱的行为。比如上面那个提交信息Skill如果不写“不要直接执行git commit”Codex可能生成完提交信息之后顺手就把commit执行了。如果提交信息里有个typo这时候已经来不及改了。还有一个细节值得注意Skill里的指令不要写成“建议性”的。用“必须使用以下格式”而不是“可以考虑使用以下格式”用“不得随意编造”而不是“尽量别编造”。Codex在agent模式下偏向于“采取行动”它会倾向于忽略语气委婉的建议而直接做事。规则只有两条腿站稳行为才会稳。3.3 附件文件与引用组织当Skill涉及大量背景材料时比如团队编码规范、API设计约定、项目架构文档不要把全部内容塞进SKILL.md。不然每次激活这个Skill这些体量庞大的文本会直接灌进上下文窗口既浪费token又稀释真正的行为指令。正确的做法是把详细规范拆到references目录下SKILL.md里只保留摘要和加载指引。例如## 参考文档 - 完整提交规范见references/commit-conventions.md - 团队分支命名规范见references/branch-naming.md这样Codex在需要时才会去检索这些附件不需要时不会白白占用上下文。我把这个机制理解为“按需查手册”和“把手册全文背下来”的区别。3.4 多个Skill的协同与优先级当你的Skill积累到一定数量开始出现一个之前没遇到过的问题两个Skill看起来都能管当前这件事Codex到底该用哪个比如你有一个git-commit-standard又有一个code-review而它们的description里都涉及“代码”、“检查”这类词。用户在对话里说“帮我看看这次改动的提交信息”就可能同时触发两个Skill的匹配。处理思路有两个方向第一让Skill的职责边界尽量不重叠这是最治本的办法。创建新Skill之前先看看已有Skill的description重复部分尽量用排除词划清边界。第二在description里主动写清楚“什么情况下不要用它”这对减轻语义歧义很有帮助。多个Skill同时激活时Codex会合并加载它们的内容。这种情况下不同Skill之间如果存在互相矛盾的指令Codex通常按照加载顺序或者对当前任务的针对性来做取舍。你很难精确控制Codex的行为所以更合理的设计是每个Skill尽量聚焦一个场景不要做一个“万能Skill”。4. 踩坑记录与问题排查4.1 常见报错速查表我自己实际使用和帮别人排查过程中遇到最多的问题大概有这几类现象可能原因处理办法Skill目录建了但Codex完全找不到目录位置不对或SKILL.md文件名大小写错误确认目录在~/.codex/skills/下确认文件名是SKILL.md重启CodexSkill能被找到但行为完全没被影响SKILL.md内容写法太“建议化”Codex没把它当成强约束把文案改成明确指令用“必须”、“不得”等强约束词激活时匹配到了错误的Skilldescription写得太泛多个Skill语义重叠收窄description增加排除条件让职责边界清晰报错提示某个模型不被支持客户端版本和配置中的模型版本不匹配或第三方模型配置里填了服务商不支持的模型名检查config.toml里的model字段升级客户端或改用该服务商支持的模型名连接Codex云端接口失败endpoint访问异常网络环境波动或服务端临时不可用检查网络连接和服务状态稍后重试或切换网络环境引用文件加载不到references里的路径写错确认路径相对于SKILL.md所在目录是否正确4.2 排障流程心得我的排障流程可以归纳为“四步法”。第一步看日志Codex一般会在终端或界面里输出一些运行时信息能直接看到它做了什么、加载了哪些Skill。第二步验证加载重启会话后直接跟Codex确认“你现在加载了哪些Skill”它可以明确地汇报加载状态。第三步检验描述把当前对话换成不同措辞看触发率是否有变化。第四步降级测试把SKILL.md里内容删到只剩最核心的规则再测一次。如果精简版能生效说明问题出在内容过于臃肿如果精简版也不生效那问题多半出在路径或文件名上。这套流程的价值在于它把“玄学”变成“可控的排查步骤”。Skill不生效的原因绝大多数集中在“没找到文件”和“找到了但没匹配上”这两个环节。前者是路径问题后者是description问题。排查时先分清楚是哪种情况能少走很多弯路。4.3 两个很容易踩的经典坑第一个坑是YAML frontmatter格式写错。SKILL.md开头的YAML区必须用---包起来字段名和冒号之间要有空格。曾经有人把description:后面的内容写了多行导致YAML解析失败Codex压根不认为这是一个合法的Skill。写完后最好用支持YAML高亮的编辑器检查一下格式或者用Python的yaml库解析一遍这个动作只需要几秒钟能省掉后面一小时的排查时间。第二个坑是Reference路径错乱。Skill加载references目录时相对路径是从SKILL.md所在目录算起的。如果SKILL.md里写references/commit-conventions.md那文件就一定要放在Skill目录下的references子目录里。有人把附件放在Skill目录外面结果Codex永远找不到。碰到“Skill激活了但引用的文档没生效”的情况优先检查路径而不是怀疑检索机制出了问题。5. 把Skill用出团队资产的味道5.1 一次只解决一个场景刚开始开发Skill时我最大的冲动是做一个“全能型”的把所有工作习惯一股脑塞进去。但实践中发现Codex对Skill的理解是“场景化”的它更适合在具体任务出现时精准激活。一个Skill里塞了太多职责反而会让Codex在执行任务时分不清轻重。我现在写Skill的原则是一个Skill对应一个高频痛点场景。要么是Git提交要么是代码审查要么是日志分析要么是接口联调。每个Skill只回答一个问题当用户陷入这个场景时我希望Codex用什么样的流程来处理。这样做出来的Skill自己清楚Codex也清楚团队成员复用起来也轻松。5.2 把个人习惯沉淀成团队可以复用的模板Skills目录天生适合放进Git仓库管理。把~/.codex/skills/做成一个项目仓库团队里每个人都clone下来就能保证大家在同一套工作规范下使用Codex。技术文档团队会维护编码规范文档但规范如果只躺在文档里就永远是死的。Skill把这套规范变成了可以被AI运行时读取并执行的规程这是和文档相比最本质的区别。初始化的方式很简单cd ~/.codex/skills git init git add . git commit -m init skills之后每次新增或修改Skill提交一次变更记录团队其他人pull下来就能同步。一套能在整个团队里以代码形式流转的统一工具习惯是很值钱的东西。5.3 我的一个工作习惯先写描述再写正文写Skill这件事我习惯倒着来。先花十分钟把description打磨到可以覆盖所有常见触发场景再动手写正文。description打磨的过程本身就是需求分析的过程它逼着你想清楚这个Skill真正的触发场景是什么、覆盖范围到哪、边界划在哪。正文反而是次要的因为正文写的是“Codex拿到这个Skill后应该怎么做”只要场景想清楚了这部分是水到渠成的事。最后说一个我自己的小习惯每个Skill的主体执行部分我尽量控制在30行以内如果超过了我会问自己是不是塞了太多职责。这个硬性约束看起来粗暴但它能倒逼Skill保持聚焦。声明一下Skill内部的reference文档不受这个限制那类材料本来就是用来承载大篇幅背景知识的。Skill应该是一份“操作指引”而不是一本百科全书。
