🎯 Claude Skills 打造完全指南

原文：The Complete Guide to Building Skills for Claude
整理：Jarvis AI 助手
适用对象：想给 AI 配置专属技能的你

📖 目录

1. 什么是 Skill？
2. 核心设计原则
3. MCP + Skills 组合拳
4. 规划与设计
5. 技术规范
6. 编写高效 Skill 教程
7. 测试与迭代
8. 分发与共享
9. 常见模式与故障排除

1. 什么是 Skill？

Skill（技能） 是一个文件夹，用来教 AI 如何处理特定任务或工作流。

文件夹里有什么？

📁 your-skill-name/
├── 📄 SKILL.md              # ⭐ 必选，核心指令文件
├── 📁 scripts/              # 可选，可执行脚本（Python、Bash 等）
├── 📁 references/           # 可选参考资料
└── 📁 assets/               # 可选，模板、字体、图标等

什么时候用 Skill？

当你有可重复的工作流时，Skill 超有用：

• 根据需求生成前端设计稿
• 用统一方法论做研究
• 按团队风格指南创建文档
• 编排多步骤流程

一句话总结： 解释一遍，永久受益，不用每次都重新教。

2. 核心设计原则

🔐 原则一：渐进式披露（Progressive Disclosure）

Skill 采用三层架构，避免一次加载太多内容：

💡 好处： 省 tokens，同时保留专业深度。

🧩 原则二：可组合性（Composability）

AI 可以同时加载多个 Skill。你的 Skill 要能和其他 Skill 和谐共处，不要假设自己是唯一选手。

🚀 原则三：可移植性（Portability）

一次创建，横跨所有平台：
- Claude.ai ✅
- Claude Code ✅
- API ✅

3. MCP + Skills 组合拳

这一节给已经搭建好 MCP 服务器的同学。

做一个比喻 🍳

没有 Skills 时：

• ❌ 用户连上 MCP 但不知道干嘛用
• ❌ 大量「这东西怎么用」的问题
• ❌ 每次对话都从头开始
• ❌ 结果不稳定（每次 prompt 不同）

有 Skills 时：

• ✅ 工作流自动触发
• ✅ 一致的工具使用
• ✅ 最佳实践嵌入每次交互
• ✅ 学习曲线大大降低

4. 规划与设计

🎯 第一步：定义使用场景

在动手写代码之前，先想清楚你的 Skill 要解决什么问题。

好的使用场景定义示例：

使用场景：项目冲刺规划
触发条件：用户说「帮我规划这次冲刺」或「创建冲刺任务」

步骤：
1. 通过 MCP 获取项目状态
2. 分析团队速率和容量
3. 建议任务优先级
4. 在 Linear 创建任务（带标签和估算）

结果：完整规划好的冲刺任务列表

灵魂拷问 🧐

• 用户想完成什么？
• 需要哪些步骤？
• 需要什么工具（内置的还是 MCP）？
• 需要嵌入什么领域知识或最佳实践？

三种常见 Skill 类型

类型一：文档 & 资产创建

用途： 生成一致的、高质量的输出（文档、PPT、表格、代码等）

例如： 前端设计 Skill

「构建具有高设计质量的生产级前端界面。用于构建 Web 组件、页面、海报或应用。」

关键技巧：
- 内嵌风格指南和品牌标准
- 模板结构保证输出一致
- 输出前质量检查清单
- 不依赖外部工具（用 AI 内置能力）

类型二：工作流自动化

用途： 多步骤流程，方法论需要标准化

例如： skill-creator Skill

「交互式引导创建新 Skill。带领用户完成使用场景定义、frontmatter 生成、指令编写和验证。」

关键技巧：
- 带验证关卡的逐步工作流
- 通用结构模板
- 内置审查和改进建议
- 迭代优化循环

类型三：MCP 增强

用途： 为 MCP 工具访问添加工作流指导

例如： Sentry 代码审查 Skill

「使用 Sentry 错误监控数据自动分析和修复 GitHub PR 中检测到的 bug。」

关键技巧：
- 协调多个 MCP 调用的顺序
- 嵌入领域专业知识
- 提供用户本来需要自己指定的内容
- MCP 常见错误处理

✅ 如何定义成功标准？

量化指标

定性指标

• ✅ 用户不需要问「下一步干嘛」
• ✅ 工作流完成无需用户纠正
• ✅ 不同会话结果一致

5. 技术规范

📁 文件结构规范

📁 your-skill-name/
├── 📄 SKILL.md              # 必选
├── 📁 scripts/              # 可选
├── 📁 references/           # 可选
└── 📁 assets/               # 可选

⚠️ 关键规则（必看！）

SKILL.md 命名

• 必须exactly 是 SKILL.md（大小写敏感）
• ❌ 不接受 SKILL.MD、skill.md、Skill.md

Skill 文件夹命名

• ✅ 用 kebab-case：notion-project-setup
• ❌ 别用空格：Notion Project Setup
• ❌ 别用下划线：notion_project_setup
• ❌ 别用大写：NotionProjectSetup

不要放 README.md

• Skill 文件夹内不要放 README.md
• 所有文档放 SKILL.md 或 references/
• （GitHub 仓库层面可以有 README，那是给人类看的）

📋 YAML Frontmatter — 最关键的部分

这是 AI 判断要不要加载你的 Skill 的依据！

最基本格式

---
name: your-skill-name
description: 技能描述。使用场景包括用户说[...]的时候。
---

字段说明

description 写作模板

[这个技能做什么] + [什么时候用] + [关键能力]

✅ 好的例子：

# 例1：具体且可执行
description: 分析 Figma 设计文件并生成开发者交接文档。
当用户上传 .fig 文件、问「设计规格」「组件文档」或「设计转代码交接」时使用。

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

# 例3：清晰价值主张
description: PayFlow 客户入职工作流。处理账户创建、支付设置和订阅管理。
当用户说「入职新客户」「设置订阅」或「创建 PayFlow 账户」时使用。

❌ 差的例子：

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

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

# 太技术化，没有用户视角
description: 实现具有层级关系的项目实体模型。

🔒 安全禁区

• 禁止在 frontmatter 里出现 XML 尖括号 < >
• 禁止在名称里放 "claude" 或 "anthropic"（保留字）

6. 编写高效 Skill 教程

推荐结构模板

---
name: your-skill
description: [...]
---

# 技能名称

## 指令

### 第一步：[主要步骤]
清晰解释发生了什么。

### 示例
```bash
python scripts/fetch_data.py --project-id PROJECT_ID
# 期望输出：[描述成功的样子]

示例

示例 1：[常见场景]

用户说： "设置新的营销活动"

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

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

故障排除

错误：[常见错误信息]

原因： [为什么发生]
解决： [如何修复]

---

### 💡 最佳实践

#### 要具体、要可执行

✅ **好：**
> 运行 `python scripts/validate.py --input {filename}` 检查数据格式。
> 如果验证失败，常见问题包括：
> - 缺少必填字段（添加到 CSV）
> - 日期格式错误（用 YYYY-MM-DD）

❌ **差：**
> 先验证数据再继续。

#### 包含错误处理

```markdown
## 常见问题

### MCP 连接失败
如果看到「Connection refused」：
1. 确认 MCP 服务器在运行：设置 > 扩展程序
2. 验证 API key 有效
3. 尝试重连：设置 > 扩展程序 > [你的服务] > 重连

清晰引用内置资源

查询前，先查阅 references/api-patterns.md 了解：
- 速率限制指南
- 分页模式
- 错误码和处理方式

7. 测试与迭代

三层测试方案

测试三个维度

1️⃣ 触发测试

目标： 确保 Skill 在该激活的时候激活。

应该触发：
✅ "帮我设置新的 ProjectHub 工作区"
✅ "在 ProjectHub 创建一个项目"
✅ "为 Q4 规划初始化一个 ProjectHub 项目"

不应该触发：
❌ "旧金山天气怎么样？"
❌ "帮我写个 Python 代码"
❌ "创建一个电子表格"（除非你的 Skill 支持）

2️⃣ 功能测试

目标： 验证 Skill 输出正确。

测试：创建 5 个任务的项目

给定：项目名「Q4 规划」，5 个任务描述

当：Skill 执行工作流

那么：
- ✅ 项目在 ProjectHub 创建成功
- ✅ 5 个任务属性正确
- ✅ 所有任务关联到项目
- ✅ 无 API 错误

3️⃣ 性能对比

目标： 证明 Skill 比不用好。

🔄 使用 skill-creator 迭代

skill-creator 是帮你构建和改进 Skill 的好帮手：

创建时：
- 从自然语言描述生成 Skill
- 生成格式正确的 SKILL.md（含 frontmatter）
- 建议触发短语和结构

审查时：
- 标记常见问题（描述模糊、缺少触发、结构问题）
- 识别过度/不足触发的风险
- 建议测试用例

迭代改进时：

「用这个聊天中发现的问题和改进建议，来优化 Skill 处理[特定边缘情况]的方式」

根据反馈迭代

8. 分发与共享

当前分发模式

个人用户获取 Skill

1. 下载 Skill 文件夹
2. 压缩为 .zip（如果需要）
3. 上传到 Claude.ai：设置 > 能力 > Skills
4. 或放到 Claude Code skills 目录

组织级别部署

• 管理员可以全局部署（2025年12月18日已上线）
• 支持自动更新
• 集中管理

推荐发布方式

第一步：托管到 GitHub

• 公开仓库（开源 Skill）
• 清晰 README（安装说明）
• 示例用法 + 截图

第二步：在 MCP 文档中链接

• 从 MCP 文档链接到 Skill
• 解释两者一起用的价值
• 提供快速开始指南

第三步：创建安装指南

## 安装 [你的服务] Skill

### 1. 下载 Skill
- 克隆仓库：`git clone https://github.com/yourcompany/skills`
- 或从 Releases 下载 ZIP

### 2. 安装到 Claude
- 打开 Claude.ai > Settings > Skills
- 点击「Upload skill」
- 选择 Skill 文件夹（压缩包）

### 3. 启用 Skill
- 开启 [你的服务] Skill
- 确认 MCP 服务器已连接

### 4. 测试
- 问 Claude：「在 [你的服务] 中设置一个新项目」

9. 常见模式与故障排除

五大常用模式

模式一：顺序工作流编排

适合： 多步骤流程，每步有固定顺序。

## 工作流：客户入职

### 第一步：创建账户
调用 MCP 工具：`create_customer`
参数：name, email, company

### 第二步：设置支付
调用 MCP 工具：`setup_payment_method`
等待：支付方式验证

### 第三步：创建订阅
调用 MCP 工具：`create_subscription`
参数：plan_id, customer_id（来自第一步）

模式二：多 MCP 协调

适合： 工作流跨越多个服务。

## 设计到开发交接

### 阶段一：设计导出（Figma MCP）
1. 从 Figma 导出设计资源
2. 生成设计规格
3. 创建资源清单

### 阶段二：资源存储（Drive MCP）
1. 在 Drive 创建项目文件夹
2. 上传所有资源
3. 生成分享链接

### 阶段三：任务创建（Linear MCP）
1. 创建开发任务
2. 把资源链接附到任务
3. 分配给工程团队

### 阶段四：通知（Slack MCP）
1. 发交接摘要到 #engineering
2. 包含资源链接和任务引用

模式三：迭代优化

适合： 输出质量随迭代提升。

## 迭代式报告创建

### 初始草稿
1. 通过 MCP 获取数据
2. 生成第一版报告
3. 保存到临时文件

### 质量检查
1. 运行验证脚本：`scripts/check_report.py`
2. 识别问题：
   - 缺少章节
   - 格式不一致
   - 数据验证错误

### 优化循环
1. 解决每个问题
2. 重新生成受影响部分
3. 重新验证
4. 重复直到质量达标

### 最终化
1. 应用最终格式
2. 生成摘要
3. 保存最终版本

故障排除速查

❌ Skill 无法上传

❌ Skill 不触发

症状： Skill 从不自动加载

检查清单：
- description 是否太模糊？（"帮助处理项目" 这种不行）
- 是否包含用户会说的触发短语？
- 是否提到了相关文件类型？

调试方法：

问 Claude：「什么时候你会用 [skill name] skill？」
Claude 会把 description 复述回来，你就知道哪里缺了。

❌ Skill 触发太频繁

解决方案：

1. 加负面触发词：
   yaml
description: 高级数据分析用于 CSV 文件...
不要用于简单数据探索（用 data-viz skill）

2. 描述更具体：
   ```yaml
   # 太宽泛
   description: 处理文档

# 更具体
description: 处理 PDF 法律合同审查文档
```

❌ MCP 连接失败

检查清单：
1. ✅ MCP 服务器已连接（设置 > 扩展程序）
2. ✅ API key 有效且未过期
3. ✅ 权限/Scopes 正确
4. ✅ OAuth token 已刷新

📌 快速检查清单

上传前必查

• [ ] 文件夹名是 kebab-case
• [ ] SKILL.md 文件存在（exact 拼写）
• [ ] YAML frontmatter 有 --- 分隔符
• [ ] name 字段：kebab-case，无空格，无大写
• [ ] description 包含「做什么」和「什么时候用」
• [ ] 无 XML 标签 < >
• [ ] 指令清晰可执行
• [ ] 包含错误处理
• [ ] 有示例
• [ ] 引用文件路径清晰

上传后必查

• [ ] 在真实对话中测试
• [ ] 监控触发率（不足/过度）
• [ ] 收集用户反馈
• [ ] 根据反馈迭代改进

🔗 资源链接

• Anthropic Skills 官方文档
• Anthropic Skills 示例库
• ClawHub - Skills 市场

整理自 Anthropic 官方《The Complete Guide to Building Skills for Claude》
由 Jarvis AI 助手转换为中文小白友好版