Anthropic官方教你如何构建Claude Skills

本文来自微信公众号：Draco正在VibeCoding，作者：DracoVibeCoding，原文标题：《万字译文：Anthropic官方发布的Claude Skills构建指南完整版！》，题图来自：AI生成

Anthropic近期官方发布了33页的Claude Skills构建指南，下面是全文中文译版，pls enjoy。

目录

• 简介

• 第一章 基础知识

• 第二章 规划与设计

• 第三章 测试与迭代

• 第四章 发布与分享

• 第五章 模式与故障排查

• 第六章 资源与参考

简介

技能（Skill）其实就是一套指令——打包成一个简单的文件夹——用来教 Claude 怎么处理特定任务或工作流程。这是你自定义 Claude 最有力的方式之一。

你有没有遇到过这种情况：每次跟 Claude 对话，都要重新解释你的偏好、流程和专业背景？有了技能，你只需要教一次，以后每次都能直接用上。

什么时候用技能最合适？就是当你有可以重复执行的工作流程时，比如：

• 根据设计稿生成前端界面

• 用固定的方法论做研究调查

• 按照团队风格指南写文档

• 协调多个步骤的复杂流程

技能跟 Claude 的内置功能（比如执行代码、创建文档）搭配起来效果很好。如果你在做 MCP 集成，技能还能帮你把原始的工具访问能力，变成可靠、顺畅的工作流程。

读完这份指南，你会学到：

• 技能的技术要求和最佳实践

• 独立技能和 MCP 增强型工作流的设计模式

• 我们观察到的那些真正有效的做法

• 怎么测试、迭代、发布你的技能

这份指南适合谁读？

• 想让 Claude 按固定流程工作的开发者

• 想让 Claude 遵循自己习惯的高级用户

• 想在团队/组织内统一 Claude 使用方式的管理者

两条阅读路径：

只做独立技能？重点看“基础知识”和“规划与设计”部分。

想在 MCP 上叠加技能？“技能 + MCP”和第五章的设计模式更适合你。

两条路径用的是同样的技术规范，按自己的需求选就好。

预计投入：读完这份指南后，配合 skill-creator 工具，通常 15-30 分钟就能做出你第一个能用的技能。

第一章：基础知识

技能到底是什么？

技能就是一个文件夹，里面放着：

三个核心设计理念

1. 渐进式披露（Progressive Disclosure）

技能用三层结构来组织内容：

• 第一层（YAML 前置信息）：每次都会加载到 Claude 的系统提示里。内容要精简——让 Claude 知道"这个技能是做什么的、什么时候该用它"就够了，不需要把所有东西都塞进来。

• 第二层（SKILL.md 正文）：当 Claude 觉得当前任务跟这个技能有关，才会加载完整指令。

• 第三层（链接文件）：放在技能文件夹里的其他文件，Claude 可以按需查阅。

这种分层设计的好处：既省 token，又能保留足够的专业深度。

2. 可组合性（Composability）

Claude 可以同时加载多个技能。你的技能要能跟其他技能和平共处，别假设自己是唯一被启用的那个。

3. 可移植性（Portability）

在 Claude.ai、Claude Code 和 API 里，技能的工作方式完全一样。写一次，到处能用——前提是运行环境支持技能所需的依赖。

面向 MCP 开发者：用技能增强 MCP

只做独立技能、不涉及 MCP？可以直接跳到第二章，随时回来看这节。

如果你已经有了运行中的 MCP 服务器，最难的部分其实已经搞定了。技能就是在上面加一层“知识层”——把你已经知道的工作流程和最佳实践固化下来，让 Claude 能够一致地应用它们。

这两者怎么配合？

 

没有技能时，用户可能遇到的问题：

• 连上了 MCP，但不知道下一步该咋办

• 不断发来“怎么用你的集成做 X”的支持提问

• 每次对话从头开始，结果每次都不一样

• 用户会把问题归咎于你的 MCP 连接器，但根本原因其实是缺少工作流程指引

有了技能之后：

• 预置的工作流程在需要时自动激活

• 工具调用稳定可靠

• 最佳实践内嵌在每次交互里

• 新用户的学习成本大幅降低

第二章：规划与设计

第一步：从用例出发

在写任何代码之前，先想清楚你的技能要解决的2-3个具体场景。

一个好的用例定义长这样：

问自己这几个问题：

• 用户想达成什么目标？

• 这需要哪些多步骤的工作流程？

• 需要哪些工具（Claude 内置的，还是 MCP 的）？

• 需要嵌入哪些领域知识或最佳实践？

三类常见用例

Anthropic 观察到三种最常见的技能使用场景：

第 1 类：文档和素材创建

适合场景：创建一致的高质量输出，比如文档、演示文稿、应用、设计、代码等。

真实案例：frontend-design技能（另见 docx、pptx、xlsx 相关技能）

关键做法：

• 嵌入风格指南和品牌规范

• 用模板结构保证输出一致

• 最终确认前做质量清单检查

• 不需要外部工具——用 Claude 的内置能力就够

第 2 类：工作流程自动化

适合场景：多步骤流程，需要一致的执行方式，可能跨多个 MCP 服务器协调。

真实案例：skill-creator技能

关键做法：

• 带验证节点的分步工作流

• 常见结构的模板

• 内置审查和改进建议

• 迭代优化循环

第 3 类：MCP 增强

适合场景：为 MCP 服务器的工具访问能力加上工作流程引导。

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

关键做法：

• 按顺序协调多个 MCP 调用

• 嵌入领域专业知识

• 提供用户本来需要手动指定的上下文

• 处理常见 MCP 问题

第二步：定义成功标准

怎么知道你的技能跑通了？

先说清楚：下面这些是参考目标，不是死板的门槛——测试时还是需要一定的感性判断。Anthropic 正在开发更完善的量化评估工具。

量化指标：

• 技能在 90% 的相关查询中触发

• 怎么测：跑 10-20 个应该触发技能的测试问题，记录自动加载的次数

  
  

• 工作流程在 X 次工具调用内完成

• 怎么测：有无技能各跑一次相同任务，对比工具调用次数和 token 消耗

  
  

• 每个工作流程 0 次 API 调用失败

• 怎么测：测试期间监控 MCP 服务器日志，追踪重试率和错误码

定性指标：

• 用户不需要提示 Claude 下一步该做什么

• 工作流程无需用户纠正就能跑完

• 跨会话结果保持一致

技术要求

文件夹结构

几条必须遵守的规则

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 前置信息：最关键的部分

YAML 前置信息是 Claude 决定要不要加载你的技能的依据，务必写对。

最简格式（够用了）：

各字段说明：

name（必填）：

• 只能用 kebab-case

• 没有空格，没有大写

• 最好和文件夹名一致

description（必填）：

• 必须同时包含：

• 这个技能能做什么

• 什么时候该用（触发条件）

• 最多 1024 个字符

• 不能含 XML 标签（<或>）

• 要包含用户可能实际说出的话

• 如果涉及特定文件类型，要提到

  
  

license（可选）：

• 开源才需要填

• 常见选项：MIT、Apache-2.0

compatibility（可选）：

• 1-500 个字符

•  说明运行环境要求，比如：目标产品、需要的系统包、是否需要网络访问等

  
  

metadata（可选）：

• 任意键值对

• 推荐写上：author、version、mcp-server

安全限制：

• 禁止用 XML 尖括号（<>）

• 技能名称不能以 "claude" 或 "anthropic" 开头（保留词）

• 原因：前置信息会进入 Claude 的系统提示，恶意内容可能被用来注入指令

写好 description 字段

Anthropic 工程博客说过：“这段元数据……提供了恰好足够让 Claude 知道该用哪个技能的信息，而不需要把所有内容都加载到上下文里。”这就是渐进式披露的第一层。

格式模板：[能做什么] + [什么时候用] + [主要功能]

好的写法：

不好的写法：

写主体指令

过了 YAML 前置信息，就用 Markdown 写具体的指令。

推荐结构：

写指令的最佳实践：

要具体，要说清楚怎么操作：

别含糊其词：

要包含错误处理：

要用渐进式引用：

SKILL.md 要保持聚焦：核心指令放在 SKILL.md，详细文档移到references/里，通过链接引用。

第三章：测试与迭代

你可以根据需要选择不同严格程度的测试方式：

• 在 Claude.ai 里手动测试——直接跑查询，看行为。迭代快，零配置。

• 在 Claude Code 里用脚本测试——自动化测试用例，每次改完都能跑一遍验证。

• 通过技能 API 程序化测试——构建系统化的评估套件，针对预定义测试集运行。

 

按实际需要选。个人用的小技能和面向数千企业用户的技能，测试严格程度自然不一样。

专业技巧：先把一个难题跑通，再推广

我们发现，最高效的做法是：先针对一个最具挑战的任务反复迭代，直到 Claude 成功搞定，再把这个成功方案提炼成技能。这样能充分利用 Claude 的上下文学习能力，比广撒网测试更快得到有效反馈。有了可运行的基础后，再扩展到多个测试用例来验证覆盖面。

推荐测试方法




1. 触发测试




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









2. 功能测试




目标：验证技能输出是对的。









3. 对比测试




目标：证明技能比没有技能时更好。









用 skill-creator 工具




skill-creator 是一个特殊的技能，内置于 Claude.ai，也可以下载用于 Claude Code。




它能帮你：




创建技能：




• 从自然语言描述生成技能

• 自动产生格式正确的 SKILL.md

• 建议触发词和结构

   

审查技能：




• 标出常见问题：描述太模糊、缺少触发条件、结构有问题

• 识别过度/不足触发的风险

• 根据技能目的建议测试用例

 

迭代改进：




• 遇到边缘案例或失败后，把问题带回 skill-creator，让它帮你改进

   

使用方法：









注意：skill-creator 帮你设计和打磨技能，但不会跑自动化测试套件，也不会生成量化评估结果。




根据反馈持续迭代




技能是“活文档”，要根据实际使用情况不断调整。




触发不足的信号：




• 技能该自动加载时没加载

• 用户手动开启它

• 有人问“什么时候用这个技能”

 

→ 解决办法：在 description 里加更多细节和关键词（包括专业术语）




触发过度的信号：




• 技能在不相关的查询里也触发了

• 用户禁用了它

• 用户搞不清它的用途

   

→ 解决办法：添加负触发词，让描述更具体




执行问题的信号：




• 结果不一致

• API 调用失败

• 需要用户帮忙纠正

 

→ 解决办法：改进指令，加上错误处理




第四章：发布与分享




技能能让你的 MCP 集成更完整。当用户在比较不同集成方案时，有技能的产品能更快展现价值，比单纯的 MCP 更有竞争力。




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




个人用户怎么获取技能：

1. 下载技能文件夹

2. 压缩成 zip

3. 通过 Claude.ai 的 设置 > 功能 > 技能 上传

4. 或放到 Claude Code 的技能目录里




组织级技能：

• 管理员可以在工作区范围内部署技能（2025 年 12 月 18 日已上线）

• 支持自动更新和集中管理

 

开放标准




Anthropic 已将 Agent Skills 作为开放标准发布。和 MCP 一样，技能应该能跨工具和平台使用——同一个技能不管在 Claude 还是其他 AI 平台上都能用。当然，有些技能可能专门利用了特定平台的能力；作者可以在compatibility字段里注明这一点。




通过 API 使用技能




如果你需要用程序来调用技能（比如构建应用、AI 代理或自动化工作流）：




• 用/v1/skills接口管理技能

• 在 Messages API 的container.skills参数里添加技能

• 在 Claude Console 里做版本控制和管理

• 配合 Claude Agent SDK 构建自定义代理

  
  

API 和 Claude.ai 怎么选？









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




今天就能做的事




第一步：托管到 GitHub




• 开源技能用公开仓库

• 写清楚 README（供人类查看——这个放仓库根目录，不是技能文件夹里）

• 附上使用示例和截图

   

第二步：在 MCP 文档里说明




• 链接到技能

• 解释 MCP + 技能一起用的价值

• 提供快速上手指南

 

安装指南参考模板：









怎么介绍你的技能




你描述技能的方式，很大程度上决定了用户愿不愿意用它。




聚焦结果，而非功能：




好的写法：









不好的写法：









讲清楚 MCP + 技能的组合故事：









第五章：模式与故障排查




下面这些模式来自早期采用者和内部团队的真实经验，是我们观察到真正有效的常见做法——不是固定模板，可以灵活用。




选你的出发点：问题优先 vs. 工具优先




想象一下去建材超市。你可能带着问题来——“我需要修厨柜”——店员帮你找合适的工具。或者你拿了个新电钻，再想怎么用它完成你的活儿。




技能也是同样的逻辑：




• 问题优先：“我需要设置项目工作区” → 技能按正确顺序协调 MCP 调用。用户说目标，技能搞定工具。

• 工具优先：“我已经连上了 Notion MCP” → 技能教 Claude 最佳工作流程和实践。用户有访问权限，技能提供专业知识。

   

大多数技能会偏向其中一个方向。搞清楚哪种框架适合你的用例，能帮你选对下面的模式。




模式一：顺序工作流编排




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









关键技术：步骤顺序要明确、步骤间依赖关系要写清楚、每个阶段要有验证、失败时要有回滚指令。




模式二：多 MCP 协调




适合场景：工作流需要跨多个服务。









关键技术：阶段分隔要清晰、MCP 间的数据传递要明确、进下一阶段前要验证、错误处理要集中。




模式三：迭代式优化




适合场景：输出质量需要通过多轮迭代来提升。









关键技术：质量标准要明确、迭代改进要有节奏、验证脚本要好用、要知道什么时候停。




进阶技巧：对于关键验证步骤，可以考虑打包一个脚本来做程序化检查，而不是靠自然语言描述。代码的执行是确定的，语言的理解不是。参考 Office 技能系列的示例。




模式四：情境感知工具选择




适合场景：同一个目标，根据上下文要选不同的工具。









关键技术：决策标准要清晰、要有备用选项、选择理由要透明。




模式五：特定领域智能




适合场景：你的技能在工具访问之外还需要提供专业知识。









关键技术：领域专业知识要嵌入逻辑、行动前要合规检查、记录要完整、治理边界要清晰。




故障排查




技能上传失败




错误："Could not find SKILL.md in uploaded folder"

原因：文件名不是精确的 SKILL.md

解决：重命名，用ls -la验证确实叫 SKILL.md




错误："Invalid frontmatter"

原因：YAML 格式有问题









错误："Invalid skill name"

原因：名称有空格或大写









技能不触发




症状：技能从来不自动加载




解决：修改 description 字段（参考前面的好/坏示例）




自查清单：




• 描述是不是太笼统？（“帮助处理项目”不够用）

• 有没有用户可能实际说的触发词？

• 如果涉及文件类型，有没有提到？

 

调试技巧：问 Claude：“你什么时候会用 [技能名] 这个技能？”Claude 会引用 description 里的内容。根据缺失的部分来调整。




技能触发太频繁




症状：技能在不相关的查询里也出现了




解决方法：




1. 加负触发词：









2. 描述更具体：









3. 明确使用范围：









MCP 连接问题




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




检查清单：




1. 确认 MCP 服务器已连接

• Claude.ai：设置 > 扩展 > [你的服务]

• 应显示"已连接"




2. 检查身份验证

• API 密钥是否有效、是否过期

• 权限/范围是否正确

• OAuth 令牌是否已刷新




3. 单独测试 MCP（不用技能）

• 直接让 Claude 调用 MCP：“用 [服务] MCP 获取我的项目”

• 如果这个也失败，问题在 MCP，不在技能




4. 核对工具名称

• 技能里引用的 MCP 工具名称是否正确

• 工具名称区分大小写，一个字母都不能错




指令没有被遵守




症状：技能加载了，但 Claude 没按指令执行。




常见原因及解决方法：




1. 指令太冗长

• 保持简洁

• 多用列表和编号

• 详细参考文档移到单独文件




2. 关键指令被埋没

• 重要内容放在最前面

• 用## 重要或## 关键这样的标题

• 关键点可以重复




3. 语言模糊









进阶技巧：对于关键验证步骤，考虑打包脚本来程序化执行检查，而不是依赖自然语言指令。代码执行是确定的，语言理解不是。参考 Office 技能系列的示例。




4. 模型“偷懒”——加上明确的激励说明：









注意：这段加在用户提示里比加在 SKILL.md 里效果更好。




上下文太大导致响应变慢或质量下降




原因：

• SKILL.md 内容太多

• 同时启用的技能太多

• 所有内容都加载了，没有用渐进式披露




解决方法：




1. 精简 SKILL.md

• 详细文档移到references/

• 用链接引用而非内联

• SKILL.md 尽量控制在 5，000 个词以内

 

2. 减少同时启用的技能数量

• 超过 20-50 个同时启用的技能就要考虑精简了

• 建议按需选择性启用

• 相关功能可以打包成技能“组合包”




第六章：资源与参考




如果你是第一次做技能，建议先看最佳实践指南，再根据需要查阅 API 文档。




官方文档




Anthropic 官方资源：




• Best Practices Guide（最佳实践指南）

• Skills Documentation（技能文档）

• API Reference（API 参考）

• MCP Documentation（MCP 文档）

   

官方博客文章：

• 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

• 可以从描述生成技能

• 提供审查和改进建议

• 使用方法："用 skill-creator 帮我构建一个技能"

 

验证与评审：

• skill-creator 也可以评估已有的技能 

• 问法："请审查这个技能，并给出改进建议"

  
  

获取支持




技术问题：

• 社区论坛 / Claude Developers Discord




Bug 报告：

• GitHub Issues：anthropics/skills/issues 

• 提交时请包含：技能名称、错误信息、复现步骤

 

附录A：快速检查清单




上传技能前后，用这个清单验证一遍。想快点开始的话，可以先用 skill-creator 生成初稿，再过一遍这个清单。




开始之前

• 确定了 2-3 个具体用例

• 确定了所需工具（内置还是 MCP）

• 看过这份指南和示例技能

• 规划好了文件夹结构

  
  

开发过程中

• 文件夹用了 kebab-case 命名

• SKILL.md文件存在（精确拼写，区分大小写）

• YAML 前置信息有---分隔符

• name字段：kebab-case、无空格、无大写

• description同时写了“做什么”和“什么时候用”

• 没有 XML 标签（<>）

• 指令清晰、可操作

• 包含了错误处理

• 提供了示例

• 参考资料有清晰的链接

上传前

• 测试了明显任务的触发

• 测试了换一种说法的触发

• 确认不会在不相关主题上触发

• 功能测试通过 

• 工具集成正常（如果有） 

• 压缩成了 .zip 文件

 

上传后

• 在真实对话里测试过

• 观察了过度/不足触发的情况

• 收集了用户反馈

• 根据反馈迭代了 description 和指令

• 更新了 metadata 里的版本号

  
  

附录B：YAML 前置信息参考




必填字段









所有可选字段









安全说明




允许的：




• 标准 YAML 类型（字符串、数字、布尔值、列表、对象） 

• 自定义 metadata 字段

• 较长的 description（最多 1024 个字符）

  
  

禁止的：




• XML 尖括号（<>）——安全限制

• YAML 中执行代码（用的是安全 YAML 解析）

• 以 "claude" 或 "anthropic" 开头的技能名（保留词）

 

附录C：完整技能示例




想看展示本指南中各种模式的完整、可生产用的技能？这里有：




• Document Skills——PDF、DOCX、PPTX、XLSX 创建 

• Example Skills——各种工作流程模式

• Partner Skills Directory——Asana、Atlassian、Canva、Figma、Sentry、Zapier 等合作伙伴的技能

  
  

这些仓库持续更新，示例比本文更丰富。克隆下来，按你的需求改，用作模板。




本文来自微信公众号：Draco正在VibeCoding，作者：DracoVibeCoding