构建 Claude Skill 的完整指南｜Anthropic

Created time

May 20, 2026 06:32 AM

引言：什么是 Skill，为什么它很重要

Skill 是一个文件夹——里面装着一组指令，用来教 Claude 如何处理某类特定的任务或工作流。它是把 Claude 定制成你专属助手的最强方式之一。

与其每次对话都重新解释你的偏好、流程和领域知识，不如把它们一次性教给 Claude，然后永远受益。

Skill 特别适合这些场景：

根据规格文档生成前端设计

用一致的方法论开展研究

按团队风格指南撰写文档

编排多步骤流程

它能很好地配合 Claude 的内建能力，比如代码执行和文档生成。如果你正在做 MCP 集成，Skill 会是另一个强大的能力层——把原始的工具访问能力转化为可靠且优化的工作流。

这份指南覆盖什么？

你会学到：

Skill 结构的技术要求与最佳实践

独立 Skill 与 MCP 增强型 Skill 的模式

在不同用例中行之有效的模式

如何测试、迭代和分发你的 Skill

适合谁读：

希望 Claude 始终如一地执行特定流程的开发者

想让 Claude 跟随特定流程的高阶用户

希望在组织内部标准化 Claude 使用方式的团队

两条阅读路径

想做独立 Skill？重点看「基础概念」「规划与设计」以及类别 1-2。

想给 MCP 集成做增强？「Skills + MCP」小节和类别 3 是为你准备的。

两条路径共享同样的技术要求，按需取舍即可。

⏱️

预期收益：读完这份指南，你能够在一次坐下来的时间内完成一个可工作的 Skill。借助 skill-creator，构建并测试第一个 Skill 通常只需 15-30 分钟。

一、基础概念（Fundamentals）

Skill 是什么样的文件夹？

一个 Skill 文件夹通常包含：

SKILL.md（必需）：带 YAML frontmatter 的 Markdown 指令文件

scripts/（可选）：可执行代码（Python、Bash 等）

references/（可选）：按需加载的参考文档

assets/（可选）：模板、字体、图标等输出资源

三大核心设计原则

Skill 采用三层加载机制，让 Claude 在不浪费上下文的前提下保留专业能力：

第一层（YAML frontmatter）：始终加载进 Claude 的系统提示。给出最少的信息，让 Claude 判断何时调用这个 Skill，但不加载具体内容。

第二层（SKILL.md 正文）：当 Claude 认为这个 Skill 与当前任务相关时才加载，包含完整指令和指导。

第三层（链接文件）：Skill 目录里的额外文件，只有 Claude 真正需要时才会去查阅。

这种设计最小化了 token 消耗，同时保留了专业能力。

Claude 可以同时加载多个 Skill。你的 Skill 应当与其他 Skill 友好共存，而不是假设自己是唯一的能力来源。

Skill 在 Claude.ai、Claude Code 和 API 上的运行方式是一致的。一次创建，多处使用——前提是运行环境支持 Skill 所依赖的资源。

给 MCP 构建者：Skill + Connector 的协同

💡

如果你只是想做独立 Skill，可以跳到「规划与设计」章节，之后再回来。

如果你已经有一个能跑的 MCP server，最难的工作已经完成。Skill 是叠加在它之上的知识层——把你已经掌握的工作流和最佳实践显式化，让 Claude 能稳定复用。

MCP 提供的是专业厨房：访问工具、食材和设备的能力。

Skill 提供的是菜谱：一步步告诉你如何做出有价值的成品。

两者结合，用户不必自己摸索每一步就能完成复杂任务。

MCP（连接性）	Skill（知识性）
把 Claude 连接到你的服务（Notion、Asana、Linear 等）	教 Claude 如何有效地使用你的服务
提供实时数据访问与工具调用	沉淀工作流与最佳实践
Claude 能做什么	Claude 应该怎么做

没有 Skill 时：

用户连上你的 MCP 后，不知道下一步该做什么

大量「怎么用你这个集成做 X」的工单涌入

每次对话都从零开始

不同用户的 prompt 不同，结果不一致

问题其实是「缺少工作流指引」，用户却以为是连接器有 bug

有 Skill 后：

预制工作流在需要时自动激活

工具调用稳定可靠

每次交互都内嵌最佳实践

你的集成学习曲线更平缓

二、规划与设计（Planning and Design）

从用例出发

动手写代码之前，先明确 2-3 个具体用例。

一个好的用例定义长这样：

问自己几个问题：

用户想完成什么？

这需要哪些多步工作流？

需要哪些工具（内建？还是 MCP？）

应该内嵌哪些领域知识或最佳实践？

三种最常见的 Skill 用例类型

Anthropic 团队总结了三种最常见的 Skill 形态：

用途：生成一致、高质量的输出，比如文档、PPT、应用、设计稿、代码等。

真实例子：frontend-design Skill（以及 docx、pptx、xlsx、ppt 系列 Skill）。

「创建独特、达到生产级品质的前端界面。在构建 Web 组件、页面、artifact、海报或应用时使用。」

核心技巧：

内嵌风格指南与品牌规范

用模板结构保证一致性

在收尾前过一遍质量清单

不依赖外部工具，纯靠 Claude 内建能力

用途：需要稳定方法论的多步流程，包括跨多个 MCP server 的协调。

真实例子：skill-creator Skill。

「创建新 Skill 的交互式向导。带用户走完用例定义、frontmatter 生成、指令撰写和校验的全过程。」

核心技巧：

带校验门的分步流程

常见结构的模板

内建的复审与改进建议

迭代式精炼循环

用途：为 MCP server 提供的工具访问能力补充工作流指引。

真实例子：Sentry 出品的 sentry-code-review Skill。

「通过 Sentry MCP 接入错误监控数据，自动分析并修复 GitHub Pull Request 中检测到的 bug。」

核心技巧：

按顺序协调多次 MCP 调用

内嵌领域专业知识

提供用户原本需要自己说明的上下文

处理常见的 MCP 错误

定义成功标准

你怎么知道 Skill 跑通了？

📏

这些是目标参照，不是精确门槛。可以追求严谨，但也得接受其中存在「凭感觉评估」的部分。Anthropic 正在持续完善更严格的衡量方法与工具。

Skill 在 90% 的相关查询上正确触发

测量方式：跑 10-20 个应该触发的测试 query，看自动加载 vs. 需要显式调用的比例。

完成工作流的工具调用数控制在 X 次以内

测量方式：开启 vs. 关闭 Skill，对同一任务计数。比较 tool call 数与 token 消耗。

每个工作流 0 次失败的 API 调用

测量方式：监控测试期间的 MCP server 日志，跟踪重试率和错误码。

用户不需要提示 Claude「下一步该做什么」

评估方式：测试中记录你需要纠偏或澄清的次数；找种子用户收集反馈。

工作流无需用户修正即可完成

评估方式：同一请求跑 3-5 次，比较结构一致性与质量。

不同会话间结果稳定

评估方式：一个新用户能否在最少指导下一次成功？

技术要求

SKILL.md 命名：

必须严格叫 SKILL.md（大小写敏感）

SKILL.MD、skill.md 等变体都不接受

Skill 文件夹命名：

✅ 使用 kebab-case：notion-project-setup

❌ 不能有空格：Notion Project Setup

❌ 不能用下划线：notion_project_setup

❌ 不能用大写：NotionProjectSetup

不要放 README.md：

Skill 文件夹内部不要包含 README.md

所有文档放进 SKILL.md 或 references/

注意：如果通过 GitHub 分发，仓库根目录仍然需要一个面向人类访问者的 README——见「分发与分享」章节。

YAML frontmatter：最重要的部分

YAML frontmatter 决定了 Claude 何时加载你的 Skill。务必写对。

这就是起步所需的全部。

name（必需）：

只能用 kebab-case

不能有空格或大写

应与文件夹名一致

description（必需）：

必须同时包含：

这个 Skill 做什么
何时使用它（触发条件）

控制在 1024 字符以内

禁止 XML 标签（< 或 >）

包含用户可能说出的具体短语

涉及文件类型时要点明

license（可选）：

适用于开源 Skill

常见值：MIT、Apache-2.0

compatibility（可选）：

1-500 字符

标明环境需求：目标产品、依赖的系统包、是否需要联网等

metadata（可选）：

任意自定义键值对

推荐字段：author、version、mcp-server

示例：

frontmatter 中禁止：

XML 尖括号（< >）

名字含 claude 或 anthropic 的 Skill（保留字）

原因：frontmatter 会进入 Claude 的系统提示，恶意内容可能注入指令。

编写有效的 Skill

Anthropic 工程博客指出：「这段 metadata……提供刚好够用的信息，让 Claude 知道何时该调用每个 Skill，而无需把全部内容塞进上下文。」这正是渐进式披露的第一层。

推荐结构：

好的描述示例：

反面教材：

frontmatter 之后，用 Markdown 写正式的指令。下面是一个可以直接套用的模板：

python scripts/fetch_data.py --project-id PROJECT_ID

具体且可执行

✅ 好：

❌ 差：

包含错误处理

清晰引用打包资源

用好渐进式披露

SKILL.md 只保留核心指令，详细文档放进 references/ 并链接过去。

三、测试与迭代（Testing and Iteration）

按需求程度，Skill 的测试可以从轻到重分几个层级：

在 Claude.ai 手动测试：直接发 query，观察行为。零成本、迭代快。

在 Claude Code 做脚本化测试：自动化测试用例，每次改动都可复现。

通过 Skills API 做程序化测试：构建评测套件，对一组定义好的测试集批量跑。

选哪种取决于你的质量要求和 Skill 的可见度——小团队内部用的 Skill 和服务千万企业用户的 Skill，测试投入完全不同。

💡

经验之谈：在扩展之前，先在单个任务上死磕。

最有效的 Skill 作者通常会在一个有挑战性的任务上反复迭代，直到 Claude 跑成功，再把胜出的方案抽象成 Skill。这样既能利用 Claude 的上下文内学习能力，反馈也比泛泛测试更快。等基础打牢，再扩展到多用例覆盖。

使用 `skill-creator` Skill

skill-creator 在 Claude.ai 的插件目录中可以拿到，Claude Code 也能下载安装。它能在一次会话内帮你构建并测试一个可工作的 Skill——前提是你已经有 MCP server 并清楚自己最关心的 2-3 个工作流。通常需要 15-30 分钟。

它能做什么：

创建 Skill：从自然语言描述生成 Skill，产出符合规范的 SKILL.md，并推荐触发短语与结构。

复审 Skill：识别常见问题（描述太模糊、缺触发词、结构问题），评估过/欠触发风险，基于声明目的建议测试用例。

迭代改进：遇到边界情况或失败后，把案例带回去，让 skill-creator 帮你针对性优化。

使用方式：

ℹ️

skill-creator 只帮你设计与精炼 Skill，不会跑自动化测试套件或产出量化评估结果。

基于反馈持续迭代

Skill 是活文档，要根据信号不断调整。

欠触发（Undertriggering）信号：

该加载时没加载

用户在手动启用

收到「什么时候用这个 Skill」的提问

解决方案：在 description 中增加细节与差异化描述，尤其是技术术语的关键词。

过触发（Overtriggering）信号：

在不相关 query 上也加载

用户在主动禁用它

用户搞不清它到底干嘛的

解决方案：加入「反向触发」，让范围更具体。

执行问题：

结果不稳定

API 调用失败

用户需要不断纠正

解决方案：改进指令、补充错误处理。

四、分发与分享（Distribution and Sharing）

Skill 让你的 MCP 集成「更完整」。当用户比较连接器时，带 Skill 的连接器能更快带来价值，相比纯 MCP 方案有明显优势。

当前的分发模型（2026 年 1 月）

个人用户如何获取 Skill：

下载 Skill 文件夹

必要时打包成 zip

在 Claude.ai 中通过 Settings > Capabilities > Skills 上传

或放进 Claude Code 的 skills 目录

组织级 Skill：

管理员可在工作区范围内统一部署（2025 年 12 月 18 日上线）

支持自动更新

集中化管理

一个开放标准

Anthropic 已经把 Agent Skills 作为开放标准发布。和 MCP 一样，他们认为 Skill 应当跨工具、跨平台可移植——同一个 Skill 应当能在 Claude 与其他 AI 平台之间通用。

当然，部分 Skill 会专门利用某平台特定能力，作者可以在 compatibility 字段里说明。Anthropic 正与生态伙伴合作推进这一标准，早期采用情况令人鼓舞。

通过 API 使用 Skill

面向程序化使用（应用、Agent、自动化工作流），API 提供了对 Skill 管理与执行的直接控制：

/v1/skills 端点：列举与管理 Skill

在 Messages API 请求中通过 container.skills 参数挂载 Skill

在 Claude Console 做版本管理

与 Claude Agent SDK 配合构建自定义 Agent

何时用 API vs. Claude.ai？

使用场景	推荐入口
终端用户直接使用 Skill	Claude.ai / Claude Code
开发过程中的手动测试与迭代	Claude.ai / Claude Code
个人临时性的一次性工作流	Claude.ai / Claude Code
程序化使用 Skill 的应用	API
大规模生产部署	API
自动化流水线与 Agent 系统	API

📌

API 中的 Skill 依赖 Code Execution Tool beta——它提供 Skill 运行所需的安全沙箱。

现阶段推荐的分发方式

托管在 GitHub

公开仓库

清晰的 README（面向人类——和 Skill 文件夹内禁止的那个 README.md 是两回事）

示例与截图

在 MCP 仓库中链接 Skill

在 MCP 文档中指向你的 Skill

说明组合使用的价值

提供快速上手指南

写一份安装指南

如何描述你的 Skill

描述方式直接决定了用户会不会去试。

聚焦结果，而不是功能：

✅ 好：

「ProjectHub Skill 让团队在几秒钟内就能搭起一个完整的项目空间——包含页面、数据库、模板——而不是花 30 分钟手动配置。」

❌ 差：

「ProjectHub Skill 是一个文件夹，包含 YAML frontmatter 和 Markdown 指令，调用我们的 MCP server 工具。」

讲好「MCP + Skill」组合的故事：

「我们的 MCP server 让 Claude 能访问你的 Linear 项目；我们的 Skill 教 Claude 团队的 Sprint 规划方法。两者结合，让 AI 真正胜任项目管理。」

五、常见模式与排错（Patterns & Troubleshooting）

以下模式来自早期采用者与 Anthropic 内部团队的实践沉淀，是已被验证好用的常见做法，而非硬性模板。

选择思路：以问题为中心 vs. 以工具为中心

把它想象成逛 Home Depot 五金店——

你可以带着问题进门：「我要修橱柜」→ 店员会给你推荐合适的工具；

也可以先选了工具：「我有了一把新电钻」→ 然后问怎么用在你的场景。

Skill 也一样：

问题驱动：「我要搭建一个项目空间」→ Skill 帮你按正确顺序协调一堆 MCP 调用。用户描述结果，Skill 处理工具。

工具驱动：「我已经接好了 Notion MCP」→ Skill 教 Claude 该如何高效使用它。用户有访问权，Skill 提供专业知识。

多数 Skill 会偏向其中一种。先明确自己的定位，再选下面对应的模式。

模式 1：顺序工作流编排

何时用：用户的多步流程必须按特定顺序执行。

示例结构：

核心技巧：

显式声明步骤顺序

表明步骤间的依赖关系

每一步都做校验

提供失败回滚指引

模式 2：多 MCP 协同

何时用：工作流横跨多个服务。

示例：设计到开发交付

核心技巧：

清晰划分阶段

MCP 之间的数据传递

进入下一阶段前先校验

集中处理错误

模式 3：迭代式精炼

何时用：输出质量随迭代而提升。

示例：报告生成

核心技巧：

明确的质量准则

迭代式改进

校验脚本兜底

知道什么时候该停

模式 4：上下文感知的工具选择

何时用：目标相同，但根据上下文要选不同工具。

示例：文件存储

核心技巧：

清晰的决策准则

备选方案兜底

对选择保持透明

模式 5：领域专属智能

何时用：Skill 在工具访问之外，额外注入专业领域知识。

示例：金融合规

核心技巧：

领域知识嵌入逻辑

行动前先做合规

完整的文档留痕

清晰的治理路径

排错（Troubleshooting）

错误：「Could not find SKILL.md in uploaded folder」

原因：文件名不严格等于 SKILL.md

解决：改名为 SKILL.md（大小写敏感）；用 ls -la 确认

错误：「Invalid frontmatter」

原因：YAML 格式错误

常见错误：

错误：「Invalid skill name」

原因：名字含空格或大写

症状：永远不自动加载。

修复：调整 description 字段。快速自检：

是不是太泛？（「Helps with projects」根本不行）

有没有包含用户真的会说的触发短语？

涉及的文件类型有没有点明？

调试技巧：问 Claude「你什么时候会用 [skill name] 这个 Skill？」Claude 会复述 description，根据回答补充缺失信息。

症状：在无关 query 上也加载。

解决方案：

加入反向触发：

更具体：

限定范围：

症状：Skill 加载了，但 MCP 调用失败。

自查清单：

MCP server 是否连上：Claude.ai > Settings > Extensions > 对应服务，状态应为「Connected」

认证：API key 是否有效、权限是否足够、OAuth token 是否刷新过

独立测试 MCP：让 Claude 不走 Skill 直接调用 MCP，「Use [Service] MCP to fetch my projects」。如果直接调用也失败，那是 MCP 的问题而不是 Skill 的。

工具名一致性：Skill 引用的 MCP 工具名是否正确、大小写是否一致

症状：Skill 加载了，但 Claude 不按指令做。

常见原因：

指令太啰嗦

保持简洁

用列表代替长段落

详细参考挪到独立文件

指令被埋没

关键指令放最上面

用 ## Important 或 ## Critical 这样的标题

必要时重复关键点

语言模糊

⚙️

进阶技巧：对于关键校验，优先用代码而不是自然语言。代码是确定的，自然语言不是。Office 系列 Skill 中有这种模式的示例。

模型「偷懒」：可以追加显式鼓励：

注：这种话放在用户 prompt 中比放在 SKILL.md 中效果更好。

症状：响应变慢或质量下降。

原因：

Skill 内容本身过大

同时启用太多 Skill

没用渐进式披露，全量加载

解决方案：

精简 SKILL.md

详细文档挪进 references/

用链接代替内嵌

控制在 5,000 字以内

减少启用的 Skill 数量

同时启用 20-50 个以上就该重审了

推荐选择性启用

考虑把相关能力打包成 Skill 「pack」

六、资源与参考（Resources & References）

官方文档

Anthropic 资源：

Best Practices Guide

Skills Documentation

API Reference

MCP Documentation

博客文章：

Introducing Agent Skills

Engineering Blog: Equipping Agents for the Real World

Skills Explained

How to Create Skills for Claude

Building Skills for Claude Code

Improving Frontend Design through Skills

示例 Skill 仓库

GitHub：anthropics/skills，包含 Anthropic 出品的可定制 Skill

工具

skill-creator Skill：Claude.ai 内建，Claude Code 可下载；能从描述生成 Skill，复审并提建议

验证：可让它复审你的 Skill 并给出改进建议（「Review this skill and suggest improvements」）

获取支持

技术问题：Claude Developers Discord 社区论坛

Bug 反馈：GitHub Issues 提交到 anthropics/skills/issues，附 Skill 名、报错信息、复现步骤

附录 A：上线前后的快速检查清单

用它来验证你的 Skill。也可以先用 skill-creator 生成初稿，再走一遍清单查漏补缺。

开始前

明确了 2-3 个具体用例

工具方案确认（内建 or MCP）

看过本指南和示例 Skill

规划好文件夹结构

开发中

文件夹用 kebab-case 命名

SKILL.md 文件存在（拼写完全正确）

YAML frontmatter 有 --- 分隔符

name 字段：kebab-case、无空格、无大写

description 包含「做什么」和「何时用」

无 XML 标签（< >）

指令清晰可操作

包含错误处理

提供了示例

引用资源链接清晰

上传前

在显式任务上跑过触发测试

在改写后的请求上跑过触发测试

在无关 query 上验证不触发

功能测试通过

工具集成可用（如适用）

已压缩为 zip 文件

上传后

在真实对话中测试

监控过/欠触发情况

收集用户反馈

迭代 description 和指令

更新 metadata 中的版本号

附录 B：YAML frontmatter 速查

必填字段：

所有可选字段：

安全说明：

允许：任何标准 YAML 类型（字符串、数字、布尔值、列表、对象）、自定义 metadata、最长 1024 字符的描述

禁止：XML 尖括号、YAML 中的代码执行、含 claude / anthropic 前缀的 Skill 名（保留字）

附录 C：完整 Skill 示例

生产级、可直接借鉴的示例：

Document Skills：PDF、DOCX、PPTX、XLSX 文档生成

Example Skills：覆盖各种工作流模式

Partner Skills Directory：Asana、Atlassian、Canva、Figma、Sentry、Zapier 等合作伙伴的 Skill

这些仓库会持续更新，包含比本指南更丰富的示例。直接 clone、改造、当模板用即可。

🪧

写在最后：Skill 是 Claude 生态中最值得长期投资的能力之一——它让你的偏好、流程、领域知识从「每次都要解释一遍」变成「教一次，永远受用」。配合 MCP，它把工具访问转化为可靠的工作流。从一个小用例开始，跑通一个真实任务，再慢慢扩展，你会很快感受到这一层抽象带来的复利。