原始来源（不可变）

Claude Skill 编写与实战指南

文件路径：raw/260311-Claude-Skill-编写与实战指南-洛小山-公众号.md

原文：The Complete Guide to Building Skills for Claude 译者：洛小山、林哲韬

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

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

引言

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 提供食谱：一步步说明怎么做出有价值的成果。
两者结合，用户不用自己摸索每个步骤就能完成复杂任务。

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

没有 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 在 90% 的相关查询中触发
在 X 次工具调用内完成工作流
每个工作流 0 次 API 调用失败

定性指标：

用户不需要提示 Claude 下一步做什么
工作流不需要用户纠正就能跑完
跨会话结果稳定

技术要求

文件结构：

skill-name/
├── SKILL.md          # 主指令文件（必需）
├── references/       # 参考资料（可选）
│   ├── api-docs.md
│   └── examples/
└── assets/          # 资源文件（可选）

关键规则：

文件夹名称：kebab-case（如 my-skill-name）
主文件必须叫 SKILL.md（大小写敏感）
YAML 前置元数据用 --- 分隔

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

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

---
name: skill-name-in-kebab-case
description: 它做什么以及何时使用。包含具体触发短语。
---

字段要求：

name：kebab-case，无空格，无大写
description：最关键，决定 Skill 的「可发现性」

安全限制： 前置元数据里禁止：

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

编写有效的 Skill

description 字段

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

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

好的 description 示例：

# 好 - 具体且可操作
description: 分析 Figma 设计文件并生成开发者交接文档。

# 好 - 包含触发短语
description: 管理 Linear 项目工作流，包括 Sprint 规划、任务创建和状态追踪。当用户提到「sprint」「Linear 任务」「项目规划」或要求「创建工单」时使用。

不好的 description 示例：

# 太模糊
description: 帮助处理项目。

# 缺少触发条件
description: 创建复杂的多页文档系统。

# 太技术化，没有用户会说的词
description: 实现具有层级关系的 Project 实体模型。

编写主体指令

推荐结构：

目标（Goal）
工作流程（Workflow）
关键约束（Constraints）
示例（Examples）
错误处理（Error Handling）

包含错误处理：

## 错误处理
- API 调用失败时，先检查认证状态
- 如果创建失败，回滚已完成的步骤
- 向用户清晰报告错误原因和解决方案

用好渐进式披露： SKILL.md 只放核心指令，详细文档放到 references/ 里并加链接。

03｜测试与迭代

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

在 Claude.ai 里手动测试：直接跑查询，看行为。迭代最快，不需要任何配置。
在 Claude Code 里写脚本测试：自动化测试用例，变更时可以重复验证。
通过 Skills API 编程测试：构建评估套件，针对预设测试集系统性地跑。

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

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

使用 skill-creator Skill

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

创建 Skill：

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

审查 Skill：

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

迭代改进：

用 Skill 过程中遇到边界情况或失败，把这些案例带回 skill-creator

根据反馈迭代

触发太少：

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

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

触发太多：

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

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

执行有问题：

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

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

04｜分发与共享

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

个人用户的安装方式：

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

组织级部署：

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

开放标准

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

通过 API 调用 Skill

/v1/skills 端点，用来列出和管理 Skill
通过 container.skills 参数把 Skill 挂到 Messages API 请求上
在 Claude Console 里做版本管理
配合 Claude Agent SDK 构建自定义 Agent

现在推荐这么做

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

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

05｜模式与故障排查

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

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

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

模式 1：顺序工作流编排

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

关键技术：

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

模式 2：多 MCP 协调

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

示例：设计到开发的交接

从 Figma 获取设计规格
在 GitHub 创建 Issue
在 Linear 创建任务
在 Slack 通知团队

关键技术：

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

模式 3：迭代优化

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

示例：报告生成

生成初稿
自我审查
改进薄弱部分
最终润色

关键技术：

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

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

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

示例：智能文件存储

敏感文档 → 加密存储
大文件 → 对象存储
协作文档 → 团队空间

模式 5：内嵌领域知识

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

示例：金融合规

检查交易限额
验证资金来源
记录审计日志
生成合规报告

关键技术：

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

故障排查

Skill 上传失败：

Could not find SKILL.md in uploaded folder → 文件名不对，重命名为 SKILL.md（大小写敏感）
Invalid frontmatter → YAML 格式有问题
Invalid skill name → 名字里有空格或大写，改用 kebab-case

Skill 不自动触发： 改 description 字段。快速自查：

描述是不是太泛？
有没有用户真会说的触发短语？
涉及特定文件类型的话，有没有提到？

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

Skill 触发太频繁： 加负面触发词或描述更精确。

MCP 连接问题： 按顺序排查：

确认 MCP 服务器已连接
检查认证（API 密钥、OAuth token）
单独测试 MCP
确认工具名称

Claude 不按指令来：

指令写太长了 → 保持简洁，用列表和编号
关键指令被埋了 → 重要的放最前面
表达含糊 → 用具体可验证的标准

Claude 偷懒： 加一段鼓励：

## 注意
- 请认真完成，不要走捷径
- 质量优先，速度其次
- 验证步骤不能跳过

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

解决方法：

精简 SKILL.md（控制在 5,000 字以内）
详细文档移到 references/ 里
减少开启的 Skill 数量
相关功能可以打包成一个 Skill「合集」

06｜资源与参考

官方文档

Anthropic 资源：最佳实践指南、Skills 文档、API 参考、MCP 文档
博客文章：介绍 Agent Skills、工程博客、Skills 详解

示例 Skill

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

工具

skill-creator Skill：

内置于 Claude.ai，也可以用于 Claude Code
能从描述直接生成 Skill
可以帮你审查和改进

遇到问题怎么办

技术问题：Claude Developers Discord 社区论坛
发现 Bug：GitHub Issues：anthropics/skills/issues

附录 A：快速检查清单

开始之前

确定了 2-3 个具体用例
确定了需要哪些工具（内置或 MCP）
看了本指南和示例 Skill
想好文件夹结构

开发过程中

上传之前

测试了明显相关的任务能否触发
测试了换个说法的请求能否触发
确认了无关话题不会触发
功能测试通过
工具集成正常（如果用了的话）
已压缩成 .zip

上传之后

在真实对话里测试过
留意过触发太多或太少的情况
收集了用户反馈
根据反馈调整了 description 和指令
metadata 里的版本号更新了

附录 B：YAML 前置元数据

必填字段：

---
name: skill-name-in-kebab-case
description: 它做什么以及何时使用。包含具体触发短语。
---

安全说明：

允许：任何标准 YAML 类型、自定义 metadata 字段、长描述（最多 1024 个字符）
禁止：XML 尖括号（< >）、YAML 中的代码执行、名称以「claude」或「anthropic」开头的 Skill

附录 C：完整 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 译者：洛小山、林哲韬

本文知识产权归洛小山所有。未经授权，禁止抓取本文内容，用于模型训练以及二次创作等用途。

Claude Skill 编写与实战指南

引言

01｜基础知识

Skill 是什么？

渐进式披露（Progressive Disclosure）

可组合性（Composability）

可移植性（Portability）

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

02｜规划与设计

从用例出发

常见 Skill 用例类别

定义成功标准

技术要求

编写有效的 Skill

目标（Goal）

工作流程（Workflow）

关键约束（Constraints）

示例（Examples）

错误处理（Error Handling）

03｜测试与迭代

推荐测试方法

使用 skill-creator Skill

根据反馈迭代

04｜分发与共享

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

开放标准

通过 API 调用 Skill

现在推荐这么做

05｜模式与故障排查

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

模式 1：顺序工作流编排

模式 2：多 MCP 协调

模式 3：迭代优化

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

模式 5：内嵌领域知识

故障排查

06｜资源与参考

官方文档

示例 Skill

工具

遇到问题怎么办

附录 A：快速检查清单

开始之前

开发过程中

上传之前

上传之后

附录 B：YAML 前置元数据

附录 C：完整 Skill 示例