## 先用一句话理解 Skill

Skill 可以理解为一份“给 AI 同事使用的标准作业手册”。

普通提示词只解决眼前这一次任务；Skill 则把一类任务的触发条件、执行步骤、参考资料、工具脚本和交付标准打包起来，让 ChatGPT 或 Codex 下次遇到相似工作时，仍能按同一套方法完成。

OpenAI 官方将 Skill 定义为一种可复用工作流的编写格式：一个 Skill 是一个目录，核心是 `SKILL.md`，还可以带脚本、参考资料和模板。它的目标不是让模型“知道更多”，而是让模型在特定任务上做事更稳定、更可重复。本文依据 [OpenAI 官方 Build skills 文档](https://learn.chatgpt.com/docs/build-skills) 整理。

## Skill 到底解决什么问题

假设团队每周都要整理用户访谈。你可以每次都重新告诉 AI：

- 不要脱离原文猜测；
- 按主题归纳痛点；
- 每个结论附上证据；
- 区分事实、判断和建议；
- 最后输出机会点与待验证问题。

只做一次时，这样写提示词没问题。但当任务反复出现、换人执行，或者需要稳定格式时，每次重新解释就会产生三个问题：

1. 指令容易遗漏；
2. 不同人写出的提示词不一致；
3. 模型不知道什么时候应该采用这套流程。

Skill 把这些约定保存下来，相当于把“某个人脑中的工作方法”变成团队可复用的产品能力。

适合做成 Skill 的通常是重复出现、过程相对稳定、质量可以检查的任务，例如代码审查、用户研究整理、周报生成、数据清洗、发布检查和文档排版。

## Skill 的工作原理

Skill 的运行可以拆成四步：发现、匹配、加载、执行。

```text
扫描可用 Skill
      ↓
先读取名称和描述
      ↓
用户点名，或当前任务与描述匹配
      ↓
加载完整 SKILL.md
      ↓
按说明读取资源、调用脚本并完成交付
```

### 第一步是发现

Codex 会从项目、用户、管理员和系统位置发现 Skill。项目级 Skill 可以跟随代码库共享，个人 Skill 可以跨项目使用，系统 Skill 则由产品提供。

常见位置如下：

| 范围 | 位置 | 适合场景 |
| --- | --- | --- |
| 当前项目 | `$CWD/.agents/skills` | 只服务当前目录或模块的流程 |
| 仓库上层 | 父目录中的 `.agents/skills` | 多个子模块共享的流程 |
| 仓库根目录 | `$REPO_ROOT/.agents/skills` | 整个团队共享的项目规范 |
| 个人 | `$HOME/.agents/skills` | 自己在所有项目中复用的习惯 |
| 管理员 | `/etc/codex/skills` | 组织或运行环境统一提供的能力 |
| 系统 | Codex 内置 | OpenAI 随产品提供的通用 Skill |

### 第二步是轻量匹配

Codex 不会在对话开始时把所有 Skill 的全文都塞进上下文。它先看到每个 Skill 的名称、描述和路径，再判断当前任务可能需要哪一个。

这叫“渐进式加载”或“渐进式披露”。官方文档说明，Codex 给初始 Skill 列表设置了上下文预算：最多使用上下文窗口的 2%；不知道窗口大小时，上限为 8,000 个字符。Skill 太多时，系统会先缩短描述，数量继续增长时还可能省略一部分。

通俗地说，模型起初看到的不是整本操作手册，而是一叠很薄的名片。`description` 就是名片上的业务范围，所以它直接决定 Skill 能不能在正确的时候被找到。

### 第三步是触发

Skill 有两种触发方式：

1. **显式触发**：用户直接选择或点名 Skill。在 Codex CLI 或 IDE 中，可以通过 `/skills` 查看，或者用 `$技能名` 提及。
2. **隐式触发**：用户没有点名，但任务与 Skill 的 `description` 匹配，Codex 自动选择它。

显式触发像是对同事说“请按发布检查清单处理”；隐式触发则像是同事看到发布任务后，主动拿出了检查清单。

### 第四步是完整加载与执行

一旦选中 Skill，Codex 才读取完整的 `SKILL.md`，并按照其中的步骤工作。Skill 还可以提供：

- `scripts/`：需要确定性或外部工具时使用的脚本；
- `references/`：规范、术语表、接口说明等参考资料；
- `assets/`：模板、图片或其他交付资源；
- `agents/openai.yaml`：展示信息、调用策略和工具依赖等可选元数据。

这套机制的好处是：平时只付出很小的上下文成本，真正需要时又能拿到完整方法和材料。

## 一个 Skill 的最小结构

最简单的 Skill 只需要一个目录和一个 `SKILL.md`：

```text
interview-synthesis/
└── SKILL.md
```

`SKILL.md` 至少包含 YAML 头部中的 `name` 和 `description`，下面再写执行说明：

```markdown
---
name: interview-synthesis
description: Turn product interview notes into evidence-backed themes, pain points, and opportunities. Use for user interview synthesis; do not use for writing fictional personas or marketing copy.
---

Read all interview notes before drawing conclusions.

Group repeated observations into themes. For every theme, include:

- the user problem;
- supporting evidence;
- affected user groups;
- confidence level;
- open questions.

Clearly separate evidence from interpretation. Never invent quotes.
```

这个版本已经能工作。`name` 是 Skill 的机器可识别名称，`description` 告诉系统何时应该或不应该触发，正文则规定被选中后具体怎么做。

## 手工写一个 Skill

下面以“用户访谈总结”为例，从零创建一个项目级 Skill。

### 创建目录

在项目根目录执行：

```bash
mkdir -p .agents/skills/interview-synthesis
```

然后创建 `.agents/skills/interview-synthesis/SKILL.md`。

### 写清触发描述

先写 YAML 头部：

```yaml
---
name: interview-synthesis
description: Analyze product user interview notes and produce evidence-backed themes, pain points, opportunities, and open questions. Use when synthesizing one or more interview transcripts. Do not use for surveys, fictional personas, or marketing copy.
---
```

好的描述通常同时回答三个问题：

- 它做什么；
- 什么输入或场景应该用；
- 哪些相似场景不该用。

官方特别建议把关键用途和触发词放在描述前面。原因很现实：当 Skill 数量很多、描述被缩短时，前面的内容更有机会保留下来。

### 把工作流写成命令

继续在 YAML 头部下面写执行步骤：

```markdown
## Goal

Turn raw user interview notes into a reviewable research synthesis grounded in source evidence.

## Required inputs

- One or more interview transcripts or notes.
- The product or research question, when available.

If the source material is missing, ask for it before continuing.

## Workflow

1. Read all supplied notes before forming themes.
2. Mark repeated behaviors, goals, pain points, workarounds, and contradictions.
3. Group related observations into themes.
4. Attach source evidence to every theme.
5. Separate direct evidence, interpretation, and recommendation.
6. Identify unanswered questions and weak evidence.

## Output

Return these sections in order:

1. Executive summary
2. Research themes
3. Pain points
4. Product opportunities
5. Contradictions and edge cases
6. Open questions

## Quality bar

- Never invent participants, quotes, numbers, or findings.
- Label low-confidence conclusions.
- Prefer concrete evidence over generic summaries.
- Preserve important disagreement instead of forcing consensus.
```

这里有四个很重要的设计元素：输入要求、顺序明确的步骤、固定输出、可检查的质量标准。它们让 Skill 不再是一段“请认真完成”的愿望，而是一套可执行的流程。

### 让 Codex 发现更新

OpenAI 官方文档说明，Codex 会自动检测 Skill 的变化。如果新增或更新后没有出现，可以重启 Codex再检查。

在 Codex 中可以用 `/skills` 查看可用 Skill，也可以直接输入类似下面的请求：

```text
$interview-synthesis 请整理这三份访谈记录，重点分析新用户第一次配置时遇到的障碍。
```

## 也可以让内置工具帮你创建

如果不想手工搭目录，Codex 提供了内置的 Skill Creator：

```text
$skill-creator
```

它会询问 Skill 做什么、什么时候触发，以及只需要说明文字还是需要附带脚本。

如果流程很难用语言解释，但你可以完整演示一遍，官方还提供 Record & Replay：先录制一次实际操作，再由系统检查步骤并起草可复用 Skill。

这两种方式都只是帮你生成初稿。最终仍需要作者检查触发范围、步骤顺序、错误处理和输出质量。

## 什么时候需要 scripts、references 和 assets

先从只有 `SKILL.md` 的版本开始。只有正文不足以稳定完成工作时，再增加其他目录：

```text
interview-synthesis/
├── SKILL.md
├── scripts/
│   └── normalize_transcript.py
├── references/
│   ├── research-taxonomy.md
│   └── output-examples.md
├── assets/
│   └── synthesis-template.md
└── agents/
    └── openai.yaml
```

### 脚本适合确定性工作

官方建议优先写说明，只有需要确定性行为或外部工具时再用脚本。

例如“识别主题”适合交给模型，因为需要理解语义；“把 200 份 JSON 访谈记录转换成统一 Markdown”更适合脚本，因为格式转换应该稳定、可测试、可重复。

脚本不是越多越专业。脚本会带来运行环境、依赖、权限和维护成本，只有当它明显降低不确定性时才值得加入。

### 参考资料适合长知识

术语表、业务规则、详细接口说明和长篇示例可以放进 `references/`。`SKILL.md` 只保留选择哪份资料、什么时候读取、读取后做什么的路由说明。

这是进一步的渐进式组织：Skill 被选中后，也不必不加区分地阅读所有背景材料。

### 素材适合直接复用

报告模板、品牌图标、文档骨架或固定资源可以放进 `assets/`。Skill 应明确哪些素材必须复用，以及最终产物放在哪里。

## 可选的 openai.yaml 做什么

`agents/openai.yaml` 可以补充用户界面信息、隐式调用策略和工具依赖。例如：

```yaml
interface:
  display_name: "Interview Synthesis"
  short_description: "Turn interview notes into evidence-backed product insights"
  icon_small: "./assets/icon.svg"
  brand_color: "#4F46E5"

policy:
  allow_implicit_invocation: true

dependencies:
  tools:
    - type: "mcp"
      value: "researchRepository"
      description: "Internal research repository"
```

`allow_implicit_invocation` 默认为 `true`。如果设为 `false`，Codex 不会仅凭任务描述自动启用该 Skill，但用户仍然可以显式点名。

对于付款、删除、正式发布等高影响工作流，可以考虑关闭隐式触发，要求用户明确选择。这里不是说显式触发可以替代权限控制，而是减少用户没有意识到流程已启用的情况；真正的写入权限、确认和审计仍应由工具与业务系统负责。

## 如何写好一个 Skill

写好 Skill 的关键不是堆更多文字，而是降低三个不确定性：什么时候用、下一步做什么、怎样算完成。

### 一个 Skill 只做一件事

“帮助产品团队完成所有工作”不是一个好 Skill。它既难触发，也无法定义统一输出。

更好的拆分是：

- 整理用户访谈；
- 编写 PRD；
- 检查埋点方案；
- 汇总版本反馈。

边界越清楚，触发越准确，正文也越容易测试。OpenAI 的最佳实践同样建议每个 Skill 聚焦一个工作。

### 把 description 当成路由规则

下面这个描述太空泛：

```yaml
description: Help with research.
```

它没有说明是哪种研究、输入是什么，也无法和市场研究、技术调研、用户访谈区分。

更可用的写法是：

```yaml
description: Synthesize product user interview transcripts into evidence-backed themes and opportunities. Use for qualitative interview analysis; do not use for survey statistics or web research.
```

不要追求广告语，要追求可判定。只要看到用户任务，就能回答“符合”或“不符合”，这才是好描述。

### 用祈使句写步骤

“可能需要关注证据”不如“为每个主题附上至少一条来源证据”。

“输出应该比较完整”不如“依次输出摘要、主题、痛点、机会点和待验证问题”。

官方建议使用带明确输入和输出的祈使步骤。因为 Skill 是操作手册，不是介绍文章，执行者需要知道接下来具体做什么。

### 明确缺少输入时怎么办

Skill 不应假设一切材料都已经准备好。至少要写清：

- 哪些输入是必需的；
- 缺少时是询问用户、跳过，还是停止；
- 哪些假设可以自行做出；
- 哪些决定必须由用户确认。

这能避免模型为了“完成任务”而自行补造事实。

### 给出完成标准

没有完成标准的 Skill 很容易在“看起来差不多”时结束。完成标准应该可检查，例如：

- 每个研究主题都有证据；
- 所有代码修改都通过指定测试；
- 发布前先完成格式校验；
- 输出必须包含风险和未解决问题。

完成标准既帮助模型自检，也方便人审阅。

### 把高频判断写在主文件

会影响触发和主流程的规则，应放在 `description` 或 `SKILL.md` 中。只有在特定分支才需要的长说明，再放进 `references/`。

如果把“什么情况下不能使用”藏在一份很深的参考文件里，系统可能在读取它之前就已经选错了 Skill。

### 让说明和脚本各司其职

模型擅长理解语义、处理例外和组织表达；脚本擅长格式转换、批量计算和确定性校验。

一个好 Skill 会把任务拆到合适的一边，而不是用长提示词模拟程序，也不是把所有判断都硬编码进脚本。

## 如何测试一个 Skill

Skill 不能只测“点名后能不能运行”，至少要准备四组提示词：

| 测试类型 | 示例 | 期望 |
| --- | --- | --- |
| 应该触发 | “整理这三份用户访谈的共同痛点” | 自动选择访谈总结 Skill |
| 不该触发 | “统计 500 份问卷的转化率” | 不选择该 Skill |
| 边界模糊 | “帮我研究用户反馈” | 先判断材料类型，必要时询问 |
| 输入缺失 | “总结访谈结论”，但没有访谈内容 | 请求补充材料，不编造结论 |

触发正确后，还要检查执行质量：

1. 是否按规定顺序执行；
2. 是否读取了正确参考资料；
3. 是否只在必要时运行脚本；
4. 输出是否满足格式和质量标准；
5. 失败时是否给出清楚、可行动的说明。

官方特别建议用提示词测试 `description` 的触发行为。实际维护中，每次修改描述后都应重新跑“应该触发”和“不该触发”两组用例，避免解决一个误触发，又制造新的漏触发。

## 常见的失败写法

**把 Skill 写成百科全书**：主文件塞入大量背景知识，真正的步骤反而难找。应把长资料拆到 `references/`，主文件保留路线。

**描述只有功能名**：例如“处理 PDF”或“帮助设计”。缺少场景与边界，隐式触发很难准确。

**只有原则，没有动作**：满篇都是“专业、准确、深入”，却没有输入、步骤和输出结构。

**凡事都写脚本**：增加依赖和维护成本，还把模型擅长的语义判断变成脆弱规则。

**没有停止条件**：材料缺失、权限不足或工具失败时仍要求继续，很容易产出猜测或半成品。

**用示例代替规则**：示例只能帮助理解，不能覆盖所有情况。应先写明确规则，再给少量代表性示例。

**一个 Skill 包办一切**：触发描述越来越长、流程分支越来越多，最终任何任务都像该用，又都无法稳定完成。

## Skill、脚本和插件怎么选择

可以用一个简单判断来区分：

| 需求 | 更合适的形式 |
| --- | --- |
| 教 AI 按固定方法完成一类任务 | Skill |
| 确定性计算、转换或批处理 | Script，通常由 Skill 调用 |
| 在一个项目或个人环境中复用 | 独立 Skill 目录 |
| 分发给更多用户，或与连接器一起安装 | Plugin |

OpenAI 官方的建议是：先用 Skill 设计工作流；当需要向更多人分发、组合多个 Skill，或把 Skill 与 MCP 连接器一起交付时，再打包成 Plugin。

换句话说，Skill 是“怎么做事”，Plugin 更像“怎么把一组能力交付给别人”。

## 一份实用检查清单

发布或共享 Skill 前，可以逐项检查：

- `SKILL.md` 是否包含 `name` 和 `description`；
- 描述开头是否直接说明核心用途；
- 是否写明应当触发和不应触发的场景；
- 一个 Skill 是否只聚焦一项工作；
- 必需输入、缺失输入处理是否明确；
- 步骤是否使用清楚的动作指令；
- 输出结构和完成标准是否可检查；
- 长资料是否移到 `references/`；
- 脚本是否只用于确定性或外部工具任务；
- 是否测试了正向、反向、边界和缺失输入；
- 高影响动作是否有权限、确认和失败处理；
- 新用户不依赖作者口头解释也能使用。

## 最后总结

Skill 的本质不是“更长的 Prompt”，而是把触发规则、工作步骤和质量标准组合成一个可复用能力。

理解它最简单的方式是：

- `name` 是能力名称；
- `description` 是路由规则；
- `SKILL.md` 正文是操作手册；
- `references/` 是资料库；
- `scripts/` 是确定性执行器；
- `assets/` 是可复用素材；
- `openai.yaml` 是可选的展示、策略和依赖配置。

先从一个小而明确、只有 `SKILL.md` 的版本开始。确认它能在正确场景触发、能稳定完成任务，再逐步增加参考资料、脚本和分发能力。一个真正好用的 Skill，应该像优秀的产品流程：入口清楚、步骤可执行、异常有去处、结果可验收。

## 官方资料

- [OpenAI：Build skills](https://learn.chatgpt.com/docs/build-skills)