一个 Skill 能不能被正确使用，通常先取决于它的入口描述，再取决于它的执行说明。很多初学者把大量知识和聊天记录直接塞进 SKILL.md，却没有写清楚什么时候触发、输入是什么、信息不足时要不要停下来。
结果往往是两种：需要使用时找不到，不该使用时误触发；或者虽然触发了，但每次执行顺序不同，输出格式也不稳定。
本文用一个“每周复盘”工作流示范如何从零写出一份最小 Skill，重点覆盖目录、YAML 头部、description、正文结构、可选资源和边界规则。文中的示例是 instruction-only Skill，不包含外部服务或敏感数据。
一、Skill 的最小结构是什么
一个最小 Skill 可以只有一个目录和一个文件：
weekly-review/
└── SKILL.md
SKILL.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-review
description: 将一周的零散记录整理成结构化复盘和下周行动计划。用户提到周报、每周复盘、一周总结、工作回顾，或要求从流水账中提炼成果、问题、经验和下一步行动时使用。
---
这里最重要的是 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 Review
short_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 负责让正确任务找到它，正文负责让任务按稳定顺序执行，验收标准负责判断结果是否合格。三者缺一不可。
官方参考：Codex Build skills 和 Build skills，用于核对 SKILL.md、渐进式加载和可选资源目录的当前说明。