ThinkLab

引言

技能（Skill） 是一组指令——以一个简单的文件夹形式打包——用于教会 Claude 如何处理特定任务或工作流程。技能是根据你的具体需求自定义 Claude 的最强大方式之一。你无需在每次对话中重复解释你的偏好、流程和领域知识，只需教授 Claude 一次，便可持续受益。

当你拥有可重复的工作流程时，技能尤为强大：例如根据规格生成前端设计、使用一致的方法进行研究、创建符合团队风格指南的文档，或编排多步骤流程。技能可以很好地结合 Claude 的内置功能，例如代码执行和文档创建。对于构建 MCP 集成的用户而言，技能还增加了一层强大的能力，将原始工具访问转化为可靠且优化的工作流程。

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

你将学习：

技能结构的技术要求与最佳实践
独立技能与 MCP 增强型工作流程 的模式
我们在不同使用场景中观察到的有效模式
如何测试、迭代并分发你的技能

本指南适合：

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

阅读本指南的两条路径

正在构建独立技能？请重点关注“基础”、“规划与设计”以及第 1–2 类内容。

正在增强 MCP 集成？请查看“Skills + MCP”部分以及第 3 类内容。

两条路径遵循相同的技术要求，但你可以根据自身使用场景选择相关内容。

你将从本指南中获得什么

完成本指南后，你将能够在一次专注的实践中构建一个可用的技能。

预计使用 skill-creator 构建并测试你的第一个可运行技能，大约需要 15–30 分钟。

让我们开始吧。

基础

什么是技能？

一个技能是一个文件夹，包含：

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

核心设计原则

渐进式披露

技能采用三层结构系统：

第一层（YAML frontmatter）：始终加载到 Claude 的系统提示中。提供足够的信息，使 Claude 知道何时使用该技能，而无需将全部内容加载到上下文中。
第二层（SKILL.md 正文）：当 Claude 认为该技能与当前任务相关时加载。包含完整的指令和指导内容。
第三层（关联文件）：技能目录中打包的其他文件，Claude 仅在需要时选择性地导航和读取。

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

可组合性

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

可移植性

技能在 Claude.ai、Claude Code 和 API 中的工作方式完全一致。只需创建一次技能，即可在所有环境中使用（前提是运行环境支持该技能所需的依赖）。

面向 MCP 构建者：技能 + 连接器

💡 如果你正在构建不依赖 MCP 的独立技能，可以跳过本节，直接前往“规划与设计”——你也可以稍后再回到这里。

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

厨房类比

MCP 提供的是一个专业厨房：可访问工具、食材和设备。

技能提供的是食谱：关于如何创造有价值成果的分步说明。

两者结合，使用户能够完成复杂任务，而无需自己摸索每一个步骤。

它们如何协同工作

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

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

没有技能时：

用户连接了你的 MCP，却不知道下一步该做什么
收到大量“如何通过你的集成完成 X？”的支持请求
每次对话都从零开始
由于用户每次提示方式不同，结果不一致
用户将问题归咎于你的连接器，而真正的问题是缺乏工作流程指导

有技能时：

预构建的工作流程在需要时自动激活
一致、可靠的工具使用方式
每次交互都嵌入最佳实践
显著降低你的集成产品的学习成本

规划与设计

从使用场景开始

在编写任何代码之前，先确定你的技能应当支持 2–3 个具体使用场景。

良好的使用场景定义示例：

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

通过 Linear 获取当前项目状态（通过 MCP）
分析团队速度与产能
给出任务优先级建议
在 Linear 中创建任务，并添加正确的标签与工时估算结果：冲刺规划完成，任务已创建

问问自己：

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

常见的技能使用场景类别

在 Anthropic，我们观察到三类常见使用场景：

类别：文档与资产创建

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

真实示例：frontend-design 技能（也可参考用于 docx、pptx、xlsx 和 ppt 的技能）

“创建具有鲜明风格、可用于生产环境的前端界面，并具备高设计质量。在构建 Web 组件、页面、制品（artifacts）、海报或应用时使用。”

关键技巧：

内置风格指南与品牌标准
用模板结构确保输出一致
在最终交付前使用质量检查清单
无需外部工具——使用 Claude 的内置能力

类别：工作流自动化

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

真实示例：skill-creator 技能

“用于创建新技能的交互式指南。引导用户完成使用场景定义、frontmatter 生成、指令撰写与校验。”

关键技巧：

带校验关口的分步工作流
常见结构的模板
内置审阅与改进建议
迭代式精炼循环

类别：MCP 增强

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

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

“通过其 MCP 服务器使用 Sentry 的错误监控数据，自动分析并修复 GitHub Pull Request 中检测到的缺陷。”

关键技巧：

顺序协调多个 MCP 调用
嵌入领域专长
提供用户原本需要自行指定的上下文
针对常见 MCP 问题的错误处理

定义成功标准

你如何判断技能是否在正常工作？

这些是理想化目标——更像粗略基准，而非精确阈值。追求严谨，但也要接受其中会包含一定的“氛围式”评估。我们正在积极开发更健壮的度量指南与工具。

定量指标

技能在 90% 的相关查询中被触发
- 如何测量：运行 10–20 条本应触发技能的测试查询，记录自动加载次数与需要显式调用的次数。
在 X 次工具调用内完成工作流
- 如何测量：对比启用技能与不启用技能时的同一任务，统计工具调用次数与总 token 消耗。
每个工作流 0 次失败的 API 调用
- 如何测量：在测试运行期间监控 MCP 服务器日志，跟踪重试率与错误码。

定性指标

用户不需要提示 Claude 下一步做什么
- 如何评估：测试时记录你需要重定向或澄清的频率，并向内测用户收集反馈。
工作流能够在无需用户纠正的情况下完成
- 如何评估：对同一请求运行 3–5 次，对比输出的结构一致性与质量。
跨会话结果一致
- 如何评估：新用户是否能在几乎不需要额外引导的情况下，一次就完成任务？

技术要求

文件结构

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 分发时，你仍然会需要一个仓库级别的 README 供人类阅读——参见“分发与共享”。

YAML frontmatter：最重要的部分

YAML frontmatter 决定了 Claude 是否加载你的技能。务必把它写对。

最小必需格式

---
name: your-skill-name
description: 它做什么。当用户询问 [具体短语] 时使用。
---

这就是开始所需的一切。

字段要求

`name`（必需）

仅允许 kebab-case
不要空格或大写
应与文件夹名一致

`description`（必需）

必须同时包含：
- 技能做什么
- 何时使用（触发条件）
少于 1024 个字符
不含 XML 标签（不要出现 < 或 >）
包含用户可能说出的具体任务表达
如相关，请提及文件类型

`license`（可选）

当你将技能开源时使用
常见值：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 的技能（保留字段）

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

编写高效技能

`description` 字段

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

结构：

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

良好的 description 示例：

# 好 - 具体且可执行
description: 分析 Figma 设计文件并生成开发交接文档。当用户上传 .fig 文件，或要求“设计规格”“组件文档”“设计到代码交接”时使用。

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

# 好 - 价值主张清晰
description: 面向 PayFlow 的端到端客户入驻工作流。处理账户创建、支付设置与订阅管理。当用户说“onboard new customer”“set up subscription”或“create PayFlow account”时使用。

糟糕的 description 示例：

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

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

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

编写主要指令

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

推荐结构：

根据你的技能改写这个模板，将方括号内容替换为你的具体内容。

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

# 你的技能名称

# 指令

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

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

期望输出：[描述成功时应当是什么样子]

（按需添加更多步骤）

示例

示例 1：[常见场景]
用户说：“建立一个新的营销活动”
动作：
1. 通过 MCP 获取现有活动
2. 使用给定参数创建新活动
结果：活动创建完成，并提供确认链接

（按需添加更多示例）

故障排除

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

（按需添加更多错误场景）

指令最佳实践

具体且可执行

✅ 好：

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

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

❌ 不好：

在继续之前验证数据。

包含错误处理

# 常见问题

### MCP 连接失败
如果你看到 “Connection refused”：

1. 确认 MCP 服务器正在运行：检查 `Settings > Extensions`
2. 确认 API key 有效
3. 尝试重新连接：`Settings > Extensions > [你的服务] > Reconnect`

清晰引用随附资源

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

限流（rate limiting）指导
分页（pagination）模式
错误码与处理方式

使用渐进式披露

让 SKILL.md 聚焦于核心指令。将详细文档移到 references/ 并在此处链接。（关于三层系统如何工作，参见“核心设计原则”。）

测试与迭代

技能可以根据你的需求采用不同程度的测试严格性：

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

选择与你的质量要求和技能可见度相匹配的方法。一个仅供小团队内部使用的技能，与一个部署给成千上万企业用户的技能，其测试需求显然不同。

专业提示：先打磨单一任务，再扩展

我们发现，最有效的技能创建者通常会围绕一个具有挑战性的任务不断迭代，直到 Claude 成功完成，然后再将成功的方法提炼为技能。这种方式能够充分利用 Claude 的 in-context learning，并比大范围测试更快获得有效反馈。一旦你拥有可行的基础，再扩展到多个测试用例以覆盖更多场景。

触发测试

目标：确保技能在正确的时机加载。

测试内容：

✅ 在明显相关任务中触发
✅ 在改写表达的请求中触发
❌ 在无关主题中不触发

示例测试集：

应当触发：

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

不应触发：

“旧金山今天天气如何？”
“帮我写 Python 代码”
“创建一个电子表格”（除非 ProjectHub 技能处理表格）

功能测试

目标：验证技能生成正确输出。

测试内容：

生成有效输出
API 调用成功
错误处理机制有效
覆盖边界情况

示例：

测试：创建包含 5 个任务的项目

已知：项目名称为 “Q4 Planning”，提供 5 条任务描述当：技能执行工作流则：

在 ProjectHub 中创建项目
创建 5 个属性正确的任务
所有任务均关联到该项目
无 API 错误

性能对比

目标：证明技能相较基线方式有改进。

使用“定义成功标准”中的指标。对比示例如下：

基线对比：

未使用技能：

用户每次都需提供完整指令
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
示例：“使用本次对话中识别的问题和解决方案，改进技能在处理 [具体边界情况] 时的方式”

使用方式：

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

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

基于反馈的迭代

技能是持续演进的文档。应根据以下信号进行迭代：

触发不足信号

技能在应触发时未加载
用户手动启用技能
用户询问何时使用该技能

解决方案：在 description 中增加更多细节与语义区分，特别是补充技术关键词。

过度触发信号

技能在无关查询中加载
用户主动禁用技能
用户对技能用途感到困惑

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

执行问题

输出结果不一致
API 调用失败
需要用户进行纠正

解决方案：改进指令内容，增加错误处理机制。

分发与共享

技能让你的 MCP 集成更加完整。当用户比较不同连接器时，带有技能的方案能够更快带来价值，从而在仅提供 MCP 的替代方案中脱颖而出。

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

个人用户如何获取技能

下载技能文件夹
（如有需要）将文件夹压缩为 ZIP
在 Claude.ai 中通过 Settings > Capabilities > Skills 上传
或将其放入 Claude Code 的 skills 目录

组织级技能

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

开放标准

我们已将 Agent Skills 发布为开放标准。与 MCP 类似，我们相信技能应当可以跨工具和平台移植——同一个技能应当既可在 Claude 上使用，也可在其他 AI 平台上运行。

当然，某些技能可能专门设计用于充分利用特定平台的能力；作者可以在技能的 compatibility 字段中注明这一点。我们一直在与生态系统成员合作推进这一标准，并对早期采用情况感到振奋。

通过 API 使用技能

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

关键能力：

使用 /v1/skills 端点列出和管理技能
在 Messages API 请求中通过 container.skills 参数添加技能
通过 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，它为技能运行提供安全环境。

有关实现细节，请参阅：

Skills API Quickstart
Create Custom Skills
Skills in the Agent SDK

当前推荐做法

首先，在 GitHub 上创建一个公开仓库来托管你的技能，提供清晰的 README（供人类读者使用——注意，这与技能文件夹内部不同，技能文件夹中不应包含 README.md），并附带示例用法与截图。随后，在你的 MCP 文档中添加相关章节，链接到该技能，说明二者结合的价值，并提供快速入门指南。

在 GitHub 上托管

为开源技能创建公开仓库
提供清晰的 README 与安装说明
展示示例用法和截图

在你的 MCP 仓库中编写文档

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

创建安装指南

# 安装 [你的服务] 技能

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

2. 在 Claude 中安装：
   - 打开 Claude.ai > Settings > Skills
   - 点击 “Upload skill”
   - 选择技能文件夹（ZIP 格式）

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

4. 测试：
   - 向 Claude 提问：“在 [你的服务] 中创建一个新项目”

为你的技能定位

你如何描述技能，将直接决定用户是否理解其价值并愿意尝试。在 README、文档或市场推广材料中撰写技能介绍时，请牢记以下原则。

关注结果，而非功能

✅ 好：

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

❌ 不好：

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

强调 MCP + 技能的协同价值

“我们的 MCP 服务器让 Claude 能访问你的 Linear 项目。我们的技能教会 Claude 你的团队如何进行冲刺规划。两者结合，实现 AI 驱动的项目管理。”

模式与故障排除

这些模式来自早期采用者与内部团队创建的技能。它们代表我们观察到的常见有效方法，并非规定性的模板。

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

把它想象成去 Home Depot。你可能带着一个问题走进去——“我需要修好厨房橱柜”——店员会把你指向正确的工具。或者你先挑了一把新电钻，然后问怎样把它用于你的具体工作。

技能的工作方式也一样：

问题优先： “我需要搭建一个项目工作区” → 你的技能以正确顺序编排合适的 MCP 调用。用户描述目标结果；技能处理工具细节。
工具优先： “我已连接 Notion MCP” → 你的技能教会 Claude 最优工作流与最佳实践。用户已有访问权限；技能提供专业方法。

大多数技能会偏向其中一个方向。明确哪种表述更适合你的使用场景，有助于你选择下面的正确模式。

模式：顺序式工作流编排

适用场景：用户需要按特定顺序执行多步骤流程。

示例结构：

# 工作流：为新客户办理入驻

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

关键技巧：

明确的步骤顺序
步骤之间的依赖关系
每一阶段都进行校验
失败时的回滚指令

模式：多 MCP 协同

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

示例：设计到开发交接（Design-to-development handoff）

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

从 Figma 导出设计资产
生成设计规格说明
创建资产清单

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

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

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

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

阶段 4：通知（Slack MCP）

将交接摘要发布到 #engineering
包含资产链接与任务引用

关键技巧：

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

模式：迭代式精炼

适用场景：输出质量会随着迭代而提升。

示例：报告生成

# 迭代式报告创建

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

### 质量检查
1. 运行校验脚本：`scripts/check_report.py`
2. 识别问题：
   - 缺失章节
   - 格式不一致
   - 数据校验错误

### 精炼循环
1. 逐条修复识别到的问题
2. 重新生成受影响的章节
3. 再次校验
4. 重复直到达到质量阈值

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

关键技巧：

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

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

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

示例：文件存储

# 智能文件存储

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

### 执行存储
基于决策：
- 调用相应的 MCP 工具
- 应用服务特定的元数据
- 生成访问链接

### 向用户提供上下文
解释为何选择该存储方案

关键技巧：

清晰的决策标准
回退方案
对选择保持透明

模式：领域特定智能

适用场景：你的技能在工具访问之外，还能提供专门知识。

示例：金融合规

# 带合规的支付处理

### 处理前（合规检查）
1. 通过 MCP 获取交易详情
2. 应用合规规则：
   - 检查制裁名单
   - 验证司法辖区允许范围
   - 评估风险等级
3. 记录合规决策

### 处理
如果合规通过：
 - 调用支付处理 MCP 工具
 - 应用适当的反欺诈检查
 - 处理交易
否则：
 - 标记为需要复核
 - 创建合规案例

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

关键技巧：

在逻辑中嵌入领域专长
行动前先合规
完整的文档记录
清晰的治理机制

故障排除

技能无法上传

错误：“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

技能不触发

症状：技能从不自动加载修复：修改你的 description 字段。参考“description 字段”中的好/坏示例。

快速检查清单：

是否过于泛化？（例如“帮助处理项目”基本不会触发）
是否包含用户实际会说的触发短语？
如适用，是否提及相关文件类型？

调试方法：

问 Claude：“你会在什么时候使用 [skill name] 技能？” Claude 会把 description 引用回来。根据缺失内容进行调整。

技能触发过于频繁

症状：技能在无关查询中加载解决方案：

添加负向触发条件

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

更加具体

# 过于宽泛
description: 处理文档

# 更具体
description: 处理 PDF 法律文档，用于合同审查

明确范围边界

description: 面向电商的 PayFlow 支付处理。仅用于在线支付工作流，不用于一般金融问题。

MCP 连接问题

症状：技能会加载，但 MCP 调用失败检查清单：

确认 MCP 服务器已连接
- Claude.ai：Settings > Extensions > [你的服务]
- 应显示 “Connected” 状态
检查认证
- API key 有效且未过期
- 权限/作用域（scopes）授予正确
- OAuth token 已刷新
独立测试 MCP
- 让 Claude 直接调用 MCP（不使用技能）
- 例如：“使用 [Service] MCP 获取我的项目”
- 如果这里失败，问题在 MCP 而非技能
验证工具名称
- 技能引用的 MCP 工具名必须正确
- 查阅 MCP 服务器文档
- 工具名 区分大小写

指令未被遵循

症状：技能加载了，但 Claude 没按指令执行常见原因：

指令过于冗长

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

关键指令被埋没

把关键指令放在最上方
使用 ## Important 或 ## Critical 标题
必要时重复关键点

语言含糊

# 不好
确保把东西正确验证一下

# 好
CRITICAL：在调用 `create_project` 之前，必须验证：
- 项目名称非空
- 至少分配一名团队成员
- 开始日期不早于今天

高级技巧：对于关键校验，考虑随技能打包一个脚本，以程序化方式执行检查，而不是依赖语言指令。 代码是确定性的；语言解释不是。 可参考 Office 系列技能中的这种模式示例。

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

# 性能说明
- 请慢慢来，务必彻底完成
- 质量比速度更重要
- 不要跳过验证步骤

注意：把这些内容加入用户提示（user prompts）通常比写进 SKILL.md 更有效。

大上下文问题

症状：技能看起来很慢，或回复质量下降原因：

技能内容过大
同时启用的技能过多
未使用渐进式披露，导致内容一次性加载

解决方案：

优化 SKILL.md 体积

将详细文档移到 references/
用链接引用 references/，不要内联全部内容
将 SKILL.md 控制在 5,000 词以内

减少启用的技能数量

评估是否同时启用了超过 20–50 个技能
建议选择性启用
可考虑为相关能力制作技能“套装（packs）”

资源与参考

如果你正在构建第一个技能，建议先阅读 Best Practices Guide，然后根据需要查阅 API 文档。

官方文档

Anthropic 资源

Best Practices Guide
Skills Documentation
API Reference
MCP Documentation

博客文章

Introducing Agent Skills
Engineering Blog: Equipping Agents for the Real World
Skills Explained
How to Create Skills for Claude
Building Skills for Claude Code
Improving Frontend Design through Skills

示例技能

公共技能仓库

GitHub: 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 社区论坛

Bug 报告

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

参考 A：快速检查清单

在上传前后，使用此清单验证你的技能。如果你想更快开始，可以使用 skill-creator 生成初稿，然后通过此列表确认没有遗漏。

开始前

已确定 2–3 个具体使用场景
已识别所需工具（内置或 MCP）
已阅读本指南和示例技能
已规划文件夹结构

开发过程中

文件夹名称为 kebab-case
存在 SKILL.md 文件（拼写完全正确）
YAML frontmatter 包含 --- 分隔符
name 字段为 kebab-case，无空格、无大写
description 包含 做什么（WHAT） 和 何时使用（WHEN）
不包含 XML 标签（< >）
指令清晰且可执行
包含错误处理
提供示例
清晰链接参考资料

上传前

测试在明显任务中触发
测试在改写请求中触发
确认不会在无关主题中触发
功能测试通过
工具集成正常（如适用）
已压缩为 .zip 文件

上传后

在真实对话中测试
监控触发不足或过度触发
收集用户反馈
迭代优化 description 和指令
在 metadata 中更新版本号

参考 B：YAML frontmatter

必需字段

---
name: 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 类型（字符串、数字、布尔值、列表、对象）
自定义 metadata 字段
较长描述（最多 1024 字符）

禁止：

XML 尖括号（< >）——出于安全限制
在 YAML 中执行代码（使用安全 YAML 解析）
技能名称以 claude 或 anthropic 为前缀（保留）

参考 C：完整技能示例

如需查看展示本指南模式的完整、生产级技能，请参考：

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

这些仓库会保持更新，并包含超出本文范围的更多示例。你可以克隆它们，根据自身使用场景进行修改，并将其作为模板使用。

目录

引言

你将学习：

本指南适合：

阅读本指南的两条路径

你将从本指南中获得什么

基础

什么是技能？

核心设计原则

渐进式披露

可组合性

可移植性

面向 MCP 构建者：技能 + 连接器

厨房类比

它们如何协同工作

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

没有技能时：

有技能时：

规划与设计

从使用场景开始

常见的技能使用场景类别

类别：文档与资产创建

类别：工作流自动化

类别：MCP 增强

定义成功标准

定量指标

定性指标

技术要求

文件结构

关键规则

SKILL.md 命名

技能文件夹命名

不要 README.md

YAML frontmatter：最重要的部分

最小必需格式

字段要求

name（必需）

description（必需）

license（可选）

compatibility（可选）

metadata（可选）

安全限制

编写高效技能

description 字段

编写主要指令

示例

故障排除

指令最佳实践

具体且可执行

包含错误处理

清晰引用随附资源

使用渐进式披露

测试与迭代

专业提示：先打磨单一任务，再扩展

推荐测试方法

触发测试

功能测试

性能对比

使用 skill-creator 技能

基于反馈的迭代

触发不足信号

过度触发信号

执行问题

分发与共享

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

个人用户如何获取技能

组织级技能

开放标准

通过 API 使用技能

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

当前推荐做法

在 GitHub 上托管

在你的 MCP 仓库中编写文档

创建安装指南

为你的技能定位

关注结果，而非功能

强调 MCP + 技能的协同价值

模式与故障排除

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

模式：顺序式工作流编排

`SKILL.md` 命名

不要 `README.md`

`name`（必需）

`description`（必需）

`license`（可选）

`compatibility`（可选）

`metadata`（可选）

`description` 字段

`skill-creator` 技能