适用对象：想让Claude按固定流程工作的开发者、遵循自定义习惯的高级用户、统一团队Claude使用方式的管理者

目录

1. 简介

2. 第一章 基础知识

3. 第二章 规划与设计

4. 第三章 测试与迭代

5. 第四章 发布与分享

6. 第五章 模式与故障排查

7. 第六章 资源与参考

8. 附录A：快速检查清单

9. 附录B：YAML前置信息参考

10. 附录C：完整技能示例

1. 简介

技能（Skill）是一套打包成文件夹的指令，用于教Claude处理特定任务或工作流程，是自定义Claude最有力的方式之一。当你有重复执行的工作流程时，技能能帮你“一次教学，多次复用”，无需每次对话都重新解释偏好、流程和专业背景。

适用场景

• 根据设计稿生成前端界面

• 用固定方法论做研究调查

• 按照团队风格指南写文档

• 协调多个步骤的复杂流程

学习收获

• 技能的技术要求和最佳实践

• 独立技能和MCP增强型工作流的设计模式

• 经验证的有效做法

• 技能的测试、迭代与发布流程

阅读路径

• 仅做独立技能：重点阅读“基础知识”“规划与设计”章节

• 叠加MCP使用：重点阅读“技能+MCP”相关内容及第五章设计模式

• 预计投入：配合skill-creator工具，15-30分钟可完成首个可用技能

第一章 基础知识

技能的定义与构成

技能本质是一个文件夹，核心组成如下：

文件/文件夹	是否必须	作用
SKILL.md	✅ 必须	带YAML前置信息的Markdown格式指令
scripts/	可选	可执行代码（Python、Bash等）
references/	可选	按需加载的参考文档
assets/	可选	输出用的模板、字体、图标等

三个核心设计理念

1. 渐进式披露（Progressive Disclosure）

   1. 第一层（YAML前置信息）：每次加载到Claude系统提示，精简说明“技能用途+触发场景”

   2. 第二层（SKILL.md正文）：任务相关时加载完整指令

   3. 第三层（链接文件）：Claude按需查阅，既省token又保专业深度

2. 可组合性（Composability）：Claude可同时加载多个技能，需确保技能间兼容，不假设唯一启用状态

3. 可移植性（Portability）：在[Claude.ai](Claude.ai)、Claude Code和API中工作方式一致，“写一次，到处能用”（需运行环境支持依赖）

面向MCP开发者：技能与MCP的配合

MCP（连接层）与技能（知识层）是互补关系，具体分工如下：

MCP（连接层）	技能（知识层）
连接Claude与第三方服务（Notion、Asana、Linear等）	教Claude高效使用这些服务
提供实时数据访问和工具调用能力	固化工作流程和最佳实践
定义Claude“能做什么”	明确Claude“应该怎么做”

有无技能的差异

• 无技能：用户连MCP后不知下一步操作、反复咨询使用方法、跨会话结果不一致、问题归咎于MCP连接器

• 有技能：预置工作流程自动激活、工具调用稳定可靠、最佳实践内嵌交互、新用户学习成本大幅降低

第二章 规划与设计

第一步：从用例出发

编写代码前，先明确技能要解决的2-3个具体场景。一个优质用例定义需包含触发条件、步骤和结果，示例如下：

用例：项目冲刺规划 触发条件：用户说"帮我规划这个冲刺"或"创建冲刺任务" 步骤： 1. 通过MCP获取Linear的当前项目状态 2. 分析团队速度和容量 3. 建议任务优先级 4. 在Linear里创建带标签和估算的任务 结果：冲刺计划规划完毕，任务全部创建好

核心思考问题

• 用户想达成什么目标？

• 需哪些多步骤工作流程？

• 依赖哪些工具（Claude内置或MCP）？

• 需嵌入哪些领域知识或最佳实践？

三类常见用例及关键做法

用例类型	适合场景	真实案例	关键做法
文档和素材创建	生成一致高质量输出（文档、代码、设计等）	frontend-design（生成生产级前端界面）	嵌入风格规范、用模板保一致、质量清单检查、仅需Claude内置能力
工作流程自动化	多步骤流程需一致执行，跨MCP协调	skill-creator（创建新技能的交互式向导）	分步工作流带验证、内置审查建议、迭代优化循环
MCP增强	为MCP工具访问添加工作流程引导	sentry-code-review（分析修复GitHub PR漏洞）	顺序协调MCP调用、嵌入专业知识、补充上下文、处理常见MCP问题

第二步：定义成功标准

成功标准包含量化指标和定性指标，均为参考目标，需结合实际场景判断：

量化指标

• 技能触发率：90%的相关查询中自动加载（测试方法：跑10-20个相关问题，记录加载次数）

• 工作流效率：在X次工具调用内完成（测试方法：对比有无技能的工具调用次数和token消耗）

• 稳定性：每个工作流程0次API调用失败（测试方法：监控MCP服务器日志，追踪重试率和错误码）

定性指标

• 用户无需提示Claude下一步操作

• 工作流程无需用户纠正即可完成

• 跨会话结果保持一致

技术要求

文件夹结构

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

命名与格式规则

1. SKILL.md命名：必须精确区分大小写，SKILL.MD、skill.md等变体均无效

2. 技能文件夹命名：需用kebab-case（短横线连接小写，如notion-project-setup），禁止空格、下划线、大写

3. 禁止在技能文件夹内放[README.md](README.md)：所有文档统一放在SKILL.md或references/中（GitHub发布时，仓库根目录可放README供人类查阅）

YAML前置信息（最关键部分）

YAML前置信息是Claude判断是否加载技能的依据，格式必须规范。

最简格式

--- name: your-skill-name description: 它干什么。当用户说[具体短语]时使用。 ---

字段说明

字段	是否必填	要求
name	是	仅用kebab-case，无空格/大写，建议与文件夹名一致
description	是	含“技能用途+触发条件”，最多1024字符，无XML标签，包含用户实际表述
license	否	开源技能需填写，常见选项：MIT、Apache-2.0
compatibility	否	1-500字符，说明运行环境要求（如目标产品、系统包、网络需求）
metadata	否	任意键值对，推荐包含：author、version、mcp-server等
allowed-tools	否	限制工具访问（如"Bash(python:) Bash(npm:) WebFetch"）

完整示例

--- name: skill-name description: [必填描述] license: MIT compatibility: Requires Claude.ai with internet allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" metadata: author: 公司名称 version: 1.0.0 mcp-server: server-name category: productivity tags: [project-management, automation] documentation: https://example.com/docs support: support@example.com ---

安全限制

• 禁止使用XML尖括号（< >）

• 技能名称不能以"claude"或"anthropic"开头（保留词）

• 原因：前置信息会进入Claude系统提示，需防范恶意指令注入

写好description字段

遵循模板：[能做什么] + [什么时候用] + [主要功能]，以下是正反示例：

✅ 优质示例

• 具体可操作：分析Figma设计文件并生成开发者交接文档。当用户上传.fig文件，或者问"设计规格"、"组件文档"、"设计转代码交接"时使用。

• 包含触发词：管理Linear项目工作流，包括冲刺规划、任务创建和状态追踪。当用户提到"冲刺"、"Linear任务"、"项目规划"，或者要求"创建工单"时使用。

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

❌ 反面示例

• 太模糊：帮助处理项目。

• 无触发条件：创建复杂的多页文档系统。

• 过于技术化：实现具有层次关系的Project实体模型。

写主体指令

YAML前置信息之后，用Markdown编写具体指令，推荐结构如下：

--- name: your-skill description: [...] --- # 你的技能名称 ## 指令 ### 第1步：[第一个主要步骤] 清楚说明这步要做什么。 示例： ```bash python scripts/fetch_data.py --project-id PROJECT_ID

预期输出：[描述成功时应该看到什么]

第2步：[下一步骤，按需添加]

示例

示例1：[常见场景]

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

操作：

1. 通过MCP获取现有活动

2. 用提供的参数创建新活动

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

故障排查

错误：[常见错误消息]

原因：[为什么会出现]

解决方法：[怎么修]

#### 指令编写最佳实践 ✅ 具体可操作：`运行 python scripts/validate.py --input {filename} 来检查数据格式。如果验证失败，常见原因有：- 缺少必填字段（把它加到CSV里）- 日期格式不对（要用YYYY-MM-DD）` ❌ 含糊表述：`继续之前请先验证数据。` ✅ 包含错误处理：明确常见问题的排查步骤和解决方法 ✅ 渐进式引用：通过链接引用参考文档，如`写查询之前，请先看 references/api-patterns.md` ✅ 聚焦核心：SKILL.md仅保留核心指令，详细文档移至`references/` ## 第三章 测试与迭代 ### 测试方式选择 根据使用场景选择不同严格程度的测试方式： - 手动测试（Claude.ai）：直接跑查询观察行为，迭代快、零配置，适合个人小技能 - 脚本测试（Claude Code）：自动化测试用例，每次修改后批量验证，适合团队协作技能 - 程序化测试（技能API）：构建系统化评估套件，针对预定义测试集运行，适合企业级生产技能 ### 专业测试技巧 先针对最具挑战的任务反复迭代，直到Claude成功完成，再提炼为技能（充分利用Claude上下文学习能力），后续扩展到多个测试用例验证覆盖面。 ### 推荐测试方法 1. **触发测试**：验证技能在正确场景加载 - 应该触发：与技能用途强相关的查询（如"帮我设置新的ProjectHub工作区"） - 不应该触发：无关查询（如"旧金山今天天气怎么样"） 2. **功能测试**：验证技能输出准确性 示例：测试"创建包含5个任务的项目" - 给定条件：项目名"Q4规划"，5个任务描述 - 执行：技能运行工作流 - 验证点：项目创建成功、任务属性正确、任务关联项目、无API报错 3. **对比测试**：证明技能价值 | 指标 | 无技能 | 有技能 | |------|--------|--------| | 用户指令方式 | 每次都要重新说明 | 自动执行 | | 来回消息数 | 15条 | 2个澄清问题 | | API调用失败次数 | 3次（需重试） | 0次 | | 消耗token | 12,000 | 6,000 | ### 用skill-creator工具辅助开发 skill-creator是内置于Claude.ai（可下载用于Claude Code）的专用技能，核心能力如下： #### 核心功能 - 创建技能：从自然语言描述生成技能，自动生成格式正确的SKILL.md，建议触发词和结构 - 审查技能：标出常见问题（描述模糊、缺少触发条件等），识别过度/不足触发风险，建议测试用例 - 迭代改进：针对边缘案例或失败场景，提供优化建议 #### 使用方法

"使用skill-creator帮我为[你的用例]构建一个技能"

⚠️ 注意：skill-creator仅负责设计和打磨技能，不支持自动化测试套件和量化评估结果生成。 ### 根据反馈持续迭代 技能是"活文档"，需根据实际使用情况调整，关键信号与解决方法如下： | 问题信号 | 解决方法 | |----------|----------| | 触发不足（该加载时未加载、用户手动开启、询问使用场景） | 在description中补充细节和关键词（含专业术语） | | 触发过度（无关查询触发、用户禁用、用途混淆） | 添加负触发词、描述更具体、明确使用范围 | | 执行问题（结果不一致、API调用失败、需用户纠正） | 改进指令、强化错误处理、添加验证步骤 | ## 第四章 发布与分享 ### 当前分发方式（2026年1月） #### 个人用户获取技能 1. 下载技能文件夹 2. 压缩为zip格式 3. 通过Claude.ai的「设置 > 功能 > 技能」上传 4. 或放到Claude Code的技能目录中 #### 组织级技能部署 - 管理员可在工作区范围内部署（2025年12月18日已上线） - 支持自动更新和集中管理 ### 开放标准 Anthropic已将Agent Skills作为开放标准发布，技能应具备跨工具和平台的兼容性（同一个技能可在Claude及其他AI平台使用）。若技能依赖特定平台能力，需在`compatibility`字段注明。 ### 通过API使用技能 适合程序化调用场景（如构建应用、AI代理、自动化工作流），核心操作如下： - 用`/v1/skills`接口管理技能 - 在Messages API的`container.skills`参数中添加技能 - 在Claude Console做版本控制和管理 - 配合Claude Agent SDK构建自定义代理 #### API与Claude.ai选择指南 | 使用场景 | 推荐方式 | |----------|----------| | 用户直接使用技能 | Claude.ai / Claude Code | | 开发时手动测试和迭代 | Claude.ai / Claude Code | | 个人或临时工作流 | Claude.ai / Claude Code | | 程序化调用技能的应用 | API | | 规模化生产部署 | API | | 自动化管道和AI代理系统 | API | ⚠️ 注意：API中使用技能需Code Execution Tool（代码执行工具）测试版支持，以提供安全运行环境。 ### 快速发布步骤 #### 第一步：托管到GitHub - 开源技能使用公开仓库 - 仓库根目录编写README（供人类查看，与技能文件夹区分） - 附上使用示例和截图 #### 第二步：在MCP文档中说明 - 链接到技能资源 - 解释MCP+技能的组合价值 - 提供快速上手指南 #### 安装指南模板 ```markdown ## 安装 [你的服务] 技能 1. 下载技能： - 克隆仓库：`git clone https://github.com/yourcompany/skills` - 或从Releases下载ZIP 2. 安装到Claude： - 打开Claude.ai > 设置 > 技能 - 点击"上传技能" - 选择技能文件夹（压缩文件） 3. 启用技能： - 打开[你的服务]技能的开关 - 确认MCP服务器已连接 4. 测试： - 让Claude："在[你的服务]里设置一个新项目"

技能推广描述技巧

聚焦结果而非功能，讲清MCP+技能的组合价值，正反示例如下：

✅ 优质描述

• 结果导向：ProjectHub技能让团队能在几秒钟内建立完整的项目工作区——包括页面、数据库和模板——而不是花30分钟手动配置。

• 组合价值：我们的MCP服务器让Claude能访问你的Linear项目。我们的技能教Claude你团队的冲刺规划工作流程。两者结合，实现AI驱动的项目管理。

❌ 反面描述

• 功能罗列：ProjectHub技能是一个包含YAML前置信息和Markdown指令并调用我们MCP工具的文件夹。

第五章 模式与故障排查

设计模式（基于真实经验的有效做法）

模式选择逻辑

• 问题优先：用户提出目标（如"我需要设置项目工作区"），技能协调MCP调用实现

• 工具优先：用户已连接MCP（如"我已经连上了Notion MCP"），技能提供最佳工作流程

模式一：顺序工作流编排

适合场景：用户需要按特定顺序执行多个步骤

## 工作流：引导新客户 ### 第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

关键技术

• 明确步骤顺序和依赖关系

• 每个阶段设置验证节点

• 失败时提供回滚指令

模式二：多MCP协调

适合场景：工作流需要跨多个服务

## 设计转开发交接 ### 阶段一：设计导出（Figma MCP） 1. 从Figma导出设计资产 2. 生成设计规格文档 3. 创建资产清单 ### 阶段二：资产存储（Drive MCP） 1. 在Drive新建项目文件夹 2. 上传所有资产 3. 生成可分享的链接 ### 阶段三：创建任务（Linear MCP） 1. 创建开发任务 2. 把资产链接附到任务 3. 分配给工程团队 ### 阶段四：发送通知（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工具 - 应用特定服务的元数据 - 生成访问链接 ### 告知用户 说明为什么选了这个存储方式

关键技术

• 清晰定义决策标准

• 提供备用选项

• 向用户透明化选择理由

模式五：特定领域智能

适合场景：技能需在工具访问外提供专业知识

## 合规支付处理 ### 处理前（合规检查） 1. 通过MCP获取交易详情 2. 应用合规规则： - 核查制裁名单 - 验证司法管辖许可 - 评估风险等级 3. 记录合规决定 ### 执行处理 若合规通过： - 调用支付处理MCP工具 - 应用适当的反欺诈检查 - 处理交易 否则： - 标记待审核 - 创建合规案例 ### 审计追踪 - 记录所有合规检查 - 记录处理决定 - 生成审计报告

关键技术

• 嵌入领域专业知识到逻辑中

• 行动前执行合规检查

• 完整记录操作过程

• 明确治理边界

常见故障排查

技能上传失败

错误提示	原因	解决方法
"Could not find [SKILL.md](SKILL.md) in uploaded folder"	文件名不是精确的SKILL.md	重命名后用ls -la验证
"Invalid frontmatter"	YAML格式错误（缺少分隔符、引号未闭合等）	按规范补充---分隔符，修正语法错误
"Invalid skill name"	技能名称含空格或大写	改为kebab-case格式（如my-cool-skill）

技能不触发

• 自查清单：description是否太笼统？是否包含用户实际表述的触发词？涉及文件类型是否明确提及？

• 调试技巧：问Claude"你什么时候会用[技能名]这个技能？"，根据反馈补充description内容

技能触发太频繁

解决方法：

1. 添加负触发词：description: 用于CSV文件的高级数据分析，适合统计建模、回归、聚类分析。不要用于简单数据探索（请改用data-viz技能）。

2. 描述更具体：将"处理文档"改为"处理PDF法律文件以供合同审查"

3. 明确使用范围：description: PayFlow电子商务支付处理。专门用于在线支付工作流，不适用于一般财务查询。

MCP连接问题（技能加载但调用失败）

检查清单：

1. 确认MCP服务器已连接（[Claude.ai](Claude.ai)：设置 > 扩展 > [你的服务]，显示"已连接"）

2. 验证身份信息（API密钥有效未过期、权限范围正确、OAuth令牌已刷新）

3. 单独测试MCP（直接让Claude调用："用[服务]MCP获取我的项目"，排除MCP本身问题）

4. 核对工具名称（区分大小写，确保无拼写错误）

指令未被遵守

常见原因及解决方法：

1. 指令冗长：保持简洁，多用列表编号，详细文档移至单独文件

2. 关键指令被埋没：重要内容放前面，用## 重要标题突出，关键点可重复

3. 语言模糊：将"确保正确验证相关内容"改为明确条件（如项目名称非空、分配团队成员等）

4. 模型"偷懒"：添加执行说明（- 请花足够时间彻底完成 - 质量比速度更重要 - 不要跳过验证步骤），建议加在用户提示中

上下文过大导致响应慢/质量下降

原因：SKILL.md内容过多、同时启用技能过多、未使用渐进式披露

解决方法：

1. 精简[SKILL.md](SKILL.md)（详细文档移至references/，用链接引用，控制在5000词以内）

2. 减少同时启用的技能数量（超过20-50个需精简，相关功能打包为"组合包"）

第六章 资源与参考

官方文档

• Best Practices Guide（最佳实践指南）

• Skills Documentation（技能文档）

• API Reference（API参考）

• MCP Documentation（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

示例技能

公开技能仓库（可直接自定义使用）：

• GitHub：anthropics/skills（Anthropic官方创建的技能）

• Document Skills：PDF、DOCX、PPTX、XLSX创建类技能

• Example Skills：各种工作流程模式示例

• Partner Skills Directory：Asana、Atlassian、Canva、Figma等合作伙伴技能

工具和实用程序

• skill-creator：技能创建、审查、迭代辅助工具

• 验证与评审：用skill-creator评估已有技能，问法："请审查这个技能，并给出改进建议"

获取支持

• 技术问题：社区论坛 / Claude Developers Discord

• Bug报告：GitHub Issues（anthropics/skills/issues），提交时需包含技能名称、错误信息、复现步骤

附录A：快速检查清单

开始之前

• 确定了2-3个具体用例

• 明确所需工具（内置或MCP）

• 阅读指南和示例技能

• 规划文件夹结构

开发过程中

• 文件夹用kebab-case命名

• SKILL.md文件存在（精确拼写，区分大小写）

• YAML前置信息有---分隔符

• name字段符合kebab-case、无空格/大写要求

• description同时包含"做什么"和"什么时候用"

• 无XML标签（< >）

• 指令清晰可操作

• 包含错误处理和示例

• 参考资料有清晰链接

上传前

• 测试明显任务和变体表述的触发效果

• 确认不会在不相关主题上触发

• 功能测试通过

• 工具集成正常（如有）

• 压缩为.zip文件

上传后

• 在真实对话中测试

• 观察过度/不足触发情况

• 收集用户反馈

• 根据反馈迭代description和指令

• 更新metadata中的版本号

附录B：YAML前置信息参考

必填字段

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

所有可选字段

name: skill-name description: [必填描述] license: MIT # 可选：开源协议 allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" # 可选：限制工具访问 compatibility: Requires network access # 可选：运行环境需求（1-500字符） metadata: # 可选：自定义字段 author: Company Name version: 1.0.0 mcp-server: server-name category: productivity tags: [project-management, automation] documentation: https://example.com/docs support: support@example.com

安全说明

允许的内容

• 标准YAML类型（字符串、数字、布尔值、列表、对象）

• 自定义metadata字段

• 最长1024字符的description

禁止的内容

• XML尖括号（< >）——安全限制

• YAML中执行代码（采用安全YAML解析）

• 以"claude"或"anthropic"开头的技能名（保留词）

附录C：完整技能示例

以下仓库提供可直接生产使用的完整技能示例，持续更新：

• Document Skills：PDF、DOCX、PPTX、XLSX创建类技能

• Example Skills：各种工作流程模式示例

• Partner Skills Directory：Asana、Atlassian、Canva、Figma、Sentry、Zapier等合作伙伴技能

可克隆仓库后按需求修改，用作自定义技能模板。

需要我帮你提取文档中的核心操作步骤清单，或将某个设计模式扩展为完整技能示例吗？