03 Claude Skills 完整构建指南

文档摘要

--- title: Claude Skills 完整构建指南 description: 从基础到高级，全面介绍如何为 Claude 构建自定义 Skills，包括设计模式、测试方法和分发策略 date: 2026-01-15 author: Anthropic source: https://docs.anthropic.com/en/docs/build-with-claude/skills category: 03-toolchain-frameworks tags: Claude Skills AI ???


title: Claude Skills 完整构建指南
description: 从基础到高级，全面介绍如何为 Claude 构建自定义 Skills，包括设计模式、测试方法和分发策略
date: 2026-01-15
author: Anthropic
source: https://docs.anthropic.com/en/docs/build-with-claude/skills
category: 03-toolchain-frameworks
tags:
- Claude
- Skills
- AI ???
- MCP
- 工作流

Claude Skills 完整构建指南

作者：Anthropic

原文：查看原文

简介

Skill 是一组指令 ?? 打包为一个简单的文件夹 ?? 教会 Claude 如何处理特定任务或工作流。Skills 是定制 Claude 以满足特定需求的最强大方式之一。无需在每次对话中重新解释你的偏好、流程和领域专业知识，skills 让你只需教一次 Claude，就能每次受益。

当你有可重复的工作流时，Skills 非常强大：从规格生成前端设计、使用一致的方法进行研究、创建遵循团队风格指南的文档，或编排多步骤流程。它们与 Claude 的内置功能（如代码执行和文档创建）配合良好。对于那些构建 MCP 集成的人来说，skills 增加了另一个强大的层，帮助将原始工具访问转化为可靠、优化的工作流。

本指南涵盖了构建有效 skills 所需了解的一切 ?? 从规划和结构到测试和分发。无论你是为自己、团队还是社区构建 skill，你都会在整个过程中找到实用的模式和真实世界的示例。

你将学到什么

Skill 结构的技术要求和最佳实践
独立 skills 和 MCP 增强工作流的模式
我们在不同用例中看到的有效模式
如何测试、迭代和分发你的 skills

适合谁

希望 Claude 始终遵循特定工作流的开发者
希望 Claude 遵循特定工作流的高级用户
希望标准化 Claude 在整个组织中工作方式的团队

本指南的两条路径

构建独立 skills？专注于基础知识、规划与设计以及类别 1-2。增强 MCP 集成？"Skills + MCP" 部分和类别 3 适合你。两条路径共享相同的技术要求，但你可以选择与你的用例相关的内容。

你将从本指南中获得什么：到最后，你将能够在一次会议中构建一个功能性 skill。使用 skill-creator 构建和测试你的第一个工作 skill 预计需要约 15-30 分钟。

让我们开始吧。

基础知识

什么是 Skill？

一个 skill 是一个包含以下内容的文件夹：

SKILL.md（必需）：带有 YAML frontmatter 的 Markdown 指令
scripts/（可选）：可执行代码（Python、Bash 等）
references/（可选）：按需加载的文档
assets/（可选）：输出中使用的模板、字体、图标

核心设计原则

渐进式披露

Skills 使用三级系统：

第一级（YAML frontmatter）：始终加载在 Claude 的系统提示中。提供足够的信息让 Claude 知道何时应该使用每个 skill，而无需将所有内容加载到上下文中。
第二级（SKILL.md 正文）：当 Claude 认为 skill 与当前任务相关时加载。包含完整的指令和指导。
第三级（链接文件）：skill 目录中捆绑的其他文件，Claude 可以选择仅在需要时导航和发现。

这种渐进式披露最小化了 token 使用，同时保持了专业知识。

可组合性

Claude 可以同时加载多个 skills。你的 skill 应该与其他 skills 配合良好，而不是假设它是唯一可用的功能。

可移植性

Skills 在 Claude.ai、Claude Code 和 API 上的工作方式完全相同。创建一次 skill，它就可以在所有平台上工作而无需修改，前提是环境支持 skill 所需的任何依赖项。

对于 MCP 构建者：Skills + 连接器

构建不带 MCP 的独立 skills？跳到规划与设计 ?? 你以后可以随时回到这里。

如果你已经有一个工作的 MCP 服务器，你已经完成了困难的部分。Skills 是顶层的知识层 ?? 捕获你已经知道的工作流和最佳实践，以便 Claude 可以一致地应用它们。

厨房类比

MCP 提供专业厨房：访问工具、食材和设备
Skills 提供食谱：如何创造有价值东西的分步说明

它们一起使用户能够完成复杂的任务，而无需自己弄清楚每一步。

它们如何协同工作

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

为什么这对你的 MCP 用户很重要

没有 skills：

用户连接你的 MCP 但不知道下一步该做什么
支持工单询问"如何使用你的集成做 X"
每次对话都从头开始
结果不一致，因为用户每次提示都不同
用户责怪你的连接器，而真正的问题是工作流指导

有了 skills：

预构建的工作流在需要时自动激活
一致、可靠的工具使用
最佳实践嵌入在每次交互中
降低集成的学习曲线

规划与设计

从用例开始

在编写任何代码之前，确定你的 skill 应该启用的 2-3 个具体用例。

良好的用例定义示例

用例：项目冲刺规划

触发器：用户说"帮我规划这个冲刺"或"创建冲刺任务"
步骤：
1. 从 Linear 获取当前项目状态（通过 MCP）
2. 分析团队速度和容量
3. 建议任务优先级
4. 在 Linear 中创建带有适当标签和估算的任务
结果：完全规划的冲刺，任务已创建

问自己

用户想要完成什么？
这需要哪些多步骤工作流？
需要哪些工具（内置或 MCP）？
应该嵌入哪些领域知识或最佳实践？

常见 Skill 用例类别

在 Anthropic，我们观察到三种常见用例：

类别 1：文档和资产创建

用途：创建一致、高质量的输出，包括文档、演示文稿、应用、设计、代码等。

真实示例：frontend-design skill（另见 docx、pptx、xlsx 和 ppt 的 skills）

"创建具有高设计质量的独特、生产级前端界面。在构建 Web 组件、页面、工件、海报或应用时使用。"

关键技术：

嵌入式风格指南和品牌标准
一致输出的模板结构
最终确定前的质量检查清单
无需外部工具 ?? 使用 Claude 的内置功能

类别 2：工作流自动化

用途：受益于一致方法的多步骤流程，包括跨多个 MCP 服务器的协调。

真实示例：skill-creator skill

"创建新 skills 的交互式指南。引导用户完成用例定义、frontmatter 生成、指令编写和验证。"

关键技术：

带验证门的分步工作流
常见结构的模板
内置审查和改进建议
迭代改进循环

类别 3：MCP 增强

用途：工作流指导，以增强 MCP 服务器提供的工具访问。

真实示例：sentry-code-review skill（来自 Sentry）

"使用 Sentry 的错误监控数据通过其 MCP 服务器自动分析和修复 GitHub Pull Requests 中检测到的错误。"

关键技术：

按顺序协调多个 MCP 调用
嵌入领域专业知识
提供用户否则需要指定的上下文
常见 MCP 问题的错误处理

定义成功标准

如何知道你的 skill 是否有效？

这些是理想目标 ?? 粗略的基准而不是精确的阈值。追求严谨但接受会有基于感觉的评估元素。我们正在积极开发更强大的测量指导和工具。

定量指标

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

如何测量：运行 10-20 个应该触发你的 skill 的测试查询。跟踪它自动加载的次数与需要显式调用的次数。

在 X 次工具调用中完成工作流

如何测量：比较启用和不启用 skill 的相同任务。计算工具调用和消耗的总 tokens。

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

如何测量：在测试运行期间监控 MCP 服务器日志。跟踪重试率和错误代码。

定性指标

用户无需提示 Claude 下一步

如何评估：在测试期间，注意你需要重定向或澄清的频率。向 beta 用户征求反馈。

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

如何评估：运行相同请求 3-5 次。比较输出的结构一致性和质量。

跨会话的一致结果

如何评估：新用户能否在第一次尝试时以最少的指导完成任务？

技术要求

文件结构


your-skill-name/
├── SKILL.md              # 必需 - 主 skill 文件
├── scripts/              # 可选 - 可执行代码
│   ├── process_data.py   # 示例
│   └── validate.sh       # 示例
├── references/           # 可选 - 文档
│   ├── api-guide.md      # 示例
│   └── examples/         # 示例
└── assets/               # 可选 - 模板等
    └── report-template.md # 示例

关键规则

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: your-skill-name
description: ?? skill ????????????????????
---

这就是你开始所需的全部。

字段要求

name（必需）：

仅 kebab-case
无空格或大写
应与文件夹名称匹配

description（必需）：

必须包括两者：
- skill 做什么
- 何时使用它（触发条件）
少于 1024 个字符
无 XML 标签（< 或 >）
包括用户可能说的特定任务
如果相关，提及文件类型

license（可选）：

如果使 skill 开源则使用
常见：MIT、Apache-2.0

compatibility（可选）：

1-500 个字符
指示环境要求：例如预期产品、所需系统包、网络访问需求等

metadata（可选）：

任何自定义键值对
建议：author、version、mcp-server
示例：


metadata:
  author: ProjectHub
  version: 1.0.0
  mcp-server: projecthub

安全限制

Frontmatter 中禁止：

XML 尖括号（< >）
名称中带有"claude"或"anthropic"的 skills（保留）

为什么：Frontmatter 出现在 Claude 的系统提示中。恶意内容可能注入指令。

编写有效的 Skills

Description 字段

根据 Anthropic 的工程博客："这些元数据...提供足够的信息让 Claude 知道何时应该使用每个 skill，而无需将所有内容加载到上下文中。" 这是渐进式披露的第一级。

结构：


[它做什么] + [何时使用它] + [关键功能]

良好描述的示例：

✅ 好 ?? 具体且可操作


description: 分析 Figma 设计文件并生成开发者交接文档。当用户上传 .fig 文件、询问"设计规格"、"组件文档"或"设计到代码交接"时使用。

✅ 好 ?? 包含触发短语


description: 管理 Linear 项目工作流，包括冲刺规划、任务创建和状态跟踪。当用户提到"冲刺"、"Linear 任务"、"项目规划"或要求"创建工单"时使用。

✅ 好 ?? 清晰的价值主张


description: PayFlow 的端到端客户入职工作流。处理账户创建、支付设置和订阅管理。当用户说"入职新客户"、"设置订阅"或"创建 PayFlow 账户"时使用。

不良描述的示例：

❌ 太模糊


description: 帮助处理项目。

❌ 缺少触发器


description: 创建复杂的多页文档系统。

❌ 太技术化，没有用户触发器


description: 实现具有层次关系的 Project 实体模型。

编写主要指令

在 frontmatter 之后，用 Markdown 编写实际指令。

推荐结构：

为你的 skill 调整此模板。用你的特定内容替换括号部分。


---
name: your-skill
description: [???????????]
---

# Your Skill Name

## 指令

### 步骤 1：[第一个主要步骤]

清楚解释发生了什么。

示例：

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

预期输出：[描述成功是什么样子]

步骤 2：[第二个主要步骤]

（根据需要添加更多步骤）

示例

示例 1：[常见场景]

用户说："设置新的营销活动"

操作：

通过 MCP 获取现有活动
使用提供的参数创建新活动

结果：活动已创建，带有确认链接

（根据需要添加更多示例）

故障排除

错误：[常见错误消息]

原因：[为什么会发生]

解决方案：[如何修复]

（根据需要添加更多错误案例）



#### 指令的最佳实践

**具体且可操作**

✅ **好**：
```markdown
运行 `python scripts/validate.py --input {filename}` 检查数据格式。
如果验证失败，常见问题包括：
- 缺少必需字段（将它们添加到 CSV）
- 无效的日期格式（使用 YYYY-MM-DD）

❌ 不好：


在继续之前验证数据。

包含错误处理


## 常见问题

### MCP 连接失败

如果你看到"连接被拒绝"：

1. 验证 MCP 服务器正在运行：检查设置 > 扩展
2. 确认 API 密钥有效
3. 尝试重新连接：设置 > 扩展 > [你的服务] > 重新连接

清楚地引用捆绑资源


在编写查询之前，请查阅 `references/api-patterns.md` 以获取：

- 速率限制指导
- 分页模式
- 错误代码和处理

使用渐进式披露

保持 SKILL.md 专注于核心指令。将详细文档移至 references/ 并链接到它。（有关三级系统如何工作，请参阅核心设计原则。）

测试与迭代

Skills 可以根据你的需求在不同的严格程度上进行测试：

Claude.ai 中的手动测试 - 直接运行查询并观察行为。快速迭代，无需设置。
Claude Code 中的脚本测试 - 自动化测试用例，以便在更改之间进行可重复验证。
通过 skills API 进行程序化测试 - 构建针对定义的测试集系统运行的评估套件。

选择与你的质量要求和 skill 可见性相匹配的方法。小团队内部使用的 skill 与部署给数千企业用户的 skill 有不同的测试需求。

专业提示：在扩展之前迭代单个任务

我们发现最有效的 skill 创建者会迭代单个具有挑战性的任务，直到 Claude 成功，然后将获胜的方法提取到 skill 中。这利用了 Claude 的上下文学习，并提供比广泛测试更快的信号。一旦你有了一个工作基础，就扩展到多个测试用例以获得覆盖率。

使用 skill-creator skill

skill-creator skill - 可通过 Claude.ai 的插件目录获得或下载用于 Claude Code - 可以帮助你构建和迭代 skills。如果你有一个 MCP 服务器并知道你的前 2-3 个工作流，你可以在一次会议中构建和测试一个功能性 skill - 通常在 15-30 分钟内。

创建 skills：

从自然语言描述生成 skills
生成格式正确的带有 frontmatter 的 SKILL.md
建议触发短语和结构

审查 skills：

标记常见问题（模糊描述、缺少触发器、结构问题）
识别潜在的过度/不足触发风险
根据 skill 的既定目的建议测试用例

迭代改进：

使用你的 skill 并遇到边缘情况或失败后，将这些示例带回 skill-creator
示例："使用此聊天中识别的问题和解决方案来改进 skill 如何处理 [特定边缘情况]"

使用方法：


"使用 skill-creator skill 帮我为 [你的用例] 构建一个 skill"

注意：skill-creator 帮助你设计和完善 skills，但不执行自动化测试套件或产生定量评估结果。

基于反馈的迭代

Skills 是活文档。计划根据以下内容进行迭代：

触发不足的信号：

Skill 在应该加载时不加载
用户手动启用它
关于何时使用它的支持问题

解决方案：向描述添加更多细节和细微差别 - 这可能包括关键字，特别是技术术语

过度触发的信号：

Skill 为不相关的查询加载
用户禁用它
对目的感到困惑

解决方案：添加负面触发器，更具体

执行问题：

结果不一致
API 调用失败
需要用户更正

解决方案：改进指令，添加错误处理

分发与共享

Skills 使你的 MCP 集成更加完整。当用户比较连接器时，那些带有 skills 的连接器提供了更快的价值路径，使你比仅 MCP 的替代方案更具优势。

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

个人用户如何获取 skills

下载 skill 文件夹
压缩文件夹（如果需要）
通过设置 > 功能 > Skills 上传到 Claude.ai
或放置在 Claude Code skills 目录中

组织级别的 skills

管理员可以在工作区范围内部署 skills（2025 年 12 月 18 日发布）
自动更新
集中管理

开放标准

我们已将 Agent Skills 发布为开放标准。像 MCP 一样，我们相信 skills 应该可以跨工具和平台移植 - 无论你使用 Claude 还是其他 AI 平台，相同的 skill 都应该有效。也就是说，某些 skills 旨在充分利用特定平台的功能；作者可以在 skill 的兼容性字段中注明这一点。我们一直在与生态系统成员就该标准进行合作，我们对早期采用感到兴奋。

通过 API 使用 skills

对于程序化用例 - 例如构建利用 skills 的应用、代理或自动化工作流 - API 提供对 skill 管理和执行的直接控制。

关键功能：

/v1/skills 端点用于列出和管理 skills
通过 container.skills 参数将 skills 添加到 Messages API 请求
通过 Claude Console 进行版本控制和管理
与 Claude Agent SDK 配合使用以构建自定义代理

何时通过 API 使用 skills 与 Claude.ai：

用例	最佳平台
最终用户直接与 skills 交互	Claude.ai / Claude Code
开发期间的手动测试和迭代	Claude.ai / Claude Code
个人、临时工作流	Claude.ai / Claude Code
以编程方式使用 skills 的应用	API
大规模生产部署	API
自动化管道和代理系统	API

注意：API 中的 Skills 需要代码执行工具 beta，它提供 skills 运行所需的安全环境。

有关实现详细信息，请参阅：

Skills API 快速入门
创建自定义 skills
AI ??? SDK 中的 Skills

今天推荐的方法

首先在 GitHub 上托管你的 skill，使用公共仓库、清晰的 README（供人类访问者使用 - 这与你的 skill 文件夹分开，不应包含 README.md）和带有屏幕截图的示例用法。然后在你的 MCP 文档中添加一个部分，链接到 skill，解释为什么一起使用两者有价值，并提供快速入门指南。

1. 在 GitHub 上托管

开源 skills 的公共仓库
带有安装说明的清晰 README
示例用法和屏幕截图

2. 在你的 MCP 仓库中记录

从 MCP 文档链接到 skills
解释一起使用两者的价值
提供快速入门指南

3. 创建安装指南


## 安装 [你的服务] skill

1. 下载 skill：
   - 克隆仓库：`git clone https://github.com/yourcompany/skills`
   - 或从 Releases 下载 ZIP

2. 在 Claude 中安装：
   - 打开 Claude.ai > 设置 > Skills
   - 点击"上传 skill"
   - 选择 skill 文件夹（压缩）

3. 启用 skill：
   - 打开 [你的服务] skill
   - 确保你的 MCP 服务器已连接

4. 测试：
   - 询问 Claude："在 [你的服务] 中设置一个新项目"

定位你的 skill

你如何描述你的 skill 决定了用户是否理解其价值并实际尝试它。在撰写关于你的 skill 的内容时 - 在你的 README、文档或营销中 - 请记住这些原则。

关注结果，而不是功能

✅ 好：


"ProjectHub skill 使团队能够在几秒钟内设置完整的项目工作区 ?? 包括页面、数据库和模板 ?? 而不是花 30 分钟进行手动设置。"

❌ 不好：


"ProjectHub skill 是一个包含 YAML frontmatter 和 Markdown 指令的文件夹，它调用我们的 MCP 服务器工具。"

突出 MCP + skills 的故事


"我们的 MCP 服务器让 Claude 访问你的 Linear 项目。我们的 skills 教 Claude 你团队的冲刺规划工作流。它们一起实现 AI 驱动的项目管理。"

模式与故障排除

这些模式来自早期采用者和内部团队创建的 skills。它们代表我们看到的有效的常见方法，而不是规定性模板。

选择你的方法：问题优先 vs. 工具优先

把它想象成家得宝。你可能带着一个问题走进去 -"我需要修理厨房橱柜"- 员工会为你指出正确的工具。或者你可能挑选一个新钻头并询问如何将其用于你的特定工作。

Skills 以同样的方式工作：

问题优先："我需要设置一个项目工作区" 你的 skill 以正确的顺序编排正确的 MCP 调用。用户描述结果；skill 处理工具。
工具优先："我已连接 Notion MCP" 你的 skill 教 Claude 最佳工作流和最佳实践。用户有访问权限；skill 提供专业知识。

大多数 skills 倾向于一个方向。知道哪种框架适合你的用例有助于你选择下面的正确模式。

模式 1：顺序工作流编排

使用时机：你的用户需要按特定顺序执行多步骤流程。

示例结构：


## 工作流：入职新客户

### 步骤 1：创建账户

调用 MCP 工具：`create_customer`
参数：name、email、company

### 步骤 2：设置支付

调用 MCP 工具：`setup_payment_method`
等待：支付方式验证

### 步骤 3：创建订阅

调用 MCP 工具：`create_subscription`
参数：plan_id、customer_id（来自步骤 1）

### 步骤 4：发送欢迎邮件

调用 MCP 工具：`send_email`
模板：welcome_email_template

关键技术：

明确的步骤排序
步骤之间的依赖关系
每个阶段的验证
失败的回滚指令

模式 2：多 MCP 协调

使用时机：工作流跨越多个服务。

示例：设计到开发交接


## 阶段 1：设计导出（Figma MCP）

1. 从 Figma 导出设计资产
2. 生成设计规格
3. 创建资产清单

## 阶段 2：资产存储（Drive MCP）

1. 在 Drive 中创建项目文件夹
2. 上传所有资产
3. 生成可共享链接

## 阶段 3：任务创建（Linear MCP）

1. 创建开发任务
2. 将资产链接附加到任务
3. 分配给工程团队

## 阶段 4：通知（Slack MCP）

1. 将交接摘要发布到 #engineering
2. 包括资产链接和任务引用

关键技术：

清晰的阶段分离
MCP 之间的数据传递
移至下一阶段前的验证
集中式错误处理

模式 3：迭代改进

使用时机：输出质量通过迭代改进。

示例：报告生成


## 迭代报告创建

### 初始草稿

1. 通过 MCP 获取数据
2. 生成第一份草稿报告
3. 保存到临时文件

### 质量检查

1. 运行验证脚本：`scripts/check_report.py`
2. 识别问题：
   - 缺少部分
   - 格式不一致
   - 数据验证错误

### 改进循环

1. 解决每个识别的问题
2. 重新生成受影响的部分
3. 重新验证
4. 重复直到达到质量阈值

### 最终确定

1. 应用最终格式
2. 生成摘要
3. 保存最终版本

关键技术：

明确的质量标准
迭代改进
验证脚本
知道何时停止迭代

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

使用时机：相同结果，根据上下文使用不同工具。

示例：文件存储


## 智能文件存储

### 决策树

1. 检查文件类型和大小
2. 确定最佳存储位置：
   - 大文件（>10MB）：使用云存储 MCP
   - 协作文档：使用 Notion/Docs MCP
   - 代码文件：使用 GitHub MCP
   - 临时文件：使用本地存储

### 执行存储

基于决策：

- 调用适当的 MCP 工具
- 应用特定于服务的元数据
- 生成访问链接

### 向用户提供上下文

解释为什么选择该存储

关键技术：

清晰的决策标准
后备选项
选择的透明度

模式 5：领域特定智能

使用时机：你的 skill 添加超越工具访问的专业知识。

示例：金融合规


## 符合合规的支付处理

### 处理前（合规检查）

1. 通过 MCP 获取交易详情
2. 应用合规规则：
   - 检查制裁名单
   - 验证管辖区许可
   - 评估风险级别
3. 记录合规决策

### 处理

如果合规通过：

- 调用支付处理 MCP 工具
- 应用适当的欺诈检查
- 处理交易

否则：

- 标记以供审查
- 创建合规案例

### 审计跟踪

- 记录所有合规检查
- 记录处理决策
- 生成审计报告

关键技术：

逻辑中嵌入的领域专业知识
行动前的合规
全面的文档
清晰的治理

故障排除

Skill 无法上传

错误："在上传的文件夹中找不到 SKILL.md"

原因：文件名不完全是 SKILL.md

解决方案：

重命名为 SKILL.md（区分大小写）
验证：ls -la 应显示 SKILL.md

错误："无效的 frontmatter"

原因：YAML 格式问题

常见错误：


# 错误 ?? 缺少分隔符
name: my-skill
description: ???? skill ?????

# 错误 ?? 未闭合引号
name: my-skill
description: "???? skill ?????

# 正确
---
name: my-skill
description: ???? skill ?????
---

错误："无效的 skill 名称"

原因：名称有空格或大写


# 错误
name: My Cool Skill

# 正确
name: my-cool-skill

Skill 不触发

症状：Skill 从不自动加载

修复：修改你的 description 字段。有关好/坏示例，请参阅 Description 字段。

快速检查清单：

是否太通用？（"帮助处理项目"不起作用）
是否包含用户实际会说的触发短语？
如果适用，是否提及相关文件类型？

调试方法：
询问 Claude："你什么时候会使用 [skill 名称] skill？" Claude 会引用描述。根据缺少的内容进行调整。

Skill 触发过于频繁

症状：Skill 为不相关的查询加载

解决方案：

添加负面触发器


description: CSV 文件的高级数据分析。用于统计建模、回归、聚类。不要用于简单的数据探索（改用 data-viz skill）。

更具体


# 太宽泛
description: 处理文档

# 更具体
description: 处理 PDF 法律文档以进行合同审查

澄清范围


description: 电子商务的 PayFlow 支付处理。专门用于在线支付工作流，而不是一般财务查询。

MCP 连接问题

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

检查清单：

验证 MCP 服务器已连接
- Claude.ai：设置 > 扩展 > [你的服务]
- 应显示"已连接"状态
检查身份验证
- API 密钥有效且未过期
- 授予适当的权限/范围
- OAuth tokens 已刷新
独立测试 MCP
- 要求 Claude 直接调用 MCP（不使用 skill）
- "使用 [服务] MCP 获取我的项目"
- 如果失败，问题在于 MCP 而不是 skill
验证工具名称
- Skill 引用正确的 MCP 工具名称
- 检查 MCP 服务器文档
- 工具名称区分大小写

指令未遵循

症状：Skill 加载但 Claude 不遵循指令

常见原因：

指令过于冗长
- 保持指令简洁
- 使用项目符号和编号列表
- 将详细参考移至单独的文件
指令被埋没
- 将关键指令放在顶部
- 使用 ## 重要或 ## 关键标题
- 如果需要，重复关键点
模糊的语言

❌ 不好


确保正确验证事物

✅ 好


关键：在调用 create_project 之前，验证：
- 项目名称非空
- 至少分配一名团队成员
- 开始日期不在过去

高级技术：对于关键验证，考虑捆绑一个以编程方式执行检查的脚本，而不是依赖语言指令。代码是确定性的；语言解释不是。有关此模式的示例，请参阅 Office skills。

模型"懒惰" 添加明确的鼓励：


## 性能说明

- 花时间彻底完成此操作
- 质量比速度更重要
- 不要跳过验证步骤

注意：将此添加到用户提示比在 SKILL.md 中更有效

大上下文问题

症状：Skill 似乎很慢或响应降级

原因：

Skill 内容太大
同时启用太多 skills
加载所有内容而不是渐进式披露

解决方案：

优化 SKILL.md 大小
- 将详细文档移至 references/
- 链接到引用而不是内联
- 保持 SKILL.md 少于 5,000 字
减少启用的 skills
- 评估是否同时启用了超过 20-50 个 skills
- 建议选择性启用
- 考虑相关功能的 skill"包"

资源与参考

如果你正在构建你的第一个 skill，请从最佳实践指南开始，然后根据需要参考 API 文档。

官方文档

Anthropic 资源：

最佳实践指南
Skills 文档
API 参考
MCP 文档

博客文章：

介绍 Agent Skills
工程博客：为现实世界装备代理
Skills 解释
如何为 Claude 创建 Skills
为 Claude Code 构建 Skills
通过 Skills 改进前端设计

示例 skills

公共 skills 仓库：

GitHub: anthropics/skills
包含你可以自定义的 Anthropic 创建的 skills

工具和实用程序

skill-creator skill：

内置于 Claude.ai 并可用于 Claude Code
可以从描述生成 skills
审查并提供建议
使用："使用 skill-creator 帮我构建一个 skill"

验证：

skill-creator 可以评估你的 skills
询问："审查此 skill 并提出改进建议"

获取支持

技术问题：

一般问题：Claude Developers Discord 的社区论坛

错误报告：

GitHub Issues: anthropics/skills/issues
包括：Skill 名称、错误消息、重现步骤

参考 A：快速检查清单

在上传之前和之后使用此检查清单验证你的 skill。如果你想更快开始，请使用 skill-creator skill 生成你的第一个草稿，然后运行此列表以确保你没有遗漏任何内容。

开始之前

确定了 2-3 个具体用例
确定了工具（内置或 MCP）
审查了本指南和示例 skills
计划了文件夹结构

开发期间

文件夹以 kebab-case 命名
SKILL.md 文件存在（精确拼写）
YAML frontmatter 有 --- 分隔符
name 字段：kebab-case，无空格，无大写
description 包括什么和何时
任何地方都没有 XML 标签（< >）
指令清晰且可操作
包含错误处理
提供了示例
清楚地链接了引用

上传前

在明显任务上测试触发
在改述请求上测试触发
验证不在不相关主题上触发
功能测试通过
工具集成有效（如果适用）
压缩为 .zip 文件

上传后

在真实对话中测试
监控触发不足/过度
收集用户反馈
迭代描述和指令
更新元数据中的版本

参考 B：YAML Frontmatter

必需字段


---
name: skill-name-in-kebab-case
description: ??????????????????????
---

所有可选字段


---
name: skill-name
description: [????????????]
license: MIT # 可选：开源许可证
allowed-tools: 'Bash python:* Bash(npm:*) WebFetch' # 可选：限制工具访问
metadata: # 可选：自定义字段
  author: Company Name
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management?automation]
  documentation: https://example.com/docs
  support: support@example.com
---

安全说明

允许：

任何标准 YAML 类型（字符串、数字、布尔值、列表、对象）
自定义元数据字段
长描述（最多 1024 个字符）

禁止：

XML 尖括号（< >）- 安全限制
YAML 中的代码执行（使用安全 YAML 解析）
以"claude"或"anthropic"前缀命名的 Skills（保留）

参考 C：完整 Skill 示例

有关演示本指南中模式的完整、生产就绪的 skills：

文档 Skills - PDF、DOCX、PPTX、XLSX 创建
示例 Skills - 各种工作流模式
合作伙伴 Skills 目录 - 查看来自 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等各种合作伙伴的 skills

这些仓库保持最新，并包含本文涵盖之外的其他示例。克隆它们，为你的用例修改它们，并将它们用作模板。

原文链接：The Complete Guide to Building Skills for Claude

发布日期：2026 年 1 月

标签：#Claude #Skills #AI智能体 #MCP #工作流自动化

作者与出处

原作者： Datawhale

来源：Datawhale

原文： https://github.com/datawhalechina/vibe-vibe

许可证：CC BY-NC-SA 4.0

整理：灏天文库整理

由灏天文库结构化整理，提供目录导航、全文检索与在线阅读，便于系统化学习

03 Claude Skills 完整构建指南

文档摘要

Claude Skills 完整构建指南

目录

简介

你将学到什么

适合谁

本指南的两条路径

基础知识

什么是 Skill？

核心设计原则

渐进式披露

可组合性

可移植性

对于 MCP 构建者：Skills + 连接器

厨房类比

它们如何协同工作

为什么这对你的 MCP 用户很重要

规划与设计

从用例开始

良好的用例定义示例

问自己

常见 Skill 用例类别

类别 1：文档和资产创建

类别 2：工作流自动化

类别 3：MCP 增强

定义成功标准

如何知道你的 skill 是否有效？

定量指标

定性指标

技术要求

文件结构

关键规则

YAML Frontmatter：最重要的部分

最小必需格式

字段要求

安全限制

编写有效的 Skills

Description 字段

编写主要指令

步骤 2：[第二个主要步骤]

示例

示例 1：[常见场景]

故障排除

错误：[常见错误消息]

测试与迭代

推荐的测试方法

1. 触发测试

2. 功能测试

3. 性能比较

使用 skill-creator skill

基于反馈的迭代

分发与共享

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

个人用户如何获取 skills

组织级别的 skills

开放标准

通过 API 使用 skills

今天推荐的方法

1. 在 GitHub 上托管

2. 在你的 MCP 仓库中记录

3. 创建安装指南

定位你的 skill

关注结果，而不是功能

突出 MCP + skills 的故事

模式与故障排除

选择你的方法：问题优先 vs. 工具优先

模式 1：顺序工作流编排

模式 2：多 MCP 协调

模式 3：迭代改进

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

模式 5：领域特定智能

故障排除

Skill 无法上传

Skill 不触发

Skill 触发过于频繁

MCP 连接问题

指令未遵循

大上下文问题

资源与参考