[小山译] Claude Skill 编写与实战指南

Hi，我是洛小山，你学习 AI 的搭子。

最近沉迷折腾龙虾，想把日常工作都 Skill 化，试了挺多方法都不怎么好用。正好最近 Anthropic 出了一份官方指南，我边学边翻，分享给你。

原文可以在「文末」查看。

原文：The Complete Guide to Building Skills for Claude

译者：洛小山、林哲韬

引言

Skill 是以文件夹的形式打包的一组指令，用来教会 Claude 怎么处理特定任务或工作流。这是针对自己需求定制 Claude 最直接的方式之一。

每次对话都要重新解释偏好、流程和背景知识太低效了，而用 Skill 一次性教会 Claude，之后每次都能直接用。

Skill 非常擅长处理高频、重复的工作流。比如，你可以用它来根据需求文档输出前端代码、基于统一的分析框架做调研、套用团队规范生成文档，或者串联起复杂的多步流程。

它们能与 Claude 内置的代码执行、文档创建等能力无缝配合。

对于做 MCP 集成的开发者来说，Skill 是额外一层，把原始的工具访问变成可靠、可复用的工作流。

本指南涵盖了从规划设计到测试与分发环节构建高效 Skill 所需的全部知识。不管你是为自己、团队还是开发者社区构建 Skill，都能在本指南中找到实用的设计模式与真实案例。

你将学到：

•Skill 结构的技结构规范和最佳实践

•独立 Skill 和 MCP 增强工作流的模式

•我们在不同使用场景中已验证的有效模式

•如何测试、迭代和分发你的 Skill

适合人群：

• 希望 Claude 持续遵循特定工作流的开发者

•希望 Claude 记住自己偏好和流程的高级用户

•希望在整个组织中统一规范 Claude 工作方式的团队

本指南的两条路径

1-2：构建独立 Skill，重点看基础知识、规划与设计，以及类别。

3：增强 MCP 集成，看「Skill + MCP」章节和类别。

两条路径的技术要求是一样的，按自己用例挑着读就行。

学完本指南后，你将能够一气呵成地构建出一个可运行的 Skill。

借助 skill-creator 工具，预计只需 15-30 分钟即可完成第一个 Skill 的构建与测试。

01｜基础知识

Skill 是什么？

核心设计原则

渐进式披露（Progressive Disclosure）

Skill 采用三级结构：

•第一级（YAML 前置元数据）：始终加载到 Claude 的系统提示里。只提供足够的信息让 Claude 判断是否要用这个 Skill，不会把所有内容都塞进上下文。

•第二级（SKILL.md 正文）：Claude 判断 Skill 与当前任务相关时才加载，包含完整的指令和说明。

•第三级（链接文件）：Skill 目录里的附加文件，Claude 可以按需去查。

这种分级结构在保持专业能力的同时，把 token 消耗控制到最低。

可组合性（Composability）

Claude 可以同时加载多个 Skill。你的 Skill 要能和其他 Skill 配合运行，不要假设自己是唯一可用的。

可移植性（Portability）

Skill 在 Claude.ai、Claude Code 和 API 上行为完全一致。做一次，所有平台都能用——前提是运行环境支持该 Skill 所需的依赖。

面向 MCP 构建者：Skill + 连接器

💡 构建不依赖 MCP 的独立 Skill？

跳到「规划与设计」章节，这部分随时可以回来看。

如果你已经有一个跑起来的 MCP 服务器，最难的部分已经完成了。Skill 是叠在上面的知识层——把你已知的工作流和最佳实践固化下来，让 Claude 每次都能稳定地执行。

类比成厨房

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

Skill 提供食谱：一步步说明怎么做出有价值的成果。

两者结合，用户不用自己摸索每个步骤就能完成复杂任务。

没有 Skill 时：

•用户连上了你的 MCP 但不知道下一步怎么做

•收到「怎么用你的集成做 X」的支持工单

•每次对话都要从头开始

•因为每次提示方式不同，结果时好时坏

•用户会觉得是连接器的问题，但真正缺的是工作流引导

有了 Skill 后：

•预构建的工作流在需要时自动激活

•工具调用稳定、可预期

•每次交互都内嵌了最佳实践

•用户上手门槛大幅降低

02｜规划与设计

从用例出发

动手写之前，先确定你的 Skill 要支持哪 2-3 个具体用例。

好的用例定义示例：

问自己：

用户想完成什么？

需要哪些多步骤工作流？

需要哪些工具（内置工具还是 MCP）？

哪些领域知识或最佳实践应该内嵌进去？

常见 Skill 用例类别

Anthropic 观察到三类常见用例：

类别 1：文档与资产创建

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

真实案例：frontend-design skill

「创建具有高设计质量的独特、生产级前端界面。在构建 Web 组件、页面、制品、海报或应用时使用。」

关键技术：内嵌风格指南和品牌标准、用于一致输出的模板结构、最终确定前的质量检查清单、不依赖外部工具——用 Claude 内置能力搞定。

类别 2：工作流自动化

用途：需要固定方法论的多步骤流程，包括跨多个 MCP 服务器的协调。

真实案例：skill-creator skill

「创建新 Skill 的交互式指南。引导用户完成用例定义、前置元数据生成、指令编写和验证。」

关键技术：带验证节点的分步工作流、常见结构的模板、内置审查和改进建议、迭代优化循环。

类别 3：MCP 增强

用途：在 MCP 服务器提供的工具访问之上，加一层工作流指导。

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

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

关键技术：按顺序协调多个 MCP 调用、内嵌领域专业知识、提供用户原本需要自己指定的上下文、处理常见 MCP 问题的错误处理。

定义成功标准

怎么判断 Skill 是否有效？

下面是一些参考目标——粗略基准，不是精确阈值。

定量指标：

•Skill 在 90% 的相关查询中触发——测量方法：运行 10-20 个应该触发 Skill 的测试查询，追踪自动加载与需要手动调用的比例。

•在 X 次工具调用内完成工作流——测量方法：对比开启和关闭 Skill 时完成同一任务的情况，统计工具调用次数和消耗的总 token 数。

•每个工作流 0 次 API 调用失败——测量方法：测试期间监控 MCP 服务器日志，追踪重试率和错误码。

定性指标：

•用户不需要提示 Claude 下一步做什么——评估方法：测试期间记录需要重新引导或澄清的频率，向 Beta 用户收集反馈。

•工作流不需要用户纠正就能跑完——评估方法：把同一请求跑 3-5 次，对比输出的结构一致性和质量。

•跨会话结果稳定——评估方法：新用户能否在几乎没有引导的情况下第一次就跑通？

技术要求

文件结构：

关键规则：

YAML 前置元数据：最重要的部分

YAML 前置元数据决定了 Claude 是否加载你的 Skill，必须写好。最简必要格式：

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

字段要求：

安全限制

前置元数据里禁止：

• XML 尖括号（< >）
• 名称以「claude」或「anthropic」开头（保留字）

原因：前置元数据会出现在 Claude 的系统提示里，恶意内容可能注入指令。

译者注：这里要求我们遵循约定，名字不能以 claude 命名是个君子协议。

如果你要做更高优先级的 Skill ，请务必这样干。

编写有效的 Skill

description 字段

根据 Anthropic 工程博客：「这些元数据……只提供足够的信息让 Claude 判断何时该用这个 Skill，而不会把全部内容加载到上下文中。」这是渐进式披露的第一级。

译者注：description 字段决定了 Skill 的「可发现性」，是整个文件里最值得花时间的地方。

很多人把大量精力放在 SKILL.md 正文，却随便写了两个字的 description，这是典型的本末倒置。

结构：[它做什么] + [何时用] + [核心能力]

好的 description 示例：

不好的 description 示例：

编写主体指令

前置元数据之后，用 Markdown 写实际指令。

推荐结构：

✅ 好的：

❌ 模糊的：

包含错误处理：

清晰引用打包的资源：

用好渐进式披露

SKILL.md 只放核心指令，详细文档放到 references/ 里并加链接。

（参见核心设计原则，了解三级结构的工作方式。）

03｜测试与迭代

Skill 的测试可以按你需要的严格程度来：

•在 Claude.ai 里手动测试：直接跑查询，看行为。迭代最快，不需要任何配置。

•在 Claude Code 里写脚本测试：自动化测试用例，变更时可以重复验证。

•通过 Skills API 编程测试：构建评估套件，针对预设测试集系统性地跑。

按你的质量要求和 Skill 的受众规模选合适的方式。

给小团队内部用的 Skill，和部署给几千名企业用户的 Skill，测试需求差距很大。

有效做法：先在一个任务上迭代，再扩展范围。

实践表明，做 Skill 最高效的方式是先盯着一个有挑战性的任务反复跑，跑通之后再把有效的方法提炼成 Skill。

这充分利用了 Claude 的上下文学习能力，比大范围撒网测试得到信号要快得多。有了能跑的基础版之后，再扩展测试用例来提高覆盖率。

译者注：我自己也是这么干的，先找一个卡点最多的任务反复调优，而不要一上来就写一堆用例覆盖场景。

你如果把 Claude 真正搞定一件难事的过程记录下来，比凭空设计测试用例靠谱得多。

推荐测试方法

有效的 Skill 测试通常覆盖三个方面：

1. 触发测试

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

测试用例：

• ✅ 在明显相关的任务上触发
• ✅ 换个说法的请求也能触发
• ❌ 无关话题不触发

示例测试用例：

2. 功能测试

目标： 验证 Skill 能产出正确的结果。

测试用例：

• 能生成有效输出
• API 调用成功
• 错误处理正常
• 边界情况有覆盖
   

示例：

3. 性能对比

目标： 验证 Skill 相比没有 Skill 的基线有实际提升。

用「定义成功标准」里的指标来量化。

对比示例：

使用 skill-creator Skill

skill-creator 在 Claude.ai 的插件目录里，也可以下载用于 Claude Code，帮你构建和打磨 Skill。

如果你有 MCP 服务器，清楚自己的 2-3 个核心工作流，通常一次坐下来（15-30 分钟）就能做出一个可用的 Skill。

译者注：skill-creator 本身也是一个 Skill，在 Claude.ai 的插件目录里直接搜就能找到。

Claude Code 用户可以把它下载到本地 skills 目录。

API 用户也能用，通过 /v1/skills 端点上传后直接调用。

创建 Skill：

• 从自然语言描述生成 Skill
• 生成格式正确的带前置元数据的 SKILL.md
• 建议触发短语和结构
   

审查 Skill：

• 找出常见问题（描述模糊、缺少触发词、结构有问题）
• 识别可能过度触发或触发不足的风险
• 根据 Skill 的目的建议测试用例
   

迭代改进：

• 用 Skill 过程中遇到边界情况或失败，把这些案例带回 skill-creator
• 示例：「用这次对话中发现的问题和解决方案，改进 Skill 处理 [特定边界情况] 的方式」

用法：

注：skill-creator 帮你设计和优化 Skill，但不跑自动化测试套件，也不产出量化评估结果。如果你想要想要数字，还是得自己跑。

根据反馈迭代

Skill 是需要持续更新的活文档，要根据实际使用中的信号持续调整：

触发太少：

• 该加载时没有加载
• 用户要手动启用
• 收到「这个 Skill 什么时候用」的支持问题

解决：在 description 里补充更多细节和关键词，特别是技术术语。

触发太多：

• 在无关查询时加载
• 用户关掉了它
• 用户搞不清楚它是干嘛的

解决：加负面触发词，把描述写得更精确。

执行有问题：

• 结果不稳定
• API 调用失败
• 需要用户来纠正

解决：改进指令，加错误处理。

04｜分发与共享

技能让你的 MCP 集成更完整。当用户在比较各类连接器时，具备技能的产品提供了更快的价值实现路径，让你在纯 MCP 方案中脱颖而出。

现在怎么分发（2026 年 1 月）

个人用户的安装方式：

1. 下载 Skill 文件夹
2. 压缩成 zip（如果还没压缩的话）
3. 打开 Claude.ai「设置 > 能力 > Skills」上传
4. 或者直接放到 Claude Code 的 Skills 目录里
    

组织级部署：

• 管理员可以全工作区一键部署 Skill（2025 年 12 月 18 日上线）
• 支持自动更新和集中管理

开放标准

我们把 Agent Skills 作为开放标准发布了。和 MCP 一样，Skill 应该能跨工具、跨平台用——同一个 Skill 无论在 Claude 还是其他 AI 平台上都应该能跑。

这个标准正在和生态里的伙伴一起推进，目前看来采用情况挺不错。

译者注：「开放标准」意味着你现在给 Claude 写的 Skill，理论上未来可以直接用在其他 AI 平台上，不用重写。这和 MCP 的设计思路是一脉相承的——Anthropic 在有意识地构建可移植的基础设施。

通过 API 调用 Skill

如果你在用代码调用 Skill——比如构建应用、Agent 或自动化流水线——API 提供了直接管理和执行 Skill 的能力。

•/v1/skills 端点，用来列出和管理 Skill

•通过 container.skills 参数把 Skill 挂到 Messages API 请求上

•在 Claude Console 里做版本管理

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

什么时候用 API，什么时候用 Claude.ai：

注：API 里的 Skill 依赖 Code Execution Tool 的 Beta 版，这是 Skill 运行需要的安全环境。目前还在 Beta，正式用之前建议先确认自己账号有这个权限。

更多实现细节：Skills API 快速入门、创建自定义 Skill、Agent SDK 中的 Skill。

现在推荐这么做

先在 GitHub 上建一个公开仓库，写好 README（供人阅读——这跟 Skill 文件夹是分开的，Skill 文件夹里不放 README.md），加上带截图的使用示例。

然后在你的 MCP 文档里加一节，链接过去，说清楚两者配合用的价值，并给个快速上手指南。

译者注：这套分发流程现在（2026 年 1 月）还比较手动，Anthropic 明显在逐步完善这块的基础设施。

如果你在做面向团队内部的 Skill，可以直接走组织级部署，不用每个人手动安装；如果是开源给社区用，现在 GitHub + README 这套是最好的路径。

译者注补充：有一个容易踩的坑——「组织级部署」目前只在 API 层面支持。

Claude.ai 上的 Skill 是个人级的，即使是 Enterprise 账号，管理员也没办法统一给全组织推送 Skill，每个人必须自己上传。

做企业内部工具的话，走 API + Agent SDK 那条路才能真正实现统一管理。

1. 放到 GitHub 上

•开源 Skill 用公开仓库

•README 里写清楚怎么安装

•加上使用示例和截图

2. 在 MCP 文档里记录

•从 MCP 文档链接到 Skill

•说清楚两者配合有什么好处

•给个快速上手步骤

3. 写一份安装指南

怎么介绍你的 Skill

你说 Skill 的方式，决定了用户有没有兴趣去试。写 README、文档或推广文案时，记住一点：

讲结果，别讲功能：

✅ 好的：「ProjectHub Skill 让团队几秒内就能建好完整的项目工作区——页面、数据库、模板一起来——而不是手动捣鼓 30 分钟。」

❌ 没用的：「ProjectHub Skill 是一个包含 YAML 前置元数据和Markdown 指令的文件夹，调用我们的 MCP 服务器工具。」

讲 MCP + Skill 的完整故事：

我们的 MCP 服务器让 Claude 能访问你的 Linear 项目。

我们的 Skill 教会 Claude 你团队的 Sprint 规划流程。

两者结合，项目管理就交给 AI 了。

05｜模式与故障排查

这些模式来自早期用户和内部团队的实践，是我们观察到的有效做法，不是模板。

两种出发点：从问题出发 vs. 从工具出发

去五金店有两种方式——带着问题去（「我得修厨房橱柜」），让店员帮你找工具；或者先看上了一把新电钻，再想怎么用它干活。

Skill 也一样：

•从问题出发：「我要建一个项目工作区」→ Skill 按顺序编排好 MCP 调用，用户说目标，Skill 搞定工具。

•从工具出发：「我已经连了 Notion MCP」→ Skill 教会 Claude 怎么用这个工具，最优流程是什么。用户有权限，Skill 提供经验。

大多数 Skill 偏向其中一种。

搞清楚你的场景更接近哪边，有助于选下面合适的模式。

模式 1：顺序工作流编排

适合场景：用户需要按固定顺序完成多个步骤。

关键技术：

• 明确步骤顺序
• 步骤之间有依赖关系
• 每个阶段都要验证
• 失败时有回滚指令

模式 2：多 MCP 协调

适合场景：流程跨越多个服务。

示例：设计到开发的交接

关键技术：

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

模式 3：迭代优化

适合场景：输出质量需要多轮打磨。

示例：报告生成

关键技术：

• 判断标准要清晰
• 有备选方案
• 选择过程对用户透明

模式 4：根据上下文选工具

适合场景：目标相同，但用哪个工具取决于情况。

示例：智能文件存储

关键技术：

• 判断标准要清晰
• 有备选方案
• 选择过程对用户透明

模式 5：内嵌领域知识

适合场景：你的 Skill 不只是调工具，还带有专业判断。

示例：金融合规

关键技术：

• 领域知识直接写进逻辑
• 先合规再行动
• 全程有记录
• 治理规则清晰

故障排查

Skill 上传失败

Could not find SKILL.md in uploaded folder

文件名不对。重命名为 SKILL.md（大小写敏感），用 ls -la 确认一下。

Invalid frontmatter

YAML 格式有问题。

常见错误：

Invalid skill name

名字里有空格或大写。改用 kebab-case：

Skill 不自动触发

改 description 字段。快速自查：

• 描述是不是太泛？（「帮助处理项目」这种没用）
• 有没有用户真会说的触发短语？
• 涉及特定文件类型的话，有没有提到？

调试方法：直接问 Claude「你什么时候会用 [Skill 名称] 这个 Skill？」

Claude 会把 description 复述给你，对比一下缺什么再调整。

Skill 触发太频繁

加负面触发词：

或者描述更精确：

或者添加限定范围：

MCP 连接问题

Skill 加载了但 MCP 调用出错，按顺序排查：

•确认 MCP 服务器已连接

Claude.ai：设置 > 扩展 > [你的服务]，状态应显示「已连接」

•检查认证

API 密钥有没有过期，权限/范围是否正确，OAuth token 是否需要刷新

•单独测试 MCP

让 Claude 不用 Skill 直接调用：「用 [服务] MCP 拉一下我的项目」。

如果这步也失败，问题在 MCP 本身，不在 Skill

•确认工具名称

Skill 里引用的工具名和 MCP 文档一致吗？工具名区分大小写

Claude 不按指令来

指令写太长了：

* 保持简洁，用列表和编号。

* 详细参考资料放到独立文件。

关键指令被埋了：

* 重要的放最前面

* 用「## 重要」或「## 关键」这类标题

* 必要时重复关键点。

表达含糊对比：

进阶做法：关键验证逻辑如果直接写成脚本，比写语言指令可靠得多。

代码结果是确定的，语言理解有偏差。Office Skill 里有这种做法的示例。

译者注：这个思路值得重视，越是核心的校验逻辑，越不该靠「说」来约束 Claude，而是直接用代码锁死。

语言指令本质上是概率性的，脚本才是确定性的。

Claude 偷懒，加一段鼓励：

注：这段话加在用户提示里比放在 SKILL.md 里更有效。

原因很简单：用户消息离当前推理更近，Claude 更容易「听进去」。

Skill 变慢或质量下降

原因通常是：Skill 文件太大、同时开太多 Skill、没有用到渐进式披露导致全量加载。

解决方法：

1. 精简 SKILL.md

• 详细文档移到 references/里，用链接引用
• SKILL.md 控制在 5,000 字以内

• 减少开启的 Skill 数量

• 同时开 20-50 个以上就要注意了
• 按需开启，别全开
• 相关功能可以打包成一个 Skill「合集」

06｜资源与参考

第一次构建 Skill，先看最佳实践指南，API 文档用到时再查。

官方文档

•Anthropic 资源：最佳实践指南、Skills 文档、API 参考、MCP 文档

•博客文章：介绍 Agent Skills、工程博客：为真实世界装备 Agent、Skills 详解、如何为 Claude 创建 Skill、为 Claude Code 构建 Skill、通过 Skill 改进前端设计

示例 Skill

公开 Skill 仓库：GitHub anthropics/skills，包含 Anthropic 做的可以直接改用的 Skill。

工具

skill-creator Skill：

• 内置于 Claude.ai，也可以用于 Claude Code
• 能从描述直接生成 Skill
• 可以帮你审查和改进
• 用法：「用 skill-creator 帮我做一个 Skill」

验证：

• skill-creator 也可以评估已有的 Skill
• 直接问：「帮我审查一下这个 Skill，给点改进建议」

遇到问题怎么办

•技术问题：Claude Developers Discord 社区论坛

•发现 Bug：GitHub Issues：anthropics/skills/issues

提交时附上：Skill 名称、错误信息、复现步骤

附录 A：快速检查清单

上传前后用这个清单验一遍你的 Skill。想快速入门的话，可以先用 skill-creator Skill 生成第一版，再逐项检查有没有遗漏。

开始之前

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

•确定了需要哪些工具（内置或 MCP）

•看了本指南和示例 Skill

•想好文件夹结构

开发过程中

•文件夹名称用 kebab-case

•有 SKILL.md 文件（大小写要对）

•YAML 前置元数据有 — 分隔符

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

•description 说清楚「做什么」和「什么时候用」

•没有 XML 标签（< >）

•指令清晰可操作

•有错误处理

•有示例

•参考资源有清晰链接

上传之前

•测试了明显相关的任务能否触发

•测试了换个说法的请求能否触发

•确认了无关话题不会触发

•功能测试通过

•工具集成正常（如果用了的话）

•已压缩成 .zip

上传之后

•在真实对话里测试过

•留意过触发太多或太少的情况

•收集了用户反馈

•根据反馈调整了 description 和指令

•metadata 里的版本号更新了

附录 B：YAML 前置元数据

必填字段：

所有可选字段：

安全说明

允许：

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

禁止：

• XML 尖括号（< >）——安全限制
• YAML 中的代码执行（使用安全 YAML 解析）
• 名称以「claude」或「anthropic」开头的 Skill（保留字）

附录 C：完整 Skill 示例

完整的、可直接用于生产的 Skill 示例：

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

•Example Skills：各种工作流模式

•Partner Skills 目录：Asana、Atlassian、Canva、Figma、Sentry、Zapier 等合作伙伴的 Skill

这些仓库持续更新，示例比本指南里的更多。

直接 clone 下来，按你的需求改，当模板用。

原文：The Complete Guide to Building Skills for Claude

译者：洛小山、林哲韬

关于我

我是洛小山，一个在 AI 浪潮中不断思考和实践的大厂产品总监。

我不追热点，只分享那些能真正改变我们工作模式的观察和工具。

如果你也在做 AI 产品，欢迎关注我，我们一起进化。