---
url: https://ain.hmgf.hxcn.space/ai/how-to-design-good-skills-202605.md
description: >-
  从 ianneo_ai 的六问出发，结合 Anthropic 的 skills 结构，拆开场景、流程、输入输出、工具、验收与默认判断，说明一个 Skill
  怎样从提示词长文变成稳定工作流。
---

# 怎么设计一个真正有用的 Skill

> （<https://x.com/ianneo_ai/status/2054890888766373926>）定制 Skill，一上来就在写 prompt？大错特错！其实真正该问的是这 6 件事：它解决哪个场景？处理流程怎么跑？输入输出是什么？要调用哪些工具？怎样算合格？它凭什么跑得比通用 AI 好？Skill 不是一句你是专家，而是一套可复用的小工作流。边界定清，流程写顺，数据喂准，工具接上，验收摆出来，最后再加一点你的判断和品味，这才像给自己雇了一个稳定同事啊。定 Skill 先问场景流程，别急着写 prompt。这 6 件事问完，Skill 才算有灵魂。最后那句"加一点你的判断和品味"太真实了，通用 AI 缺的往往就是这点主观边界。重复性高的工作都适合做成 Skill。

这段话已经把问题说得很到位：Skill 要压缩的是重复工作流程。

为了把这六问落到一手资料上，同时参考了两个官方仓库：

* `anthropics/skills`：一个专门收集技能结构和最佳实践的仓库；
* `anthropics/claude-code` 里的 plugin-dev skill-development：更贴近 Claude Code 插件 / skill 开发的示例。

从这两套资料里能看出来，成熟 Skill 的核心在组织方式：`SKILL.md` 负责触发条件和主流程，`scripts/` 负责确定性动作，`references/` 放长文说明，`assets/` 放模板或素材。下面就按六问往下拆。

## 第一问：它解决哪个场景

Skill 设计最容易犯的错，就是场景写成领域。

比如"做前端""写科研""做运营"都只是范围。能落成 Skill 的场景，通常还要再具体一点：

* 把一篇长文改成站内正式文章；
* 给现有仓库补一份 handoff 文档；
* 读一组日志后做结构化诊断；
* 把 PDF 资料转成 Markdown 并归档图片；
* 跑一次代码评审并输出 fix list。

`anthropics/skills` 仓库里反复强调的一点，就是 description 要写清楚 **when to trigger**。说白了，就是逼你把场景写窄。Skill 关心的是"当用户遇到哪类任务时，触发这套流程"。

### 场景写到什么程度才算够

一个简单办法是看这三个问题：

1. 用户会在什么时刻想调用它？
2. 输入材料通常长什么样？
3. 结果交付出来后，用户拿它做什么？

如果这三个问题答不出来，场景大概率还太虚。

### 场景写清楚后会是什么样

下面这个写法就比"写一个代码优化 Skill"清楚得多：

```text
场景：仓库已经能跑，但目录结构开始变乱；用户想找出哪几个模块最该先整理，并给出可执行的重构候选项。
```

写到这个程度，已经能看出它对应的是 `improve-codebase-architecture` 这一类 Skill，不再是泛泛一句"帮我优化代码"。

## 第二问：处理流程怎么跑

GitHub：<https://github.com/anthropics/skills/tree/main/skills/skill-creator>
文档：<https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills/skill-development>

场景定下来之后，第二件事是把流程写顺。

流程不是目录树，也不是功能清单。流程是 agent 真正执行任务时要走的步骤序列。一个成熟 Skill 往往会把下面几类阶段写清楚：

* 读哪些材料；
* 要补问什么；
* 什么时候运行脚本；
* 什么时候停下来等用户；
* 什么时候给出产物；
* 如果失败，回退到哪里。

`anthropics/skills` 里的 `skill-creator` 明确推崇 progressive disclosure，这意味着流程不能一触发就把所有材料全部灌进上下文，而要按步骤加载。只有流程顺了，Skill 才不会一触发就变成长篇 dump。

### 流程怎么拆

最常见的拆法是四段：

1. **收集**：读输入、补上下文；
2. **判断**：决定走哪条子路径；
3. **执行**：调用脚本、生成草稿、修改文件；
4. **收口**：验收、列风险、给后续步骤。

比如一个"把研究资料整理成文章"的 Skill，可以写成：

```text
1. 读取相关材料和目标文件。
2. 判断这篇文章属于单项目介绍、多项目整理还是翻译整合。
3. 归档仓库说明、官网材料和本地原文，再起正文。
4. 写完后执行一轮去 AI 味和 copy-editing 自检。
5. 输出修改文件、来源概况和待回访问题。
```

这个流程一旦写清楚，后续同类文章就能反复跑。

## 第三问：输入输出是什么

输入输出不清楚，Skill 很快就会"好像做了很多，结果没人能接"。

### 输入要写到什么粒度

至少要分四类：

* **用户口头输入**：一句目标、补充偏好、约束；
* **文件输入**：Markdown、HTML、PDF、代码库、数据表；
* **环境输入**：当前目录、已安装工具、可用 MCP；
* **对话输入**：上一个步骤生成的中间结果。

很多 Skill 失控，问题就出在这里。它只写"用户给我资料"，没有写资料可以是哪几种，也没有写缺资料时怎么办。

### 输出也要写成交付物

输出别只写"给出结果"。应该写成用户能拿去下一步继续工作的东西，比如：

* 写入哪个文件；
* 返回哪种格式；
* 是否附来源列表；
* 是否要给状态记录字段；
* 是否需要截图、归档、脚本产物。

例如：

```text
输出：
- docs/ai/xxx.md 正文
- docs/ai/references/xxx/ 下的仓库说明 / official / x-reference / source-notes
- docs/ai/assets/xxx/ 下的本地图片
- 最终回执：文件列表、资料来源、待回访问题、状态字段
```

一旦写到这个粒度，Skill 的交付范围就会稳定很多。

## 第四问：要调用哪些工具

Skill 真正和普通提示词拉开差距，往往就在工具层。

`anthropics/skills` 与 Claude Code 的示例都默认了一个前提：Skill 可以调脚本、读引用资料、操作文件系统，必要时再接外部工具。这一点很关键，因为只靠自然语言说明，很多重复任务根本不稳。

### 工具层最常见的四类组件

1. `scripts/`：适合放确定性步骤，比如批量重命名、提取图片、跑校验；
2. `references/`：放需要按需读取的长文说明、规范、对照表；
3. `assets/`：放模板、示意图、封面、表格样板；
4. 外部工具：CLI、MCP、API、本地程序。

比如 PDF 处理类 Skill，工具层就可能长成这样：

```text
pdf-to-markdown/
├── SKILL.md
├── scripts/
│   ├── extract-images.py
│   └── fix-line-breaks.py
├── references/
│   └── formatting-rules.md
└── assets/
    └── article-template.md
```

这比把所有规则全塞进 `SKILL.md` 里稳定得多，也更省上下文。

### 什么情况该上工具，什么情况不用

一个实用判断标准是：它是否需要**可重复、可核验、少歧义**。

* 需要，就优先脚本化；
* 不需要，就留在自然语言流程里。

比如"帮我判断这段文字更像摘要还是导语"，这类就不必写脚本；但"把 30 张图片改名并移动到目标目录"，就很适合脚本。

## 第五问：怎样算合格

很多 Skill 看着很聪明，实际最弱的地方就是没有验收条件。

没有验收，agent 往往会把"我觉得差不多了"当完成；一旦跨会话、跨项目，这种模糊完成状态就特别容易出事故。

### 验收至少要有三层

1. **格式层**：文件有没有写到指定路径，代码块有没有标语言，链接是否可点；
2. **内容层**：是否覆盖所有必写项目，是否保留原文链接，是否区分官方资料和社区讨论；
3. **结果层**：这份产物能不能直接进入下一步，比如发布、交接、复核、构建。

例如文章类 Skill 的验收可以写成：

```text
- 正文已写入指定文件。
- references 目录已保存仓库说明 / official / x-reference / source-notes。
- 正文覆盖全部关键点，且不比原文更简略。
- 仓库介绍小节标题下已放 GitHub / 官网 / 文档直链。
```

只要这类清单存在，Skill 的稳定度就会上去。

### 验收别只写"高质量"

"高质量""专业""详细"都不是验收条件，因为它们不可直接检查。

更有用的写法是：

* 至少列出 3 个关键失败模式；
* 给出 1 组可执行命令；
* 保留全部非 `t.co` 链接；
* 修改路径不得超出 ownership。

这已经接近工程里 definition of done 的写法。

## 第六问：凭什么比通用 AI 好

第六问才轮到"判断和品味"。

Skill 和通用 AI 的差别，不在规则多少，而在默认取舍是否稳定。你要能说清楚：

* 为什么这条流程比临场发挥更稳；
* 哪些判断我不想每次都重新做；
* 哪些默认值体现了作者经验；
* 失败时该保守到什么程度。

### "判断和品味"到底落在哪

它通常落在这些地方：

* 默认优先读一手资料，社区转述只做补充；
* 目录写法固定，不让 agent 自己发明结构；
* 缺资料时先停下来标注来源层级，不乱补事实；
* handoff 放在 archive 前面；
* 文章里项目顺序按真实工作流，不按营销热度排。

这些看起来都不大，却直接决定 Skill 质量。用户为什么觉得某个 Skill 像"稳定同事"，往往就是因为这些默认值靠谱。

### 通用 AI 已经会做，为什么还要做 Skill

因为通用 AI 会做，不等于每次都按同一标准做。

一个好 Skill 的意义，是把"偶尔做对一次"变成"在这个场景里大概率持续做对"。它把你最不想反复解释的那部分经验，前移到结构里。

## 一个可直接复用的 Skill 设计草稿

下面这份草稿，可以直接拿去起手写新 Skill：

```markdown
---
name: your-skill-name
description: 说明这个 skill 解决什么具体场景，以及何时触发。
---

# 这个 Skill 解决什么问题

- 目标场景：
- 典型输入：
- 典型输出：
- 不适用场景：

# 工作流程

1. 读取材料：
2. 选择路径：
3. 执行任务：
4. 验收结果：

# 工具与资料

- scripts/：
- references/：
- assets/：
- 外部工具 / MCP / CLI：

# 验收标准

- 文件路径：
- 内容覆盖：
- 风格 / 格式要求：
- 风险与回退：

# 作者默认取舍

- 优先级：
- 保守策略：
- 何时停下来问用户：
```

这份草稿不华丽，但够用。把这六块写清楚，再去打磨 prompt 细节，顺序会稳很多。

## 资料来源

* ianneo\_ai 原帖：<https://x.com/ianneo_ai/status/2054890888766373926>
* `anthropics/skills`：<https://github.com/anthropics/skills>
* `skill-creator`：<https://github.com/anthropics/skills/tree/main/skills/skill-creator>
* `anthropics/claude-code` plugin-dev skill-development：<https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills/skill-development>
* 本地归档：`docs/ai/references/how-to-design-good-skills/`