企业官网建设流程全解析

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.md

Skill目录放在~/.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提交信息规范Skill

2.1 明确需求和设计思路

写Skill之前，先回答三个问题：这个Skill在什么场景下被触发？它希望Codex做到什么程度？它需要哪些边界约束？

我用一个最常见的场景来演示：很多人都烦AI生成的Git提交信息，要么是一句“fix bug”糊弄过去，要么洋洋洒洒写一段小作文。我想让Codex在我每次提交代码时，按照Conventional Commits规范生成提交信息，格式固定为type(scope): subject，type必须是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 常见报错速查表

我自己实际使用和帮别人排查过程中，遇到最多的问题大概有这几类：

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应该是一份“操作指引”，而不是一本百科全书。