【附赠双语PDF】Anthropic 官方发布:Claude Skills 构建完整指南

📚 33页官方指南 | 🛠️ 实战案例 | 🎯 从入门到精通

Anthropic 之前悄咪咪放了个大招——33页的《Claude 技能构建完整指南》。

这不是那种泛泛而谈的文档，而是从实战出发的硬核手册。从技能设计到 MCP 集成，从测试迭代到发布分发，全流程覆盖。

特此分享给各位读者！！！如果读后有感，帮忙三连🙏🙏🙏

为什么你应该读这本指南？

如果你用过 Claude，一定遇到过这种情况：

每次都要重新解释你的偏好、流程、代码规范……明明之前说过无数次。

技能（Skills）就是解决这个问题的答案。

它是 Anthropic 推出的”自定义 Claude”方式——通过一套简单的文件夹结构，把你的工作流、最佳实践、领域知识固化下来，让 Claude 一次学会，终身受用。

指南里有什么？

📋 六大章节，33页干货

第一章：基础知识 — 什么是技能、三层渐进式披露设计、MCP 集成原理

第二章：规划与设计 — 用例定义、三类常见场景、YAML 规范、指令编写最佳实践

第三章：测试与迭代 — 触发测试、功能测试、skill-creator 工具、基于反馈的优化

第四章：发布与分享 — GitHub 托管、API 使用、组织级部署、营销文案怎么写

第五章：模式与故障排查 — 5种设计模式（顺序编排/多MCP协调/迭代优化等）、6类故障排查

第六章：资源与参考 — 完整检查清单、YAML 参考、官方示例仓库

谁应该读？

✅ 想让Agents按固定流程工作的开发者

✅ 有重复工作流想自动化的效率党

✅ 正在做 MCP 集成想加技能层的构建者

✅ 想在团队内统一 Agents 使用方式的管理者

学完能做什么？

根据官方说法，配合 skill-creator 工具，15-30 分钟就能做出你的第一个可用技能。

想象一下：

以前每次都要说”用我们团队的代码规范写”，现在 Agents 自动就知道；以前每次都要解释项目结构，现在打开对话就能直接用。

这就是技能的价值——一次配置，长期受益。

🎁 读者福利

为了帮助大家更好地学习和使用，我整理了：

📚 中英文双语版 PDF 文件

领取方式：

关注公众号后私信回复 👉 skills指南

即可获取PDF 文件的下载链接

如果你已经在用 OpenClaw、Claude Code 或任何 Agents 工具，强烈建议花 1 小时读完这本指南，然后动手做一个技能试试。

你会发现，Agents 的上限，其实由你的技能设计决定。

—— 以下为指南中文完前三张版 ——

Claude 技能构建完整指南

简介 ………………………………………………………………………… 3
第一章：基础知识 ……………………………………………………… 4
第二章：规划与设计 ………………………………………………….. 7
第三章：测试与迭代 ………………………………………………… 14
第四章：发布与分享 ………………………………………………… 18
第五章：模式与故障排查 …………………………………………….. 21
第六章：资源与参考 ………………………………………………… 28

简介

技能（Skill）是一套指令——打包成一个简单的文件夹——用来教 Claude 如何处理特定任务或工作流程。技能是自定义 Claude 以满足你特定需求的最强大方式之一。

每次对话都要重新解释你的偏好、流程和专业背景？有了技能，你只需要教一次，以后每次都能直接用上。

当你有可重复执行的工作流程时，技能特别强大： – 根据设计稿生成前端界面 – 用固定的方法论做研究调查 – 按照团队风格指南编写文档 – 协调多个步骤的复杂流程

技能与 Claude 的内置功能（如代码执行、创建文档）配合得很好。对于那些正在构建 MCP 集成的人来说，技能添加了另一层强大的功能——帮助将原始工具访问转变为可靠、优化的工作流程。

本指南涵盖构建有效技能所需的一切知识——从规划和结构到测试和分发。无论你是为自己、团队还是社区构建技能，你都会在整个过程中找到实用的模式和真实示例。

你将学到什么：

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

本指南适合谁：

希望 Claude 一致地遵循特定工作流程的开发者
希望 Claude 遵循特定工作流程的高级用户
希望在团队/组织内标准化 Claude 使用方式的管理者

两条阅读路径：

只构建独立技能？ 重点阅读”基础知识”和”规划与设计”部分，以及第1-2类用例。

增强 MCP 集成？ “技能 + MCP”部分和第3类用例更适合你。

两条路径使用相同的技术要求，你可以根据自己的用例选择相关内容。

你将从本指南中获得什么：

阅读完本指南后，你将能够在一次工作中构建一个功能完整的技能。使用 skill-creator 工具，预计需要15-30分钟来构建和测试你的第一个工作技能。

让我们开始吧。

第一章：基础知识

什么是技能？

技能是一个包含以下内容的文件夹：

文件/文件夹	是否必须	作用
SKILL.md	✅ 必须	带 YAML 前置信息的 Markdown 格式指令
scripts/	可选	可执行代码（Python、Bash 等）
references/	可选	按需加载的参考文档
assets/	可选	输出用的模板、字体、图标等

三个核心设计理念

1. 渐进式披露（Progressive Disclosure）

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

第一层（YAML 前置信息）

：每次都会加载到 Claude 的系统提示里。内容要精简——让 Claude 知道”这个技能是做什么的、什么时候该用它”就够了，不需要把所有东西都塞进来。
第二层（SKILL.md 正文）

：当 Claude 觉得当前任务跟这个技能有关时，才会加载完整指令。
第三层（链接文件）

：放在技能文件夹里的其他文件，Claude 可以按需查阅。

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

2. 可组合性（Composability）

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

3. 可移植性（Portability）

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

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

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

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

厨房比喻： – MCP 提供专业厨房：工具、食材、设备的访问权限 – 技能提供食谱：逐步指导如何创造有价值的成果

两者结合，让用户无需自己摸索每一步就能完成复杂任务。

它们如何配合：

MCP（连接层）	技能（知识层）
把 Claude 连接到你的服务（Notion、Asana、Linear 等）	教 Claude 怎么有效地使用这些服务
提供实时数据访问和工具调用能力	固化工作流程和最佳实践
Claude 能做什么	Claude 应该怎么做

为什么这对你的 MCP 用户很重要：

没有技能时，用户可能遇到的问题： – 连上了 MCP，但不知道下一步该干啥 – 不断发来”怎么用你的集成做 X”的支持提问 – 每次对话从头开始，结果每次都不一样 – 用户会把问题归咎于你的 MCP 连接器，但根本原因其实是缺少工作流程指引

有了技能之后： – 预置的工作流程在需要时自动激活 – 工具调用稳定可靠 – 最佳实践内嵌在每次交互里 – 新用户的学习成本大幅降低

第二章：规划与设计

第一步：从用例出发

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

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

用例：项目冲刺规划触发条件：用户说"帮我规划这个冲刺"或"创建冲刺任务"步骤：  1. 通过 MCP 获取 Linear 的当前项目状态  2. 分析团队速度和容量  3. 建议任务优先级  4. 在 Linear 里创建带标签和估算的任务结果：冲刺计划规划完毕，任务全部创建好

问自己这几个问题： – 用户想达成什么目标？ – 这需要哪些多步骤的工作流程？ – 需要哪些工具（Claude 内置的，还是 MCP 的）？ – 需要嵌入哪些领域知识或最佳实践？

三类常见用例

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

第 1 类：文档和素材创建

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

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

"创建有辨识度的、生产级别的前端界面，注重设计质量。在构建 Web 组件、页面、作品、海报或应用时使用。"

关键做法： – 嵌入风格指南和品牌规范 – 用模板结构保证输出一致 – 最终确认前做质量清单检查 – 不需要外部工具——用 Claude 的内置能力就够

第 2 类：工作流程自动化

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

真实案例：skill-creator 技能

"创建新技能的交互式向导。引导用户完成用例定义、前置信息生成、指令撰写和验证。"

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

第 3 类：MCP 增强

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

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

"利用 Sentry 错误监控数据，通过其 MCP 服务器自动分析和修复 GitHub Pull Requests 中发现的 bug。"

关键做法： – 按顺序协调多个 MCP 调用 – 嵌入领域专业知识 – 提供用户本来需要手动指定的上下文 – 处理常见 MCP 问题

第二步：定义成功标准

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

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

量化指标： – 技能在 90% 的相关查询中触发 – 怎么测：跑 10-20 个应该触发技能的测试问题，记录自动加载的次数 – 工作流程在 X 次工具调用内完成 – 怎么测：有无技能各跑一次相同任务，对比工具调用次数和 token 消耗 – 每个工作流程 0 次 API 调用失败 – 怎么测：测试期间监控 MCP 服务器日志，追踪重试率和错误码

定性指标： – 用户不需要提示 Claude 下一步该做什么 – 工作流程无需用户纠正就能跑完 – 跨会话结果保持一致

技术要求

文件夹结构

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

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

最简格式（够用了）：

---name: your-skill-namedescription: 它干什么。当用户说[具体短语]时使用。---

各字段说明

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 知道该用哪个技能的信息，而不需要把所有内容都加载到上下文里。”这就是渐进式披露的第一层。

格式模板：

[能做什么] + [什么时候用] + [主要功能]

✅ 好的写法：

# 好——具体且可操作description: 分析 Figma 设计文件并生成开发者交接文档。  当用户上传 .fig 文件，或者问"设计规格"、"组件文档"、  "设计转代码交接"时使用。# 好——包含触发词description: 管理 Linear 项目工作流，包括冲刺规划、任务创建和状态追踪。  当用户提到"冲刺"、"Linear 任务"、"项目规划"，  或者要求"创建工单"时使用。# 好——价值主张清晰description: PayFlow 的端到端客户引导工作流。  处理账户创建、支付设置和订阅管理。  当用户说"引导新客户"、"设置订阅"或"创建 PayFlow 账户"时使用。

❌ 不好的写法：

# 太模糊description: 帮助处理项目。# 没有触发条件description: 创建复杂的多页文档系统。# 太技术化，用户不会这么说description: 实现具有层次关系的 Project 实体模型。

写主体指令

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

推荐结构：

---name: your-skilldescription: [...]---# 你的技能名称## 指令### 第 1 步：[第一个主要步骤]清楚说明这步要做什么。示例：```bashpython scripts/fetch_data.py --project-id PROJECT_ID

预期输出：[描述成功时应该看到什么]

第 2 步：[下一步骤，按需添加]

（根据需要添加更多步骤）

示例

示例 1：[常见场景]

用户说：”设置一个新的营销活动”

操作： 1. 通过 MCP 获取现有活动 2. 用提供的参数创建新活动

结果：活动创建成功，附上确认链接

（根据需要添加更多示例）

故障排查

错误：[常见错误消息] 原因：[为什么会出现] 解决方法：[怎么修]

（根据需要添加更多错误案例）

**写指令的最佳实践：****✅ 要具体，要说清楚怎么操作：**```markdown运行 `python scripts/validate.py --input {filename}` 来检查数据格式。如果验证失败，常见原因有：- 缺少必填字段（把它加到 CSV 里）- 日期格式不对（要用 YYYY-MM-DD）

❌ 别含糊其词：

继续之前请先验证数据。

✅ 要包含错误处理：

## 常见问题### MCP 连接失败看到 "Connection refused" 时：1. 确认 MCP 服务器在运行：检查 设置 > 扩展2. 确认 API 密钥有效3. 尝试重连：设置 > 扩展 > [你的服务] > 重新连接

✅ 要用渐进式引用：

写查询之前，请先看 `references/api-patterns.md`，里面有：- 速率限制指南- 分页模式- 错误码和处理方式

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

第三章：测试与迭代

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

在 Claude.ai 里手动测试

——直接跑查询，看行为。迭代快，零配置。
在 Claude Code 里用脚本测试

——自动化测试用例，每次改完都能跑一遍验证。
通过技能 API 程序化测试

——构建系统化的评估套件，针对预定义测试集运行。

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

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

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

指标	无技能	有技能
用户如何提供指令	每次都要	自动执行
来回消息数	15 条	2 个澄清问题
API 调用失败次数	3 次（需要重试）	0 次
消耗的 token	12,000	6,000

使用 skill-creator 工具

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

它能帮你：

创建技能： – 从自然语言描述生成技能 – 自动产生格式正确的 SKILL.md – 建议触发词和结构

审查技能： – 标出常见问题：描述太模糊、缺少触发条件、结构有问题 – 识别过度/不足触发的风险 – 根据技能目的建议测试用例

迭代改进： – 遇到边缘案例或失败后，把问题带回 skill-creator，让它帮你改进 – 示例：”用这次对话中发现的问题和解决方案来改进技能处理[特定边缘案例]的方式”

使用方法：

"使用 skill-creator 帮我为[你的用例]构建一个技能"

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

根据反馈持续迭代

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

触发不足的信号： – 技能该自动加载时没加载 – 用户手动开启它 – 有人问”什么时候用这个技能”

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

触发过度的信号： – 技能在不相关的查询里也触发了 – 用户禁用了它 – 用户搞不清它的用途

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

执行问题的信号： – 结果不一致 – API 调用失败 – 需要用户帮忙纠正

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

原文：Anthropic《The Complete Guide to Building Skills for Claude》译文版本：2026年3月

👇 觉得有用？

别忘了关注公众号后私信回复 skills指南 领取双语版 PDF

恳请点赞、在看、分享到朋友圈三连支持 ❤️

⬇️ 扫码加作者微信 ⬇️