Claude Skill 构建指南总结

Claude Skill 构建指南总结

一、这份指南在讲什么

这份《The Complete Guide to Building Skills for Claude》系统讲解了如何为 Claude 设计、实现、测试、分发Skill。文中把 Skill 定义为一种“可打包、可复用的任务能力封装”：它不是单次对话里的提示词，而是一套长期可复用的指令、流程、参考资料与可执行脚本。

它的核心价值是：

• 把反复出现的工作流沉淀下来
• 让 Claude 在合适场景下自动调用正确的方法
• 降低每次重新解释背景、规则、步骤的成本
• 让不同用户、不同会话下的执行结果更稳定

从适用对象来看，这份指南面向三类人：

• 希望 Claude 稳定执行特定流程的开发者
• 想把个人方法论固化下来的高频用户
• 希望在团队内统一 AI 工作方式的组织

二、什么是 Skill

2.1 Skill 的本质

指南对 Skill 的定义很明确：Skill 是一个文件夹，其中包含 Claude 在某类任务中需要遵循的说明和资源。

一个标准 Skill 通常由以下内容组成：

• SKILL.md：必需，主说明文件
• scripts/：可选，放可执行脚本
• references/：可选，放参考文档
• assets/：可选，放模板、字体、图标等资源

这意味着 Skill 不是一句 prompt，也不是零散文档，而是一个结构化能力包。

2.2 Skill 解决什么问题

如果没有 Skill，用户往往需要在每次对话中重复描述：

• 要做什么
• 按什么流程做
• 有哪些边界条件
• 失败后怎么处理
• 输出需要符合什么规范

有了 Skill 之后，这些信息可以一次沉淀、重复复用。Claude 在识别到合适场景时，就能自动加载并执行对应能力。

2.3 Skill 与普通 Prompt 的区别

可以把两者理解为：

• Prompt：一次性指令，偏即时
• Skill：长期能力资产，偏可复用

Prompt 更适合临时任务；Skill 更适合可重复、可标准化、可沉淀的任务。

三、为什么 Skill 很重要

3.1 对个人用户的价值

对个人来说，Skill 的最大意义是把“经验”变成“默认行为”。

例如：

• 写研究报告时，始终按固定分析框架展开
• 生成前端页面时，自动遵循既定设计风格
• 调用某类工具时，按稳定步骤执行，而不是每次临场发挥

这样可以显著减少重复沟通和返工。

3.2 对团队和组织的价值

对团队来说，Skill 更像是一种AI 工作规范载体。它可以把团队约定统一固化为 Claude 的执行方式，例如：

• 文档模板和写作规范
• 研发或运营工作流
• 某类平台的最佳实践
• 特定业务域的专业判断规则

这样，团队成员即使提示方式不同，Claude 也能更一致地输出结果。

3.3 对 MCP 场景的价值

文中专门强调了 Skill 与 MCP 的配合价值。

• MCP提供“能做什么”——即对外部系统、服务、数据、工具的访问能力
• Skill提供“应该怎么做”——即工作流、方法论、最佳实践

指南用了一个很形象的比喻：

• MCP 像专业厨房，提供设备和食材
• Skill 像菜谱，告诉你如何把这些资源变成有价值的结果

因此，只有 MCP 没有 Skill，常见问题是：

• 用户接上能力后，不知道下一步该怎么做
• 每次都要重新解释流程
• 工具调用不稳定，结果不一致
• 用户把“不会用”误认为“连接器不好用”

Skill 的作用，就是把这些使用门槛前置消化掉。

四、Skill 的核心设计原则

文中提出了三个关键原则。

4.1 Progressive Disclosure：渐进式加载

这是整份指南里最核心的设计思想之一。

Skill 采用三层加载结构：

1. 第一层：YAML frontmatter
   始终进入 Claude 的系统提示中，用来判断“这个 Skill 什么时候该被用到”。
2. 第二层：SKILL.md正文
   只有在 Claude 判断当前任务相关时才加载，用于提供完整操作说明。
3. 第三层：外链资源文件
   例如references/下的资料，只有确实需要时才进一步查看。

这样做的好处是：

• 节省上下文 token
• 保留专门知识
• 避免把所有细节一股脑塞进主上下文
• 让 Skill 既专业又不臃肿

可理解为：先让 Claude 知道“何时用”，再让它知道“怎么做”，最后在必要时补充“细节资料”。

4.2 Composability：可组合性

Claude 可以同时加载多个 Skill，因此单个 Skill 不能假设自己是系统中唯一的能力。

这意味着设计 Skill 时要注意：

• 不要写成与其他 Skill 强冲突
• 说明边界和适用范围
• 让它能与其他能力协同工作

好的 Skill 不是封闭的，而是可组合的。

4.3 Portability：可移植性

指南强调，Skill 应尽量做到“一次构建，多处可用”，可运行在 Claude.ai、Claude Code 和 API 场景中。

这要求作者注意：

• 环境依赖要清楚
• 文件结构要标准
• 不要依赖某个特定使用界面才成立的隐含假设

如果有额外依赖，也应该通过compatibility等字段说明清楚。

五、设计 Skill 时，应该先想什么

5.1 从 Use Case 出发，而不是从文件开始

指南明确建议：不要一上来就写代码或写说明，先定义 2~3 个明确的用例。

一个好的用例定义通常包括：

• 用户想完成什么目标
• 触发语句可能是什么
• 整个工作流分几步
• 需要哪些工具
• 最终结果长什么样

文中的示例是“冲刺规划（Sprint Planning）”，结构非常典型：

• 触发：用户说“帮我规划这个 sprint”
• 步骤：拉取当前状态、分析容量、建议优先级、创建任务
• 结果：输出完整的 Sprint 规划

这个方法背后的本质是：Skill 不是写给作者自己看的，而是为了让 Claude 在实际用户任务里稳定复现一套目标导向流程。

5.2 三类常见 Skill 场景

指南总结了三种高频模式。

类别一：文档与资产生成

适合输出标准化成果物，例如：

• 文档
• 报告
• 演示稿
• 设计稿
• 页面或代码

其关键技巧包括：

• 内嵌风格规范
• 预设输出模板
• 交付前质量检查清单
• 充分利用 Claude 自带的生成能力

类别二：工作流自动化

适合多步骤流程，例如：

• 建立项目
• 处理审批
• 生成任务
• 执行跨系统动作

关键技巧是：

• 明确步骤顺序
• 加入校验门
• 内置迭代优化闭环
• 用模板提升流程稳定性

类别三：MCP 能力增强

适合在已有 MCP 接入基础上，进一步加入方法论和业务知识。

关键技巧包括：

• 按顺序协调多个工具调用
• 将领域知识嵌入流程
• 替用户补齐隐含上下文
• 对常见错误做提前处理

六、如何定义一个“好 Skill”的成功标准

文中指出，Skill 的成功不只是“能运行”，而是要看它是否在真实任务中稳定生效。

6.1 定量指标

建议关注以下指标：

• 是否能在大多数相关问题上正确触发
• 完成任务所需工具调用次数是否降低
• token 消耗是否下降
• 每次工作流中的 API 失败次数是否减少

例如可以比较“有 Skill”和“无 Skill”两种情况下：

• 需要几轮来回澄清
• 是否出现失败重试
• 总调用成本如何

6.2 定性指标

还要观察：

• 用户是否还需要频繁提醒下一步
• 工作流是否能在较少人工纠正下跑完
• 不同会话下结果是否一致
• 新用户是否能较低门槛上手

指南承认，这里暂时还存在一定“经验判断”成分，但方向很清楚：Skill 的目标是提升稳定性、可用性和复用价值。

七、Skill 的技术结构要求

7.1 文件结构要求

标准结构如下：

your-skill-name/ ├── SKILL.md ├── scripts/ ├── references/ └── assets/

其中，只有SKILL.md是强制项，其余目录按需添加。

7.2 命名规范

Skill 文件夹和name字段都应使用kebab-case，也就是全小写、单词之间用-连接。

正确示例：

notion-project-setup

错误示例：

• Notion Project Setup
• notion_project_setup
• NotionProjectSetup

7.3SKILL.md必须严格命名

文中特别强调：

• 必须叫SKILL.md
• 大小写必须准确
• 不能写成skill.md、SKILL.MD等变体

7.4 Skill 目录内不要放README.md

Skill 目录是给 Claude 用的，不是给人类读者看的。因此：

• 面向 Claude 的内容放在SKILL.md或references/
• 如果要开源展示，可在仓库根目录写面向人的README.md

这个区分很重要：Skill 内部强调机器可执行与可判断，仓库层面才强调人类理解与安装说明。

八、最关键的部分：YAML Frontmatter

指南明确指出：frontmatter 是 Skill 最重要的部分。

因为 Claude 是否决定加载某个 Skill，首先依赖这里的元信息。

8.1 最小可用格式

最简结构如下：

---name:your-skill-namedescription:What it does. Use when user asks to[specific phrases].---

起步时只要有这两个字段就可以。

8.2name字段要求

• 必填
• 必须使用 kebab-case
• 最好和文件夹名一致
• 不能包含保留词，例如claude、anthropic

8.3description字段要求

这是最重要的字段，必须同时说明两件事：

• 这个 Skill 做什么
• 什么时候应该使用它

还要满足：

• 1024 字以内
• 不能有 XML 尖括号< >
• 应尽量写出用户真实会说的话
• 如果和文件类型相关，要写出文件类型

文中给出了很重要的判断逻辑：

description的任务，是让 Claude 在不加载完整 Skill 的情况下，也能判断这项能力是否适用。

这本质上就是触发机制设计。

8.4 可选字段

可选字段包括：

• license
• compatibility
• metadata

其中metadata可用于放：

• 作者
• 版本
• 关联 MCP 服务
• 类别、标签、文档地址等

这些信息不会替代主逻辑，但对维护、分发、版本管理很有帮助。

8.5 安全限制

frontmatter 中禁止：

• XML 尖括号< >
• 带有claude或anthropic的 Skill 名称

原因很直接：frontmatter 会进入系统提示，若允许注入性内容，存在安全风险。

九、如何写出有效的 Skill 说明

9.1description要写得像“触发器说明”，不是简介

文中对好坏写法对比得非常清楚。

好的写法具有三个特征：

• 清楚说明做什么
• 明确列出何时使用
• 包含用户可能会说出的触发词

例如：

• 当用户上传.fig文件时使用
• 当用户说“design specs”时使用
• 当用户提到“sprint”“create tickets”时使用

坏的写法则通常是：

• 过于抽象
• 只讲能力，不讲触发条件
• 过于技术化，但没有用户视角

一个实用判断标准是：如果只看 description，Claude 能否知道“什么时候该调用它”？

9.2 主说明要足够具体、可执行

SKILL.md正文建议包含：

• 明确的操作步骤
• 命令或工具调用示例
• 成功结果示例
• 常见场景案例
• 故障排查说明

文中推荐的组织结构大致是：

• Skill 名称
• Instructions
• 分步骤说明
• 示例
• Troubleshooting

9.3 写指令时的最佳实践

指南强调几条很实用的原则：

原则 1：具体，而不是泛泛而谈

好例子：

• 明确执行哪个脚本
• 明确输入参数格式
• 明确失败后要检查什么

差例子：

• “在继续前先验证一下数据”

前者可执行，后者仍然要靠 Claude 自己猜。

原则 2：要有错误处理

如果接入了 MCP 或外部系统，应该提前写出：

• 常见错误是什么
• 可能原因是什么
• 如何恢复或重试

原则 3：详细资料放到references/

不要把所有内容都塞进SKILL.md。

更好的方式是：

• 在主说明里保留核心流程
• 详细规范、错误码、分页规则等放到references/
• 需要时再查

这正是“渐进式加载”的实践体现。

十、Skill 的测试与迭代方法

指南没有把 Skill 看成“一次写完”的产物，而是强调持续迭代。

10.1 三类测试方式

可以按需求选择不同强度：

• 手工测试：直接在 Claude.ai 中试
• 脚本化测试：在 Claude Code 中批量验证
• 程序化测试：通过 Skills API 构建系统性评估

不同场景对测试要求不同：

• 小团队内部使用，可偏快速迭代
• 大规模面向企业用户，需要更严格验证

10.2 推荐测试框架

文中建议至少覆盖三类测试。

1）触发测试

验证 Skill 是否在该触发时触发，不该触发时不触发。

应测：

• 明显表达
• 同义改写
• 无关请求

这是验证description是否写对的关键。

2）功能测试

验证 Skill 执行后，结果是否正确。

应测：

• 输出是否有效
• API 是否成功
• 错误处理是否生效
• 边界情况是否覆盖

3）效果对比测试

比较有 Skill 和无 Skill 的差异，例如：

• 来回消息数是否更少
• 失败调用是否更少
• token 是否更省
• 用户是否更少干预

10.3 迭代策略：先打磨一个难任务

这是指南中非常有启发的一点：

先围绕一个困难但典型的任务反复调到成功，再把成功做法提炼成 Skill。

也就是说，不要一开始就追求覆盖面很广；先找到一个代表性任务，把流程打磨稳定，再逐步扩展。

这样获得的反馈最直接，迭代速度也更快。

10.4 关注三类失败信号

触发不足（Undertriggering）

表现为：

• 本该触发却没触发
• 用户需要手动开启
• 用户经常问“这个什么时候用”

解决思路：

• 在description中加入更明确的场景词、专业词、触发语句

过度触发（Overtriggering）

表现为：

• 不相关任务也触发
• 用户频繁关闭
• 技能边界模糊

解决思路：

• 加入负向触发条件
• 收窄描述范围
• 明确“不适用于什么”

执行问题

表现为：

• 结果不稳定
• 工具调用容易失败
• 用户需要频繁纠正

解决思路：

• 精炼说明
• 增加错误处理
• 把关键校验做成脚本，而不只靠语言描述

十一、Skill 的分发与共享

11.1 当前分发方式

指南介绍了 Skill 的主流分发方式：

• 个人用户可下载 Skill 文件夹后上传到 Claude.ai
• 也可放到 Claude Code 的技能目录中
• 组织管理员可在工作区范围内统一部署

这表明 Skill 不只是个人配置，也可以成为组织级能力资产。

11.2 技能标准是开放的

Anthropic 将 Agent Skills 作为开放标准来推动，希望 Skill 像 MCP 一样具备跨平台可移植性。

这意味着：

• Skill 不应只为某个产品页面而写
• 设计时要尽量遵循标准结构
• 如果有平台特定依赖，应明确写在兼容性说明里

11.3 API 使用场景

对于应用、代理系统、自动化流程等程序化场景，可以通过 API 管理和调用 Skill。

适合 API 的场景包括：

• 生产环境部署
• 自动化流水线
• 自定义智能体系统
• 规模化应用集成

而手工开发、调试和临时使用，更适合 Claude.ai 或 Claude Code。

11.4 推荐的对外发布方式

文中建议：

1. 把 Skill 托管到 GitHub
2. 写清 README、安装方法、截图和示例
3. 在 MCP 仓库或产品文档里链接这个 Skill
4. 给出快速上手指南

这里有一个重要区分：

• Skill 文件夹内部：不给 README
• 公开仓库根目录：应有 README，服务于人类用户

11.5 对外描述要强调“结果价值”

指南特别提醒：向外介绍 Skill 时，不要只讲技术结构，而要讲用户收益。

正确表达应聚焦：

• 它替用户节省了什么时间
• 它把什么复杂工作自动化了
• 它与 MCP 配合后能实现什么结果

也就是：讲“成果”，不要只讲“机制”。

十二、五种常见 Skill 设计模式

这一章非常适合实际落地时参考。

12.1 顺序式工作流编排

适用于必须按固定顺序执行的流程。

特点：

• 步骤依赖明确
• 每一步有输入输出
• 可在中间设置校验
• 失败时可定义回滚

典型场景：开户、订阅、通知等严格链式流程。

12.2 多 MCP 协同

适用于跨多个系统的复合任务。

例如：

• 从设计平台导出资源
• 存入云盘
• 在任务系统中建单
• 再发通知

其重点在于：

• 阶段划分清楚
• 数据在不同 MCP 间顺畅传递
• 每阶段切换前先校验
• 统一做错误处理

12.3 迭代式优化

适用于成果质量需要逐轮提升的场景，例如报告生成。

典型流程：

1. 先生成初稿
2. 跑校验
3. 找问题
4. 修复并重生成局部
5. 反复迭代直到满足标准

关键不是“多做几轮”，而是建立明确的质量标准和停止条件。

12.4 上下文感知的工具选择

适用于同一目标在不同上下文下要选择不同工具的场景。

例如文件存储：

• 大文件走云存储
• 协作文档走 Docs/Notion
• 代码文件走 GitHub
• 临时文件走本地

这种模式的核心是：

• 先有清晰决策树
• 再做工具选择
• 最后向用户解释原因

12.5 领域智能嵌入

适用于 Skill 除了会调用工具，还承担专业判断职责的场景。

例如金融合规处理：

• 先检查制裁名单
• 判断司法辖区
• 评估风险
• 记录合规决策
• 只有通过后才处理交易

这类 Skill 的价值不只是“自动化”，而是把领域知识直接融入执行逻辑。

十三、常见问题与排查思路

13.1 技能上传失败

常见原因：

• SKILL.md文件名不正确
• frontmatter YAML 格式错误
• name字段不符合 kebab-case 规范

这是最基础也最常见的问题，通常先检查：

• 文件名是否完全正确
• YAML 是否有---包裹
• 是否有未闭合引号或格式错误

13.2 技能不触发

最常见原因是description写得太泛。

检查重点：

• 是否明确写了触发短语
• 是否包含用户真实会说的话
• 是否提及相关文件类型
• 是否把任务范围写得足够具体

指南还给了一个很实用的调试方法：

• 直接问 Claude：“什么时候会用这个 Skill？”
• 看它是否只复述了模糊描述
• 再针对缺失信息修改description

13.3 技能触发过多

如果频繁在不相关场景下被拉起，解决办法包括：

• 加负向触发条件
• 缩小场景范围
• 明确“只适用于什么，不适用于什么”

13.4 MCP 连接问题

如果 Skill 已经触发，但工具调用失败，排查顺序应是：

1. MCP 是否连接成功
2. 鉴权是否过期或权限不足
3. 不带 Skill 时，单独调用 MCP 能否成功
4. Skill 内写的工具名是否正确且大小写匹配

也就是说，要先区分是“工具连接有问题”，还是“Skill 编排有问题”。

13.5 指令没有被很好遵循

常见原因有：

• 说明过长、过散
• 关键规则埋得太深
• 表达含糊
• 只说原则，没有给出可执行检查项

指南给出的优化方向非常实用：

• 把关键要求放到前面
• 使用Critical、Important等显眼标题
• 把模糊要求改写成可核验清单
• 对关键校验尽量用脚本实现，而不是只靠自然语言

13.6 上下文过大导致效果下降

表现为：

• 响应变慢
• 结果变差
• 技能内容难以稳定执行

对应优化方式：

• 缩短SKILL.md
• 把细节移到references/
• 控制同时启用的 Skill 数量
• 对相关能力打包而不是全量开启

十四、文末提供的实用清单

14.1 Quick Checklist 的价值

文末的快速检查清单很适合拿来做发布前自检。它覆盖了四个阶段：

• 开始前
• 开发中
• 上传前
• 上传后

其中最值得落实的检查点包括：

• 是否已明确 2~3 个用例
• 是否确定所需工具
• 文件夹命名是否规范
• SKILL.md是否存在且命名准确
• description是否同时写明做什么、何时用
• 是否已测触发与误触发
• 是否完成功能测试
• 上传后是否继续收集反馈并迭代

这说明 Skill 不是“写完就完”，而是一个持续维护的产品化资产。

14.2 Frontmatter 参考价值

文末还给了 frontmatter 的完整示例，帮助作者理解：

• 最小必填结构是什么
• 可选字段怎么扩展
• 什么内容允许写，什么内容禁止写

对于新手来说，这一部分非常适合当模板起点。

14.3 示例技能仓库的重要性

官方还给出了公开示例技能仓库与合作伙伴目录。它们的意义不只是“给你看例子”，更重要的是：

• 帮你理解成熟 Skill 的组织方式
• 帮你参考不同场景的写法
• 帮你在真实案例基础上改造，而不是从零空想

十五、这份指南传达的核心方法论

如果把整份 PDF 压缩成一套方法论，我认为可以总结为以下几点。

15.1 Skill 不是提示词技巧，而是能力工程

它关注的不是“怎么把一句 prompt 写得更像魔法”，而是：

• 怎么把知识、流程、资源、脚本组织成可复用资产
• 怎么让 Claude 在正确时机自动使用它
• 怎么通过结构设计降低上下文负担
• 怎么通过测试和迭代不断提高稳定性

15.2 好 Skill 的核心不是“内容多”，而是“触发准、步骤清、边界明”

一个优秀 Skill 往往具备这些特征：

• description让 Claude 知道何时该用
• SKILL.md让 Claude 知道具体怎么做
• references/让 Claude 在需要时获取细节
• scripts/让高风险校验更确定、更稳定

15.3 Skill 的设计应从真实工作流逆推

最好的起点不是抽象能力名称，而是：

• 用户到底想完成什么结果
• 为实现这个结果，Claude 应按什么步骤做
• 哪些地方需要专业判断
• 哪些地方必须做校验和容错

15.4 Skill 与 MCP 结合后，AI 才真正接近“可交付工作流”

MCP 解决连接问题，Skill 解决执行质量问题。只有二者结合，Claude 才能从“有工具可用”进一步走向“会正确使用工具完成复杂工作”。

十六、面向实践的落地建议

如果你准备真正开始做 Skill，可以直接按这条路线推进：

1. 先选一个高频、重复、容易出错的任务
   不要一开始贪大求全。

2. 写出 2~3 个明确用例
   包括触发语句、步骤、结果。

3. 先把description打磨准确
   它决定触发效果，优先级极高。

4. 主说明聚焦核心流程
   详细资料移入references/。

5. 高风险校验尽量脚本化
   尤其是格式检查、参数校验、质量检查。

6. 优先做触发测试和功能测试
   先保证“能在对的时候触发、触发后能跑通”。

7. 关注 undertriggering / overtriggering 信号
   这两类问题几乎是所有 Skill 迭代的主轴。

8. 把 Skill 当产品维护，而不是一次性交付
   收集反馈、修描述、补错误处理、更新版本。

十七、总结

这份指南最有价值的地方，不在于告诉你一个“Skill 文件夹该怎么摆”，而在于它清楚定义了 Skill 的产品思维：

• 它是一个可复用能力单元
• 它以触发机制为入口
• 以结构化说明为核心
• 以渐进式加载控制复杂度
• 以测试和迭代保障质量
• 以分发和共享实现规模化价值

如果只用一句话概括：

Skill 的本质，是把零散经验、专业方法和工具使用策略，沉淀成 Claude 可以稳定调用的工作能力。

对于个人，它意味着更少重复说明；对于团队，它意味着更一致的 AI 协作方式；对于 MCP 生态，它意味着从“接上能力”升级到“真正把能力用起来”。

如果你后续要基于这份指南自己设计 Skill，最值得优先记住的三个关键词是：

• 触发准确
• 说明具体
• 迭代持续

这三点，基本决定了一个 Skill 最终是否真正好用。