The Complete Guide to Building Skill for Claude

发表于 2026-03-29 分类于书籍翻译

简介

Introduction

技能 (Skill) 是一组指令——封装为一个简单的文件夹中——它教会 Claude 如何处理特定的任务或工作流。技能是针对你的特定需求自定义 Claude 最强大的方式之一。与其在每次对话中重复解释你的偏好、流程和领域专业知识，技能让你只需教导 Claude 一次，便能持久受益。

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

本指南涵盖了构建有效技能所需了解的一切——从规划和结构到测试和分发（ from planning and structure to testing and distribution ）。无论你是为自己、为团队还是为社区构建技能，你都会在其中找到实用的模式和真实的案例。

你将学到：

技能结构（skill structure）的技术要求和最佳实践
独立技能和经由 MCP 增强的工作流模式（Patterns for standalone skills and MCP-enhanced workflows）
我们在不同用例中看到的行之有效的模式
如何测试、迭代（iterate）和分发你的技能

适用人群：

希望 Claude 能一致地遵循特定工作流的开发者
希望 Claude 能一致地遵循特定工作流的高级用户
希望在组织内部实现 Claude 工作方式标准化的团队

学习本指南的两条路径：

正在构建独立技能？关注基础知识、规划与设计，以及类别 1-2。正在增强 MCP 集成？关注“技能 + MCP”章节及类别 3。两条路径共享相同的技术要求，但你可以根据自己的用例选择相关内容。

你将从本指南中获得什么：

到最后，你将能够一次性构建出一个功能完备的技能。预计花费 15-30 分钟，你就能使用技能创建器 (skill-creator) 构建并测试你的第一个可用技能。

让我们开始吧。

Chapter 1 基础知识

Fundamentals

什么是技能 (skill)？

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

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

核心设计原则

1、渐进式披露 (Progressive Disclosure)

技能使用一个三层系统：

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

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

2、可组合性 (Composability)

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

3、可移植性 (Portability)

技能在 Claude.ai、Claude Code 和 API 上的运行方式完全相同。一次创建技能，即可在所有平台上无需修改地运行，前提是环境支持该技能所需的任何依赖项。

致 MCP 构建者：技能 + 连接器

Skills + Connectors

💡 正在构建不带 MCP 的独立技能？跳转到“规划与设计”部分——你稍后随时可以回到这里。

如果你已经有一个正在运行的 MCP 服务器，你已经完成了最难的部分。技能是顶层的知识层——捕捉你已经了解的工作流和最佳实践，以便 Claude 能够一致地应用它们。

厨房类比

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

技能提供菜谱：关于如何创造有价值事物的逐步指令。

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

它们如何协同工作：

MCP (连接性)	Skills (知识)
将 Claude 连接到您的服务 (Notion, Asana, Linear 等)	教会 Claude 如何有效地使用您的服务
提供实时数据访问和工具调用	捕捉工作流和最佳实践
Claude 能做什么	Claude 应该怎么做

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

如果没有技能 (Without skills)：

用户连接了您的 MCP，但不知道下一步该做什么
客服工单都在询问“我该如何通过您的集成实现 X”
每次对话都从零开始
结果不一致，因为用户每次的提示词 (prompt) 都不同
用户将责任归咎于您的连接器，而真正的问题在于缺乏工作流指导

有了技能 (With skills)：

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

Chapter 2 规划与设计

Planning and design

从用例 (Use cases) 开始

在编写任何代码之前，请确定您的技能应该实现的 2-3 个具体用例。

好的用例定义：

Use Case: Project Sprint Planning
Trigger: User says "help me plan this sprint" or "create
sprint tasks"
Steps:
1. Fetch current project status from Linear (via MCP)
2. Analyze team velocity and capacity
3. Suggest task prioritization
4. Create tasks in Linear with proper labels and estimates
Result: Fully planned sprint with tasks created

用例： 项目迭代规划 (Project Sprint Planning)

触发条件： 用户说“帮我规划这次迭代”或“创建迭代任务”

步骤：

从 Linear 获取当前项目状态（通过 MCP）

分析团队速率和容量

建议任务优先级

在 Linear 中创建带有适当标签和预估时间的任务

结果： 迭代规划完成并创建了相关任务

问问你自己：

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

常见的技能用例类别

在 Anthropic，我们观察到了三类常见的用例：

类别 1：文档与资产创建 (Document & Asset Creation)

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

真实案例： frontend-design-skill（另请参阅 skills for docx, pptx, xlsx, and ppt）

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

核心技巧：

嵌入风格指南和品牌标准
模板结构以确保输出一致
完成前的质量检查清单
无需外部工具 - 使用 Claude 的内置能力

类别 2：工作流自动化 (Workflow Automation)

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

真实案例： skill-creator 技能

“创建新技能的交互式指南。引导用户完成用例定义、前置内容 (frontmatter) 生成、指令编写和验证。”

核心技巧：

带有验证关卡(validation gates)逐步工作流
常用结构的模板
内置审查和改进建议
迭代优化循环

类别 3：MCP 增强 (MCP Enhancement)

用于：通过工作流指南来增强 MCP 服务器提供的工具访问能力。

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

“利用 Sentry 的错误监控数据（通过其 MCP 服务器），自动分析并修复 GitHub 拉取请求 (Pull Requests) 中检测到的错误。”

核心技巧：

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

定义成功标准

Define success criteria

如何判断您的技能运行良好？

这些是愿景目标——是粗略的基准而非精确的阈值。追求严谨，但也要接受评估中会存在“凭感觉 (vibes-based)”的成分。我们正在积极开发更强大的测量指南和工具。

定量指标：

技能在 90% 的相关查询中触发
- 如何测量： 运行 10-20 个应该触发该技能的测试查询。追踪它自动加载的次数 vs. 需要明确调用的次数。
在 X 次工具调用中完成工作流
- 如何测量： 比较在启用和不启用技能的情况下完成同一任务的情况。计算工具调用次数和消耗的总 Token 数。
每个工作流 0 次失败的 API 调用
- 如何测量： 在测试运行期间监控 MCP 服务器日志。追踪重试率和错误代码。

定性指标：

用户不需要就下一步动作提示 Claude
- 如何评估： 在测试期间，记录你需要重新引导或澄清的频率。向 Beta 测试用户征求反馈。
工作流无需用户纠正即可完成
- 如何评估： 运行同一个请求 3-5 次。比较输出的结构一致性和质量。
跨会话结果一致
- 如何评估： 新用户是否能在最少指导下，首次尝试就完成任务？

技术要求

Technical requirements

1、文件结构

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

2、关键规则

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.md —— 详见“分发与共享”章节。

3、YAML 前置内容 (frontmatter)：最重要的部分

YAML 前置内容是 Claude 决定是否加载你的技能的依据。务必确保其准确。

最小必需格式

---
name: your-skill-name
description: 它的功能是什么。当用户要求 [特定短语] 时使用。
---

这就是开始所需的全部内容。

4、字段要求

name（必需）：

仅限短横线命名法 (kebab-case)
无空格或大写字母
应与文件夹名称匹配

description（必需）：

必须包含以下两项：
- 技能的功能
- 何时使用（触发条件）
低于 1024 个字符
不含 XML 标签（< 或 >）
包含用户可能说的具体任务描述
如果相关，提及文件类型

license（可选）：

如果将技能开源时使用
常见协议：MIT, Apache-2.0

compatibility（可选）：

1-500 个字符
指明环境要求：例如目标产品、所需的系统软件包、网络访问需求等。

metadata（可选）：

任何自定义的键值对
建议包含：author（作者）, version（版本）, mcp-server（MCP 服务器）

示例：

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

5、安全限制 (Security restrictions)

前置内容 (frontmatter) 中禁止出现：

XML 尖括号 (< >)
名字中包含 "claude" 或 "anthropic" 的技能（这些是保留字）

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

编写有效的技能

Writing effective skills

1、描述 (description) 字段

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

结构：

1	[What it does] + [When to use it] + [Key capabilities]

1	[它的功能] + [何时使用它] + [核心能力]

优质描述示例：

# Good - specific and actionable
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".

# Good - includes trigger phrases
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".

# Good - clear value proposition
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: 分析 Figma 设计文件并生成开发者交付文档。当用户上传 .fig 文件，要求“设计规范”、“组件文档”或“设计转代码交付”时使用。
# 优：包含触发短语

description: 管理 Linear 项目工作流，包括迭代规划、任务创建和状态追踪。当用户提到“sprint（迭代）”、“Linear 任务”、“项目规划”，或要求“创建工单”时使用。
# 优：清晰的价值主张

description: 为 PayFlow 提供端到端的客户入职工作流。处理账户创建、支付设置和订阅管理。当用户要求“入职新客户”、“设置订阅”或“创建 PayFlow 账户”时使用。

劣质描述示例：

# Too vague
description: Helps with projects.

# Missing triggers
description: Creates sophisticated multi-page documentation
systems.

# Too technical, no user triggers
description: Implements the Project entity model with
hierarchical relationships.

# 太模糊

description: 帮助处理项目。
# 缺失触发条件

description: 创建复杂的、多页面的文档系统。
# 太过技术化，无用户触发词

description: 实现具有层级关系的项目实体模型。

2、编写主体指令 (Writing the main instructions)

在完成前置内容 (frontmatter) 后，请使用 Markdown 编写实际指令。

推荐结构：

*根据你的技能调整此模板。将括号部分(bracketed sections )_替换为你的具体内容。*

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

# 你的技能名称

## 指令

### 步骤 1：[第一个主要步骤]
清楚解释发生了什么。
预期输出：[描述成功时的样子]

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


# Your Skill Name

## Instructions

### Step 1: [First Major Step]
Clear explanation of what happens.

Example:
```bash
python scripts/fetch_data.py --project-id PROJECT_ID
Expected output: [describe what success looks like]

(根据需要添加更多步骤)

Examples

Example 1: [common scenario]

User says: "Set up a new marketing campaign"

Actions:

Fetch existing campaigns via MCP
Create new campaign with provided parameters

Result: Campaign created with confirmation link

(Add more examples as needed)

Troubleshooting

Error: [Common error message]

Cause: [Why it happens]

Solution: [How to fix]

(Add more error cases as needed)

**示例 (Examples)**

**示例 1：[常见场景]**
用户说：“设置一个新的营销活动”
动作：
1. 通过 MCP 获取现有营销活动
2. 使用提供的参数创建新活动
结果：活动已创建并附带确认链接
(根据需要添加更多示例)


**故障排除 (Troubleshooting)**
**错误：[常见错误信息]**
**原因：** [为什么会发生]
**解决方案：** [如何修复]
(根据需要添加更多错误案例)

指令的最佳实践

Best Practices for Instructions

具体且可操作 (Be Specific and Actionable)

✅ 优：

Run `python scripts/validate.py --input {filename}` to check
data format.
If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)

运行 python scripts/validate.py --input {filename} 来检查数据格式。

如果验证失败，常见问题包括：

缺失必需字段（请将其添加到 CSV 中）

日期格式无效（请使用 YYYY-MM-DD）

❌ 劣：

1	Validate the data before proceeding.

在继续操作前验证数据。

包含错误处理 (Include error handling)

## Common Issues
--# MCP Connection Failed
If you see "Connection refused":
1. Verify MCP server is running: Check Settings > Extensions
2. Confirm API key is valid
3. Try reconnecting: Settings > Extensions > [Your Service] >
Reconnect

## 常见问题

### MCP 连接失败
如果你看到 "Connection refused"（连接被拒绝）：
1. 验证 MCP 服务器是否正在运行：检查 设置 > 扩展
2. 确认 API 密钥有效
3. 尝试重新连接：设置 > 扩展 > [您的服务] > 重新连接

清晰地引用捆绑资源 (Reference bundled resources clearly)

Before writing queries, consult `references/api-patterns.md`
for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handling

在编写查询之前，请参考 references/api-patterns.md 获取：

速率限制指南

分页模式

错误代码及处理

使用渐进式披露 (Use progressive disclosure)

保持 SKILL.md 专注于核心指令。将详细文档移动到 references/ 目录并链接到它。（参见核心设计原则以了解三层系统的工作原理。）

Chapter 3 测试与迭代

Testing and iteration

根据您的需求，可以按不同严谨程度对技能进行测试：

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

选择与您的质量要求和技能可见度相匹配的方法。由小团队内部使用的技能与部署给数千名企业用户的技能具有不同的测试需求。

专业提示： 在扩展之前，先针对单一任务进行迭代。

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

使用 skill-creator 技能

Using the skill-creator skill

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

创建技能：

根据自然语言描述生成技能
生成格式正确的带前置内容的 SKILL.md
建议触发短语和结构

评审技能：

标记常见问题（模糊的描述、缺失触发词、结构性问题）
识别潜在的过度触发或触发不足风险
根据技能陈述的目的建议测试用例

迭代改进：

在使用技能并遇到边界情况或失败后，将这些示例带回 skill-creator
示例：“利用本次对话中确定的问题和解决方案，改进技能处理 [特定边界情况] 的方式(Use the issues & solution identified in this chat to improve how the skill handles [specific edge case])”

使用方法：

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

“使用 skill-creator 技能帮我为[您的使用场景]构建一个技能”

注：skill-creator 协助您设计和优化技能，但不会执行自动化测试套件或生成定量评估结果。

基于反馈的迭代

技能是动态文档(living documents.)。计划基于以下内容进行迭代：

触发不足信号：

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

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

过度触发信号：

技能在无关查询时加载
用户禁用它
对用途产生困惑

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

执行问题：

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

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

Chapter 4 分发与共享

Distribution and sharing

技能（Skills）使您的 MCP 集成更加完整。当用户比较连接器时，拥有技能的连接器能更快提供价值，使您在仅支持 MCP 的替代方案中脱颖而出。

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

个人用户如何获取技能：

下载技能文件夹
压缩文件夹（如有必要）
通过 设置 > 能力 > 技能 (Settings > Capabilities > Skills) 上传至 Claude.ai
或放置在 Claude Code 的技能目录中

组织级技能：

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

开放标准

我们已将 Agent Skills 作为一项开放标准发布。与 MCP 一样，我们认为技能应该是跨工具和平台可移植的——无论您使用的是 Claude 还是其他 AI 平台，同一个技能都应该可以运行。即便如此，某些技能旨在充分利用特定平台的功能；作者可以在技能的 compatibility（兼容性）字段中注明。我们一直与生态系统的成员就该标准进行合作，并对其早期被采用感到兴奋。

通过 API 使用技能

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

核心能力：

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

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

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

注意： API 中的技能需要代码执行工具（Code Execution Tool）测试版，它为技能运行提供了安全环境。

有关实现细节，请参阅：

技能 API 快速入门
创建自定义技能
Agent SDK 中的技能

现阶段推荐方法

首先将您的技能托管在 GitHub 的公共仓库中，配备清晰的 README（供人类访问者阅读——这与您的技能文件夹是分开的，技能文件夹内不应包含 README.md），以及带有截图的使用示例。然后在您的 MCP 文档中添加一个章节，链接到该技能，解释两者结合使用的价值，并提供快速入门指南。

托管在 GitHub

开源技能使用公共仓库
包含安装说明的清晰 README
使用示例和截图

在您的 MCP 仓库中记录

从 MCP 文档链接到技能
解释两者结合使用的价值
提供快速入门指南

创建安装指南

## Installing the [Your Service] skill
1. Download the skill:
- Clone repo: `git clone https://github.com/yourcompany/
skills`
- Or download ZIP from Releases
2. Install in Claude:
- Open Claude.ai > Settings > skills
- Click "Upload skill"
- Select the skill folder (zipped)
3. Enable the skill:
- Toggle on the [Your Service] skill
- Ensure your MCP server is connected
4. Test:
- Ask Claude: "Set up a new project in [Your Service]"

## 安装 [您的服务] 技能

1. 下载技能：

克隆仓库：git clone https://github.com/yourcompany/skills

或从 Releases 下载 ZIP 包

2. 在 Claude 中安装：

打开 Claude.ai > 设置 (Settings) > 技能 (skills)

点击“上传技能 (Upload skill)”

选择技能文件夹（压缩包）

3. 启用技能：

开启 [您的服务] 技能开关

确保您的 MCP 服务器已连接

4. 测试：

询问 Claude：“在 [您的服务] 中创建一个新项目”

技能定位

您对技能的描述决定了用户是否能理解其价值并真正尝试它。在编写关于技能的内容时（在 README、文档或营销资料中），请牢记以下原则。

关注结果，而非功能：

✅ 好：

"The ProjectHub skill enables teams to set up complete project workspaces in seconds — including pages, databases, and templates — instead of spending 30 minutes on manual setup."

“ProjectHub 技能使团队能在几秒钟内建立完整的项目工作区——包括页面、数据库和模板——而不是花费 30 分钟进行手动设置。”

❌ 差：

"The ProjectHub skill is a folder containing YAML frontmatter and Markdown instructions that calls our MCP server tools."

“ProjectHub 技能是一个包含 YAML 前置内容和 Markdown 指令的文件夹，用于调用我们的 MCP 服务器工具。”

突出 MCP + 技能的故事：

"Our MCP server gives Claude access to your Linear projects. Our skills teach Claude your team's sprint planning workflow. Together, they enable AI-powered project management."

“我们的 MCP 服务器让 Claude 能够访问您的 Linear 项目。我们的技能则教会 Claude 您团队的冲刺规划工作流。两者结合，实现了 AI 驱动的项目管理。”

Chapter 5 模式与故障排除

Patterns and troubleshooting

这些模式源自早期采用者和内部团队创建的技能。它们代表了我们观察到的行之有效的常见方法，而非强制性的模板。

选择您的路径：问题优先 vs. 工具优先

Choosing your approach: Problem-first vs. tool-first

可以把它想象成逛家装超市（Home Depot）。你可能带着问题走进来——“我需要修理厨房橱柜”——然后员工指引你使用正确的工具。或者，你可能挑选了一个新的钻机，然后询问针对你的具体工作该如何使用它。

技能的运作方式相同：

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

大多数技能会倾向于其中一个方向。了解哪种框架适合您的用例，有助于您选择下方的正确模式。

模式 1：顺序工作流编排

适用场景： 您的用户需要按特定顺序执行多步过程。

示例结构：

## Workflow: Onboard New Customer

### Step 1: Create Account
Call MCP tool: `create_customer`
Parameters: name, email, company

### Step 2: Setup Payment
Call MCP tool: `setup_payment_method`
Wait for: payment method verification

### Step 3: Create Subscription
Call MCP tool: `create_subscription`
Parameters: plan_id, customer_id (from Step 1)

### Step 4: Send Welcome Email
Call MCP tool: `send_email`
Template: welcome_email_template

## 工作流：入职新客户

### 步骤 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 协作

适用场景： 工作流跨越多个服务。

示例：从设计到开发的交付 (Design-to-development handoff)

### Phase 1: Design Export (Figma MCP)
1. Export design assets from Figma
2. Generate design specifications
3. Create asset manifest

### Phase 2: Asset Storage (Drive MCP)
1. Create project folder in Drive
2. Upload all assets
3. Generate shareable links

### Phase 3: Task Creation (Linear MCP)
1. Create development tasks
2. Attach asset links to tasks
3. Assign to engineering team

### Phase 4: Notification (Slack MCP)
1. Post handoff summary to #engineering
2. Include asset links and task references

### 阶段 1：设计导出 (Figma MCP)

从 Figma 导出设计资产

生成设计规范

创建资产清单 (Asset manifest)

### 阶段 2：资产存储 (Drive MCP)

在 Drive 中创建项目文件夹

上传所有资产

生成可共享链接

### 阶段 3：任务创建 (Linear MCP)

创建开发任务

将资产链接附加到任务中

分配给工程团队

### 阶段 4：通知 (Slack MCP)

向 #engineering 频道发布交付摘要

包含资产链接和任务引用

关键技术：

清晰的阶段划分
不同 MCP 之间的数据传递
进入下一阶段前的验证
集中式错误处理

模式 3：迭代优化

适用场景： 输出质量随迭代而提高。

## Iterative Report Creation

### Initial Draft
1. Fetch data via MCP
2. Generate first draft report
3. Save to temporary file

### Quality Check
1. Run validation script: `scripts/check_report.py`
2. Identify issues:
	- Missing sections
	- Inconsistent formatting
	- Data validation errors
	
### Refinement Loop
1. Address each identified issue
2. Regenerate affected sections
3. Re-validate
4. Repeat until quality threshold met

### Finalization
1. Apply final formatting
2. Generate summary
3. Save final version

示例：报告生成 (Report generation)

## 迭代式报告创建

### 初稿 (Initial Draft)

通过 MCP 获取数据

生成报告初稿

保存至临时文件

### 质量检查 (Quality Check)

运行验证脚本：scripts/check_report.py

识别问题：

章节缺失

格式不一致

数据验证错误

### 优化循环 (Refinement Loop)

解决每个识别出的问题

重新生成受影响的章节

重新验证

重复直到达到质量阈值

### 定稿 (Finalization)

应用最终格式

生成摘要

保存最终版本

关键技术：

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

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

Context-aware tool selection

适用场景： 目标相同，但根据具体上下文使用不同的工具。

示例：文件存储 (File storage)

## Smart File Storage

### Decision Tree
1. Check file type and size
2. Determine best storage location:
	- Large files (>10MB): Use cloud storage MCP
	- Collaborative docs: Use Notion/Docs MCP
	- Code files: Use GitHub MCP
	- Temporary files: Use local storage

### Execute Storage
Based on decision:
- Call appropriate MCP tool
- Apply service-specific metadata
- Generate access link

### Provide Context to User
Explain why that storage was chosen

## 智能文件存储

### 决策树 (Decision Tree)

检查文件类型和大小

确定最佳存储位置：

大文件 (>10MB)：使用云存储 MCP

协作文档：使用 Notion/Docs MCP

代码文件：使用 GitHub MCP

临时文件：使用本地存储

### 执行存储

基于决策：

调用相应的 MCP 工具

应用特定于服务的元数据

生成访问链接

### 向用户提供上下文

解释为什么选择了该存储位置

关键技术：

清晰的决策标准
备选方案 (Fallback options)
选择的透明度

模式 5：特定领域智能

Domain-specific intelligence

适用场景： 您的技能在工具访问之外增加了专业知识。

## Payment Processing with Compliance

### Before Processing (Compliance Check)
1. Fetch transaction details via MCP
2. Apply compliance rules:
	- Check sanctions lists
	- Verify jurisdiction allowances
	- Assess risk level
3. Document compliance decision

### Processing
IF compliance passed:
	- Call payment processing MCP tool
	- Apply appropriate fraud checks
	- Process transaction
ELSE:
	- Flag for review
	- Create compliance case

### Audit Trail
- Log all compliance checks
- Record processing decisions
- Generate audit report

示例：金融合规 (Financial compliance)

## 带合规检查的支付处理

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

通过 MCP 获取交易详情

应用合规规则：

检查制裁名单

核实司法管辖范围许可

评估风险等级

记录合规决策

### 处理 (Processing)

如果 (IF) 合规通过：

调用支付处理 MCP 工具

应用适当的欺诈检查

执行交易

否则 (ELSE)：

标记待人工审核

创建合规案件

### 审计追踪 (Audit Trail)

记录所有合规检查

记录处理决策

生成审计报告

关键技术：

逻辑中嵌入领域专业知识
动作前先行合规
详尽的文档记录
清晰的治理

故障排除 (Troubleshooting)

1、技能无法上传

错误信息："Could not find SKILL.md in uploaded folder"（在上传的文件夹中找不到 SKILL.md）

原因： 文件名不完全是 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
---

# Wrong - missing delimiters
name: my-skill
description: Does things
# Wrong - unclosed quotes
name: my-skill
description: "Does things
# Correct
---
name: my-skill
description: Does things
---

错误信息："Invalid skill name"（无效的技能名称）

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

YAML

# 错误
name: My Cool Skill

# 正确
name: my-cool-skill

2、技能未触发

症状： 技能从未自动加载。

修复方法：

修改您的 description（描述）字段。参考“描述字段”部分查看好坏示例。

快速自查清单：

描述是否太泛泛？（例如：“帮助处理项目”是行不通的）
是否包含用户实际会说的触发短语？
如果适用，是否提到了相关的文件类型？

调试方法：

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

3、技能触发过于频繁

症状： 技能在无关查询时也会加载。

解决方案：

1）. 添加负向触发 (Negative triggers)

示例：

1
2

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).
description: 用于 CSV 文件的高级数据分析。用于统计建模、回归、聚类。不要 (Do NOT)用于简单的数据探索（请改用 data-viz 技能）。

2）. 更加具体 (Be more specific)

# 太宽泛
description: Processes documents

# 更具体
description: Processes PDF legal documents for contract review
（处理用于合同审查的 PDF 法律文件）

3.）明确范围 (Clarify scope)

1
2

description: PayFlow payment processing for e-commerce. Use specifically for online payment workflows, not for general financial queries.
（PayFlow 电子商务支付处理。专门用于在线支付工作流，而非通用的财务查询。）

4、MCP 连接问题

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

检查清单：

1）验证 MCP 服务器是否已连接：

Claude.ai: 设置 (Settings) > 扩展 (Extensions) > [您的服务]
应该显示“已连接 (Connected)”状态。

2）检查身份验证：

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

3）独立测试 MCP：

要求 Claude 直接调用 MCP（不使用技能）。
“使用 [服务] MCP 来获取我的项目。”
如果此步失败，则问题出在 MCP 而非技能。

4）核对工具名称：

技能中引用的 MCP 工具名称是否正确。
检查 MCP 服务器文档。
工具名称区分大小写。

5、未遵循指令 (Instructions not followed)

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

常见原因：

1）指令太冗长：

保持指令简洁。
使用项目符号和数字列表。
将详细的参考资料移动到独立文件中。

2）指令被“埋没”：

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

3）语言模棱两可：

# 差
Make sure to validate things properly
（确保正确验证相关事项）

# 好
CRITICAL: Before calling create_project, verify:
- Project name is non-empty
- At least one team member assigned
- Start date is not in the past
（关键：在调用 create_project 之前，验证：项目名称不为空；至少分配了一名团队成员；开始日期不在过去。）

高级技术： 对于关键验证，考虑捆绑一个以编程方式执行检查的脚本，而不是依赖语言指令。代码是确定性的，而语言理解则不是。

4）模型“偷懒”： 添加明确的鼓励：

## Performance Notes
- Take your time to do this thoroughly
- Quality is more important than speed
- Do not skip validation steps
（性能备注：花时间彻底完成；质量比速度更重要；不要跳过验证步骤。）

注：将这些内容添加到用户提示词中，比放在 SKILL.md 中更有效。

6、大上下文问题 (Large context issues)

症状： 技能运行缓慢或响应质量下降

原因：

技能内容过于庞大
同时启用的技能过多
一次性加载了全部内容，而非采用渐进式呈现（progressive disclosure）

解决方案：

1）优化 SKILL.md 大小

将详细文档移至 references/ 目录
使用链接指向参考资料，而非在文中内联（inline）显示
保持 SKILL.md 在 5,000 字以内

2）减少启用的技能数量

评估是否同时启用了超过 20 - 50 个技能
建议选择性启用
考虑将相关功能打包成技能“包”（packs）

Chapter 6 资源与参考

Resources and references

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

官方文档

Anthropic 资源：

最佳实践指南 (Best Practices Guide)
技能文档 (Skills Documentation)
API 参考 (API Reference)
MCP 文档 (MCP Documentation)

博客文章：

Agent Skills 介绍
工程博客：为现实世界武装代理 (Equipping Agents for the Real World)
技能详解 (Skills Explained)
如何为 Claude 创建技能
为 Claude Code 构建技能
通过技能改进前端设计

示例技能

公共技能仓库：

GitHub: anthropics/skills
包含您可以自定义的 Anthropic 官方创建的技能。

工具与实用程序

skill-creator 技能：

内置于 Claude.ai 且适用于 Claude Code。
可以根据描述生成技能。
审查并提供优化建议。
使用方法：“帮我使用 skill-creator 构建一个技能”。

验证 (Validation)：

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

获取支持

技术问题：

通用问题：Claude 开发者 Discord 社区论坛。

Bug 报告：

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

参考 A：快速检查清单

在上传前后，使用此清单验证您的技能。如果您想更快开始，可以使用 skill-creator 技能生成初稿，然后对照此清单确保没有遗漏。

开始之前

确定了 2-3 个具体的使用场景
确定了工具（内置工具或 MCP）
阅读了本指南和示例技能
规划了文件夹结构

开发期间

上传前

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

上传后

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

参考 B：YAML 前置内容 (frontmatter)

必填字段

---
name: 以-短横线-隔开的-技能-名称
description: 该技能的作用以及何时使用。包含特定的触发词。
---

所有可选字段

name: 技能名称
description: [必填描述]
license: MIT # 可选：开源许可证
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" # 可选：限制工具访问权限
metadata: # 可选：自定义字段
  author: 公司名称
  version: 1.0.0
  mcp-server: 服务器名称
  category: 生产力
  tags: [项目管理, 自动化]
  documentation: https://example.com/docs
  support: support@example.com

安全注意事项

允许：

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

禁止：

XML 尖括号 (< >) - 安全限制
YAML 中的代码执行（使用安全 YAML 解析）
以 "claude" 或 "anthropic" 为前缀的技能名称（保留字段）

参考 C：完整技能示例

如需了解展示本指南中模式的完整、生产就绪型技能：

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

这些代码库保持实时更新，并包含此处未涵盖的其他示例。您可以克隆它们，根据您的使用场景进行修改，并将其用作模板。

参考D（个人增加）：Claude Code CLI 和 Skill比较

Claude Code CLI 和 Skill比较

在 Claude Code 的语境下，CLI 和 Skill 分别代表了它的“身体素质”和“专业技能书”。

Claude Code CLI：执行工具 (The Tool)

CLI 是 Claude Code 的基础运行形态。当你安装并在终端输入 claude 时，你就进入了它的 CLI 环境。

本质： 一个具备 Agent（智能体）能力的终端界面。
核心能力：
- 文件操作： 直接读取、写入和编辑你本地的项目文件。
- 命令执行： 它可以“代替你”在终端敲命令（如 npm run dev、pytest、git commit）。
- 环境感知： 它能看到报错信息、监听端口输出，并根据反馈自动修正代码。
比喻： 它是你的“全能实习生”。他坐在你的电脑前，手放在键盘上，你让他跑什么命令他就跑什么。

Claude Code Skill：知识与流程扩展 (The Playbook)

Skill 是对 Claude Code 能力的结构化扩展。它通过 YAML 配置文件定义，将特定的规则、工具调用和 Prompt 打包在一起。

本质： 一套可复用的标准化作业程序 (SOP)。
核心能力：
- 领域知识注入： 告诉 Claude 某种特定的代码风格（如“所有 React 组件必须使用 Tailwind”）。
- 复杂流程自动化： 将多个 CLI 步骤封装。例如，一个 deploy 技能可能包含了编译、跑测试、上传服务器、发送通知等一系列动作。
- 工具集成： 可以定义它能调用哪些外部工具（通过 MCP 或内建工具）。
调用方式： 通常在 Claude Code 界面中通过 / 指令触发（例如 /frontend-slides）。
比喻： 它是实习生手里拿的一本“高级操作手册”。这本手册告诉他：当遇到某种特定任务时，按照这一套流程去执行 CLI 命令。

核心区别对比

特性	CLI (命令行能力)	Skill (自定义技能)
存在形式	Claude Code 程序本身的功能	存储在 `.claude/skills/` 下的 YAML/指令集
解决的问题	“如何做？”（执行具体的增删改查）	“应该怎么做？”（遵循某种规范或复杂流程）
交互逻辑	AI 自由发挥，根据当前报错随机应变	严格遵循预定义的规则、模板和触发条件
复用性	通用，任何项目都能跑命令	专一，通常针对特定技术栈或团队规范
典型例子	`git add .` 或 `grep -r "TODO"`	`/make-pr` (自动写描述并提交) 或 `/audit` (安全审计)

总结

CLI 赋予了 Claude “手”（操作权限）和 “眼睛”（查看代码）。
Skill 赋予了 Claude “大脑中的经验”（知道你们公司的特殊规范、知道如何一步步完成复杂的部署）。

在实际使用中，你通过 Skill 告诉 Claude 任务的逻辑，而 Claude 最终通过 CLI 命令来落地执行这些逻辑。

CLI 和 Skill 的调用关系

在 Claude Code 或类似的 AI 开发工具中，CLI 和 Skill 的关系可以看作是“工具”与“剧本”的关系。

Skill（剧本）定义了任务的逻辑和规则，而 CLI（工具）*是实现这些逻辑的具体手段。它们通过 AI 的*推理引擎进行互调。

互调逻辑图解

通常的调用流向是：用户指令 → 触发 Skill → Skill 指导 AI 调用 CLI 执行命令。

加载阶段： AI 启动时读取 .claude/skills/ 下的 YAML 配置文件（即你之前图片里的 Frontmatter 内容）。
匹配阶段： 当你的对话命中 Skill 的 description 或 name 时，AI 会进入该 Skill 定义的“专业模式”。
执行阶段： Skill 内部的指令会告诉 AI：“在这种情况下，你应该使用终端执行 npm test，如果失败了，请读取报错文件。”
反馈阶段： CLI 执行后的输出（Stdout/Stderr）返回给 AI，AI 根据 Skill 的逻辑决定下一步动作。
举个具体的例子：自动测试与修复技能

假设你定义了一个名为 auto-fix-test 的 Skill。

Skill 定义 (YAML)

YAML

---
name: auto-fix-test
description: 运行本地单元测试，如果失败则自动修复代码。
allowed-tools: ["Bash"]
---
# 内部指令（Prompt）：
1. 首先在 CLI 执行 `npm test`。
2. 如果看到 "FAIL"，读取对应的测试文件和源代码。
3. 修复代码后再次执行 `npm test` 直到通过。

实际互调过程：

你（用户）： 输入 /auto-fix-test 或说“帮我修一下测试”。
Skill 触发： Claude 识别到这个 Skill，大脑切换到“测试修复专家”模式。
调用 CLI： * Claude 自动在终端输入：npm test（这是 CLI 的能力）。
- CLI 返回结果： AssertionError: expected 10 to be 20。
Skill 逻辑处理： Skill 的指令让 Claude 意识到必须解决这个错误。
再次调用 CLI：
- Claude 调用 CLI 读取文件：cat src/math.js。
- Claude 调用 CLI 修改文件：使用内建编辑器修改代码。
- Claude 再次调用 CLI 验证：npm test。
任务完成： CLI 返回 PASS，Skill 任务结束。

核心纽带：allowed-tools 字段

在你上传的图片中，有一个关键字段：

1	allowed-tools: "Bash(python:) Bash(npm:) WebFetch"

这就是 Skill 对 CLI 的“授权许可”：

它规定了这个 Skill 有权调用哪些 CLI 工具。
如果 Skill 没写 Bash，AI 就只能动嘴皮子（写代码块），而不能真的在你的终端里运行命令。

总结：

Skill 是策略，它告诉 AI “什么时候、按什么顺序、用什么规则”*去敲命令；CLI 是*接口，它负责“把命令发给操作系统并拿回结果”。

简介

Chapter 1 基础知识

什么是技能 (skill)？

核心设计原则

致 MCP 构建者：技能 + 连接器

厨房类比

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

Chapter 2 规划与设计

从用例 (Use cases) 开始

常见的技能用例类别

定义成功标准

技术要求

编写有效的技能

Examples

Troubleshooting

指令的最佳实践

Chapter 3 测试与迭代

推荐的测试方法

使用 skill-creator 技能

基于反馈的迭代

Chapter 4 分发与共享

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

开放标准

通过 API 使用技能

现阶段推荐方法

## 安装 [您的服务] 技能

技能定位

Chapter 5 模式与故障排除

模式 1：顺序工作流编排

## 工作流：入职新客户

### 步骤 1：创建账户

### 步骤 2：设置支付方式

### 步骤 3：创建订阅

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

模式 2：多 MCP 协作

### 阶段 1：设计导出 (Figma MCP)

### 阶段 2：资产存储 (Drive MCP)

### 阶段 3：任务创建 (Linear MCP)

### 阶段 4：通知 (Slack MCP)

模式 3：迭代优化

## 迭代式报告创建

### 初稿 (Initial Draft)

### 质量检查 (Quality Check)

### 优化循环 (Refinement Loop)

### 定稿 (Finalization)

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

## 智能文件存储

### 决策树 (Decision Tree)

### 执行存储

### 向用户提供上下文

模式 5：特定领域智能

## 带合规检查的支付处理

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

### 处理 (Processing)

### 审计追踪 (Audit Trail)

故障排除 (Troubleshooting)

Chapter 6 资源与参考

官方文档

示例技能

工具与实用程序

获取支持

参考 A：快速检查清单

参考 B：YAML 前置内容 (frontmatter)

参考 C：完整技能示例

参考D（个人增加）：Claude Code CLI 和 Skill比较

Claude Code CLI 和 Skill比较

CLI 和 Skill 的调用关系