Claude Skills
构建完全指南

Skill（技能）是一组指令——打包为一个简单的文件夹——用于教会 Claude 如何处理特定任务或工作流程。Skills 是自定义 Claude 最强大的方式之一。无需在每次对话中重复解释你的偏好、流程和领域专业知识，Skills 让你只需教 Claude 一次，便可永久受益。

当你有可重复的工作流程时，Skills 尤为强大：从规格说明生成前端设计、使用一致的方法论进行研究、创建遵循团队风格指南的文档，或编排多步骤流程。它们与 Claude 的内置能力（如代码执行和文档创建）配合良好。对于构建 MCP 集成的开发者，Skills 增加了另一个强大的层次，帮助将原始工具访问转化为可靠、优化的工作流程。

• Skill 结构的技术要求和最佳实践
• 独立 Skills 和 MCP 增强工作流程的模式
• 在不同用例中效果良好的模式
• 如何测试、迭代和分发你的 Skills

• 开发者——希望 Claude 始终遵循特定工作流程
• 高级用户——希望 Claude 遵循特定工作流程
• 团队——希望标准化 Claude 在组织中的工作方式

你将获得什么：到最后，你将能够在一次会话中构建一个功能性 Skill。预计使用 skill-creator 构建和测试你的第一个工作 Skill 大约需要 15-30 分钟。

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

• SKILL.md（必需）：使用 YAML frontmatter 的 Markdown 指令文件
• scripts/（可选）：可执行代码（Python、Bash 等）
• references/（可选）：按需加载的文档
• assets/（可选）：模板、字体、图标等输出资源

your-skill-name/
├── SKILL.md          # 必需 - 主技能文件
├── scripts/          # 可选 - 可执行代码
│   ├── process_data.py
│   └── validate.sh
├── references/       # 可选 - 文档资料
│   ├── api-guide.md
│   └── examples/
└── assets/           # 可选 - 模板等
    └── report-template.md

Skills 使用三级系统：

这种渐进式披露在保持专业知识的同时最小化 token 使用。

可组合性：Claude 可以同时加载多个 Skills。你的 Skill 应该能与其他 Skills 良好协作，不要假设它是唯一可用的能力。

可移植性：Skills 在 Claude.ai、Claude Code 和 API 中的工作方式完全相同。创建一次 Skill，它就能在所有平台上无需修改地工作，前提是环境支持 Skill 所需的依赖。

在编写任何代码之前，确定你的 Skill 应该支持的 2-3 个具体用例。

用例：项目 Sprint 规划
触发：用户说"帮我规划这个 sprint"或"创建 sprint 任务"
步骤：
  1. 从 Linear 获取当前项目状态（通过 MCP）
  2. 分析团队速度和容量
  3. 建议任务优先级
  4. 在 Linear 中创建带有适当标签和估算的任务
结果：完整规划的 sprint，任务已创建

问自己这些问题：

• 用户想要完成什么？
• 这需要什么多步骤工作流程？
• 需要哪些工具（内置或 MCP）？
• 应该嵌入哪些领域知识或最佳实践？

这些是理想目标——粗略基准而非精确阈值。

YAML frontmatter 是 Claude 决定是否加载你的 Skill 的方式。必须写对。

---
name: your-skill-name
description: 它做什么。当用户要求 [特定短语] 时使用。
---

字段要求

name（必需）：

• 仅使用 kebab-case
• 无空格或大写字母
• 应与文件夹名称匹配

description（必需）：

• 必须同时包含：Skill 做什么 + 何时使用它（触发条件）
• 1024 字符以内
• 不含 XML 标签（< 或 >）
• 包含用户可能说的特定任务
• 如相关，提及文件类型

可选字段：license、compatibility（1-500 字符）、metadata（自定义键值对）

描述字段的结构：[它做什么] + [何时使用] + [关键能力]

# 具体且可操作
description: 分析 Figma 设计文件并生成开发交接文档。
当用户上传 .fig 文件、要求"设计规格"、"组件文档"
或"设计到代码交接"时使用。

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

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

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

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

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

在 frontmatter 之后，用 Markdown 编写实际指令。推荐结构：

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

# 你的 Skill 名称

## 指令

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

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

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

## 示例

### 示例 1：[常见场景]
用户说："设置一个新的营销活动"
操作：
1. 通过 MCP 获取现有活动
2. 使用提供的参数创建新活动
结果：活动已创建，附带确认链接

## 故障排除

错误：[常见错误消息]
原因：[为什么会发生]
解决方案：[如何修复]

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

在继续之前验证数据。

其他最佳实践

• 清晰引用打包资源：在编写查询前，参考 references/api-patterns.md
• 使用渐进式披露：保持 SKILL.md 专注于核心指令，将详细文档移至 references/
• 包含错误处理：为常见错误提供具体的解决步骤

Skills 可以根据你的需求在不同严格程度下进行测试：

• 在 Claude.ai 中手动测试——直接运行查询并观察行为。快速迭代，无需设置。
• 在 Claude Code 中脚本测试——自动化测试用例，以便在更改时进行可重复验证。
• 通过 Skills API 编程测试——构建针对定义测试集系统运行的评估套件。

目标：确保你的 Skill 在正确的时间加载。

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

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

目标：验证 Skill 产生正确的输出。

测试：创建包含 5 个任务的项目
给定：项目名称 "Q4 Planning"，5 个任务描述
当：Skill 执行工作流
则：
  - 项目在 ProjectHub 中创建
  - 5 个任务以正确属性创建
  - 所有任务链接到项目
  - 无 API 错误

测试用例应覆盖：

• 有效输出生成
• API 调用成功
• 错误处理工作正常
• 边缘情况覆盖

目标：证明 Skill 相比基线改善了结果。

skill-creator 可以帮助你构建和迭代 Skills。如果你有 MCP 服务器并知道你的前 2-3 个工作流程，你可以在一次会话中构建和测试一个功能性 Skill——通常在 15-30 分钟内。

• 创建 Skills：从自然语言描述生成 Skills，产生格式正确的 SKILL.md
• 审查 Skills：标记常见问题，识别潜在的过度/不足触发风险
• 迭代改进：遇到边缘情况后，将示例带回 skill-creator 改进

"使用 skill-creator 帮我构建一个用于 [你的用例] 的 Skill"

Skills 是活文档。计划基于以下信号进行迭代：

个人用户获取 Skills 的方式

1. 下载 Skill 文件夹
2. 如需要，压缩文件夹
3. 通过 设置 > 功能 > Skills 上传到 Claude.ai
4. 或放置在 Claude Code 的 Skills 目录中

组织级 Skills

• 管理员可以在整个工作区部署 Skills（2025年12月18日发布）
• 自动更新
• 集中管理

对于编程用例——如构建应用、代理或利用 Skills 的自动化工作流——API 提供对 Skill 管理和执行的直接控制。

1. 托管在 GitHub——公开仓库，清晰的 README，示例用法和截图
2. 在 MCP 文档中记录——从 MCP 文档链接到 Skills，解释两者结合的价值
3. 创建安装指南——提供分步安装说明

# 安装 [你的服务] Skill

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

2. 安装到 Claude：
   - 打开 Claude.ai > 设置 > Skills
   - 点击"上传 Skill"
   - 选择 Skill 文件夹（已压缩）

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

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

你如何描述你的 Skill 决定了用户是否理解其价值并实际尝试。

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

# 工作流：入职新客户

## 步骤 1：创建账户
调用 MCP 工具：create_customer
参数：name, email, company

## 步骤 2：设置支付
调用 MCP 工具：setup_payment_method
等待：支付方式验证

## 步骤 3：创建订阅
调用 MCP 工具：create_subscription
参数：plan_id, customer_id（来自步骤 1）

## 步骤 4：发送欢迎邮件
调用 MCP 工具：send_email
模板：welcome_email_template

关键技术：明确的步骤排序 · 步骤间的依赖关系 · 每阶段验证 · 失败时的回滚指令

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

# 设计到开发交接

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

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

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

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

关键技术：清晰的阶段分离 · MCP 之间的数据传递 · 进入下一阶段前的验证 · 集中错误处理

使用场景：输出质量通过迭代改善。

# 迭代报告创建

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

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

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

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

关键技术：明确的质量标准 · 迭代改进 · 验证脚本 · 知道何时停止迭代

使用场景：相同结果，根据上下文使用不同工具。

# 智能文件存储

## 决策树
1. 检查文件类型和大小
2. 确定最佳存储位置：
   - 大文件（>10MB）：使用云存储 MCP
   - 协作文档：使用 Notion/Docs MCP
   - 代码文件：使用 GitHub MCP
   - 临时文件：使用本地存储

## 执行存储
基于决策：
- 调用适当的 MCP 工具
- 应用服务特定的元数据
- 生成访问链接

## 向用户提供上下文
解释为什么选择了该存储方式

使用场景：你的 Skill 添加超越工具访问的专业知识。

# 带合规性的支付处理

## 处理前（合规检查）
1. 通过 MCP 获取交易详情
2. 应用合规规则：
   - 检查制裁名单
   - 验证管辖权许可
   - 评估风险级别
3. 记录合规决定

## 处理
如果合规通过：
  - 调用支付处理 MCP 工具
  - 应用适当的欺诈检查
  - 处理交易
否则：
  - 标记待审查
  - 创建合规案例

## 审计跟踪
- 记录所有合规检查
- 记录处理决定
- 生成审计报告

关键技术：领域专业知识嵌入逻辑 · 行动前合规 · 全面文档 · 清晰治理

Anthropic 资源

• 最佳实践指南
• Skills 文档
• API 参考
• MCP 文档

博客文章

• Introducing Agent Skills
• Engineering Blog: Equipping Agents for the Real World
• Skills Explained
• How to Create Skills for Claude
• Building Skills for Claude Code
• Improving Frontend Design through Skills

skill-creator

• 内置于 Claude.ai，也可用于 Claude Code
• 可以从描述生成 Skills
• 审查并提供改进建议
• 使用方式："帮我使用 skill-creator 构建一个 Skill"

验证

• skill-creator 可以评估你的 Skills
• 使用方式："审查这个 Skill 并建议改进"

示例 Skills

• 公开 Skills 仓库：GitHub: anthropics/skills
• 包含 Anthropic 创建的可自定义 Skills
• 文档 Skills——PDF、DOCX、PPTX、XLSX 创建
• 示例 Skills——各种工作流模式
• 合作伙伴 Skills 目录——来自 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等

使用此清单在上传前后验证你的 Skill。如果想快速开始，可以使用 skill-creator 生成初稿，然后对照此清单确保没有遗漏。

以下是展示本指南中各种模式的完整、可用于生产环境的 Skills：

这些仓库持续更新，包含本指南之外的更多示例。你可以克隆它们，根据你的用例修改，并将其作为模板使用。

技术问题

• 一般问题：Claude Developers Discord 社区论坛

Bug 报告

• GitHub Issues：anthropics/skills/issues
• 请包含：Skill 名称、错误信息、复现步骤