Codex Skills 怎么写？SKILL.md 结构、触发条件与团队复用指南

适用人群：把重复步骤变成可复用能力

本文适合已经在 Codex 桌面应用、CLI 或 IDE 扩展中反复执行同类任务的开发者，也适合想统一团队交付标准的维护者。常见场景包括生成固定格式的报告、处理特定类型的数据、执行发布检查、整理素材，或按照公司模板创建文件。

核验日期为 2026 年 9 月 9 日。OpenAI 当前文档将 Skill 描述为由说明、资源和可选脚本组成的任务能力包，并采用渐进加载：先让系统看到名称与描述，任务匹配后再读取完整 SKILL.md。这与把一大段说明长期复制进每个对话不同。

先分清 Skill、AGENTS.md、脚本和 MCP

Skill 适合封装一类任务的做法；AGENTS.md 更适合描述仓库内长期生效的工程规则；脚本负责可重复的确定性操作；MCP 则用于连接外部工具或数据。四者可以组合，但没有必要为了一个简单检查命令同时引入全部组件。

一个实用判断是：如果需求能用一句仓库规则说清，就先放进 AGENTS.md；如果需要按步骤读取资料、选择模板并产出特定结果，再考虑 Skill；如果步骤中包含容易出错的机械处理，可把那部分放入脚本。已有仓库规则可参考AGENTS.md 团队协作实践。

最小目录：先只有一个 SKILL.md

官方说明的最小 Skill 是一个目录加 SKILL.md。文件开头的元数据至少包含 name 与 description，后面写执行说明。scripts/、references/、assets/ 以及可选的代理配置都可以等真实需求出现后再增加。

名称应短而稳定，描述要同时回答“什么时候应该触发”和“什么时候不该触发”。例如“把商品图片整理成指定导入表，并校验 SKU、缺图与重复编码”比“处理图片和表格”更容易命中正确任务，也更不容易在普通图片编辑时误触发。

• name：使用唯一、可读、不会频繁更改的名称。
• description：把典型输入、预期产物、触发词和排除边界写在前面。
• instructions：按执行顺序写动作、判断条件、失败处理和验收。
• references：只有任务确实需要时才读取对应资料，不要默认全部加载。
• scripts：参数与输出要清楚，失败时返回可定位的错误。

触发描述怎么写，才能既命中又不误触发

Codex 可以通过显式提及或任务与描述匹配来选择 Skill，因此描述不是宣传语，而是路由条件。建议把高价值名词和动作放在开头，例如“生成日报 PDF”“修复 GitHub Actions CI”“转换淘宝上架模板”，再补充输入类型和不适用场景。

测试时准备三组语句：明确应该触发、可能相关但不应触发、表述模糊需要判断。每组至少两到三个真实例子。若大量无关任务也会触发，先收窄描述；若用户使用常见说法却始终不触发，补上这些自然语言，而不是在说明正文里堆关键词。

把流程写成可验证的六个阶段

一份可靠的 Skill 不只告诉代理“做什么”，还要规定完成证据。可以沿用“读取输入—确认范围—执行转换—检查结果—生成报告—交付”的结构。每个阶段只写必要动作，并说明哪些情况可以继续、哪些情况必须停下。

例如发布类 Skill 可以要求先查重复内容，再生成草稿和封面，检查标题、日期、链接和图片，最后才公开发布。成功条件不是“已经处理”，而是公开地址返回 200、列表可见、移动端可读、报告已保存。更多任务拆解写法可参考Codex 任务说明模板和测试证据验收指南。

• 输入：允许哪些文件、页面或参数，缺少时怎样处理。
• 范围：哪些目录、账号和系统明确在任务内。
• 动作：把需要判断的工作与机械步骤分开。
• 验证：列出可观察结果，不用“应该没问题”作结论。
• 失败：保留草稿、日志与可恢复状态，避免静默跳过。
• 交付：给出产物位置、摘要和仍需人工决定的事项。

什么时候加入脚本、参考资料和模板

当同一步骤第三次出现，而且输入输出已经稳定，再考虑写脚本。适合脚本化的内容包括图片压缩、字段校验、固定格式转换和重复链接检查；需要业务判断、风险权衡或外部授权的步骤，仍应保留清楚的人工边界。

参考资料按主题拆分，并在 SKILL.md 中写明何时读取哪一份。这样能减少无关上下文，也方便单独更新。模板应保留占位符和示例数据，不能把真实客户邮箱、服务器密码、Cookie 或 API 密钥当成示例打包。

团队维护：版本、回归样例与安全边界

把 Skill 当成代码维护：每次修改记录原因，保留一组正例、反例与失败例，重要脚本做最小测试。若输出格式变化，应说明迁移方式；若删除字段，先检查下游是否仍依赖。不要因为 Skill 可以复用，就默认它能在所有仓库和账号上安全执行。

与网络、发布、付款或生产系统有关的 Skill，要写清授权边界、允许访问的目标和回滚办法。默认只读取必要数据；写入前解析精确目标；遇到验证码、权限不足或来源不明的内容时停止并报告。

• 为每次变更保留版本说明和至少一个回归样例。
• 脚本不要硬编码密码、Token、Cookie 或生产账号。
• 对删除、覆盖、公开发布设置明确的前置检查。
• 输出报告记录输入、执行时间、结果和异常。
• 定期删除失效参考资料，避免把旧规则继续当成事实。

结论：先让一个真实流程稳定，再扩大复用范围

制作 Codex Skill 的关键不是目录越多越好，而是触发准确、步骤清楚、失败可解释、结果可验收。先选一个重复频率高且边界明确的任务，只用最小 SKILL.md 跑通，再依据实际失败逐步增加脚本、参考资料和模板。

你可以从 GPTUPCN 首页继续查看 Codex、ChatGPT Plus 与 ChatGPT Pro 的实践文章。本站为第三方中文信息与服务入口，非 OpenAI 官方。Skill、插件和客户端能力会更新，是否可用应以当前版本、账号与官方文档为准；会员充值或订阅不等于某个自定义 Skill 一定能运行。