Claude Agent Skills 完全指南：构建、测试与分发自定义工作流

如果你希望 Claude 能像熟知你工作习惯的伙伴一样，无需反复叮嘱就能执行特定任务，那么构建 Skill（技能）是目前最有效的解决方案。本文将系统性地拆解 Skill 的核心概念、设计原则、构建步骤、测试方法与分发策略，帮助开发者和高级用户将复杂的工作流程转化为 Claude 可自动调用的能力。

本文欲回答的核心问题：如何从零开始构建一个高质量、可分发、能真正提升工作效率的 Claude Skill？

什么是 Claude Skill：重新定义 AI 能力边界

Skill 本质上是一个封装了特定指令集的文件夹，它教会 Claude 如何处理特定任务或工作流。与其在每次对话中重复解释你的偏好、流程和领域知识，不如通过 Skill 教会 Claude 一次，然后在后续每一次交互中受益。

Skill 的核心价值与应用场景

当工作流具有可重复性时，Skill 的威力最为显著。无论是根据规范生成前端设计、使用一致的方法论进行研究、创建符合团队风格指南的文档，还是编排多步骤流程，Skill 都能发挥重要作用。它与 Claude 内置的代码执行和文档创建能力协同良好。

对于构建 MCP（Model Context Protocol）集成的人来说，Skill 增添了一层强大的功能，帮助将原始的工具访问转化为可靠、优化的工作流。通过 Skill，我们可以实现：

标准化：确保 Claude 在整个组织内以一致的方式工作。
效率提升：减少用户每次对话时的重复说明成本。
可靠性：将最佳实践嵌入每一次交互中。

一个核心类比：厨房与食谱

为了更直观地理解 Skill 与 MCP 的关系，我们可以用一个厨房类比：

MCP 提供了专业厨房：它连接了 Claude 与各种服务（如 Notion、Asana、Linear 等），提供了工具、食材和设备的访问权限。这是 Claude “能做什么” 的基础。
Skill 提供了食谱：它包含了关于如何利用这些工具创造价值的分步指令。这是 Claude “应该怎么做” 的指导。

两者结合，用户无需自己摸索每一步，就能完成复杂的任务。如果没有 Skill，用户虽然连接了 MCP，却往往不知道下一步该做什么，导致支持工单增加、结果不一致，甚至错误地归咎于连接器本身。

技术基础：Skill 的文件结构与设计原则

构建 Skill 的第一步是理解其文件结构和核心设计原则。这不仅是技术规范，更是确保 Skill 能够被 Claude 正确识别和高效执行的基础。

标准文件结构

一个典型的 Skill 文件夹结构如下：

your-skill-name/
├── SKILL.md        # 必需 - 主要技能文件
├── scripts/        # 可选 - 可执行代码
├── references/     # 可选 - 按需加载的文档
└── assets/         # 可选 - 输出中使用的模板、字体、图标

SKILL.md（必需）：这是 Skill 的核心，包含 YAML 格式的元数据和 Markdown 格式的指令。文件名必须严格为 SKILL.md，区分大小写。
scripts/：存放 Python、Bash 等可执行脚本，用于处理数据或执行验证。
references/：存放参考文档，Claude 可以根据需要选择性地查阅这些内容。
assets/：存放模板、字体等在输出中需要使用的静态资源。

三大核心设计原则

Skill 的设计遵循三个关键原则，确保了其在不同场景下的高效性与可移植性。

1. 渐进式披露

Skill 采用三级加载系统，旨在最小化 Token 使用量，同时保持专业知识的完整性。

第一级（YAML 元数据）：始终加载在 Claude 的系统提示中。它提供了刚好足够的信息，让 Claude 知道何时应该使用该 Skill，而无需加载所有内容。这是 Skill 的”门面”，决定了触发的准确性。
第二级（SKILL.md 正文）：当 Claude 认为该 Skill 与当前任务相关时加载。这里包含了完整的指令和指导。
第三级（链接文件）：Skill 目录内捆绑的额外文件（如 scripts/ 或 references/），Claude 仅在需要时才会选择导航和发现这些内容。

这种设计既保证了响应速度，又确保了复杂任务的深度支持。

2. 可组合性

Claude 可以同时加载多个 Skill。这意味着你的 Skill 应该能够与其他 Skill 良好协作，而不是假设它是唯一可用的能力。在设计时，应专注于特定领域，避免功能过于宽泛。

3. 可移植性

Skill 在 Claude.ai、Claude Code 和 API 之间的工作方式完全相同。创建一次，即可在所有支持的环境中使用，前提是环境满足 Skill 所需的依赖项。这保证了 Skill 的一次构建，处处运行。

命名与格式规范

在构建过程中，严格遵守命名和格式规范是避免上传错误的关键。

Skill 文件夹命名：必须使用 kebab-case（短横线连接），如 notion-project-setup。禁止使用空格、下划线或大写字母。
SKILL.md 命名：必须完全匹配 SKILL.md，任何变体（如 skill.md、SKILL.MD）都会导致错误。
禁止 README.md：Skill 文件夹内部不应包含 README.md。所有文档都应整合进 SKILL.md 或 references/ 目录中（在通过 GitHub 分发时，仓库级别的 README 供人类阅读，但这与 Skill 内部结构是两回事）。

规划与设计：从场景到成功指标

在编写任何代码或指令之前，明确 Skill 的使用场景和成功标准至关重要。这是区分一个”能用”的 Skill 和一个”好用”的 Skill 的分水岭。

定义明确的用例

一个优秀的 Skill 应该针对 2-3 个具体的用例进行设计。一个好的用例定义应包含触发条件、步骤和预期结果。

示例：项目冲刺规划

触发条件：用户说”帮我规划这次冲刺”或”创建冲刺任务”。
步骤：
1. 通过 MCP 获取当前项目状态（如 Linear）。
2. 分析团队速度和容量。
3. 建议任务优先级。
4. 在 Linear 中创建带有正确标签和估算的任务。
结果：创建了一个包含所有任务的完整冲刺计划。

在定义用例时，需思考：用户想要达成什么？这需要哪些多步骤工作流？需要哪些工具（内置或 MCP）？应该嵌入哪些领域知识或最佳实践？

常见 Skill 类别与模式

根据实际观察，Skill 主要分为三大类别，每种都有其独特的技术重点。

类别	用途	关键技术	实例
文档与资产创建	创建一致、高质量的输出，如文档、演示文稿、代码、设计等。	嵌入式风格指南、模板结构、质量检查清单。无需外部工具，依赖 Claude 内置能力。	`frontend-design` Skill，用于构建生产级前端界面。
工作流自动化	受益于一致方法的多步骤流程，包括跨多个 MCP 服务器的协调。	分步工作流与验证关卡、通用结构模板、迭代优化循环。	`skill-creator` Skill，交互式引导创建新技能。
MCP 增强	增强 MCP 服务器提供的工具访问的工作流指导。	按顺序协调多个 MCP 调用、嵌入领域专业知识、常见 MCP 问题错误处理。	`sentry-code-review` Skill，利用 Sentry 数据自动分析和修复 GitHub PR 中的 Bug。

设定成功标准

如何知道你的 Skill 是否在正常工作？以下是定量和定性的衡量指标。这些是理想目标，而非精确阈值。

定量指标：

触发率：在相关查询中，Skill 应在 90% 的情况下被触发。
- 衡量方法：运行 10-20 个应触发 Skill 的测试查询，追踪自动加载与手动调用的比例。
工具调用次数：在 X 次工具调用内完成工作流。
- 衡量方法：对比启用与未启用 Skill 时完成相同任务的情况，统计工具调用次数和总 Token 消耗。
API 调用失败率：每个工作流的失败 API 调用为 0 次。
- 衡量方法：在测试运行期间监控 MCP 服务器日志，追踪重试率和错误代码。

定性指标：

用户无需提示 Claude 下一步该做什么。
工作流无需用户修正即可完成。
不同会话间结果一致。

反思与见解：在早期测试中，我们发现很多开发者容易陷入”过度设计”的陷阱，试图让一个 Skill 解决所有问题。但经验表明，专注于解决一个具有挑战性的单一任务，直到 Claude 能稳定成功，然后将其提炼为 Skill，往往比一开始就进行广泛测试更高效。这种”先做深，再做广”的策略，利用了 Claude 的上下文学习能力，能更快地获得有效信号。

编写实战：构建 SKILL.md 核心文件

SKILL.md 是 Skill 的大脑。理解其结构，特别是 YAML 元数据的写法，是决定 Skill 能否被正确触发和执行的关键。

YAML 元数据：触发器的艺术

YAML 元数据是 Claude 决定是否加载你的 Skill 的依据。这是渐进式披露的第一级，其重要性怎么强调都不为过。

最简必需格式：

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

字段详细要求：

name（必需）：
- 仅限 kebab-case。
- 无空格、无大写。
- 应与文件夹名称匹配。
description（必需）：
- 必须同时包含：Skill 的功能 + 何时使用（触发条件）。
- 长度限制在 1024 字符以内。
- 禁止包含 XML 标签（< 或 >）。
- 应包含用户可能说的具体任务或短语。
- 若涉及特定文件类型，应明确提及。
license（可选）：如果开源，使用标准标识，如 MIT、Apache-2.0。
metadata（可选）：自定义键值对，建议包含 author、version、mcp-server 等。

安全限制：

元数据中严禁出现 XML 尖括号。
Skill 名称禁止包含 “claude” 或 “anthropic”（保留关键字）。

描述字段编写指南

描述字段不仅是说明，更是匹配用户意图的核心。

优秀描述的结构： [功能] + [触发时机] + [关键能力]

优秀范例：

# 范例 1：具体且可操作
description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".

# 范例 2：包含具体触发短语
description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets".

反面教材：

# 过于模糊
description: Helps with projects.

# 缺失触发条件
description: Creates sophisticated multi-page documentation systems.

# 过于技术化，缺乏用户视角
description: Implements the Project entity model with hierarchical relationships.

编写主要指令内容

在元数据之后，使用 Markdown 编写具体的操作指令。建议采用模板化结构，包含指令、步骤、示例和故障排除。

推荐模板结构：

---
name: your-skill
description: [功能与触发条件]
---

# Your Skill Name

## Instructions
[总体指导原则]

## Step 1: [第一步]
Clear explanation of what happens.
Example:
```bash
python scripts/fetch_data.py --project-id PROJECT_ID

Expected output: [描述成功样貌]

Examples

Example 1: [常见场景]

User says: “Set up a new marketing campaign”
Actions:

Fetch existing campaigns via MCP
Create new campaign with provided parameters
Result: Campaign created with confirmation link

Troubleshooting

Error: [常见错误信息]

Cause: [原因]
Solution: [解决方案]


**最佳实践：**

1.  **具体且可操作**：明确命令和参数，而非模糊的指令。
    *   *好*：运行 `python scripts/validate.py --input {filename}` 来检查数据格式。
    *   *差*：在继续之前验证数据。
2.  **包含错误处理**：预见常见问题（如 MCP 连接失败），并给出检查步骤。
3.  **清晰引用捆绑资源**：指导 Claude 在何时查阅 `references/` 目录下的文档。
4.  **利用渐进式披露**：将核心指令保留在 `SKILL.md`，将详细文档移至 `references/` 并链接。

## 五大模式：构建复杂工作流的实战策略

根据早期采用者和内部团队的经验，我们总结出五种常见且有效的 Skill 构建模式。选择哪种模式取决于你的具体问题。

### 模式一：顺序工作流编排

**适用场景**：用户需要按特定顺序执行的多步骤流程。

**实例结构**：新客户入职工作流。

```markdown
## Workflow: Onboard New Customer

### Step 1: Create Account
Call MCP tool: `create_customer`
Parameters: name, email, company

### Step 2: Setup Payment
Call MCP tool: `setup_payment_method`
Wait for: payment method verification

### Step 3: Create Subscription
Call MCP tool: `create_subscription`
Parameters: plan_id, customer_id (from Step 1)

### Step 4: Send Welcome Email
Call MCP tool: `send_email`
Template: welcome_email_template

关键技巧：明确步骤顺序、定义步骤间依赖关系、每个阶段设置验证、为失败准备回滚指令。

模式二：多 MCP 协调

适用场景：工作流跨越多个服务。

实例：设计到开发的移交流程。

第一阶段：设计导出 -> 2. 第二阶段：资产存储 -> 3. 第三阶段：任务创建 -> 4. 第四阶段：通知

关键技巧：清晰的阶段分离、在 MCP 间传递数据、进入下一阶段前验证、集中式错误处理。

模式三：迭代优化

适用场景：输出质量随迭代提升。

实例：报告生成。

流程：初始草稿 -> 质量检查（运行验证脚本）-> 优化循环（修复问题、重新验证）-> 定稿。

关键技巧：明确的质量标准、迭代改进逻辑、验证脚本、明确的停止迭代条件。

模式四：上下文感知工具选择

适用场景：根据上下文不同，使用不同工具达成相同目标。

实例：智能文件存储。

## Decision Tree
1. Check file type and size
2. Determine best storage location:
   - Large files (>10MB): Use cloud storage MCP
   - Collaborative docs: Use Notion/Docs MCP
   - Code files: Use GitHub MCP
   - Temporary files: Use local storage

关键技巧：明确的决策标准、备选方案、对选择原因的透明解释。

模式五：领域特定智能

适用场景：Skill 在工具访问之外增加了专业知识。

实例：金融合规支付处理。

在处理支付前，先执行合规检查（制裁名单、司法管辖区、风险评估）。只有通过检查才处理交易，否则标记审查。全程记录审计追踪。

关键技巧：逻辑中嵌入领域专业知识、行动前合规检查、全面的文档记录、清晰的治理流程。

测试、迭代与诊断

Skill 的构建不是一次性的工作，而是一个持续迭代的过程。有效的测试和诊断策略能确保 Skill 的稳定性和可靠性。

三层测试方法

根据质量要求不同，可采取不同层级的测试：

Claude.ai 中的手动测试：直接运行查询并观察行为。迭代快，无需设置。
Claude Code 中的脚本测试：自动化测试用例，跨更改进行可重复验证。
通过 Skill API 进行程序化测试：针对定义的测试集系统化运行评估套件。

常见问题诊断与修复

问题：Skill 无法上传

错误：”Could not find SKILL.md” -> 原因：文件名不精确。解决：重命名为 SKILL.md（区分大小写）。
错误：”Invalid frontmatter” -> 原因：YAML 格式问题，如缺少分隔符 --- 或引号未闭合。

问题：Skill 不触发

诊断：描述字段可能过于宽泛或缺失触发短语。
修复：修订描述字段，使其包含用户实际会说的短语和相关文件类型。
调试技巧：直接问 Claude：”When would you use the [skill name] skill?”，根据回复调整描述。

问题：Skill 触发过于频繁

解决：添加负面触发条件（如 “Do NOT use for…”），或缩小范围，使其更具体。

问题：指令未被执行

常见原因：指令过于冗长、关键指令被埋没、语言模糊。
修复：精简指令、使用 ## Important 等标题突出重点、使用明确而非模糊的语言。对于关键验证，建议捆绑脚本而非依赖语言指令。

分发与共享：让价值流动起来

Skill 使 MCP 集成更加完整。拥有 Skill 的连接器能为用户提供更快的价值实现路径，从而在竞争中占据优势。

当前分发模型

个人用户获取方式：

下载 Skill 文件夹。
如需要，压缩文件夹。
通过 Claude.ai 的 Settings > Capabilities > Skills 上传。
或放置在 Claude Code 的 skills 目录中。

组织级 Skill：
管理员可以在工作区范围内部署 Skill，实现自动更新和集中管理。

定位你的 Skill

在描述 Skill 时，应聚焦于结果而非功能。强调 MCP + Skill 的组合故事——MCP 提供”能做什么”，Skill 提供”如何做”。

优秀定位：”ProjectHub Skill 让团队能在几秒钟内建立完整的项目工作区——包括页面、数据库和模板——而不是花费 30 分钟手动设置。”
不佳定位：”ProjectHub Skill 是一个包含 YAML 元数据和 Markdown 指令的文件夹，它调用我们的 MCP 服务器工具。”

结论与实用清单

构建 Claude Skill 是将重复、复杂的工作流程转化为 AI 可自动执行能力的有效途径。通过遵循渐进式披露、可组合性和可移植性的原则，并采用顺序编排、多 MCP 协调等实战模式，我们可以显著提升 AI 在特定领域的专业性和可靠性。

一页速览

核心构成：Skill = SKILL.md（YAML 元数据 + Markdown 指令）+ scripts/references/assets。
设计核心：渐进式披露（元数据 -> 指令 -> 文件），先定义用例再写代码。
关键文件：SKILL.md 命名必须精确；description 必须包含功能与触发时机。
构建模式：顺序工作流、多 MCP 协调、迭代优化、上下文感知选择、领域智能。
测试重点：验证触发准确性、功能正确性和性能提升。
分发方式：GitHub 托管 + 组织部署 + API 集成。

实用操作清单

构建前：

[ ] 识别 2-3 个具体用例
[ ] 确定所需工具（内置或 MCP）
[ ] 规划文件夹结构

开发中：

[ ] 文件夹命名使用 kebab-case
[ ] 确保 SKILL.md 文件存在且命名正确
[ ] YAML 元数据包含 --- 分隔符
[ ] description 包含 “做什么” 和 “何时用”
[ ] 无 XML 标签

上传前：

[ ] 测试触发情况（相关/不相关查询）
[ ] 功能测试通过
[ ] 如需，压缩为 .zip

上传后：

[ ] 在真实对话中测试
[ ] 监控触发频率
[ ] 收集反馈并迭代

常见问答 (FAQ)

Q1: Skill 和 MCP 有什么区别？
MCP（Model Context Protocol）主要负责连接 Claude 与外部服务（如 Notion、GitHub），提供”工具”和”食材”；而 Skill 是一套”食谱”，它教会 Claude 如何利用这些工具和食材，以特定的步骤和逻辑完成复杂任务。

Q2: SKILL.md 文件最关键的部分是什么？
YAML 元数据中的 description 字段最关键。它直接决定了 Claude 是否会在正确的时机触发你的 Skill。描述必须清晰说明功能和使用场景，并包含用户可能使用的具体触发短语。

Q3: 我的 Skill 文件夹可以包含 README.md 吗？
不可以。Skill 文件夹内部不应包含 README.md，否则可能导致加载问题。所有面向 AI 的文档应放在 SKILL.md 或 references/ 目录下。如果通过 GitHub 分发，可以在仓库根目录放置面向人类的 README。

Q4: 如何防止我的 Skill 在不相关的话题上被触发？
在 description 字段中添加负面触发条件，例如明确说明 “Do NOT use for [某种场景]”，或者使描述更加具体，限定其适用范围，避免使用过于宽泛的语言。

Q5: 我可以在 Skill 中使用外部脚本吗？
可以。你可以将 Python、Bash 等可执行脚本放在 scripts/ 目录中，并在 SKILL.md 的指令中调用它们。这特别适用于数据验证、复杂逻辑处理等需要确定性的任务。

Q6: 构建一个 Skill 通常需要多长时间？
如果你已经清楚工作流程并准备好了必要的工具（如 MCP 服务器），使用 skill-creator Skill 辅助，通常可以在 15-30 分钟内构建并测试一个功能性的 Skill。

Q7: 如何让团队其他成员使用我的 Skill？
目前，组织管理员可以将 Skill 部署到整个工作区，实现自动更新和集中管理。对于公开分享，推荐在 GitHub 托管，并提供清晰的安装说明。

Q8: Skill 是否可以在不同平台上通用？
是的，Skill 具有可移植性。同一个 Skill 文件夹在 Claude.ai、Claude Code 和 API 中的工作方式完全一致，前提是运行环境满足 Skill 的任何依赖要求。

Claude Skills终极指南：3步构建+测试+分发工作流自动化

Claude Agent Skills 完全指南：构建、测试与分发自定义工作流

什么是 Claude Skill：重新定义 AI 能力边界

Skill 的核心价值与应用场景

一个核心类比：厨房与食谱

技术基础：Skill 的文件结构与设计原则

标准文件结构

三大核心设计原则

1. 渐进式披露

2. 可组合性

3. 可移植性

命名与格式规范

规划与设计：从场景到成功指标

定义明确的用例

常见 Skill 类别与模式

设定成功标准

编写实战：构建 SKILL.md 核心文件

YAML 元数据：触发器的艺术

描述字段编写指南

编写主要指令内容

Examples

Example 1: [常见场景]

Troubleshooting

Error: [常见错误信息]

模式二：多 MCP 协调

模式三：迭代优化

模式四：上下文感知工具选择

模式五：领域特定智能

测试、迭代与诊断

三层测试方法

推荐测试流程

常见问题诊断与修复

分发与共享：让价值流动起来

当前分发模型

推荐分发路径

定位你的 Skill

结论与实用清单

一页速览

实用操作清单

常见问答 (FAQ)

Claude Skills终极指南：3步构建+测试+分发工作流自动化

Claude Agent Skills 完全指南：构建、测试与分发自定义工作流

什么是 Claude Skill：重新定义 AI 能力边界

Skill 的核心价值与应用场景

一个核心类比：厨房与食谱

技术基础：Skill 的文件结构与设计原则

标准文件结构

三大核心设计原则

1. 渐进式披露

2. 可组合性

3. 可移植性

命名与格式规范

规划与设计：从场景到成功指标

定义明确的用例

常见 Skill 类别与模式

设定成功标准

编写实战：构建 SKILL.md 核心文件

YAML 元数据：触发器的艺术

描述字段编写指南

编写主要指令内容

Examples

Example 1: [常见场景]

Troubleshooting

Error: [常见错误信息]

模式二：多 MCP 协调

模式三：迭代优化

模式四：上下文感知工具选择

模式五：领域特定智能

测试、迭代与诊断

三层测试方法

推荐测试流程

常见问题诊断与修复

分发与共享：让价值流动起来

当前分发模型

推荐分发路径

定位你的 Skill

结论与实用清单

一页速览

实用操作清单

常见问答 (FAQ)

相关文章