技能（Skill）是一组打包成简单文件夹的指令，用于教导 Claude 如何处理特定任务或工作流程。技能是根据您的具体需求定制 Claude 的最强大方式之一。无需在每次对话中重新解释您的偏好、流程和领域专业知识，技能让您一次性教导 Claude，每次使用都能从中受益。
当您有可重复的工作流程时，技能尤为强大：根据规格生成前端设计、以一致的方法进行研究、创建遵循团队风格指南的文档，或编排多步骤流程。它们与 Claude 的内置能力（如代码执行和文档创建）配合良好。对于构建 MCP 集成的开发者，技能增添了另一层强大的功能——帮助将原始工具访问转化为可靠、优化的工作流程。
本指南涵盖构建有效技能所需了解的一切内容——从规划与结构到测试与分发。无论您是为自己、团队还是社区构建技能，您都会在全书中找到实用的模式和真实案例。
构建独立技能？专注于第一章"基础知识"、第二章"规划与设计"以及分类 1-2。要增强 MCP 集成？"技能 + MCP"部分和分类 3 正是为您准备的。两条路径共享相同的技术要求，但您可以选择与自身用例相关的内容。
读完本指南，您将能够在一次坐下来的时间里构建一个功能完整的技能。预计使用 skill-creator 构建并测试您的第一个可用技能约需 15—30 分钟。
开始吧。
技能是包含以下内容的文件夹：
技能使用三层系统：
这种渐进式披露机制在保持专业能力的同时，最大程度地减少了 Token 消耗。
Claude 可以同时加载多项技能。您的技能应能与其他技能良好协作，而不是假设自己是唯一可用的能力。
技能在 Claude.ai、Claude Code 和 API 中完全相同地工作。创建一次技能，无需修改即可在所有平台上使用——前提是环境支持该技能所需的依赖项。
💡 构建不依赖 MCP 的独立技能？跳到第二章"规划与设计"——您随时可以回来阅读本节。
如果您已经有一个正常运行的 MCP 服务器，那么最难的部分已经完成了。技能是其上的知识层——捕获您已知的工作流程和最佳实践，让 Claude 能够一致地应用它们。
MCP 提供专业厨房：访问工具、食材和设备。
技能提供食谱：一步步的指令，说明如何创造出有价值的成品。
两者合力，让用户无需自己摸索每一个步骤，就能完成复杂任务。
| MCP（连接性） | 技能（知识） |
|---|---|
| 将 Claude 连接到您的服务（Notion、Asana、Linear 等） | 教导 Claude 如何有效使用您的服务 |
| 提供实时数据访问和工具调用 | 捕获工作流程和最佳实践 |
| Claude 能做什么 | Claude 应该怎么做 |
在编写任何代码之前，先确定您的技能应支持的 2—3 个具体用例。
优质的用例定义示例：
问问自己：
Anthropic 观察到三类常见用例：
适用于：创建高质量的一致性输出，包括文档、演示文稿、应用、设计、代码等。
真实案例：frontend-design 技能（另见 docx、pptx、xlsx、ppt 等文档类技能）
核心技术：
适用于：受益于一致方法论的多步骤流程，包括跨多个 MCP 服务器的协调。
真实案例：skill-creator 技能
核心技术：
适用于：为 MCP 服务器提供的工具访问提供工作流指导。
真实案例：sentry-code-review 技能（来自 Sentry）
核心技术：
如何判断您的技能运行良好？
这些是方向性目标——粗略的基准，而非精确的阈值。追求严谨，但也接受主观感受的存在。Anthropic 正在积极开发更完善的测量指南和工具。
SKILL.md 命名：
技能文件夹命名：
禁止 README.md：
YAML 前置元数据决定了 Claude 是否会加载您的技能。务必写好这部分。
这就是您开始所需的全部内容。
name（必填）：
description（必填）：
前置元数据中禁止的内容：
原因：前置元数据会出现在 Claude 的系统提示中，恶意内容可能注入指令。
根据 Anthropic 工程博客："这些元数据……提供足够的信息，让 Claude 知道每项技能何时应该被使用，而无需将全部内容加载到上下文中。"这是渐进式披露的第一层。
结构：[功能说明] + [使用时机] + [核心能力]
在前置元数据之后，用 Markdown 编写实际指令。
根据您的具体技能调整此模板，将括号内容替换为您的实际内容。
提示：模板中的结构是建议，而非强制要求。根据技能的具体需求灵活调整章节和格式。
✅ 优：
❌ 差：
保持 SKILL.md 专注于核心指令。将详细文档移至 references/ 并提供链接。（参见"核心设计原则"中三层系统的工作原理。）
最有效的技能往往是最具体的技能。模糊的指令会导致不一致的结果；精确的指令会带来可预期的行为。在不确定时，宁可过于具体，也不要模棱两可。
技能可以根据实际需求，以不同严格程度进行测试：
根据质量要求和技能受众规模，选择最匹配的测试方式。供小团队内部使用的技能与面向数千名企业用户部署的技能，测试需求截然不同。
在扩展之前，先针对单一任务迭代。我们发现，最高效的技能创建者会反复迭代一项有挑战性的任务，直到 Claude 成功完成，再将成功的方法提炼进技能。这充分利用了 Claude 的上下文学习能力，比广撒网式测试能更快地得到反馈。有了可用的基础之后，再扩展到多个测试用例，提升覆盖率。
根据早期实践，有效的技能测试通常涵盖三个方面：
目标：确保技能在正确时机加载。
测试用例：
测试套件示例：
目标：验证技能能产出正确的输出结果。
测试用例：
示例：
目标：证明技能相比基准线能提升结果。
使用来自定义成功标准的评估指标。以下是对比示例。
基线对比：
skill-creator 技能——可通过插件目录在 Claude.ai 获取，或在 Claude Code 中下载使用——能帮助您构建和迭代技能。如果您拥有 MCP 服务器并明确了2—3 个核心工作流，就可以在单次会话中构建并测试一个可用技能，通常仅需 15—30 分钟。
创建技能：
审查技能：
迭代改进：
使用方法：
注：skill-creator 可帮助您设计和完善技能，但不会执行自动化测试套件或输出量化评估结果。
技能是活文档，应根据以下信号持续迭代：
解决方案：在描述中添加更多细节和层次——可以包含关键词，尤其是技术术语
解决方案：添加负向触发词，使描述更精准具体
解决方案：改进指令，添加错误处理
技能让您的 MCP 集成更加完整。当用户比较各类连接器时，拥有技能的方案能更快创造价值，相比纯 MCP 方案更具竞争优势。
我们将 Agent Skills 作为开放标准发布。与 MCP 一样，我们相信技能应该能够跨工具和平台移植——同一个技能，无论是用 Claude 还是其他 AI 平台都应能正常工作。当然，部分技能专为充分利用特定平台能力而设计，作者可在技能的 compatibility 字段中注明。我们一直与生态系统成员协作推动该标准，并对早期采用者的热情感到振奋。
对于以编程方式使用技能的场景——例如构建应用程序、Agent 或利用技能的自动化工作流——API 提供了对技能管理与执行的直接控制。
/v1/skills 端点列出和管理技能container.skills 参数将技能添加到 Messages API 请求中| 使用场景 | 最佳界面 |
|---|---|
| 终端用户直接与技能交互 | Claude.ai / Claude Code |
| 开发期间的手动测试与迭代 | Claude.ai / Claude Code |
| 个人临时工作流 | Claude.ai / Claude Code |
| 以编程方式使用技能的应用 | API |
| 生产环境大规模部署 | API |
| 自动化流水线与 Agent 系统 | API |
注意：API 中的技能需要代码执行工具（Code Execution Tool）Beta，它为技能运行提供安全沙箱环境。
如需实现细节，请参阅：
首先在 GitHub 上以公开仓库托管技能，附上清晰的 README（面向人类访客——这与技能文件夹是分开的，技能文件夹本身不应包含 README.md），并提供带截图的使用示例。然后在您的 MCP 文档中新增一个章节，链接到该技能、说明两者结合的价值，并提供快速入门指南。
如何推广您的技能与如何构建同样重要。当用户理解技能能为他们做什么时，他们才更可能去安装和使用它。
✅ 好的示例：
✗ 差的示例：
这些模式来源于早期用户和 Anthropic 内部团队创建的技能，代表了经过验证的常见实践方法，而非一成不变的规定模板。
想象一下走进家得宝（Home Depot）。您可能带着一个问题进去——“我需要修厨柜”——然后由员工为您指路找到合适的工具。也可能是您先挑好一把新锥头，再和咨如何用它完成具体工程。
技能同理：
大多数技能倾向于其中一种方式。了解哪种框架适合您的场景，有助于选择下方合适的模式。
适用场景：需要以特定顺序完成多个步骤，且每一步的输出会影响下一步的任务。
适用场景：工作流横跨多个外部服务，且需要在它们之间协调操作时。
适用场景：输出需要经过多轮生成、评估和改进，直至满足质量标准。
适用场景：根据输入特征或上下文条件，应选择不同工具或不同处理路径时。
适用场景：任务需要特定领域知识、合规要求或专业判断，而这些并非模型的通用能力。
错误：“在上传的文件夹中找不到 SKILL.md”
原因：文件未精确命名为 SKILL.md
解决方案：
错误：“无效的 frontmatter”
原因：YAML 格式问题
常见错误：
错误：“无效的技能名称”
原因：名称中包含空格或大写字母
症状：技能从不自动加载
修改技能的描述字段。参见“描述字段”章节中的好/差示例。
快速检查清单：
调试方法：询问 Claude：“你什么时候会使用 [技能名称] 这个技能？”Claude 会复述描述内容，根据缺失的信息进行调整。
症状：技能在不相关的任务中被激活
解决方案：添加负触发词，明确说明不适用的场景。
1. 添加负触发词
2. 更具体地描述
3. 明确使用范围
症状：技能加载成功，但 MCP 调用失败
排查清单：
1. 验证 MCP 服务器已连接
2. 检查认证
3. 独立测试 MCP
4. 核对工具名称
症状：技能加载成功，但 Claude 未按指令执行
常见原因：
## Important 或 ## Critical 标题，重复关键要点4. 模型"惰性"：添加明确的鼓励性说明：
进阶技巧：对于关键验证逻辑，可在技能中打包一个脚本——代码是确定性的。参见 Office skills 示例。
注：将此类说明加入用户提示词比写入 SKILL.md 更为有效。
症状：技能响应变慢或质量下降
原因：
解决方案：
1. 优化 SKILL.md 体积
2. 减少同时启用的技能数量
如果您正在构建第一个技能，建议先阅读最佳实践指南，再根据需要参阅 API 文档。
使用此清单在上传前后验证您的技能。如果希望快速入门，可使用 skill-creator 技能生成初稿，然后对照此清单确保没有遗漏。
< >）< >）— 安全限制以下仓库提供完整的、可用于生产环境的技能示例，体现了本指南所介绍的各类模式：
这些仓库持续更新，收录了超出本指南范围的更多示例。您可以克隆它们，根据自己的使用场景进行修改，并将其作为模板直接使用。