怎么设计一个真正有用的 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/ 放模板或素材。下面就按六问往下拆。

第一问：它解决哪个场景

GitHub：https://github.com/anthropics/skills GitHub：https://github.com/anthropics/claude-code

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

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

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

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

场景写到什么程度才算够

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

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

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

场景写清楚后会是什么样

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

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

写到这个程度，已经能看出它对应的是 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，可以写成：

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

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

第三问：输入输出是什么

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

输入要写到什么粒度

至少要分四类：

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

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

输出也要写成交付物

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

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

例如：

输出：
- 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，工具层就可能长成这样：

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 的验收可以写成：

- 正文已写入指定文件。
- 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：

---
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/