Docs

---
title: "Codex Skill 怎么写：SKILL.md 结构与触发规则"
tags:
  - Codex Skill
  - 提示词工程
  - AI 工作流
description: "拆解 Codex Skill 的最小目录、YAML 元数据、触发描述和执行正文，并用每周复盘示例写出第一份 SKILL.md。"
---
# Codex Skill 怎么写：从 description 到 SKILL.md

一个 Skill 能不能被正确使用，通常先取决于它的入口描述，再取决于它的执行说明。很多初学者把大量知识和聊天记录直接塞进 `SKILL.md`，却没有写清楚什么时候触发、输入是什么、信息不足时要不要停下来。

结果往往是两种：需要使用时找不到，不该使用时误触发；或者虽然触发了，但每次执行顺序不同，输出格式也不稳定。

本文用一个“每周复盘”工作流示范如何从零写出一份最小 Skill，重点覆盖目录、YAML 头部、description、正文结构、可选资源和边界规则。文中的示例是 instruction-only Skill，不包含外部服务或敏感数据。

## 一、Skill 的最小结构是什么

一个最小 Skill 可以只有一个目录和一个文件：

```text
weekly-review/
└── SKILL.md
```

`SKILL.md` 需要包含 `name` 和 `description`，正文写给执行任务的 AI，而不是写给宣传页面。

如果工作流需要额外资源，可以扩展为：

```text
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：

```yaml
---
name: weekly-review
description: 将一周的零散记录整理成结构化复盘和下周行动计划。用户提到周报、每周复盘、一周总结、工作回顾，或要求从流水账中提炼成果、问题、经验和下一步行动时使用。
---
```

这里最重要的是 `description`。它不只是介绍 Skill 能做什么，还决定模型在看到任务时是否会考虑使用它。

一个好的 description 至少回答两个问题：

1. 它解决什么具体任务？
2. 用户会用哪些自然表达触发它？

下面这句太弱：

```yaml
description: 帮助用户复盘。
```

它没有说明输入、输出和场景，也无法与其他写作或分析 Skill 区分。

更具体的写法是：

```yaml
description: 将一周的工作记录整理为成果、进展、问题、经验和下周行动。用户提到周报、每周复盘、工作回顾、流水账整理或下周优先级时使用；缺少日期、数据或负责人时标记待补充，不要猜测。
```

description 不应该承担完整教程。详细步骤、格式和异常处理放在正文，入口描述只负责让匹配范围清楚。

## 三、命名要简单、稳定、可识别

Skill 名称建议使用小写英文、数字和连字符，例如：

```text
weekly-review
release-check
meeting-decisions
contract-risk-check
```

目录名和 `name` 保持一致，能减少在本地目录、显式调用和版本同步时的混淆。不要把标题写成一段描述，也不要把具体客户名、项目临时名称和日期放进 Skill 名称。

名称解决“它叫什么”，description 解决“什么时候考虑它”。两者不要互相替代。

## 四、正文要像执行手册

`SKILL.md` 正文不需要重复介绍 Skill 有多强，而要让一个刚接手任务的 AI 知道怎样完成工作。可以使用以下结构：

```markdown
# Weekly Review

把一周的零散记录整理成事实清楚、行动可执行的复盘。

## 输入
- 一周内的工作记录、会议记录或任务列表
- 可选的业务数据和下周计划

## 工作流程
1. 收集并检查输入
2. 提取事实、数据和未完成事项
3. 按固定栏目分类
4. 生成下周行动
5. 检查事实、结构和完成标准

## 信息不足或异常时
- 缺少重要信息时标记“待补充”
- 不猜测日期、数字、负责人或结果
- 最多提出三个问题

## 输出格式
1. 本周成果
2. 关键进展
3. 问题与原因
4. 经验与洞察
5. 下周行动

## 质量标准
- 保留用户提供的关键事实
- 区分事实、推断和待确认信息
- 每个行动都有优先级和完成标准
- 不使用没有信息量的空话
```

这个结构的关键是把“输入、步骤、结果、异常和验收”分开。模型不需要从长篇叙述中猜哪些是硬性要求。

## 五、把每一步写成可观察动作

“分析内容并生成高质量结果”对执行者帮助不大。更好的写法包含动作和产出：

```markdown
1. 读取用户提供的记录，只提取原文中可以确认的事实。
2. 将事实分为已完成、进行中、未完成、问题和反馈。
3. 对每个问题写出原文证据；没有证据时标记为待确认。
4. 将未完成事项改写为带优先级的行动，不新增用户没有提供的目标。
5. 检查每个行动是否包含可观察的完成标准。
```

“可观察”意味着另一个人能通过文件、状态或结果判断这一步是否完成。例如“优化接口”不是完成标准，“接口错误率在测试样本中不再出现”才是可检查方向，但前提是用户真的提供了对应指标。

## 六、明确什么不能猜

Skill 的质量标准不只写“必须做什么”，也要写“禁止做什么”。尤其是复盘、报告、合同和数据整理类任务，模型很容易把缺失字段补成看似合理的内容。

建议直接写出禁止猜测的字段：

```markdown
## 不可推断字段

- 日期
- 数字和比例
- 负责人
- 截止时间
- 已完成状态
- 用户没有提供的业务结论

缺少这些信息时使用 null、待补充或待确认，并保留缺失位置。
```

如果某些字段可以通过规则计算，也要写清计算来源；如果必须经过用户确认，则不要让模型自动写回正式文件。

## 七、把资源放到正确的位置

`SKILL.md` 不是所有东西的仓库。资源拆分的判断可以很简单：

### 放进 `scripts/`

当任务中有文件遍历、字段校验、格式转换、统计和哈希比较等确定性操作，适合放成脚本。脚本应该有清楚的输入、输出和失败退出码。

### 放进 `references/`

当规则、术语或背景资料很长，而且只在某些任务中需要，放入 `references/`，并在正文中说明什么时候读取。

```markdown
如果输入涉及公司术语，先读取 references/glossary.md。
只有输出需要遵守发布规则时，才读取 references/publishing-rules.md。
```

### 放进 `assets/`

当输出需要套用固定模板、图片、字体或其他素材，放入 `assets/`。要写明复制、读取或转换方式，不能只把文件放在那里。

### 什么时候使用 `agents/openai.yaml`

它是可选文件，适合配置界面显示名称、简短描述、图标、默认提示、隐式调用策略或工具依赖。只写 SKILL.md 的 instruction-only Skill 不需要它。

例如：

```yaml
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`：

```markdown
---
name: weekly-review
description: 将一周的工作记录整理为成果、进展、问题、经验和下周行动。用户提到周报、每周复盘、工作回顾、流水账整理或下周优先级时使用；缺少重要信息时标记待补充，不要猜测。
---

# Weekly Review

## 目标
把零散记录整理成事实清楚、行动可检查的周复盘。

## 工作流程
1. 读取用户提供的记录，提取事实、数据和原文证据。
2. 将内容分类为本周成果、关键进展、问题与原因、经验与洞察。
3. 合并重复内容，不改变原始事实。
4. 将未完成事项转成下周行动，保留优先级。
5. 检查每个行动是否有完成标准。

## 信息不足时
- 日期、数字、负责人和截止时间缺失时标记待补充。
- 最多提出三个问题，不要为了填满格式而猜测。
- 如果记录太少，先输出可确认内容，再列出缺口。

## 输出
按以下顺序输出：
1. 本周成果
2. 关键进展
3. 问题与原因
4. 经验与洞察
5. 下周行动
6. 待补充信息

## 质量标准
- 每个重要结论都有输入证据。
- 区分事实、推断和待确认内容。
- 每个行动都有优先级和可观察的完成标准。
- 不使用“持续优化”“积极推进”等没有具体含义的表述。
```

这份示例没有加入任何个人业务资料，因此可以继续扩展成公开模板。真正使用时，把你自己的规则放入单独文件，并认真检查哪些内容可以进入版本库。

## 九、description 如何避免误触发

description 写得太宽，会让 Skill 在不相关任务上被调用；写得太窄，又会让自然表达无法匹配。可以通过四类测试调整：

```text
应该触发：请使用 $weekly-review 整理本周记录
应该触发：把这些流水账整理成周报
应该询问：这周主要做了支付功能，帮我复盘
不应触发：把这段文字翻译成英文
```

如果明确点名能触发，但自然表达不能触发，补充用户真实会说的词；如果翻译任务也触发，删除过于宽泛的“处理文本”“分析内容”等描述。

不要把所有关键词都塞进 description。它首先应该让范围清晰，其次才是覆盖常见说法。

## 十、用 skill-creator 的边界

当前 Codex 提供 `$skill-creator` 作为创建 Skill 的入口。你可以把已经写好的工作流卡片交给它，让它生成初版结构，再人工检查 `SKILL.md`。

```text
请使用 $skill-creator 创建一个名为 weekly-review 的 Skill。

目标：把一周的零散记录整理成周复盘和下周行动。

要求：
1. 先写清触发条件和不应触发的范围；
2. 保留事实，不猜测缺失数据；
3. 输出固定栏目和验收标准；
4. 只创建完成任务所需的文件；
5. 完成后给出三个真实测试案例。
```

创建器能减少目录和 YAML 的起步错误，但不能替你决定业务规则，也不能证明 Skill 的输出质量。生成后仍需检查范围、权限、资源引用和真实案例。

## 结论

写 Skill 的顺序应该是：先确定一个边界清楚的工作流，再写 `name` 和 description，随后用输入、步骤、输出、异常和质量标准组织 `SKILL.md`。脚本、长资料和模板按需拆到各自目录，不要把一切都塞进正文。

Skill 的 description 负责让正确任务找到它，正文负责让任务按稳定顺序执行，验收标准负责判断结果是否合格。三者缺一不可。

官方参考：[Codex Build skills](https://learn.chatgpt.com/docs/build-skills) 和 [Build skills](https://developers.openai.com/plugins/build/skills)，用于核对 `SKILL.md`、渐进式加载和可选资源目录的当前说明。