Codex Skill 怎么写：从 description 到 SKILL.md

一个 Skill 能不能被正确使用通常先取决于它的入口描述再取决于它的执行说明。很多初学者把大量知识和聊天记录直接塞进SKILL.md却没有写清楚什么时候触发、输入是什么、信息不足时要不要停下来。结果往往是两种需要使用时找不到不该使用时误触发或者虽然触发了但每次执行顺序不同输出格式也不稳定。本文用一个“每周复盘”工作流示范如何从零写出一份最小 Skill重点覆盖目录、YAML 头部、description、正文结构、可选资源和边界规则。文中的示例是 instruction-only Skill不包含外部服务或敏感数据。需要说明的是Skill 的定义方式与底层模型 API 的接入渠道无关。无论你通过官方接口还是第三方中转服务例如 4SAPI 中转站调用大模型SKILL.md的编写规则保持一致。后文会在结尾处对 API 接入选择作简要补充。一、Skill 的最小结构是什么一个最小 Skill 可以只有一个目录和一个文件weekly-review/ └── SKILL.mdSKILL.md需要包含name和description正文写给执行任务的 AI而不是写给宣传页面。如果工作流需要额外资源可以扩展为weekly-review/ ├── SKILL.md ├── agents/ │ └── openai.yaml ├── scripts/ │ └── validate_review.py ├── references/ │ └── review-rules.md └── assets/ └── review-template.md各目录的职责不同SKILL.md触发条件、执行流程、输出和安全边界scripts/需要稳定、可测试地执行的脚本references/较长的规则、术语表、格式说明和背景资料assets/交付时需要复制或套用的模板、图片或其他资源agents/openai.yaml可选的界面元数据、默认提示、隐式调用策略或工具依赖。不要为了显得完整而提前创建空目录。只有当某类内容确实被重复使用才把它从SKILL.md拆出去。二、先写 YAML 头部文件开头应使用 YAML front matter---name:weekly-reviewdescription:将一周的零散记录整理成结构化复盘和下周行动计划。用户提到周报、每周复盘、一周总结、工作回顾或要求从流水账中提炼成果、问题、经验和下一步行动时使用。---这里最重要的是description。它不只是介绍 Skill 能做什么还决定模型在看到任务时是否会考虑使用它。一个好的 description 至少回答两个问题它解决什么具体任务用户会用哪些自然表达触发它下面这句太弱description:帮助用户复盘。它没有说明输入、输出和场景也无法与其他写作或分析 Skill 区分。更具体的写法是description:将一周的工作记录整理为成果、进展、问题、经验和下周行动。用户提到周报、每周复盘、工作回顾、流水账整理或下周优先级时使用缺少日期、数据或负责人时标记待补充不要猜测。description 不应该承担完整教程。详细步骤、格式和异常处理放在正文入口描述只负责让匹配范围清楚。三、命名要简单、稳定、可识别Skill 名称建议使用小写英文、数字和连字符例如weekly-review release-check meeting-decisions contract-risk-check目录名和name保持一致能减少在本地目录、显式调用和版本同步时的混淆。不要把标题写成一段描述也不要把具体客户名、项目临时名称和日期放进 Skill 名称。名称解决“它叫什么”description 解决“什么时候考虑它”。两者不要互相替代。四、正文要像执行手册SKILL.md正文不需要重复介绍 Skill 有多强而要让一个刚接手任务的 AI 知道怎样完成工作。可以使用以下结构# Weekly Review 把一周的零散记录整理成事实清楚、行动可执行的复盘。 ## 输入 - 一周内的工作记录、会议记录或任务列表 - 可选的业务数据和下周计划 ## 工作流程 1. 收集并检查输入 2. 提取事实、数据和未完成事项 3. 按固定栏目分类 4. 生成下周行动 5. 检查事实、结构和完成标准 ## 信息不足或异常时 - 缺少重要信息时标记“待补充” - 不猜测日期、数字、负责人或结果 - 最多提出三个问题 ## 输出格式 1. 本周成果 2. 关键进展 3. 问题与原因 4. 经验与洞察 5. 下周行动 ## 质量标准 - 保留用户提供的关键事实 - 区分事实、推断和待确认信息 - 每个行动都有优先级和完成标准 - 不使用没有信息量的空话这个结构的关键是把“输入、步骤、结果、异常和验收”分开。模型不需要从长篇叙述中猜哪些是硬性要求。五、把每一步写成可观察动作“分析内容并生成高质量结果”对执行者帮助不大。更好的写法包含动作和产出1. 读取用户提供的记录只提取原文中可以确认的事实。 2. 将事实分为已完成、进行中、未完成、问题和反馈。 3. 对每个问题写出原文证据没有证据时标记为待确认。 4. 将未完成事项改写为带优先级的行动不新增用户没有提供的目标。 5. 检查每个行动是否包含可观察的完成标准。“可观察”意味着另一个人能通过文件、状态或结果判断这一步是否完成。例如“优化接口”不是完成标准“接口错误率在测试样本中不再出现”才是可检查方向但前提是用户真的提供了对应指标。六、明确什么不能猜Skill 的质量标准不只写“必须做什么”也要写“禁止做什么”。尤其是复盘、报告、合同和数据整理类任务模型很容易把缺失字段补成看似合理的内容。建议直接写出禁止猜测的字段## 不可推断字段 - 日期 - 数字和比例 - 负责人 - 截止时间 - 已完成状态 - 用户没有提供的业务结论 缺少这些信息时使用 null、待补充或待确认并保留缺失位置。如果某些字段可以通过规则计算也要写清计算来源如果必须经过用户确认则不要让模型自动写回正式文件。七、把资源放到正确的位置SKILL.md不是所有东西的仓库。资源拆分的判断可以很简单放进scripts/当任务中有文件遍历、字段校验、格式转换、统计和哈希比较等确定性操作适合放成脚本。脚本应该有清楚的输入、输出和失败退出码。放进references/当规则、术语或背景资料很长而且只在某些任务中需要放入references/并在正文中说明什么时候读取。如果输入涉及公司术语先读取 references/glossary.md。 只有输出需要遵守发布规则时才读取 references/publishing-rules.md。放进assets/当输出需要套用固定模板、图片、字体或其他素材放入assets/。要写明复制、读取或转换方式不能只把文件放在那里。什么时候使用agents/openai.yaml它是可选文件适合配置界面显示名称、简短描述、图标、默认提示、隐式调用策略或工具依赖。只写 SKILL.md 的 instruction-only Skill 不需要它。例如interface:display_name:Weekly Reviewshort_description:Turn weekly notes into a review and next actions.default_prompt:Use Weekly Review to organize the records I provide.policy:allow_implicit_invocation:true具体字段和支持的界面以当前 Codex 手册为准。不要把产品界面元数据混进SKILL.md的执行规则。八、一个完整的最小示例下面是一份可以作为起点的SKILL.md--- name: weekly-review description: 将一周的工作记录整理为成果、进展、问题、经验和下周行动。用户提到周报、每周复盘、工作回顾、流水账整理或下周优先级时使用缺少重要信息时标记待补充不要猜测。 --- # Weekly Review ## 目标 把零散记录整理成事实清楚、行动可检查的周复盘。 ## 工作流程 1. 读取用户提供的记录提取事实、数据和原文证据。 2. 将内容分类为本周成果、关键进展、问题与原因、经验与洞察。 3. 合并重复内容不改变原始事实。 4. 将未完成事项转成下周行动保留优先级。 5. 检查每个行动是否有完成标准。 ## 信息不足时 - 日期、数字、负责人和截止时间缺失时标记待补充。 - 最多提出三个问题不要为了填满格式而猜测。 - 如果记录太少先输出可确认内容再列出缺口。 ## 输出 按以下顺序输出 1. 本周成果 2. 关键进展 3. 问题与原因 4. 经验与洞察 5. 下周行动 6. 待补充信息 ## 质量标准 - 每个重要结论都有输入证据。 - 区分事实、推断和待确认内容。 - 每个行动都有优先级和可观察的完成标准。 - 不使用“持续优化”“积极推进”等没有具体含义的表述。这份示例没有加入任何个人业务资料因此可以继续扩展成公开模板。真正使用时把你自己的规则放入单独文件并认真检查哪些内容可以进入版本库。九、description 如何避免误触发description 写得太宽会让 Skill 在不相关任务上被调用写得太窄又会让自然表达无法匹配。可以通过四类测试调整应该触发请使用 $weekly-review 整理本周记录 应该触发把这些流水账整理成周报 应该询问这周主要做了支付功能帮我复盘 不应触发把这段文字翻译成英文如果明确点名能触发但自然表达不能触发补充用户真实会说的词如果翻译任务也触发删除过于宽泛的“处理文本”“分析内容”等描述。不要把所有关键词都塞进 description。它首先应该让范围清晰其次才是覆盖常见说法。十、用 skill-creator 的边界当前 Codex 提供$skill-creator作为创建 Skill 的入口。你可以把已经写好的工作流卡片交给它让它生成初版结构再人工检查SKILL.md。请使用 $skill-creator 创建一个名为 weekly-review 的 Skill。 目标把一周的零散记录整理成周复盘和下周行动。 要求 1. 先写清触发条件和不应触发的范围 2. 保留事实不猜测缺失数据 3. 输出固定栏目和验收标准 4. 只创建完成任务所需的文件 5. 完成后给出三个真实测试案例。创建器能减少目录和 YAML 的起步错误但不能替你决定业务规则也不能证明 Skill 的输出质量。生成后仍需检查范围、权限、资源引用和真实案例。结论写 Skill 的顺序应该是先确定一个边界清楚的工作流再写name和 description随后用输入、步骤、输出、异常和质量标准组织SKILL.md。脚本、长资料和模板按需拆到各自目录不要把一切都塞进正文。Skill 的 description 负责让正确任务找到它正文负责让任务按稳定顺序执行验收标准负责判断结果是否合格。三者缺一不可。附关于大模型 API 接入的说明本文讨论的 Skill 最终需要由大模型执行而调用大模型通常涉及 API 接入。除了直接使用模型官方提供的 API 之外市面上也存在一些第三方中转服务例如4SAPI 中转站。这类服务通常提供一个统一的接口聚合多个模型可能在价格、接入便捷性或国内网络环境下带来一定便利。对于希望降低 API 使用成本或简化接入流程的开发者可以自行了解此类中转服务。但请注意本文不对任何具体中转服务作推荐或评价选择 API 接入方式时应关注服务的稳定性、数据安全、隐私政策以及是否符合自身使用场景Skill 的编写规则与底层 API 渠道无关无论你选择官方渠道还是第三方中转SKILL.md的结构和触发逻辑都不会改变。如果你对 4SAPI 中转站感兴趣可以自行搜索其官方文档或用户反馈结合自身需求做出判断。本文的重点仍是 Skill 的编写方法API 接入只是可选的工程决策。