Claude Skills in Practice Claude Skills 实战指南
The Complete Guide to Building Skills for Claude
一份专为开发者与团队打造的阶梯式教育手册，
教您如何将
SOP 与专家知识转化为自动化工作流。
核心概念：什么是 Skill？
Skill 是一个装载了指令与工作流的文档夹，它能让 Claude 精准掌握您专属的作业流程，而无需每次对话都重新解释背景。
一个标准的 Skill 文档夹包含：
- SKILL.md (必填)：核心指令，包含决定何时触发的 YAML 前置数据。
- scripts/ (选填)：可执行的自动化脚本 (如 Python、Bash)。
- references/ (选填)：让 Claude 按需读取的参考文档与手册。
优势：透过教导 Claude 一次，未来即可永久受益，并确保团队产出的高度一致性。
阶梯式开发路径 (The Staircase)
Step 1. 规划与场景
定义明确的 Use Case，决定触发条件与目标，评估是否需要搭配外部工具 (MCP)。
Step 2. 结构建立
建立文档夹，配置必须的 SKILL.md，并遵循严格的 kebab-case 命名规范。
Step 3. 撰写指令
设置精准的 YAML 触发词，并运用渐进式揭露原则撰写强大的 Markdown 指令。
Step 4. 测试与发布
从手动单一任务测试开始，确认 API 与功能无误后，打包为 ZIP 并发布给团队。
MCP 与 Skills 的强大组合
(What Claude can do)
赋予工具灵魂的关键大脑
如果 MCP (Model Context Protocol) 提供了对外连接的「四肢」，例如读取 Notion 或建立 Linear 任务；那么 Skills 就是告诉 Claude 该如何正确使用这些工具的「大脑」。
没有 Skill 的 MCP：用户面对工具箱不知从何下手，每次都需要重新下达复杂 Prompt。
搭配 Skill 的
MCP：默认工作流自动启动，将最佳实践 (Best Practices) 嵌入每一次交互中，降低集成学习门槛。
三大核心应用场景 (Use Cases)
1. 文档与资产生成
用于创建具备高度一致性与质量的输出物。可嵌入品牌指南、模板结构与发布前的质量检查清单。(无需外部工具)
2. 工作流自动化
适用于多步骤流程，能确保 Claude 按部就班执行，并包含自动验证机制。通常需协调多个 MCP 服务器。
3. MCP 增强防护
专为增强既有 MCP 服务器所设计。注入领域知识 (如：Sentry 自动分析 Bug)、提供自动上下文，并预防常见的 API 错误。
YAML 撰写准则：决定生死的第一线
严格的命名规范 (Naming)
Claude 非常挑剔文档夹与文档名称的格式，任何微小的错误都会导致 Skill 无法加载。
- 主文档名必须精确为 SKILL.md (区分大小写，不可写成 skill.md)。
- 文档夹与
name:字段必须使用 kebab-case。 - 严格禁止包含空格、大写字母或底线 (例如：
Notion_Setup是错误的)。 - 禁止包含
README.md于 Skill 根目录内。
描述与触发词 (Description)
Description 是 Claude 判断是否主动启动 Skill 的唯一依据，长度需小于 1024 字符。
- 必须同时包含：「它能做什么」与「何时该使用它」(具体触发词)。
- 例如：「用于分析设计图稿。当用户上传 fig 文档，或要求『设计规格』时使用。」
- 网络安全禁令：绝对禁止在 YAML 中使用 XML 标签
< >，以防 Prompt 注入攻击。
指令设计的最佳实践 (Best Practices)
具体且可执行
避免空泛的指示。例如，不要写「妥善验证数据」，应该明确指示：「执行
scripts/validate.py，若出现错误，请检查是否遗漏必填字段。」代码比语言更具确定性。
渐进式揭露机制
为避免消耗过多 Token，保持 SKILL.md 精简，仅放核心步骤。将详细的 API 规范或庞大的样板移至 references/
文档夹，让 Claude 需要时再去读取。
默认错误处理
预见系统可能发生的错误并提供解法。例如设立一个「常见问题」区块：「若遭遇连接拒绝，请用户至设置 > 扩充功能中重新连接。」这能大幅减少人工介入。
实战案例一：Code Review 助手
单一任务标准结构
这是一个不需要外部 MCP 工具的标准 SKILL.md 写法。重点在于明确的前置条件与防呆机制。
- YAML 区块：精准定义触发条件。
- Role (角色设置)：赋予 Claude 专家视角。
- Workflow (工作流)：用数字编号强制执行顺序。
- Rules (限制)：明确告知「不该做什么」，防止过度干预。
---
name: strict-pr-reviewer
description: 当用户上传代码片段，或要求 Code Review 时触发。
---
# Role
你是一位严格且资深的后端架构师。
# Workflow
被触发时，请严格按顺序执行以下步骤：
1. **安全性扫描**：检查是否有 SQL Injection 或 Hardcoded 密码。
2. **性能评估**：标出时间复杂度超过 O(N^2) 的写法。
3. **产出报告**：以 Markdown 表格呈现修改建议。
# Rules
- 绝对**不要**直接给出完整重写的代码。
- 只提供具体的修改指引与思路。实战案例二：串接 MCP 的自动化
---
name: linear-bug-reporter
description: 协助将对话中的错误日志直接转换为 Linear 任务。
---
# Objective
分析错误日志，并主动使用 `linear` MCP 建立 Bug Ticket。
# Instructions
1. 从用户的 Error Log 中提取：代码、时间、可能原因。
2. 自动调用 `linear_create_issue` 工具。
3. 将 Title 设置为 `[Bug] {错误代码}` 格式。
# Error Handling (Fallbacks)
- 若找不到 `linear` 工具或连接失败，**请勿道歉**。
- 直接回退：产出 Markdown Bug 报告，请用户手动复制。多步骤与错误回退处理
这示范了如何让 Claude 像一个 RPA 机器人一样调用外部 API，并具备自我修复的逻辑。
- Objective (目标)：一句话讲明这个脚本的最终目的。
- 工具调用指示：明确写出要调用的工具名称 (如
linear_create_issue)。 - Fallback (回退机制)：极度重要！默认 MCP 可能会断线，告诉 Claude 在工具失效时该如何改用纯文字输出，避免流程中断。
测试与验证阶段
「先在单一任务上确保 Claude 能完美执行，再将该成功模式提取并封装为 Skill。」
全面测试指南：三个关键维度
| 测试维度 | 测试目标 | 衡量与检验标准 (Metrics) |
|---|---|---|
| 触发测试 (Triggering) | 确保 Skill 在正确的时机点被加载，并且不会在无关话题中过度触发。 | 90% 的相关请求能自动触发 Skill (不需用户手动叫出)；使用无关指令时保持静默。 |
| 功能测试 (Functional) | 验证工作流是否如预期产出正确结果，且妥善处理各种边缘情况。 | 0 个未处理的 API 错误；工具调用皆成功完成；确保输出格式结构一致。 |
| 性能对比 (Performance) | 证明导入 Skill 后，整体流程效率优于原始的「人工引导」基线。 | 对话来回次数大幅减少；所需的 Token 消耗量降低；无需用户介入纠正。 |
高级设计：五大常见专家模式
- 顺序编排 (Sequential Workflow)：严格定义步骤 1 到步骤 N。适用于具备先后依赖关系的任务，如「新建客户 -> 设置付款 -> 寄送欢迎信」。
- 多 MCP 协同 (Multi-MCP)：跨服务编排。如将 Figma 设计导出 (MCP 1)、存入 Google Drive (MCP 2)、并在 Linear 建立任务 (MCP 3)。
- 迭代优化 (Iterative Refinement)：建立「产出草稿 -> 脚本验证 -> 自动修正」的封闭循环，直到质量达标才结束对话。
- 上下文感知 (Context-aware)：为 Claude 建立决策树。例如：「若文档大于 10MB，调用云端硬盘 MCP；若为代码，调用 GitHub MCP。」
- 领域知识注入 (Domain-specific)：在调用 API 前嵌入合规检查或风控逻辑，让 Claude 表现得像一位资深专家。
最终步：封装与发布
打包与安装：完成测试后，将文档夹压缩为 .zip。个人用户可透过 Claude.ai 上传；企业团队管理员则可将其布署至整个
Workspace (自动更新)。
开源与 API：您可以将 Skill 托管于 GitHub，提供清晰的 README.md 安装教学。若是应用程序开发者，也能透过
API 的 container.skills 参数以程序化方式调用。
行销定位：在推广时，专注于「成果」而非技术。强调「此 Skill 能在几秒钟内为您完成项目配置」，让 MCP 与 Skill 成为您系统集成的最大卖点。
准备好打造专属 Skill 了吗？
「用知识驱动工具，让自动化成为团队标准」