===== 第 1 页 =====

为 Claude 构建技能的完整指南

===== 第 2 页 =====

3

引言 3
基础 4
规划与设计 7
测试与迭代 14
分发与共享 18
模式与故障排除 21
资源与参考 28

===== 第 3 页 =====

引言

技能（Skill）是一组指令——打包成一个简单的文件夹——用于教导 Claude 如何处理特定的任务或工作流程。技能是根据你的特定需求定制 Claude 的最强大方式之一。你无需在每次对话中重新解释你的偏好、流程和领域专业知识，只需教给 Claude 一次，即可在每次对话中受益。

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

本指南涵盖了构建有效技能所需了解的所有内容——从规划和结构到测试和分发。无论你是为自己、你的团队还是为社区构建技能，你都将在本指南中找到实用的模式和真实世界的例子。

你将学到什么：

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

适用人群：

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

本指南的两种学习路径

构建独立技能？请关注“基础”、“规划与设计”以及第 1-2 类。
增强 MCP 集成？ “技能 + MCP”部分和第 3 类非常适合你。
两种路径共享相同的技术要求，但你可以根据自己的用例选择相关内容。

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

让我们开始吧。

===== 第 4 页 =====

===== 第 5 页 =====

基础

什么是技能？

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

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

核心设计原则

渐进式披露

技能采用三级系统：

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

这种渐进式披露在保持专业技能的同时，最大限度地减少了令牌使用量。

可组合性

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

可移植性

技能在 Claude.ai、Claude Code 和 API 上的工作方式完全相同。只需创建一次技能，只要环境支持该技能所需的任何依赖项，它就可以在所有表面上无需修改地工作。

对于 MCP 构建者：技能 + 连接器

没有 MCP 的情况下构建独立技能？请跳至“规划与设计”——你可以稍后再回到这里。

如果你已经有一个可用的 MCP 服务器，那么最困难的部分已经完成。技能是之上的知识层——捕捉你已经知道的工作流程和最佳实践，以便 Claude 能够一致地应用它们。

厨房类比

  • MCP 提供专业厨房：访问工具、食材和设备。
  • 技能 提供食谱：关于如何创造有价值东西的逐步说明。

===== 第 6 页 =====

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

它们如何协同工作：

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

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

没有技能的情况下：

  • 用户连接了你的 MCP，但不知道下一步该做什么
  • 支持工单询问“如何使用你的集成做 X”
  • 每次对话都从零开始
  • 由于用户每次提示方式不同，导致结果不一致
  • 当真正的问题是工作流程指导时，用户会责怪你的连接器

有了技能：

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

===== 第 7 页 =====

规划与设计

===== 第 8 页 =====

规划与设计

从用例开始

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

好的用例定义：

用例：项目冲刺规划
触发条件：用户说“帮我规划这个冲刺”或“创建冲刺任务”
步骤：

  1. 从 Linear（通过 MCP）获取当前项目状态
  2. 分析团队速度和容量
  3. 建议任务优先级
  4. 在 Linear 中创建带有正确标签和估算的任务
    结果：完整规划的冲刺，并已创建任务

问问自己：

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

常见技能用例类别

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

类别 1：文档与资产创建

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

真实示例：frontend-design 技能（另请参阅 docx、pptx、xlsx 和 ppt 技能）

“创建独特、生产级别的前端界面，具有高设计质量。在构建 Web 组件、页面、 artifacts、海报或应用程序时使用。”

关键技术：

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

===== 第 9 页 =====

类别 2：工作流程自动化

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

真实示例：skill-creator 技能

“用于创建新技能的交互式指南。引导用户完成用例定义、头部生成、指令编写和验证。”

关键技术：

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

类别 3：MCP 增强

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

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

“使用 Sentry 通过其 MCP 服务器提供的错误监控数据，自动分析并修复 GitHub 拉取请求中检测到的错误。”

关键技术：

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

定义成功标准

你如何知道你的技能是否有效？

这些是理想目标——大致的基准，而非精确的阈值。力求严谨，但要接受会存在基于“感觉”评估的成分。我们正在积极开发更强大的测量指导和工具。

定量指标：

  • 技能在 (90%) 的相关查询中被触发
    • 如何测量：运行 10-20 个应该触发你技能的测试查询。跟踪它自动加载的次数与需要显式调用的次数。
  • 在 X 次工具调用内完成工作流程
    • 如何测量：比较使用和不使用技能时完成相同任务的情况。计算工具调用次数和消耗的总令牌数。
  • 每个工作流程有 0 次失败的 API 调用
    • 如何测量：在测试运行期间监控 MCP 服务器日志。跟踪重试率和错误代码。

定性指标：

  • 用户不需要提示 Claude 下一步该做什么
    • 如何评估：在测试期间，注意你需要重定向或澄清的频率。向测试版用户寻求反馈。
  • 无需用户纠正即可完成工作流程
    • 如何评估：将相同的请求运行 3-5 次。比较输出的结构一致性和质量。
  • 跨会话的结果一致
    • 如何评估：新用户能否在首次尝试时只需最少指导就能完成任务？

===== 第 10 页 =====

技术要求

文件结构

your-skill-name/
├── SKILL.md # Required - main skill file
├── scripts/ # Optional - executable code
│ ├── process_data.py # Example
│ └── validate.sh # Example
├── references/ # Optional - documentation
│ ├── api-guide.md # Example
│ └── examples/ # Example
└── assets/ # Optional - templates, etc.
 └── report-template.md # Example

关键规则

SKILL.md 命名：

  • 必须确切命名为 SKILL.md（区分大小写）
  • 不接受任何变体（如 SKILL.MD, skill.md 等）

技能文件夹命名：

  • 使用小写字母加连字符（kebab-case）：notion-project-setup
  • 无空格：Notion Project Setup
  • 无下划线：notion_project_setup
  • 无大写：NotionProjectSetup

不要使用 README.md：

  • 不要在技能文件夹内包含 README.md
  • 所有文档都应放在 SKILL.md 或 references/ 中
  • 注意：通过 GitHub 分发时，你仍然需要一个仓库级别的 README 给人类用户——请参阅“分发与共享”部分。

YAML 头部：最重要的部分

YAML 头部是 Claude 决定是否加载你的技能的依据。这一点必须正确。

最小必需格式

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

这就是你开始所需的一切。

字段要求

  • name （必需）：
    • 小写字母加连字符
    • 无空格或大写
    • 应与文件夹名称匹配
  • description （必需）：
    • 必须同时包含：
      • 技能的功能
      • 何时使用它（触发条件）
    • 少于 1024 个字符
    • 不含 XML 标签（< 或 >）
    • 包含用户可能会说的具体任务
    • 如果相关，提及文件类型

===== 第 11 页 =====

  • license （可选）：
    • 如果技能是开源的，则使用
    • 常见：MIT， Apache-2.0
  • compatibility （可选）：
    • 1-500 个字符
    • 指明环境要求：例如，目标产品、所需的系统包、网络访问需求等。
  • metadata （可选）：
    • 任何自定义键值对
    • 建议：author, version, mcp-server
    • 示例： 
      metadata:
  author: ProjectHub
  version: 1.0.0
  mcp-server: projecthub

安全限制

头部中禁止出现：

  • XML 尖括号（< >）
  • 名称中包含“claude”或“anthropic”的技能（已保留）

原因：头部会出现在 Claude 的系统提示中。恶意内容可能会注入指令。

编写有效的技能

description 字段

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

结构：
[技能功能] + [使用时机] + [关键能力]

好描述的示例：

# 好 - 具体且可操作的描述
description: 分析 Figma 设计文件并生成开发者交接文档。当用户上传 .fig 文件、询问“设计规范”、“组件文档”或“设计到代码交接”时使用。

# 好 - 包含触发短语
description: 管理 Linear 项目工作流程，包括冲刺规划、任务创建和状态跟踪。当用户提到“冲刺”、“Linear 任务”、“项目规划”或要求“创建工单”时使用。

# 好 - 明确的价值主张
description: 为 PayFlow 提供端到端的客户 onboarding 工作流程。处理账户创建、付款设置和订阅管理。当用户说“onboard 新客户”、“设置订阅”或“创建 PayFlow 账户”时使用。

===== 第 12 页 =====

不好描述的示例：

# 太模糊
description: 帮助处理项目。

# 缺少触发条件
description: 创建复杂的多页面文档系统。

# 过于技术化，没有用户触发条件
description: 实现具有层次关系的 Project 实体模型。

编写主要指令

在头部之后，用 Markdown 编写实际的指令。

推荐结构：

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

# 你的技能名称

## 指令

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

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

预期输出：[描述成功的样子]

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

示例

示例 1：[常见场景]

用户说：“设置一个新的营销活动”

操作：

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

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

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

故障排除

错误：[常见错误信息]
原因：[发生原因]
解决方案：[如何修复]

（根据需要添加更多错误情况）

===== 第 13 页 =====

1

### 指令最佳实践

**具体且可操作**

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

**不好：**
> 在进行之前验证数据。

**包含错误处理**

**常见问题**
> **MCP 连接失败**
> 如果你看到“Connection refused”：
> 1. 验证 MCP 服务器正在运行：检查 设置 > 扩展
> 2. 确认 API 密钥有效
> 3. 尝试重新连接：设置 > 扩展 > [你的服务] > 重新连接

**清晰引用捆绑的资源**

> 在编写查询之前，请查阅 `references/api-patterns.md` 了解：
> *   速率限制指导
> *   分页模式
> *   错误代码和处理

**使用渐进式披露**

保持 `SKILL.md` 专注于核心指令。将详细文档移至 `references/` 并链接到它。（请参阅“核心设计原则”了解三级系统的工作原理。）

===== 第 14 页 =====

# 测试与迭代

===== 第 15 页 =====

## 测试与迭代

技能可以根据你的需求以不同的严格程度进行测试：

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

选择符合你质量要求和技能可见性的方法。一个团队内部使用的技能与部署给数千名企业用户的技能有不同的测试需求。

**专业提示：在扩展到多个任务之前，先迭代单个任务**

我们发现，最有效的技能创建者会针对一个具有挑战性的任务进行迭代，直到 Claude 成功，然后将成功的方法提炼成一个技能。这利用了 Claude 的上下文学习能力，并比广泛测试提供更快的反馈信号。一旦你有了一个可用的基础，再扩展到多个测试用例以提高覆盖率。

### 推荐的测试方法

根据早期经验，有效的技能测试通常涵盖三个方面：

#### 1. 触发测试

**目标**：确保你的技能在正确的时间加载。

**测试用例**：
*   在明确的任务上触发
*   在改写后的请求上触发
*   在不相关的主题上不触发

**示例测试套件**：

*应该触发：*
*   “帮我在 ProjectHub 中设置一个新的工作区”
*   “我需要在 ProjectHub 中创建一个项目”
*   “为 Q4 规划初始化一个 ProjectHub 项目”

*不应该触发：*
*   “旧金山的天气怎么样？”
*   “帮我写 Python 代码”
*   “创建一个电子表格”（除非 ProjectHub 技能也处理表格）

===== 第 16 页 =====

#### 2. 功能测试

**目标**：验证技能是否产生正确的输出。

**测试用例**：
*   生成有效输出
*   API 调用成功
*   错误处理有效
*   覆盖边缘情况

**示例**：
> **测试**：创建包含 5 个任务的项目
> **给定**：项目名称“Q4 Planning”，5 个任务描述
> **当**：技能执行工作流程
> **那么**：
> *   在 ProjectHub 中创建了项目
> *   创建了 5 个具有正确属性的任务
> *   所有任务都链接到项目
> *   没有 API 错误

#### 3. 性能比较

**目标**：证明技能相比于基线改善了结果。

使用“定义成功标准”中的指标。下面是一个比较的样子。

**基线比较：**

*没有技能：*
*   用户每次都需要提供指令
*   15 条来回消息
*   3 次失败的 API 调用需要重试
*   消耗 12,000 个令牌

*有技能：*
*   自动执行工作流程
*   仅需 2 个澄清问题
*   0 次失败的 API 调用
*   消耗 6,000 个令牌

### 使用 `skill-creator` 技能

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

**创建技能：**
*   从自然语言描述生成技能
*   生成格式正确的 `SKILL.md`，包含头部
*   建议触发短语和结构

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

**迭代改进：**
*   在使用你的技能并遇到边缘情况或失败后，将这些例子带回给 `skill-creator`
*   例如：“使用本次聊天中识别的问题和解决方案，来改进技能处理[特定边缘情况]的方式”

===== 第 17 页 =====

**使用方法：**

> “使用 `skill-creator` 技能来帮助我为[你的用例]构建一个技能”

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

### 基于反馈进行迭代

技能是活的文档。计划根据以下情况进行迭代：

**触发不足的信号：**
*   技能在应该加载时没有加载
*   用户手动启用它
*   关于何时使用它的支持问题

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

**过度触发的信号：**
*   技能在不相关的查询时加载
*   用户禁用它
*   对用途感到困惑

**解决方案**：添加否定触发条件，更具体化。

**执行问题：**
*   结果不一致
*   API 调用失败
*   用户需要纠正

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

===== 第 18 页 =====

# 分发与共享

===== 第 19 页 =====

4

## 分发与共享

技能使你的 MCP 集成更加完整。当用户比较连接器时，那些带有技能的连接器提供了更快的价值实现路径，使你在竞争中优于纯 MCP 的替代方案。

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

**个人用户如何获取技能：**
1.  下载技能文件夹
2.  压缩文件夹（如果需要）
3.  通过 设置 > 能力 > 技能 上传到 Claude.ai
4.  或者放置在 Claude Code 的技能目录中

**组织级技能：**
*   管理员可以在整个工作区内部署技能（于 2025 年 12 月 18 日发布）
*   自动更新
*   集中管理

### 一个开放标准

我们已将 Agent Skills 发布为一个开放标准。像 MCP 一样，我们相信技能应该可以在不同的工具和平台之间移植——同一个技能无论你使用的是 Claude 还是其他 AI 平台，都应该能工作。也就是说，一些技能旨在充分利用特定平台的独特能力；作者可以在技能的 `compatibility` 字段中注明这一点。我们一直在与生态系统的成员就这个标准进行合作，并对早期的采用感到兴奋。

### 通过 API 使用技能

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

**关键能力：**
*   `/v1/skills` 端点用于列出和管理技能
*   通过 `container.skills` 参数向 Messages API 请求添加技能
*   通过 Claude Console 进行版本控制和管理
*   与 Claude Agent SDK 协同工作，用于构建自定义代理

**何时通过 API 与 Claude.ai 使用技能：**

| 用例 | 最佳界面 |
| :--- | :--- |
| 最终用户直接与技能交互 | Claude.ai / Claude Code |
| 开发过程中的手动测试和迭代 | Claude.ai / Claude Code |
| 个人、临时的临时工作流程 | Claude.ai / Claude Code |
| 以编程方式使用技能的应用程序 | API |
| 生产环境大规模部署 | API |
| 自动化流水线和代理系统 | API |

===== 第 20 页 =====

**注意**：API 中的技能需要代码执行工具测试版，该测试版提供了技能运行所需的安全环境。

有关实现细节，请参阅：
*   Skills API 快速入门
*   创建自定义技能
*   Agent SDK 中的技能

### 今天推荐的方法

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

#### 1. 托管在 GitHub 上
*   开源技能的公共仓库
*   包含安装说明的清晰 README
*   使用示例和截图

#### 2. 在你的 MCP 仓库中记录
*   从 MCP 文档链接到技能
*   解释一起使用两者的价值
*   提供快速入门指南

#### 3. 创建安装指南

> **安装 [你的服务] 技能**
>
> 1.  **下载技能**：
>     *   克隆仓库：`git clone https://github.com/yourcompany/skills`
>     *   或者从 Releases 下载 ZIP 文件
> 2.  **在 Claude 中安装**：
>     *   打开 Claude.ai > 设置 > 技能
>     *   点击“上传技能”
>     *   选择技能文件夹（压缩后）
> 3.  **启用技能**：
>     *   打开 [你的服务] 技能开关
>     *   确保你的 MCP 服务器已连接
> 4.  **测试**：
>     *   询问 Claude：“在 [你的服务] 中设置一个新项目”

### 定位你的技能

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

**关注结果，而非功能：**

*   **好：**
    > “ProjectHub 技能使团队能够在几秒钟内设置完整的项目工作区——包括页面、数据库和模板——而无需花费 30 分钟进行手动设置。”
*   **差：**
    > “ProjectHub 技能是一个包含 YAML 头部和 Markdown 指令的文件夹，用于调用我们的 MCP 服务器工具。”

**突出 MCP + 技能的价值：**

> “我们的 MCP 服务器让 Claude 可以访问你的 Linear 项目。我们的技能教导 Claude 你团队的冲刺规划工作流程。它们共同实现了 AI 驱动的项目管理。”

===== 第 21 页 =====

# 模式与故障排除

===== 第 22 页 =====

1

## 模式与故障排除

这些模式来自于早期采用者和内部团队创建的技能。它们代表了我们看到的行之有效的常见方法，而不是必须遵循的模板。

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

可以把它想象成家得宝（Home Depot）。你可能是带着问题走进来的——“我需要修理厨房的橱柜”——然后店员会指向正确的工具。或者你可能挑选了一个新的电钻，并询问如何将它用于你的特定工作。

技能的工作方式相同：

*   **问题优先**：“我需要设置一个项目工作区” \(\Rightarrow\) 你的技能按正确的顺序编排正确的 MCP 调用。用户描述结果；技能处理工具。
*   **工具优先**：“我连接了 Notion MCP” \(\Rightarrow\) 你的技能教导 Claude 最佳的工作流程和最佳实践。用户拥有访问权限；技能提供专业知识。

大多数技能会倾向于一个方向。了解哪种框架适合你的用例，可以帮助你在下面选择正确的模式。

### 模式 1：顺序工作流程编排

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

**示例结构**：

> **工作流程：Onboard 新客户**
>
> **步骤 1：创建账户**
> 调用 MCP 工具：`create_customer`
> 参数：姓名， 邮箱， 公司
>
> **步骤 2：设置付款**
> 调用 MCP 工具：`setup_payment_method`
> 等待：付款方式验证
>
> **步骤 3：创建订阅**
> 调用 MCP 工具：`create_subscription`
> 参数：plan_id， customer_id（来自步骤 1）
>
> **步骤 4：发送欢迎邮件**
> 调用 MCP 工具：`send_email`
> 模板：welcome_email_template

**关键技术**：
*   明确的步骤顺序
*   步骤之间的依赖关系
*   每个阶段的验证
*   失败时的回滚指令

===== 第 23 页 =====

### 模式 2：多 MCP 协调

**使用时机**：你的工作流程需要跨多个服务（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. 保存最终版本

**关键技术**：
*   明确的质量标准
*   迭代改进
*   验证脚本
*   知道何时停止迭代

===== 第 24 页 =====

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

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

**示例结构**：

> **工作流程：智能文件存储**
>
> **决策树**
> 1. 检查文件类型和大小
> 2. 确定最佳存储位置：
>    *   大文件（>10MB）：使用云存储 MCP
>    *   协作文档：使用 Notion/Docs MCP
>    *   代码文件：使用 GitHub MCP
>    *   临时文件：使用本地存储
>
> **执行存储**
> 根据决策：
> *   调用适当的 MCP 工具
> *   应用特定于服务的元数据
> *   生成访问链接
>
> **向用户提供上下文**
> 解释为什么选择该存储方式

**关键技术**：
*   清晰的决策标准
*   备选方案
*   关于选择的透明度

### 模式 5：特定领域的智能

**使用时机**：你的技能增加了超越工具访问权限的专业知识。

**示例结构**：

> **工作流程：符合合规性的支付处理**
>
> **处理前（合规性检查）**
> 1. 通过 MCP 获取交易详情
> 2. 应用合规性规则：
>    *   检查制裁名单
>    *   验证司法管辖区许可
>    *   评估风险等级
> 3. 记录合规性决策
>
> **处理中**
> 如果合规性通过：
> *   调用支付处理 MCP 工具
> *   应用适当的欺诈检查
> *   处理交易
> 否则：
> *   标记以供审查
> *   创建合规性案例
>
> **审计跟踪**
> *   记录所有合规性检查
> *   记录处理决策
> *   生成审计报告

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

===== 第 25 页 =====

## 故障排除

### 技能无法上传

**错误**：“Could not find SKILL.md in uploaded folder”

**原因**：文件未确切命名为 `SKILL.md`

**解决方案**：
*   重命名为 `SKILL.md`（区分大小写）
*   通过 `ls -la` 验证，应显示 `SKILL.md`

---

**错误**：“Invalid frontmatter”

**原因**：YAML 格式问题

**常见错误**：

*错误 - 缺少分隔符*
```yaml
name: my-skill
description: Does things

错误 - 引号未闭合

---
name: my-skill
description: "Does things
---

正确

---
name: my-skill
description: Does things
---

错误：“Invalid skill name”

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

错误：My Cool Skill

正确：my-cool-skill

技能未触发

症状：技能从未自动加载

修复方法：
修改你的 description 字段。有关好坏示例，请参阅“description 字段”部分。

快速检查清单：

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

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

技能触发过于频繁

症状：技能在不相关的查询时加载

解决方案：

1. 添加否定触发条件

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

===== 第 26 页 =====

2. 更具体

太宽泛：

description: 处理文档。

更具体：

description: 处理用于合同审查的 PDF 法律文档。

3. 明确范围

description: PayFlow 电子商务支付处理。特别用于在线支付工作流程，不用于一般金融查询。

MCP 连接问题

症状：技能已加载，但 MCP 调用失败

检查清单：

  1. 验证 MCP 服务器已连接

    • Claude.ai: 设置 > 扩展 > [你的服务]
    • 应显示“已连接”状态

  2. 检查身份验证

    • API 密钥有效且未过期
    • 已授予适当的权限/范围
    • OAuth 令牌已刷新

  3. 独立测试 MCP

    • 要求 Claude 直接调用 MCP（不使用技能）
    • 例如：“使用 [服务] MCP 获取我的项目”
    • 如果失败，则问题是 MCP，而不是技能

  4. 验证工具名称

    • 技能引用了正确的 MCP 工具名称
    • 查阅 MCP 服务器文档
    • 工具名称区分大小写

未遵循指令

症状：技能已加载，但 Claude 不遵循指令

常见原因：

1. 指令过于冗长

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

2. 指令被埋没

  • 将关键指令放在顶部
  • 使用 ## 重要 或 ## 关键 标题
  • 必要时重复关键点

3. 语言模糊

差：

确保正确地验证各项内容。

好：

关键：在调用 create_project 之前，请验证：

  • 项目名称非空
  • 至少分配了一名团队成员
  • 开始日期不在过去

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

4. 模型“懒惰”
添加明确的鼓励语：

  • 花点时间仔细完成这件事
  • 质量比速度更重要
  • 不要跳过验证步骤

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

===== 第 27 页 =====

大型上下文问题

症状：技能似乎很慢或响应质量下降

原因：

  • 技能内容过大
  • 同时启用了太多技能
  • 加载了所有内容，而不是渐进式披露

解决方案：

1. 优化 SKILL.md 大小

  • 将详细文档移至 references/
  • 链接到参考文件而不是内联写入
  • 保持 SKILL.md 在 5,000 词以下

2. 减少启用的技能

  • 评估是否同时启用了超过 20-50 个技能
  • 建议选择性启用
  • 考虑为相关能力设置技能“包”

===== 第 28 页 =====

资源与参考

===== 第 29 页 =====

6

资源与参考

如果你是首次构建技能，请从最佳实践指南开始，然后根据需要参考 API 文档。

官方文档

Anthropic 资源：

  • 最佳实践指南
  • 技能文档
  • API 参考
  • MCP 文档

博客文章：

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

示例技能

公共技能仓库：

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

工具和实用程序

skill-creator 技能：

  • 内置在 Claude.ai 中，也可用于 Claude Code
  • 可以根据描述生成技能
  • 提供审查和建议
  • 使用方法：“使用 skill-creator 帮我建立一个技能”

验证：

  • skill-creator 可以评估你的技能
  • 询问：“审查这个技能并提出改进建议”

获取支持

技术问题：

  • 一般问题：Claude 开发者 Discord 的社区论坛

错误报告：

  • GitHub Issues: anthropics/skills/issues
  • 请包含：技能名称、错误信息、重现步骤

===== 第 30 页 =====

[此页原为占位或无关图片/文字]

===== 第 31 页 =====

参考 B：YAML 头部

必需字段

---
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  # 可选：开源许可证
allowed-tools: "Bash(python:*) Bash(np:*) 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”为前缀的技能（已保留）

===== 第 32 页 =====

参考 C：完整技能示例

有关展示本指南中模式的完整、生产就绪技能，请参阅：

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

这些仓库保持最新，并包含此处未涵盖的其他示例。克隆它们，根据你的用例进行修改，并将其用作模板。

===== 第 33 页 =====

原文地址：https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf