如何为 Claude 构建技能：一份完整的指南

最近，人工智能的发展日新月异。我们与 AI 的交互方式，正在从简单的对话，走向更复杂的任务协作。一个明显的趋势是，我们希望 AI 不仅仅是一个知识问答引擎，更能成为一个能理解我们特定工作流程、并能自主完成任务的“智能助理”。

在这个背景下，Anthropic 公司为他们的 AI 模型 Claude 提出一个叫做“技能”（Skills）的概念。这套机制，允许我们把特定的指令、流程和知识“教会”给 Claude，让它在处理特定任务时，能像一个经验丰富的专家那样，有条不紊、高度定制化地完成工作。

这就像我们不再满足于一个什么都懂一点的通才，而是开始培养一个个“专才”——有的擅长帮你规划项目，有的精通将设计稿转化为代码，有的则能严格遵循你的公司规范来撰写文档。

Anthropic 发布了一份官方指南，详细介绍了如何构建这些“技能”。我觉得这份文档很有价值，它不仅是写给开发者的技术手册，更揭示了未来我们与 AI 协作的一种新范式。因此，我将这份指南的核心内容翻译并整理出来，希望能给大家带来一些启发。

一、基础知识：什么是“技能”？

首先，我们要理解“技能”到底是什么。简单来说，一个“技能”就是一个包含了特定指令和资源的文件夹。通过这个文件夹，我们等于给 Claude 安装了一个“插件”或“扩展”，让它学会一项新本领。

一个标准的“技能”文件夹结构如下：

your-skill-name/
├── SKILL.md          # 核心文件，包含指令和元数据（必需）
├── scripts/            # 存放可执行脚本，如 Python、Bash 等（可选）
│   ├── process_data.py
│   └── validate.sh
├── references/         # 存放参考文档，供 Claude 按需阅读（可选）
│   └── api-guide.md
└── assets/             # 存放模板、图标等静态资源（可选）

它的核心设计思想，可以总结为以下几点：

1. 渐进式披露（Progressive Disclosure）

为了在提供强大能力的同时，不占用过多的计算资源（也就是我们常说的“tokens”），“技能”采用了一种三级信息加载机制：

• 第一级：元数据（YAML Frontmatter）。 这是 SKILL.md 文件头部的几行配置信息。它会常驻在 Claude 的“系统提示”中，像一个索引目录，告诉 Claude “我有这个技能，它大概是做什么的”。这部分内容极少，消耗资源可以忽略不计。

• 第二级：核心指令（SKILL.md Body）。 当 Claude 判断当前用户的请求与某个“技能”相关时，它才会去加载 SKILL.md 的正文。这里包含了完成任务所需的详细步骤和指南。

• 第三级：外部文件（Linked Files）。 如果核心指令还不够，SKILL.md 里面可以链接到 scripts/ 或 references/ 目录下的其他文件。Claude 只有在绝对必要时，才会去读取这些文件。

这种设计非常精妙，它确保了系统的高效运转，只在需要时才加载必要的信息。

2. 可组合性（Composability）

Claude 可以同时加载多个“技能”。这意味着我们编写的“技能”不是孤立的，它需要能和其他“技能”协同工作。比如，一个“项目管理”技能可以和一个“文档生成”技能组合，先从项目管理工具（如 Asana）中获取任务列表，然后自动生成一份周报文档。

3. 可移植性（Portability）

一次创建，处处运行。一个“技能”在 Claude.ai 网站、Claude Code（代码环境）以及通过 API 调用时，其行为应该是一致的。这大大降低了开发和维护成本。

“技能”与 MCP 的关系

对于开发者来说，这里还有一个重要的概念：MCP（Model Context Protocol）。你可以把它理解为一个连接器，它让 Claude 能够与外部的 API 和服务进行通信。

官方用了一个很形象的比喻：

MCP 提供了一个专业厨房：里面有各种工具、食材和设备（比如连接了 Notion、Jira、GitHub 的 API）。

“技能”则提供了菜谱：一步步教你如何使用这些工具和食材，做出一道道美味佳肴（比如“如何使用 Jira 和 GitHub 创建一个完整的开发工作流”）。

简单来说：

• MCP 解决的是“能做什么”（连接外部世界）。
• “技能”解决的是“应该怎么做”（提供工作流程和最佳实践）。

两者结合，就能让 Claude 真正成为一个强大的自动化引擎。用户不再需要自己摸索如何一步步调用工具，而是可以直接通过自然语言，触发一个预设好的、可靠的工作流。

---

二、规划与设计：谋定而后动

任何软件开发项目，前期的规划和设计都至关重要。构建“技能”也不例外。一个好的“技能”，不是一上来就写指令，而是要先想清楚三个问题：它的应用场景是什么？成功的标准是什么？技术上需要满足哪些要求？

1. 从应用场景出发

首先，要明确你的“技能”是用来解决什么具体问题的。官方总结了三类常见的应用场景：

第一类：文档与资产创作（Document & Asset Creation）

这类“技能”专注于生成格式统一、质量稳定的产出物，比如文档、演示文稿、设计稿、代码等。它通常不需要调用外部工具，而是充分利用 Claude 自身强大的内容生成能力。

真实案例：frontend-design 技能

• 描述：“创建独特、生产级别的、具有高设计质量的前端界面。当需要构建网页组件、页面、海报或应用程序时使用。”
• 关键技术：内置风格指南、品牌标准、模板结构、质量检查清单。

第二类：工作流自动化（Workflow Automation）

这类“技能”用于固化一个多步骤的流程，确保每次执行都遵循同样的方法论。它像一个交互式的向导，一步步引导用户完成复杂操作。

真实案例：skill-creator 技能

• 描述：“一个用于创建新‘技能’的交互式指南。它会引导用户完成应用场景定义、元数据生成、指令编写和验证的全过程。”
• 关键技术：带验证关卡的步骤化工作流、常用结构模板、内置审查和改进建议。

第三类：MCP 增强（MCP Enhancement）

这类“技能”是 MCP 连接器的“大脑”，它为 Claude 提供了如何有效使用外部工具的“领域知识”。它负责将零散的 API 调用，编排成一个有意义的工作流。

真实案例：sentry-code-review 技能

• 描述：“通过 Sentry 的 MCP 服务器，利用其错误监控数据，自动分析并修复 GitHub Pull Request 中检测到的 Bug。”
• 关键技术：按顺序协调多个 MCP 调用、嵌入领域知识、处理常见的 MCP 错误。

2. 定义成功的标准

你怎么知道你的“技能”是有效的？我们需要一些可衡量的指标。这些指标分为定量和定性两类。

定量指标：

• 触发准确率：在相关的查询中，有 90% 的情况“技能”能被自动触发。
• 工具调用次数：启用“技能”后，完成同一任务所需的工具调用次数显著减少。
• API 调用成功率：整个工作流中，失败的 API 调用次数为 0。

定性指标：

• 用户无需干预：用户不需要提示 Claude 下一步该做什么。
• 结果一致性：多次运行同一请求，输出的结构和质量保持一致。
• 易用性：一个新用户在没有太多指导的情况下，也能成功完成任务。

3. 技术要求

规划好应用场景和成功标准后，我们就可以开始技术实现了。最重要的部分，就是 SKILL.md 文件。

文件头部的元数据（YAML Frontmatter）至关重要，因为它决定了 Claude 能否在恰当的时候“发现”你的技能。

一个最简化的 SKILL.md 格式如下：

---
name: your-skill-name
description: 这个技能是做什么的。当用户说[某些特定短语]时使用。
---

# 这里是技能的核心指令
... ...

name 和 description 是必填字段。

• name：必须使用 kebab-case 命名法（即小写字母和短横线），例如 project-sprint-planning。
• description：这是最关键的部分。你必须清晰地描述**“这个技能做什么”以及“什么时候使用它”**。描述越具体、越贴近用户的真实提问方式，触发的准确率就越高。

一个好的 description 示例：

description: 分析 Figma 设计文件并生成开发者交接文档。当用户上传 .fig 文件，或询问“设计规范”、“组件文档”、“设计稿转代码交接”时使用。

一个糟糕的 description 示例：

description: 帮助处理项目。 (过于模糊，无法触发)

在元数据之后，就是用 Markdown 格式编写的核心指令。这部分内容，我们应该遵循一些最佳实践，比如：指令要具体、可操作；清晰地引用 scripts/ 或 references/ 目录下的资源；包含错误处理逻辑等。

---

三、测试与迭代：让“技能”更可靠

构建“技能”是一个持续优化的过程。写完第一版指令后，我们需要通过反复的测试和迭代，来确保它的可靠性和有效性。测试，是为了回答三个核心问题：

1. 它能在正确的时候被触发吗？（触发测试）
2. 它能正确地完成任务吗？（功能测试）
3. 它真的比没有它时更好用吗？（性能比较）

1. 触发测试（Triggering Tests）

这是测试的第一步，也是最基本的一步。我们需要验证“技能”是否足够“聪明”，能在用户需要它的时候自动出现，在用户不需要它的时候保持安静。

测试用例应该覆盖：

• 正面案例：明确的指令，比如“帮我规划一下项目冲刺”。
• 正面案例（改写）：换一种说法，比如“我需要为下一个 sprint 创建一些任务”。
• 负面案例：完全无关的请求，比如“今天天气怎么样？”

如果一个“技能”在不该出现的时候频繁跳出来，这会非常烦人。反之，如果它总是在需要时“深藏不露”，那它就失去了意义。问题的根源，通常都出在 description 字段写得不够好。

• 触发不足（Under-triggering）：说明你的描述太“窄”了，没有覆盖到用户可能的提问方式。你需要补充更多的关键词和场景描述。
• 过度触发（Over-triggering）：说明你的描述太“宽”了，过于泛化。你需要增加一些排除条件，让描述更具体。比如，明确指出“不要在...情况下使用”。

2. 功能测试（Functional Tests）

当“技能”被正确触发后，我们需要验证它是否能按照我们的指令，一步步正确地执行任务。

测试用例应该关注：

• 产出是否有效：生成的文件、创建的任务是否符合预期？
• API 调用是否成功：与外部服务的交互是否都成功了？
• 错误处理是否工作：当遇到预设的错误时，能否给出正确的提示和解决方案？
• 边界情况是否覆盖：输入为空、输入超长、输入格式错误等情况，是否能妥善处理？

3. 性能比较（Performance Comparison）

最后，我们需要证明，使用这个“技能”确实带来了效率的提升。最直接的方法，就是进行“有”和“无”的对比实验。

对比场景示例：

任务：创建一个包含5个任务的项目。

不使用“技能”：

• 用户需要手动提供每一步的指令。
• 来回对话了 15 轮。
• 发生了 3 次需要重试的 API 调用失败。
• 总共消耗了 12,000 个 tokens。

使用“技能”：

• 工作流自动执行。
• Claude 只问了 2 个澄清性的问题。
• API 调用全部成功。
• 总共只消耗了 6,000 个 tokens。

通过这样的对比，我们就能直观地看到“技能”带来的价值：更少的交互、更高的成功率、更低的资源消耗。

迭代的艺术

测试中发现的问题，就是我们迭代的方向。“技能”是一个“活的文档”，它会随着我们使用的深入而不断进化。一个有效的迭代方法是，当你发现一个任务失败或者结果不理想时，把这次失败的对话记录下来，然后对 Claude 说：

“根据我们刚才的对话，改进一下这个‘技能’，让它在处理 [某个特定场景] 时能做得更好。”

Anthropic 甚至提供了一个名为 skill-creator 的官方“技能”，它可以帮助我们创建和审查其他“技能”。这形成了一个有趣的“元循环”：我们用“技能”来创造“技能”。

---

四、分发与共享：让“技能”触达更多人

当你开发出一个好用的“技能”后，自然希望将它分享给更多人使用。目前，“技能”的分发主要有以下几种方式：

1. 个人使用

最简单的方式，就是将你的“技能”文件夹打包成一个 .zip 文件，然后在 Claude.ai 的设置界面中上传。对于开发者，也可以直接将文件夹放置在 Claude Code 的指定目录中。

2. 组织内共享

对于企业用户，管理员可以将“技能”部署到整个工作区。这样，团队成员无需单独安装，就能统一使用标准化的工作流，并且“技能”的更新也能集中管理。

3. 公开分发

目前，推荐的公开分发方式是通过 GitHub。

• 为你的“技能”创建一个公开的 GitHub 仓库。
• 在仓库中，除了包含“技能”文件夹本身，还要有一个写给人类阅读的 README.md 文件，清晰地介绍它的功能、用法和安装步骤。
• 如果你的“技能”是配合某个 MCP 连接器使用的，你应该在 MCP 的文档中，链接到这个“技能”仓库，并说明两者结合使用的价值。

一个开放的标准

值得一提的是，Anthropic 将“技能”作为一个开放标准来推广。他们希望，一个“技能”不仅能在 Claude 上使用，未来也能在其他 AI 平台上运行。这展现了一种开放和协作的姿态，有利于构建一个更繁荣的 AI 生态。

五、模式与排错：常见问题的解决方案

在构建“技能”的过程中，我们不可避免地会遇到各种问题。官方指南总结了一些常见的设计模式和排错技巧，非常实用。

常见设计模式

• 模式一：质量门禁（Quality Gates）：在生成复杂内容（如代码、文档）时，设置明确的检查点。比如，先生成大纲，让用户确认后，再填充内容；完成初稿后，再根据一个“质量清单”进行自我审查和修订。

• 模式二：链式调用（Chaining MCPs）：将多个外部工具串联起来，完成一个更复杂的工作流。比如，先从 GitHub 拉取代码，然后用 Sentry 分析错误，最后将报告发送到 Slack。

• 模式三：上下文感知的工具选择（Context-aware Tool Selection）：根据文件的类型、大小等上下文信息，动态选择最合适的工具。比如，大文件存到云存储，协作文档存到 Notion，代码文件存到 GitHub。

常见问题排错

• 问题：技能无法上传。

  • 原因：很可能是文件夹结构不对，或者核心文件没有被正确命名为 SKILL.md（注意大小写）。

• 问题：技能不触发。

  • 原因：99% 的可能是 description 写得太模糊。尝试让它更具体，包含用户可能说的关键词。

• 问题：技能触发过于频繁。

  • 原因：description 写得太宽泛。尝试增加一些负面条件，明确指出在什么情况下“不”使用。

• 问题：指令不被遵循。

  • 原因：可能是指令太冗长、模糊，或者关键指令被埋没在大量文字中。尝试使用列表、要点，并将关键要求放在最前面，甚至使用“关键”、“重要”等字眼来强调。

• 问题：MCP 连接失败。

  • 原因：先排查 MCP 服务器本身是否正常，API 密钥是否有效。可以尝试在不使用“技能”的情况下，直接调用 MCP，以定位问题根源。

六、总结与资源

“技能”机制，为我们提供了一种结构化的方式，来扩展和定制 AI 的能力。它不仅仅是简单的“提示词工程”，更是一种将领域知识、工作流程和最佳实践“代码化”的方法论。

通过“技能”，我们可以将重复性的、依赖经验的工作，交给 AI 来完成，从而将我们的精力解放出来，专注于更具创造性的任务。这可能是未来人机协作的一个重要方向。

如果你对构建“技能”感兴趣，可以参考以下官方资源：

• 官方文档：Skills Documentation
• API 参考：API Reference
• GitHub 示例仓库：github.com/anthropics/…

希望这篇文章，能帮助你理解“技能”的核心思想，并启发你构建出属于自己的、强大的 AI 助理。