[译] 为 Claude 构建 Skills 完全指南译自：The Complete Guide to Building

译自：The Complete Guide to Building Skills for Claude（33 页 PDF）

引言

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/（可选）：输出中使用的模板、字体、图标

核心设计原则

渐进式披露（Progressive Disclosure）

Skills 使用三级系统：

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

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

可组合性（Composability）

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

可移植性（Portability）

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 时：

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

第二章：规划与设计

从用例开始

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

好的用例定义：

Use Case: 项目 Sprint 规划
Trigger: 用户说 "help me plan this sprint" 或 "create sprint tasks"
Steps:
  1. 通过 MCP 从 Linear 获取当前项目状态
  2. 分析团队速度和产能
  3. 建议任务优先级排序
  4. 在 Linear 中创建带有正确标签和估算的任务
Result: 完成 sprint 规划并创建任务

问问自己：

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

常见 skill 用例类别

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

类别 1：文档和资产创建

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

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

"创建独特的、生产级的前端界面，具有高设计质量。用于构建 web 组件、页面、artifacts、海报或应用程序。"

关键技术：

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

类别 2：工作流自动化

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

真实案例：skill-creator skill

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

关键技术：

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

类别 3：MCP 增强

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

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

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

关键技术：

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

定义成功标准

你如何知道你的 skill 正在工作？

这些是期望目标——粗略的基准而非精确的阈值。追求严谨，但接受会有基于直觉评估的成分。我们正在积极开发更强大的测量指导和工具。

定量指标：

Skill 在 90% 的相关查询上触发
- 如何衡量： 运行 10-20 个应该触发你的 skill 的测试查询。跟踪它自动加载的次数与需要显式调用的次数。
在 X 次工具调用中完成工作流
- 如何衡量： 比较启用和未启用 skill 时的相同任务。计算工具调用次数和消耗的总 token 数。
每个工作流 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: What it does. Use when user asks to [specific phrases].
---

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

字段要求

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 示例：

# 好 - 具体且可操作
description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".

# 好 - 包含触发短语
description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets".

# 好 - 清晰的价值主张
description: End-to-end customer onboarding workflow for PayFlow. Handles account creation, payment setup, and subscription management. Use when user says "onboard new customer", "set up subscription", or "create PayFlow account".

差的 description 示例：

# 太模糊
description: Helps with projects.

# 缺少触发条件
description: Creates sophisticated multi-page documentation systems.

# 太技术化，没有用户触发条件
description: Implements the Project entity model with hierarchical relationships.

编写主体指令

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

推荐结构：

根据你的 skill 调整此模板。用你的具体内容替换方括号中的部分。

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

# 你的 Skill 名称

## 指令

### 步骤 1：[第一个主要步骤]
清晰解释会发生什么。

示例：
```bash
python scripts/fetch_data.py --project-id PROJECT_ID
预期输出：[描述成功的样子]

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

示例

示例 1：[常见场景]

用户说："Set up a new marketing campaign"

操作：

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

结果：活动已创建并附有确认链接

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

故障排除

错误：[常见错误消息]

原因： [为什么会发生] 解决方案： [如何修复]

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


### 指令编写的最佳实践

#### 具体且可操作

✅ **好：**

运行 python scripts/validate.py --input {filename} 检查数据格式。如果验证失败，常见问题包括：

缺少必需字段（将其添加到 CSV 中）
无效的日期格式（使用 YYYY-MM-DD）


❌ **差：**

在继续之前验证数据。


#### 包含错误处理

```markdown
## 常见问题

### MCP 连接失败
如果看到 "Connection refused"：
1. 验证 MCP 服务器是否正在运行：检查 Settings > Extensions
2. 确认 API 密钥有效
3. 尝试重新连接：Settings > Extensions > [Your Service] > Reconnect

清晰引用捆绑资源

在编写查询之前，查阅 `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
示例："Use the issues & solution identified in this chat to improve how the skill handles [specific edge case]"

使用方法：

"Use the skill-creator skill to help me build a skill for [your use case]"

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

基于反馈的迭代

Skills 是活文档。计划基于以下方面进行迭代：

触发不足信号：

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

解决方案： 在 description 中添加更多细节和细微差别——这可能包括关键词，特别是技术术语

过度触发信号：

Skill 对无关查询加载
用户禁用它
对用途的困惑

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

执行问题：

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

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

第四章：分发与共享

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

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

个人用户如何获取 skills：

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

组织级 skills：

管理员可以在整个工作空间部署 skills（2025 年 12 月 18 日发布）
自动更新
集中管理

开放标准

我们已将 Agent Skills 发布为开放标准。与 MCP 一样，我们相信 skills 应该可以跨工具和平台移植——无论你使用 Claude 还是其他 AI 平台，同一个 skill 都应该可以工作。话虽如此，有些 skills 是为充分利用特定平台的功能而设计的；作者可以在 skill 的 compatibility 字段中注明这一点。我们一直在与生态系统中的成员合作制定该标准，我们对早期采用感到兴奋。

通过 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 需要 Code Execution Tool beta，它提供了 skills 运行所需的安全环境。

有关实现细节，请参阅：

当前推荐方法

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

1. 在 GitHub 上托管

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

2. 在你的 MCP 仓库中记录

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

3. 创建安装指南

## 安装 [Your Service] skill

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

2. 在 Claude 中安装：
   - 打开 Claude.ai > Settings > skills
   - 点击 "Upload skill"
   - 选择 skill 文件夹（已压缩）

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

4. 测试：
   - 向 Claude 提问："Set up a new project in [Your Service]"

定位你的 skill

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

聚焦于结果，而非特性：

✅ 好：

"ProjectHub skill 让团队能在几秒钟内搭建完整的项目工作空间——
包括页面、数据库和模板——而不是花 30 分钟手动设置。"

❌ 差：

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

突出 MCP + skills 的故事：

"我们的 MCP 服务器让 Claude 可以访问你的 Linear 项目。
我们的 skills 教会 Claude 你团队的 sprint 规划工作流。
两者结合，实现 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. 记录合规决策

### 处理
IF 合规通过：
    - 调用支付处理 MCP 工具
    - 应用适当的欺诈检查
    - 处理交易
ELSE：
    - 标记为待审查
    - 创建合规案例

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

关键技术：

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

故障排除

Skill 无法上传

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

原因： 文件未精确命名为 SKILL.md

解决方案：

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

错误："Invalid frontmatter"

原因： YAML 格式问题

常见错误：

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

# 错误 - 未关闭的引号
name: my-skill
description: "Does things

# 正确
---
name: my-skill
description: Does things
---

错误："Invalid skill name"

原因： 名称包含空格或大写

# 错误
name: My Cool Skill

# 正确
name: my-cool-skill

Skill 不触发

症状： Skill 从不自动加载

修复方法：

修改你的 description 字段。参见"description 字段"部分了解好/差的示例。

快速检查清单：

是否太笼统？（"Helps with projects" 不会起作用）
是否包含用户实际会说的触发短语？
如果适用，是否提及了相关文件类型？

调试方法：

询问 Claude："When would you use the [skill name] skill?" Claude 会引用 description 回答。根据缺少的内容进行调整。

Skill 触发过于频繁

症状： Skill 对无关查询加载

解决方案：

1. 添加负面触发条件

description: Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration (use data-viz skill instead).

2. 更加具体

# 太宽泛
description: Processes documents

# 更具体
description: Processes PDF legal documents for contract review

3. 明确范围

description: PayFlow payment processing for e-commerce. Use specifically for online payment workflows, not for general financial queries.

MCP 连接问题

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

检查清单：

验证 MCP 服务器已连接
- Claude.ai：Settings > Extensions > [Your Service]
- 应该显示 "Connected" 状态
检查身份验证
- API 密钥有效且未过期
- 已授予适当的权限/范围
- OAuth token 已刷新
独立测试 MCP
- 要求 Claude 直接调用 MCP（不使用 skill）
- "Use [Service] MCP to fetch my projects"
- 如果这失败了，问题在 MCP 而非 skill
验证工具名称
- Skill 引用了正确的 MCP 工具名称
- 查看 MCP 服务器文档
- 工具名称区分大小写

指令未被遵循

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

常见原因：

1. 指令过于冗长

保持指令简洁
使用项目符号和编号列表
将详细参考移至单独文件

2. 指令被埋没

将关键指令放在顶部
使用 ## Important 或 ## Critical 标题
如有需要重复关键点

3. 模糊的语言

# 差
确保正确验证内容

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

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

4. 模型"偷懒" 添加明确的鼓励：

## 性能注意事项
- 花时间彻底完成此任务
- 质量比速度更重要
- 不要跳过验证步骤

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

大上下文问题

症状： Skill 似乎缓慢或响应质量下降

原因：

Skill 内容过大
同时启用的 skills 过多
所有内容都被加载而非渐进式披露

解决方案：

1. 优化 SKILL.md 大小

将详细文档移至 references/
链接到引用而非内联
保持 SKILL.md 在 5,000 词以下

2. 减少启用的 skills

评估是否同时启用了超过 20-50 个 skills
建议选择性启用
考虑为相关功能创建 skill "包"

第六章：资源与参考

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

官方文档

Anthropic 资源：

Best Practices Guide（最佳实践指南）
Skills Documentation（Skills 文档）
API Reference（API 参考）
MCP Documentation（MCP 文档）

博客文章：

示例 skills

公共 skills 仓库：

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

工具与实用程序

skill-creator skill：

内置于 Claude.ai 并可用于 Claude Code
可以从描述生成 skills
审查并提供建议
使用："Help me build a skill using skill-creator"

验证：

skill-creator 可以评估你的 skills
询问："Review this skill and suggest improvements"

获取支持

技术问题：

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

Bug 报告：

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

附录 A：快速检查清单

使用此清单在上传前后验证你的 skill。如果你想更快开始，使用 skill-creator skill 生成你的初稿，然后浏览此列表确保没有遗漏。

开始之前

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

开发期间

上传之前

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

上传之后

附录 B：YAML frontmatter

必需字段

---
name: skill-name-in-kebab-case
description: What it does and when to use it. Include specific trigger phrases.
---

所有可选字段

name: skill-name
description: [required description]
license: MIT # Optional: License for open-source
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" # Optional: Restrict tool access
metadata: # Optional: Custom fields
    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 类型（字符串、数字、布尔值、列表、对象）
自定义 metadata 字段
长 description（最多 1024 个字符）

禁止的：

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

附录 C：完整 skill 示例

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

Document Skills - PDF、DOCX、PPTX、XLSX 创建
Example Skills - 各种工作流模式
Partner Skills Directory - 查看来自 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等合作伙伴的 skills

这些仓库保持更新，并包含超出此处涵盖范围的额外示例。克隆它们，根据你的用例修改它们，并将它们用作模板。

[译] 为 Claude 构建 Skills 完全指南

引言

你将学到什么：

适用人群：

本指南的两条路径

第一章：基础知识

什么是 skill？

核心设计原则

渐进式披露（Progressive Disclosure）

可组合性（Composability）

可移植性（Portability）

面向 MCP 构建者：Skills + 连接器

厨房类比

它们如何协同工作：

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

第二章：规划与设计

从用例开始

常见 skill 用例类别

类别 1：文档和资产创建

类别 2：工作流自动化

类别 3：MCP 增强

定义成功标准

你如何知道你的 skill 正在工作？

技术要求

文件结构

关键规则

YAML frontmatter：最重要的部分

字段要求

安全限制

编写有效的 skills

description 字段

编写主体指令

示例

示例 1：[常见场景]

故障排除

错误：[常见错误消息]

清晰引用捆绑资源

使用渐进式披露

第三章：测试与迭代

推荐的测试方法

1. 触发测试

2. 功能测试

3. 性能比较

使用 skill-creator skill

基于反馈的迭代

第四章：分发与共享

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

开放标准

通过 API 使用 skills

当前推荐方法

定位你的 skill

第五章：模式与故障排除

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

模式 1：顺序工作流编排

模式 2：多 MCP 协调

模式 3：迭代优化

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

模式 5：领域特定智能

故障排除

Skill 无法上传

Skill 不触发

Skill 触发过于频繁

MCP 连接问题

指令未被遵循

大上下文问题

第六章：资源与参考

官方文档

示例 skills

工具与实用程序

获取支持

附录 A：快速检查清单

开始之前

开发期间

上传之前

上传之后

附录 B：YAML frontmatter

必需字段

所有可选字段

安全注意事项

附录 C：完整 skill 示例