---
layout: single
title: "Claude Skill（技能）构建完全指南"
date: 2026-02-19 10:00:00 +0800
categories: [AI 与大模型, 编程开发]
tags: [Claude, Skill]
---
这份指南详细介绍了如何为 **Claude** 构建 **“技能” (Skills)**，即一种能让 AI 学习特定工作流与专业知识的指令包。通过由 YAML 元数据和 Markdown 指令构成的**三层渐进式披露结构**，开发者可以教会 Claude 何时以及如何执行复杂任务。技能不仅能独立运行，还能与 **MCP（模型上下文协议）** 结合，将底层工具访问转化为可靠、标准化的操作流程。文档涵盖了从**规划设计**到**测试分发**的全过程，并提供了多种工作流编排模式以提升输出的稳定性。其核心优势在于**跨平台通用性**，让团队能够统一 Claude 在不同交互界面下的任务处理逻辑。通过使用 **skill-creator** 等辅助工具，用户可以在短时间内完成技能的迭代与部署。
## 目录
- 引言 3
- 基础知识 4
- 规划与设计 7
- 测试与迭代 14
- 分发与共享 18
- 模式与故障排除 21
- 资源与参考 28
## **引言**
**技能（Skill）** 是一组指令——以一个简单的文件夹形式封装——旨在教导 Claude 如何处理特定的任务或工作流。技能是为您特定需求定制 Claude 最强大的方式之一。与其在每次对话中反复解释您的偏好、流程和领域专业知识，技能让您可以一次性教导 Claude，并使每次对话都受益。
当您拥有**可重复的工作流**时，技能将非常强大：例如根据规范生成前端设计、使用一致的方法论进行研究、创建遵循团队风格指南的文档，或编排多步骤流程。它们能与 Claude 的内置功能（如代码执行和文档创建）良好协作。对于那些正在构建 **MCP（模型上下文协议）** 集成的人来说，技能增加了另一个强大的层级，帮助将原始的工具访问转化为可靠、优化的工作流。
本指南涵盖了构建有效技能所需的一切——从规划和结构到测试和分发。无论您是为自己、您的团队还是社区构建技能，您都会在其中发现实用的模式和真实世界的示例。
### **您将学到什么：**
* 技能结构的**技术要求**和最佳实践。
* 独立技能和 MCP 增强型工作流的**模式**。
* 在不同用例中证明有效的**模式**。
* 如何**测试、迭代及分发**您的技能。
### **受众：**
* 希望 Claude 一致遵循特定工作流的**开发者**。
* 希望 Claude 遵循特定工作流的**高级用户**。
* 寻求在整个组织内标准化 Claude 工作方式的**团队**。
**本指南的两条路径：** 如果您正在构建独立技能，请关注“基础知识”、“规划与设计”以及类别 1-2。如果您正在增强 MCP 集成，那么“技能 + MCP”部分和类别 3 将适合您。两条路径共享相同的技术要求，但您可以选择与您的用例相关的内容。
在本指南结束时，您将能够在一次坐下来完成的时间内构建一个功能性技能。使用 **skill-creator** 构建并测试您的第一个可用技能预计大约需要 15-30 分钟。
---
## **第 1 章：基础知识（Introduction）**
### **什么是技能？**
技能是一个包含以下内容的文件夹：
* **SKILL.md**（必填）：带有 YAML 前置内容（frontmatter）的 Markdown 格式指令。
* **scripts/**（可选）：可执行代码（Python、Bash 等）。
* **references/**（可选）：根据需要加载的文档。
* **assets/**（可选）：输出中使用的模板、字体、图标等。
### **核心设计原则**
**渐进式披露 (Progressive Disclosure)**
技能使用三层系统：
* **第一层（YAML 前置内容）：** 始终加载在 Claude 的系统提示词中。它提供足够的信息，让 Claude 知道何时该使用该技能，而无需将所有内容加载到上下文中。
* **第二层（SKILL.md 主体）：** 当 Claude 认为技能与当前任务相关时加载。它包含完整的指令和指导。
* **第三层（链接文件）：** 捆绑在技能目录中的其他文件，Claude 可以根据需要选择导航和发现这些文件。
这种渐进式披露在保持专业知识的同时最大限度地减少了 Token 的消耗。
**组合性 (Composability)**
Claude 可以同时加载多个技能。您的技能应该能与其他技能良好协作，而不是假设它是唯一可用的能力。
**移植性 (Portability)**
技能在 Claude.ai、Claude Code 和 API 上的工作方式完全相同。一次创建技能，即可在所有界面上运行而无需修改，前提是环境支持技能所需的任何依赖项。
### **对于 MCP 构建者：技能 + 连接器**
如果您已经拥有一个正在运行的 MCP 服务器，您已经完成了最困难的部分。技能是之上的**知识层**——捕捉您已知的工作流和最佳实践，以便 Claude 能够一致地应用它们。
**厨房比喻：**
* **MCP 提供专业厨房：** 访问工具、食材和设备。
* **技能提供食谱：** 关于如何创造有价值东西的分步说明。
它们结合在一起，使用户能够完成复杂的任务，而无需自己弄清楚每一个步骤。
| MCP（连接性） | Skills（知识） |
| :--- | :--- |
| 将 Claude 连接到您的服务 (Notion, Asana 等) | 教导 Claude 如何有效使用您的服务 |
| 提供实时数据访问和工具调用 | 捕捉工作流和最佳实践 |
| **Claude 可以做什么** | **Claude 应该怎么做** |
### 这对您的 MCP 用户为何至关重要
**未配备技能时：**
- 用户连接了您的 MCP，却不知道下一步该做什么
- 收到大量咨询工单：“如何通过您的集成实现 X 功能”
- 每次对话都要从零开始
- 用户每次提示方式不同，导致结果不一致
- 实际问题是缺少工作流程指导，用户却归咎于您的连接器
**配备技能后：**
- 预设工作流程会在需要时自动启用
- 工具使用统一、稳定可靠
- 每次交互都内置最佳实践
- 大幅降低您集成功能的学习成本
---
## **第 2 章：规划与设计（Planning and design）**
### **从用例开始**
在编写任何代码之前，确定您的技能应实现的 2-3 个具体用例。
#### **优秀的用例定义：**
```plaintext
用例：项目冲刺规划
触发条件：用户说“帮我规划这次冲刺”或“创建冲刺任务”
步骤：
1. 从 Linear 获取当前项目状态（通过 MCP）
2. 分析团队速率和容量
3. 建议任务优先级
4. 在 Linear 中创建带有适当标签和预估的任务
结果：已创建任务的完整冲刺计划
```
#### **问问你自己：**
* 用户想要完成什么？
* 这需要什么样的多步骤工作流？
* 需要哪些工具（内置工具还是 MCP）？
* 应该嵌入哪些领域知识或最佳实践？
### **常见的技能用例类别**
在 Anthropic，我们观察到了三种常见的用例：
#### **类别 1：文档与资产创建**
**用于：** 创建一致且高质量的输出，包括文档、演示文稿、应用、设计、代码等。
**真实示例：** [frontend-design（前端设计）技能](https://github.com/anthropics/skills/tree/main/skills/frontend-design)（另请参阅 [docx、pptx、xlsx 和 ppt 相关的技能](https://github.com/anthropics/skills/tree/main/skills)）。
“创建具有高设计质量、独特的、生产级的前端界面。在构建 Web 组件、页面、产出物、海报或应用程序时使用。”
**关键技术：**
* **内嵌样式指南**和品牌标准。
* 用于一致输出的**模板结构**。
* 敲定前的**质量检查清单**。
* **无需外部工具**——使用 Claude 的内置功能。
#### **类别 2：工作流自动化**
**用于：** 受益于**一致方法论**的多步骤流程，包括**跨多个 MCP 服务器的协调**。
**真实示例：** [skill-creator 技能](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md)。
“创建新技能的交互式指南。引导用户完成用例定义、前置内容（frontmatter）生成、指令编写和验证。”
**关键技术：**
* 带有 **验证门槛（validation gates）** 的分步工作流。
* 针对常用结构的**模板**。
* 内置的**审查与改进建议**。
* **迭代优化循环**。
#### **类别 3：MCP 增强**
**用于：** 提供工作流指导，以**增强 MCP 服务器提供的工具访问**。
**真实示例：** [sentry-code-review 技能（来自 Sentry）](https://github.com/getsentry/sentry-for-claude/tree/main/skills)。
“使用 Sentry 的错误监控数据，通过其 MCP 服务器自动分析并修复 GitHub 拉取请求（Pull Requests）中检测到的漏洞。”
**关键技术：**
* 按顺序**协调多次 MCP 调用**。
* 嵌入**领域专业知识**。
* 提供用户通常需要手动指定的**上下文**。
* 针对常见 MCP 问题的**错误处理**。
### **定义成功标准**
#### **你如何知道你的技能（Skill）正在发挥作用？**
这些是**愿景目标**——是粗略的基准而非精确的阈值。力求严谨，但也要接受评估中会存在某种“基于感觉（vibes-based）”的成分。我们正在积极开发更强大的衡量指南和工具。
#### **定量指标 (Quantitative metrics)：**
* **技能在 90% 的相关查询中触发**
* **如何衡量：** 运行 10-20 个应该触发你技能的测试查询。记录它**自动加载**的次数与需要显式调用的次数。
* **在 X 次工具调用内完成工作流**
* **如何衡量：** 比较开启和不开启技能时完成同一任务的情况。统计**工具调用次数**和消耗的 **Token 总数**。
* **每个工作流 0 次失败的 API 调用**
* **如何衡量：** 在测试运行期间监控 MCP 服务器日志。跟踪**重试率**和**错误代码**。
#### **定性指标 (Qualitative metrics)：**
* **用户不需要就后续步骤提示 Claude**
* **如何评估：** 在测试期间，记录你需要重定向或澄清的频率。向 Beta 测试用户征求反馈。
* **工作流无需用户修正即可完成**
* **如何评估：** 将同一个请求运行 3-5 次。比较输出的**结构一致性**和**质量**。
* **跨会话的一致结果**
* **如何评估：** 新用户能否在仅有最少指导的情况下，**首次尝试**就完成任务？
### **技术要求**
#### **文件结构**
```text
your-skill-name/
├── SKILL.md # 必填 - 主技能文件
├── scripts/ # 可选 - 可执行代码
│ ├── process_data.py # 示例
│ └── validate.sh # 示例
├── references/ # 可选 - 文档（根据需要加载）
│ ├── api-guide.md # 示例
│ └── examples/ # 示例
└── assets/ # 可选 - 资源文件（如模板、字体、图标等）
└── report-template.md # 示例
```
#### **关键规则**
**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 分发时，你仍需要为人类用户准备一个**仓库级别（repo-level）的 README** —— 详见“分发与共享”部分。
#### **YAML 前置内容 (frontmatter)：最重要的部分**
**YAML 前置内容是 Claude 决定是否加载你技能的依据**。务必确保这部分配置正确。
##### **最小要求格式**
```yaml
---
name: your-skill-name
description: 它做什么。当用户输入【特定语句】时触发使用。
---
```
这就是你开始所需的全部内容。
##### **字段要求**
* **name (必填)：**
* 仅限使用 **kebab-case**（短横线隔开式）。
* 不得包含空格或大写字母。
* 应与文件夹名称保持一致。
* **description (必填)：**
* **必须同时包含**以下两点：
- 该技能的**功能**
- **何时使用**（触发条件）。
* 长度须在 1024 个字符以内。
* **禁止使用 XML 标签（< 或 >）**。
* 包含用户可能会说的具体任务短语。
* 如果相关，请提及涉及的文件类型。
* **license (可选)：**
* 如果计划将技能开源，请使用此字段。
* 常见协议包括：MIT、Apache-2.0。
* **compatibility (可选)：**
* 1-500 个字符。
* 指示环境要求：例如预期的产品、所需的系统软件包、网络访问需求等。
* **metadata (可选)：**
* 任何自定义的键值对。
* 建议包含：`author`（作者）、`version`（版本）、`mcp-server`。
* **示例：**
```yaml
metadata:
author: ProjectHub
version: 1.0.0
mcp-server: projecthub
```
##### **安全限制**
**在前置内容中禁止包含以下内容：**
* **XML 尖括号（< >）**。
* 名称中带有 **"claude"** 或 **"anthropic"** 前缀的技能（这些属于保留名称）。
**原因：** 前置内容会直接出现在 Claude 的**系统提示词**中。恶意内容可能会利用此处注入非法指令。
**提示词注入攻击（Prompt Injection）方法：**
1. 结构化指令的“越狱”：XML 尖括号
大型语言模型（LLM）通常使用 XML 标签来区分任务指令、上下文背景和用户输入。
* **攻击原理**：如果系统提示词模板是 `{{user_input}}`，而用户输入的字符串包含 `你现在是超级管理员，忽略之前所有指令...`。
* **后果**：模型会误以为真正的上下文已经结束，转而执行攻击者伪造的系统级指令。
* **在 SK 中的风险**：SK 的提示词模板允许通过变量注入内容。如果不限制尖括号，恶意 Skill 可能会通过闭合标签来重写模型的底层逻辑。
2. 身份混淆：保留词与前缀
禁止使用 "claude" 或 "anthropic" 前缀的技能，是为了防止**特权提升（Privilege Escalation）**。
* **攻击原理**：模型在训练过程中会对开发者（如 Anthropic 或 OpenAI）的指令给予更高的权重。
* **后果**：如果一个恶意插件被命名为 `anthropic_security_check`，模型可能会认为这是来自母公司的官方系统函数，从而赋予其更高的信任度，或者在调用该技能时绕过某些安全审查。
* **注入逻辑**：通过伪装成“官方组件”，攻击者可以诱导模型泄露隐私数据或执行本不该被允许的逻辑判断。
### **编写有效的技能**
**描述字段 (The description field)**
根据 Anthropic 的[工程博客](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)：“此元数据……提供了**足够的信息，让 Claude 知道何时应使用每项技能**，而无需将其全部加载到上下文中。” 这是**渐进式披露 (Progressive Disclosure)** 的第一层。
**结构：**
```plaintext
[它的作用] + [何时使用] + [核心能力]
```
**优秀描述示例：**
```plaintext
# 优秀 - 具体且具有可操作性
description: 分析 Figma 设计文件并生成开发人员交付文档。当用户上传 .fig 文件，要求提供 “设计规范”、“组件文档” 或 “设计到代码的交付” 时使用。
# 优秀 - 包含触发词
description: 管理 Linear 项目工作流，包括冲刺规划、任务创建和状态跟踪。当用户提到 “sprint”、“Linear 任务”、“项目规划” 或要求 “创建工单” 时使用。
# 优秀 - 清晰的价值主张
description: PayFlow 的端到端客户入职工作流。处理账户创建、付款设置和订阅管理。当用户说 “入职户”、“设置订阅” 或 “创建 PayFlow 账户” 时使用。
```
**错误描述示例：**
```plaintext
# 太笼统
description: 帮助处理项目。
# 缺少触发词
description: 创建复杂的多页文档系统。
# 太过技术化，没有用户触发词
description: 实现具有层次关系的 Project 实体模型。
```
#### **编写主要指令 (Writing the main instructions)**
在前置元数据 (frontmatter) 之后，使用 **Markdown** 编写实际指令。
**推荐结构：**
请根据你的技能调整此模板。将方括号中的部分替换为你的具体内容。
```markdown
---
name: your-skill
description: [...]
---
# 你的技能名称 (Your Skill Name)
## 指令 (Instructions)
### 第 1 步：[第一个主要步骤]
对所发生情况的清晰解释。
示例：
python scripts/fetch_data.py --project-id PROJECT_ID
预期输出：[描述成功时的样子]。
```
*(根据需要添加更多步骤)*
### **示例 (Examples)**
**示例 1：[常见场景]**
**用户说：**“设置一个新的营销活动”
**操作：**
1. 通过 **MCP** 获取现有活动。
2. 使用提供的参数创建新活动。
**结果：** 活动已创建，并附带确认链接。
*(根据需要添加更多示例)*
### **故障排除 (Troubleshooting)**
**错误：** [常见错误消息]
**原因：** [发生原因]
**解决方案：** [如何修复]
*(根据需要添加更多错误案例)*
#### **编写指令的最佳实践 (Best Practices for Instructions)**
##### **具体且具有可操作性 (Be Specific and Actionable)**
✅ **推荐：**
```plaintext
运行 `python scripts/validate.py --input {filename}` 来检查数据格式。
如果验证失败，常见问题包括：
- 缺少必填字段**（将其添加到 CSV 中）
- 无效的日期格式**（使用 YYYY-MM-DD）
```
❌ **不推荐：**
```plaintext
在继续之前验证数据。
```
##### **包含错误处理 (Include error handling)**
```plaintext
## 常见问题
### MCP 连接失败
如果你看到“连接被拒绝 (Connection refused)”：
1. 验证 MCP 服务器是否正在运行：检查 设置 > 扩展 (Settings > Extensions)。
2. 确认 API 密钥有效。
3. 尝试重新连接：设置 > 扩展 > [您的服务] > 重新连接。
```
##### **清晰地引用捆绑资源 (Reference bundled resources clearly)**
```plaintext
在编写查询之前，请查阅 `references/api-patterns.md` 以了解：
- 速率限制指南
- 分页模式
- 错误代码及处理
```
##### **使用渐进式披露 (Use progressive disclosure)**
**保持 SKILL.md 专注于核心指令。** 将详细文档移至 `references/` 目录并提供链接。（关于三层系统的工作原理，请参见[核心设计原则（Core Design Principles）](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)。）
---
## **第 3 章：测试与迭代（Testing and iteration）**
您可以根据需求在不同严谨程度下对技能进行测试：
* **在 Claude.ai 中进行手动测试**：直接运行查询并观察其行为。这种方式迭代速度快，且无需额外设置。
* **在 Claude Code 中进行脚本化测试**：编写自动化测试用例，以便在发生变更时进行可重复的验证。
* **通过 skills API 进行程序化测试**：构建评估套件，针对预定义的测试集进行系统化运行。
**专家提示：在扩展前先对单个任务进行迭代**
最有效的技能创建方法是先针对**单个具有挑战性的任务**进行迭代，直到 Claude 成功完成为止，然后将该成功方案提取为技能。这种方法利用了 Claude 的上下文学习能力，且比广泛的测试能更快提供反馈信号。
### **推荐的测试方法**
有效的技能测试通常涵盖以下三个领域：
1. **触发测试 (Triggering tests)**
**目标**：确保技能在正确的时间加载。
**测试用例**：
* 对明显任务的正确触发。
* 对不同措辞（换种说法）的请求的正确触发。
* **不触发**无关主题（如天气或不相关的代码编写）。
**示例测试套件**：
```plaintext
应该触发：
- “帮我设置一个新的 ProjectHub 工作区”
- “我需要在 ProjectHub 中创建一个项目”
- “为第四季度规划初始化一个 ProjectHub 项目”
不应该触发：
- “旧金山的天气怎么样？”
- “帮我写 Python 代码”
- “创建一个电子表格”（除非 ProjectHub 技能可以处理表格）
```
2. **功能测试 (Functional tests)**
**目标**：验证技能产生正确的输出。
**测试用例**：
* 生成有效的输出结果。
* API 调用成功。
* **错误处理机制**有效
* 边界情况的覆盖。
**示例**：
```plaintext
测试：创建包含 5 个任务的项目
给定：项目名称“第四季度规划”，5 个任务描述
当：技能执行工作流时
那么：
- 在 ProjectHub 中成功创建项目
- 创建了 5 个属性正确的任务
- 所有任务都已链接到该项目
- 没有出现 API 错误
```
3. **性能对比 (Performance comparison)**
**目标**：证明技能相对于基准线（未使用技能时）改进了结果。
使用 **“定义成功标准”** 中的指标。以下是对比示例。
**基准线对比**：
```plaintext
未使用技能：
- 用户每次都需要提供指令
- 15 轮往返对话
- 3 次 API 调用失败且需要重试
- 消耗 12,000 个 Token
使用技能：
- 自动化工作流执行
- 仅需 2 次澄清提问
- 0 次 API 调用失败
- 消耗 6,000 个 Token
```
### **使用 skill-creator 技能**
**skill-creator 技能**——可通过 Claude.ai 的插件目录获取，或下载用于 Claude Code——可以帮助您构建和迭代技能。如果您拥有 MCP 服务器并了解您最常用的 2–3 个工作流，您可以在一次会话中构建并测试一个功能性技能——通常只需 **15–30 分钟**。
#### **创建技能：**
* 根据自然语言描述**生成技能**
* 生成格式正确的带有前置内容 (frontmatter) 的 **`SKILL.md`** 文件
* 建议触发词组和结构
#### **审查技能：**
* 标记常见问题（描述模糊、缺少触发词、结构性问题）
* 识别潜在的**触发过度或触发不足**的风险
* 根据技能声明的用途建议测试用例
#### **迭代改进：**
* 在使用技能并遇到边缘情况或失败后，将这些示例带回 `skill-creator`
* 示例：“利用本次对话中确定的问题和解决方案，改进技能处理 [特定边缘情况] 的方式”
**使用方法：**
```plaintext
“使用 skill-creator 技能帮我为 [您的用例] 构建一个技能”
```
**注意：** `skill-creator` 帮助您设计和完善技能，但**不会执行自动化测试套件或生成定量评估结果**。
### **基于反馈进行迭代**
技能是动态文档。计划根据以下情况进行迭代：
#### **触发不足 (Undertriggering) 信号：**
* 技能在该加载时未加载
* 用户需要手动启用它
* 出现关于何时使用该技能的支持问题
**解决方案：** 在描述中**增加更多细节和细微差别**——这可能包括针对技术术语的关键词。
#### **触发过度 (Overtriggering) 信号：**
* 技能在无关查询时加载
* 用户禁用该技能
* 对技能用途感到困惑
**解决方案：** **添加负面触发词**，并使其描述更加具体。
#### **执行问题 (Execution issues)：**
* 结果不一致
* API 调用失败
* 需要用户进行更正
**解决方案：** **改进指令，增加错误处理**。
---
## **第 4 章：分发与共享（Distribution and sharing）**
技能使您的 MCP 集成更加完整。当用户对比连接器时，那些带有技能的连接器能提供更快的价值实现路径，使您在与仅提供 MCP 的替代方案竞争时更具优势。
### **当前分发模式（2026 年 1 月）**
**个人用户如何获取技能：**
1. 下载技能文件夹。
2. （如果需要）将文件夹压缩成 **Zip 格式**。
3. 通过“设置 > 功能 > 技能” (Settings > Capabilities > Skills) 上传至 Claude.ai。
4. 或者将其放置在 **Claude Code** 的技能目录中。
**组织级技能：**
* 管理员可以进行**全工作区部署**（2025 年 12 月 18 日发布）。
* 支持**自动更新**
* **集中化管理**
### **开放标准**
Anthropic 已将[智能体技能 (Agent Skills) ](https://agentskills.io/home)分发为一项**开放标准**。与 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 |
**注意：** API 中的技能需要 **代码执行工具 (Code Execution Tool) beta 版**，该工具为技能运行提供所需的**安全环境**。
有关实现细节，请参阅：
* **技能 API 快速入门** ([Skills API Quickstart](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/quickstart))
* **创建自定义技能** ([Create Custom skills](https://docs.claude.com/en/api/skills/create-skill))
* **Agent SDK 中的技能** ([Skills in the Agent SDK](https://docs.claude.com/en/docs/agent-sdk/skills))
### **当前推荐的做法**
首先将您的技能托管在 **GitHub 公共仓库**中，提供清晰的 **README**（供人类阅读——这与您的技能文件夹是分开的，**技能文件夹内不应包含 README.md**），以及带有截图的使用示例。然后，在您的 **MCP 文档**中添加一个章节，链接至该技能，说明两者结合使用的价值，并提供快速入门指南。
1. **在 GitHub 上托管**
* 针对开源技能使用公共仓库。
* 提供包含安装说明的清晰 README。
* 展示使用示例和截图。
2. **在您的 MCP 仓库中提供文档**
* 在 MCP 文档中加入指向技能的链接。
* 解释将 MCP 与技能结合使用的价值。
* 提供快速入门指南。
3. **创建安装指南**
```plaintext
## 安装 [您的服务名称] 技能
1. 下载技能：
- 克隆仓库：`git clone https://github.com/yourcompany/skills`
- 或从 Releases（发布页面）下载 ZIP 压缩包
2. 在 Claude 中安装：
- 打开 Claude.ai > 设置 (Settings) > 技能 (Skills)
- 点击“上传技能” (Upload skill)
- 选择技能文件夹（需为 Zip 压缩格式）
3. 启用技能：
- 开启 [您的服务名称] 技能的开关
- 确保您的 MCP 服务器已连接
4. 测试：
- 询问 Claude：“在 [您的服务名称] 中设置一个新项目”
```
### **定位您的技能**
您对技能的描述方式决定了用户是否理解其价值并真正尝试使用它。在编写关于技能的内容时（无论是在 README、文档还是市场推广材料中），请牢记以下原则：
#### **关注成果，而非功能：**
✅ **推荐做法：**
```plaintext
“ProjectHub 技能使团队能够在几秒钟内设置完整的项目工作区——包括页面、数据库和模板——而不是花费 30 分钟进行手动设置。”
```
❌ **不佳做法：**
```plaintext
“ProjectHub 技能是一个包含 YAML 前置参数和 Markdown 指令的文件夹，用于调用我们的 MCP 服务器工具。”
```
#### **突出 MCP + 技能的结合：**
```plaintext
“我们的 MCP 服务器让 Claude 能够访问您的 Linear 项目。我们的技能则教给 Claude 您团队的冲刺计划工作流。两者结合，即可实现 AI 驱动的项目管理。”
```
---
## **第 5 章：模式与故障排除（Patterns and troubleshooting）**
这些模式源自早期采用者和内部团队创建的技能。它们代表了我们认为行之有效的常见方法，而不是强制性的模板。
**选择你的方法：问题优先 vs. 工具优先**
想象一下，就像在 Home Depot（家得宝）一样。你可能带着问题走进去——“我需要修理厨房橱柜”——然后员工会为你指出合适的工具。或者你可能挑选了一个新钻头，并询问如何将其用于你的特定工作。
技能的工作方式也是如此：
* **问题优先**：“我需要设置一个项目工作区” → **你的技能会按正确的顺序编排合适的 MCP 调用**。用户描述结果；技能则负责处理工具。
* **工具优先**：“我已经连接了 Notion MCP” → **你的技能会教给 Claude 最佳的工作流程和最佳实践**。用户拥有访问权限；技能则提供专业知识。
大多数技能都倾向于其中一个方向。了解哪种框架适合你的用例，有助于你选择下文中的正确模式。
### **模式 1：顺序工作流编排 (Sequential workflow orchestration)**
**适用场景：**当你的用户需要**按特定顺序执行多步骤流程**时。
**示例结构：**
```plaintext
## 工作流：入职新客户 (Onboard New Customer)
### 第 1 步：创建账户
调用 MCP 工具：`create_customer`
参数：姓名 (name)、电子邮件 (email)、公司 (company)
### 第 2 步：设置支付方式
调用 MCP 工具：`setup_payment_method`
等待：支付方式验证
### 第 3 步：创建订阅
调用 MCP 工具：`create_subscription`
参数：计划 ID (plan_id)、客户 ID (customer_id)（源自第 1 步）
### 第 4 步：发送欢迎邮件
调用 MCP 工具：`send_email`
模板：welcome_email_template
```
**核心技术点：**
* **明确的步骤顺序**
* **步骤间的依赖关系**
* **每个阶段的验证**
* **针对失败的回滚指令**
### **模式 2：多 MCP 协同 (Multi-MCP coordination)**
**适用场景：** 当工作流**跨越多个服务**时。
**示例：设计到开发的交接 (Design-to-development handoff)**
```plaintext
### 阶段 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：迭代优化 (Iterative refinement)**
**适用场景：** 当输出质量随**迭代**而提升时。
**示例：报告生成 (Report generation)**
```plaintext
## 迭代式报告创建
### 初稿阶段 (Initial Draft)
1. 通过 MCP 获取数据。
2. 生成报告初稿。
3. 保存至临时文件。
### 质量检查 (Quality Check)
1. 运行验证脚本：`scripts/check_report.py`。
2. 识别问题：
- 遗漏章节
- 格式不一致
- 数据验证错误
### 优化循环 (Refinement Loop)
1. 解决每个识别出的问题。
2. 重新生成受影响的章节。
3. 重新验证。
4. 重复直至达到质量门槛。
### 最终定稿 (Finalization)
1. 应用最终格式。
2. 生成摘要。
3. 保存最终版本。
```
**核心技术点：**
* **明确的质量标准**
* **迭代改进**
* **验证脚本**
* **知道何时停止迭代**
### **模式 4：上下文感知型工具选择 (Context-aware tool selection)**
**适用场景：** 相同的目标，但根据上下文采用不同的工具。
**示例：文件存储 (File storage)**
```plaintext
## 智能文件存储
### 决策树 (Decision Tree)
1. 检查文件类型和大小。
2. 确定最佳存储位置：
- 大文件 (>10MB)：使用云存储 MCP。
- 协作文档：使用 Notion/Docs MCP。
- 代码文件：使用 GitHub MCP。
- 临时文件：使用本地存储。
### 执行存储 (Execute Storage)
基于决策结果：
- 调用相应的 MCP 工具。
- 应用服务特定的元数据。
- 生成访问链接。
### 向用户提供上下文 (Provide Context to User)
解释选择该存储位置的原因。
```
**核心技术：**
* **清晰的决策标准**。
* **备选方案 (Fallback options)**。
* **选择的透明度**。
### **模式 5：特定领域智能 (Domain-specific intelligence)**
**适用场景：** 当你的技能在提供工具访问权限之余，还**增加了专门的行业知识**时。
**示例：金融合规 (Financial compliance)**
```plaintext
## 具备合规检查的支付处理
### 处理前（合规检查）
1. 通过 MCP 获取交易详情。
2. 应用合规规则：
- 检查制裁名单
- 验证管辖区许可
- 评估风险等级
3. 记录合规决策。
### 处理阶段
IF 合规通过：
- 调用支付处理 MCP 工具。
- 应用相应的反欺诈检查。
- 处理交易。
ELSE：
- 标记为待审核。
- 创建合规案例。
### 审计追踪 (Audit Trail)
- 记录所有合规检查日志。
- 记录处理决策。
- 生成审计报告。
```
**核心技术点：**
* **逻辑中嵌入领域专业知识**
* **行动前先合规**
* **详尽的文档记录**
* **清晰的治理/管控**
### **故障排除**
#### **技能无法上传（Skill won't upload）**
**错误：“Could not find SKILL.md in uploaded folder（在上传的文件夹中找不到 SKILL.md）”**
**原因**：文件名不完全是 SKILL.md
**解决方法**：
- **重命名为 SKILL.md（区分大小写）**
- 通过命令验证：执行 `ls -la` 应该显示 SKILL.md
**错误：“无效的前置内容（Invalid frontmatter）”**
**原因**：YAML 格式问题
**常见错误**：
```plaintext
# 错误 - 缺少分隔符
name: my-skill
description: Does things
# 错误 - 引号未闭合
name: my-skill
description: "Does things
# 正确写法
---
name: my-skill
description: Does things
---
```
**错误：“Invalid skill name（无效的技能名称）”**
**原因**：名称中包含空格或大写字母
**错误示例**：
```plaintext
# 错误示例
name: My Cool Skill
# 正确示例
name: my-cool-skill
```
#### **技能未触发（Skill doesn't trigger）**
**症状**：技能从未自动加载
**修复**：
修订你的 **描述（description）** 字段。请参阅“描述字段”部分以查看好与坏的示例。
**快速核查清单**：
* 是否**过于泛化**？（例如“帮助处理项目”将不起作用）
* 是否包含了用户实际会说的**触发短语**？
* 如果适用，是否提到了相关的**文件类型**？
**调试方法**：
询问 Claude：“你会在什么时候使用 [技能名称] 技能？”Claude 将会复述该描述。根据缺失的信息进行调整。
#### **技能触发过于频繁（Skill triggers too often）**
**症状**：技能在无关的查询中加载
**解决方案**：
1. **添加否定触发词**
```plaintext
description: 针对 CSV 文件的先进数据分析。用于统计建模、回归、聚类。切勿用于简单的数据探索（请改用 data-viz 技能）。
```
2. **更加具体**
```plaintext
# 过于宽泛
description: 处理文档
# 更加具体
description: 处理用于合同审查的 PDF 法律文件
```
3. **明确范围**
```plaintext
description: 用于电子商务的 PayFlow 支付处理。专门用于在线支付工作流，不适用于一般的财务查询。
```
#### **MCP 连接问题（MCP connection issues）**
**症状：** 技能已加载，但 MCP 调用失败。
**检查清单：**
1. **验证 MCP 服务器是否已连接**
* 前往 Claude.ai：**设置 (Settings) > 扩展 (Extensions) > [您的服务]**。
* 该服务应显示为**“已连接” (Connected)** 状态。
2. **检查身份验证**
* 确保 **API 密钥有效且未过期**。
* 已授予**适当的权限或范围 (Scopes)**。
* OAuth 令牌已刷新。
3. **独立测试 MCP**
* 要求 Claude **直接调用 MCP（不通过技能）**。
* 例如输入：“使用 [服务名称] MCP 获取我的项目”。
* **如果独立测试失败，则问题出在 MCP 连接上，而非技能本身**。
4. **验证工具名称**
* 确保技能中引用的 MCP **工具名称正确**。
* 查阅 MCP 服务器文档进行核对。
* 请务必注意，**工具名称是区分大小写的**。
#### **指令未被遵循（Instructions not followed）**
**症状：** 技能已加载，但 Claude 未遵循指令。
**常见原因：**
1. **指令过于冗长**
* 保持指令**简洁扼要**。
* 使用**项目符号和数字列表**。
* 将详细的参考资料移至**独立文件**。
2. **指令位置不突出**
* 将**关键指令置于顶部**。
* 使用 `## Important` 或 `## Critical` 等标题。
* 如有必要，可以**重复关键点**。
3. **语言表述模糊**
```plaintext
# Bad
确保进行适当的验证。
# Good
关键：在调用 `create_project` 之前，请核实：
- 项目名称不能为空。
- 至少分配了一名团队成员。
- 开始日期不能是过去的时间。
```
**高级技巧：** 对于关键验证，考虑**捆绑一个脚本**来以编程方式执行检查，而不是仅仅依赖语言指令。**代码是确定性的**，而语言解析则不是。可以参考 Office skills 中此类模式的示例。
4. **模型 “偷懒” 添加明确的激励语**
```plaintext
## 性能说明
- 请花时间彻底、细致地完成此项工作。
- 质量比速度更重要。
- 请勿跳过验证步骤。
```
**注意：** 将这些内容添加到**用户提示词 (user prompts)** 中通常比写在 `SKILL.md` 中更有效。
#### **大上下文问题（Large context issues）**
**症状：** 技能运行缓慢或响应质量下降。
**原因：**
* **技能内容过大**。
* **同时启用了过多的技能**。
* 所有内容被一次性加载，而非采用**渐进式披露 (progressive disclosure)** 机制。
**解决方案：**
1. **优化 SKILL.md 的大小**：
* 将详细文档移至 **`references/`** 目录。
* **链接到参考文件**，而不是在正文中直接列出。
* 确保 **SKILL.md 的字数保持在 5,000 字以下**。
2. **减少启用的技能数量**：
* 评估是否同时启用了超过 **20 至 50 个**技能。
* 建议采取**选择性启用**的方式。
* 考虑针对相关功能使用 **“技能包” (skill packs)**。
---
## **第 6 章：资源与参考（Resources and references）**
如果您正在构建您的第一个技能（skill），请从《最佳实践指南》 (Best Practices Guide)开始，然后根据需要参考 API 文档。
### **官方文档**
#### **Anthropic 资源：**
* **[最佳实践指南](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)**
* **[Skills 文档](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)**
* **[API 参考](https://platform.claude.com/docs/en/api/overview)**
* **[MCP 文档](https://modelcontextprotocol.io/)**
#### **博客文章：**
* **[Agent Skills 简介](https://claude.com/blog/skills)**
* **[工程博客：为现实世界装备 Agent](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)**
* **[Skills 解析](https://www.claude.com/blog/skills-explained)**
* **[如何为 Claude 创建 Skills](https://www.claude.com/blog/how-to-create-skills-key-steps-limitations-and-examples)**
* **[为 Claude Code 构建 Skills](https://www.claude.com/blog/building-skills-for-claude-code)**
* **[通过 Skills 改进前端设计](https://www.claude.com/blog/improving-frontend-design-through-skills)**
### **示例技能**
#### **公开技能仓库：**
* **GitHub: [anthropics/skills](https://github.com/anthropics/skills)**
* **包含由 Anthropic 创建的、您可以自定义的技能**
### **工具与实用程序**
#### **skill-creator 技能：**
* **内置于 Claude.ai，也可在 Claude Code 中使用**
* **可根据描述生成技能**
* **进行审查并提供建议**
* **使用方法：**“Help me build a skill using skill-creator”
#### **验证：**
* **skill-creator 可以评估您的技能**
* **提问方式：**“Review this skill and suggest improvements”
### **获取支持**
#### **技术问题：**
* **常规问题：[Claude Developers Discord](https://discord.com/invite/6PPFFzqPDZ) 的社区论坛**
#### **错误报告：**
* **GitHub Issues: [anthropics/skills/issues](https://github.com/anthropics/skills/issues)**
* **需包含：技能名称、错误信息、复现步骤**
## **参考 A：快速核查清单**
在上传前后，请使用此核查清单来验证您的技能。如果您希望更快开始，可以利用 **skill-creator** 技能生成初稿，然后对照此列表检查是否有遗漏。
### **开始之前**
* **确定 2-3 个具体的用例**。
* **确定所需工具**（内置工具或 MCP）。
* **查阅本指南和示例技能**。
* **规划文件夹结构**。
### **开发期间**
* **文件夹以 kebab-case（短横线命名法）命名**。
* **存在 SKILL.md 文件**（拼写需完全一致）。
* **YAML 前置内容（frontmatter）包含 `---` 分隔符**。
* **name 字段**：使用 kebab-case，无空格，无大写字母。
* **description（描述）**：包含“做什么（WHAT）”和“何时使用（WHEN）”。
* **不包含任何 XML 标签**（< >）。
* **指令清晰且具可操作性**。
* **包含错误处理**。
* **提供了示例**。
* **引用内容已清晰链接**。
### **上传之前**
* **在明显任务上测试了触发情况**。
* **在换种说法的请求上测试了触发情况**。
* **验证了在不相关主题上不会触发**。
* **功能测试通过**。
* **工具集成可正常工作**（如果适用）。
* **压缩为 .zip 文件**。
### **上传之后**
* **在真实对话中进行测试**。
* **监控触发不足或过度触发的情况**。
* **收集用户反馈**。
* **迭代优化描述和指令**。
* **在元数据（metadata）中更新版本号**。
## **参考 B：YAML 前置内容 (frontmatter)**
### **必需字段**
```yaml
---
name: skill-name-in-kebab-case
description: 技能的功能说明以及何时使用。包含具体的触发短语。
---
```
### **所有可选字段**
```yaml
name: skill-name
description: [必需的描述内容]
license: MIT # 可选：开源许可证
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" # 可选：限制工具访问权限
metadata: # 可选：自定义字段
author: 公司名称
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" 为前缀命名的技能**（这些是保留关键字）。
## **参考 C：完整技能示例**
以下是展示了本指南中所述模式的**完整、生产就绪型**技能：
* **文档技能 (Document Skills)** —— **[PDF](http://https//github.com/anthropics/skills/tree/main/skills/pdf)、[DOCX](https://github.com/anthropics/skills/tree/main/skills/docx)、[PPTX](https://github.com/anthropics/skills/tree/main/skills/pptx)、[XLSX](https://github.com/anthropics/skills/tree/main/skills/xlsx)** 的创建。
* **[示例技能 (Example Skills)](https://github.com/anthropics/skills/tree/main/skills)** —— 各种**工作流模式**。
* **[合作伙伴技能目录 (Partner Skills Directory)](https://www.claude.com/connectors)** —— 查看来自 **Asana、Atlassian、Canva、Figma、Sentry、Zapier** 等各种合作伙伴的技能。
这些仓库会**保持实时更新**，并包含本指南所涵盖内容之外的**附加示例**。您可以**克隆**这些仓库，根据您的实际用例进行**修改**，并将其作为**模板**使用。
## 参考资料
- [The Complete Guide to Building Skills for Claude](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf?hsLang=en)
- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)