Skill是Codex提供的一种能力扩展机制，简单来说，它允许你把一组约定、流程或领域知识写成结构化的文档，让Codex在合适的时机自动读取并遵循。比如你的团队有特定的代码提交规范、发布流程或者某个内部框架的使用套路，都可以封装成Skill，而不必每次对话都重复交代一遍。本文将从目录结构讲起，完整演示Skill的创建、编写与调用全过程。
一、Skill的基本概念与目录结构
一个Skill本质上是一个包含说明文档的文件夹，核心文件是SKILL.md。Codex在初始化时会扫描技能目录，读取每个SKILL.md的元信息，判断当前任务是否与该技能相关，相关则加载完整内容作为上下文。这意味着Skill并不是传统意义上的插件或脚本，而是一种"声明式"的知识注入方式。
标准的Skill目录结构如下：
my-codex-project/
└── .codex/
└── skills/
└── deploy-guide/
├── SKILL.md # 技能说明文件（必需）
├── scripts/
│ └── deploy.sh # 可选的辅助脚本
└── templates/
└── nginx.conf.tpl # 可选的模板文件其中SKILL.md是唯一必需的文件，其余文件夹按需添加。Codex只会自动读取SKILL.md本身，其他文件需要在文档中显式引用路径，Codex才会按需打开。这种懒加载设计可以有效控制上下文长度，避免技能太多时撑爆token。
二、编写第一个SKILL.md文件
SKILL.md由两部分组成：顶部的YAML元信息块和下方的Markdown正文。元信息用三条横线包围，包含名称、描述等字段；正文则是给Codex看的详细指令。描述字段非常关键，它决定了Codex何时会激活这个技能，所以要写得具体、带有关键词。
下面是一个完整的示例，演示如何编写一个部署规范技能：
--- name: deploy-guide description: 当用户要求部署服务、发布上线、执行deploy命令或更新生产环境时使用本技能，包含公司标准的部署流程与回滚方案 --- # 部署规范 ## 部署流程 1. 先运行 scripts/deploy.sh --check 进行预检查 2. 预检查通过后执行 scripts/deploy.sh --release 3. 部署完成后访问健康检查接口确认服务正常 ## 约束事项 - 禁止在周五下午五点后执行发布 - 回滚必须使用 templates/rollback.md 中记录的标准话术通知运维 - 任何数据库变更需单独确认，不允许随代码一起自动执行
编写时有几个要点值得注意。第一，description字段要写触发场景而非功能罗列，"当用户要求部署服务时使用"比"这是一个部署技能"的匹配效果好得多。第二，正文指令尽量用祈使句和列表，Codex对结构化内容的遵循度明显高于长段落。第三，如果技能依赖外部文件，一定要在文档中写明相对路径，例如上面引用的scripts/deploy.sh，Codex会根据路径自行读取。
三、Skill的触发机制与调用方式
Skill的触发分为自动和手动两种。自动触发依赖description的语义匹配：当你提出"帮我发布新版本"这类请求时，Codex会在所有已注册技能的描述中寻找关联，命中后把对应的SKILL.md内容注入上下文。可以在Codex的输出中观察到技能是否被激活，通常会有加载提示。
手动触发则更直接，在对话中明确点名技能名称即可，例如输入"使用deploy-guide技能执行发布流程"。这种方式适合测试阶段，用来验证技能内容是否符合预期。此外还可以在AGENTS.md中声明默认技能：
# 项目协作约定 本项目默认启用以下技能： - deploy-guide：所有发布操作必须遵循该技能中的流程 - code-style：代码修改时自动应用团队代码风格约定
这样声明的技能会在每次会话中都保持可用状态，相当于全局生效。需要注意的是，技能数量并非越多越好。描述相近的多个技能可能互相干扰，导致Codex选择错误的流程。建议定期梳理技能库，把职责重叠的合并，把过大的拆分，保持每个技能只负责一件事。
四、常见问题与最佳实践
实际使用中最常见的坑是技能不触发。多数情况下问题出在description写得过于宽泛或过于简略，比如只写"代码相关技能"，几乎无法匹配任何具体任务。解决办法是枚举典型的用户意图关键词，像"重构、优化、修改代码"都可以写进描述里。
第二个常见问题是技能文档过长导致上下文膨胀。SKILL.md建议控制在一千字以内，把详细的参考资料放到独立的文件中，主文档只保留流程骨架和文件索引。Codex按需读取外部文件的设计正是为了解决这个问题，善用它可以让技能既全面又轻量。
最后给出几条实践建议：一是技能纳入版本管理，与代码一起评审变更；二是为每个技能写一个最小触发用例，方便回归测试；三是团队共享技能库时统一放在仓库的.codex/skills目录下，成员克隆仓库后无需额外配置即可使用。按照这套方法搭建起来，Codex很快就能成为真正懂你团队规则的得力助手。
Codex Skill功能Codex技能配置Codex使用教程修改时间：2026-09-09 01:50:44