官方链接地址 《The Complete Guide to Building Skills for Claude》

相关连接查看原文对应位置

简介

   skill 是一组指令，被打包一个简单的文件夹，用于教会 Claude 如何处理特定任务或工作流程。Skills 是根据你的具体需求定制 Claude 最强大的方式之一。你无需在每次对话中重复说明你的偏好、流程和领域专业知识，只需通过 skills 一次性教会 Claude，之后每次使用都能受益。
   当你拥有可复用的工作流时，skills 会发挥强大作用：例如根据需求文档生成前端设计、以统一的研究方法开展调研、创建符合团队风格规范的文档，或是编排多步骤流程。它们能与 Claude 内置能力完美配合，比如代码执行和文档生成。对于正在构建 MCP 集成的开发者而言，skills 还能提供一层强大的增强能力，帮助将原始工具调用转化为可靠、优化的工作流。
   本指南涵盖了构建高效 skills 所需的全部知识 —— 从规划、结构设计，到测试与发布。无论你是为自己、团队还是社区开发 skill，都能在全文中找到实用的模式与真实案例。

你将学习到什么：

• skill 结构的技术要求与最佳实践
• 独立 skills 与 MCP 增强工作流的设计模式
• 在各类使用场景中都验证有效的模式
• 如何测试、迭代与分发你的 skills

适用人群：

• 希望 Claude 稳定遵循特定工作流的开发者
• 希望 Claude 遵循特定工作流的高级用户
• 希望在组织内部统一 Claude 使用规范的团队

本指南的两种阅读途径：

• 构建独立 skills？请重点阅读基础、规划与设计以及类别 1‑2
• 增强 MCP 集成？“Skills + MCP” 章节和类别 3 适合你
• 两条路径共用相同的技术要求，你只需选择与自身使用场景相关的内容即可

学习本指南你将收获：

• 学完本指南后，你将能够一次性构建出可用的 skill.使用 skill-creator 构建并测试你的第一个可运行 skill，预计只需 15–30 分钟。

章节一：Fundamentals（基础）

什么是skill?

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

• SKILL.md（必需）： 包含 YAML 前置信息、用 Markdown 编写的指令说明
• scripts/（可选）： 可执行代码（Python、Bash 等）
• references/（可选）： 按需加载的参考文档
• assets/（可选）： 输出内容所用的模板、字体、图标等资源文件

核心设计原则:

渐进式展示

Skill 采用三级体系：

• 第一级（YAML 前置信息）：始终加载到 Claude 的系统提示词中。仅提供必要信息，让 Claude 知道何时该使用每个 skill，而不会把全部内容加载到上下文里。
• 第二级（SKILL.md 正文）：当 Claude 判断该技能与当前任务相关时才会加载。包含完整的指令与指导说明。
• 第三级（关联文件）：技能目录中打包的额外文件，Claude 只会在需要时才去查阅和使用。

这种渐进式展示可以最小化 Token 消耗，同时保留专业能力。

可组合性:

   Claude 可以同时加载多个技能。你的技能应当能与其他技能良好配合，而不是假设自己是唯一可用的功能。

可移植性：

   Skills 在 Claude.ai、Claude Code 和 API 上的表现完全一致。只需创建一次技能，只要环境支持技能所需的依赖项，无需修改即可在所有平台运行。

面向 MCP 构建者： Skills + Connectors

   不使用 MCP 开发独立技能？直接跳到「规划与设计」章节即可 —— 你随时可以再回到这里。

   如果你已经有了可正常运行的 MCP 服务器，那最难的部分你已经完成了。技能是建立在其之上的知识层—— 它把你已有的工作流程和最佳实践固化下来，让 Claude 能够稳定、一致地应用它们。

厨房类比

• MCP 提供专业厨房：可使用工具、食材和设备
• Skills 提供食谱：一步步教你如何做出有价值的东西
• 二者结合，用户无需自行理清每一步，就能完成复杂任务

它们如何协同工作：

这对 MCP 用户为何重要

没有 Skills 时：

• 用户连接了你的 MCP，却不知道接下来该做什么
• 收到大量支持工单，询问 “如何通过你的集成实现 X 功能”
• 每次对话都要从零开始
• 用户每次提示方式不同，导致结果不一致
• 实际问题是缺少工作流程指导，用户却归咎于你的连接器

拥有 Skills 后：

• 预设工作流会在需要时自动激活
• 工具使用稳定、可靠、统一
• 最佳实践融入每一次交互
• 降低集成产品的学习成本

章节二：Planning and design

从用例入手

在编写任何代码之前，先确定 2–3 个你的 skill 能够支撑的具体用例。

优质示例如下：

用例：项目冲刺规划
触发条件：用户说 “帮我规划本次冲刺” 或 “创建冲刺任务”
步骤：

• 从 Linear 获取当前项目状态（通过 MCP）
• 分析团队速率与工作量容量
• 给出任务优先级建议
• 在 Linear 中创建任务，设置合适的标签和预估工时
• 结果：完成完整冲刺规划并创建好所有任务

问问你自己：

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

通用技能用例分类：

在 Anthropic，我们观察到三类常见用例：

类别 1：文档与资源创建

   用途：用于创建统一、高质量的产出，包括文档、演示文稿、应用、设计、代码等。
   真实示例：前端设计技能（另见 docx、pptx、xlsx 和 ppt 相关技能）
   “创建具有高设计水准的独特、生产级前端界面。适用于构建网页组件、页面、成果物、海报或应用。”

核心技术：

• 内置的风格指南与品牌规范
• 保证输出统一的模板结构
• 最终定稿前的质量清单
• 无需外部工具，使用 Claude 内置能力

类别 2：工作流自动化

   用途：适用于能从标准化方法中受益的多步骤流程，包括跨多个 MCP 服务器的协同操作。

   实际示例：skill-creator skill

   “用于创建新技能的交互式指南。引导用户完成用例定义、前置内容生成、指令编写和验证环节。”

核心技术：

• 带验证关卡的分步式工作流
• 通用结构模板
• 内置审核与优化建议
• 迭代优化循环

类别 3：MCP 增强

   用途：提供工作流指导，以增强 MCP 服务器所提供的工具访问能力。

   实际示例：sentry-code-review 技能（来自 Sentry）

   “通过 Sentry 的 MCP 服务器，利用 Sentry 的错误监控数据，自动分析并修复 GitHub 拉取请求中检测到的漏洞。”

核心技术：

• 按顺序协调多个 MCP 调用
• 嵌入领域专业知识
• 提供用户原本需要手动指定的上下文信息
• 针对常见 MCP 问题的错误处理

定义成功标准

   如何判断你的 skills 是否有效？

   这些是理想目标—— 是粗略基准，而非精确阈值。力求严谨，但也要接受评估会带有一定主观判断。我们正在积极开发更完善的衡量标准与工具。

量化指标：

• skill 在 90% 的相关查询中被触发
  – 衡量方式：运行 10–20 条应触发该技能的测试查询，统计自动加载次数与需要显式调用次数的比例
• 在 X 次工具调用内完成工作流
  – 衡量方式：对比开启 / 不开启 skill 时完成同一任务的情况，统计工具调用次数与总 Token 消耗
• 每个工作流 API 调用失败次数为 0
  – 衡量方式：测试期间监控 MCP 服务器日志，统计重试率与错误码

定性指标：

• 用户无需提示 Claude 下一步该做什么
  – 评估方式：测试中记录需要引导或澄清的频率，收集内测用户反馈
• 工作流无需用户修正即可完成
  – 评估方式：同一请求运行 3–5 次，对比输出在结构一致性与质量上的表现
• 多次会话间结果保持一致
  – 评估方式：新用户能否在最少引导下第一次尝试就完成任务

技术要求

文件结构：

严格规则：

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：最重要的部分

   YAML frontmatter 是 Claude 用来判断是否加载你的 skill 的依据。必须写对

最低格式要求：

   这就是你开始所需的全部内容

字段要求：

name（必填）：

• 只能使用 kebab-case 短横线命名
• 不能有空格或大写字母
• 必须与文件夹名称一致

description（必填）:

• 必须同时包含两项内容：
  – 该 skill 实现什么功能
  – 何时使用该 skill（触发条件）
• 长度不超过 1024 个字符
• 不能包含 XML 标签（<或>）
• 要写出用户可能会说的具体任务
• 如果相关，需提及文件类型

license（可选）:

• 用于开源 skill
• 常用：MIT、Apache-2.0

compatibility（可选）:

• 1–500 字符
• 说明环境要求：如适用产品、依赖系统包、网络权限等

metadata（可选）:

• 自定义键值对
• 建议填写：author、version、mcp-server

示例：

metadata:
  author: ProjectHub
  version: 1.0.0
  mcp-server: projecthub

安全限制

   前置配置（frontmatter）中禁止出现：

• XML 尖括号 < >
• name 中包含 claude 或 anthropic（为官方保留词）

   原因：frontmatter 会出现在 Claude 的系统提示词中，恶意内容可能造成指令注入攻击

编写高效的 skill

description 字段

   根据 Anthropic 工程博客的说明：“这些元数据…… 只为 Claude 提供刚好足够的信息，让它知道什么时候应该使用某个 skill，而不必把全部内容都加载到上下文中。” 这是渐进式信息披露的第一层。

结构：

- [What it does] + [When to use it] + [Key capabilities]
- [功能说明] + [使用场景] + [核心能力]

优质 description 示例：

# Good - specific and actionable
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".

# Good - includes trigger phrases
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".

# Good - clear value proposition
description: End-to-end customer onboarding workflow for
PayFlow. Handles account creation, payment setup, and
subscription management. Use when user says "onboard new
customer", "set up subscription", or "create PayFlow account".

译文：

# 优质示例 —— 具体且可执行
description: 分析 Figma 设计文件并生成开发者交接文档。
当用户上传 .fig 文件、询问 “设计规范”“组件文档” 或 “设计到代码交接” 时使用。

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

# 优质示例 —— 清晰的价值呈现
description: PayFlow 的端到端客户接入工作流。处理账号创建、支付配置和订阅管理。
当用户说 “接入新客户”“配置订阅” 或 “创建 PayFlow 账号” 时使用。

劣质 description 示例：

# Too vague
description: Helps with projects.

# Missing triggers
description: Creates sophisticated multi-page documentation
systems.

# Too technical, no user triggers
description: Implements the Project entity model with
hierarchical relationships.

译文：

# 过于模糊
description: 协助处理项目

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

# 过于技术化，无用户触发语句
description: 实现带有层级关系的项目实体模型

编写主指令：

在 frontmatter 之后，用 Markdown 编写实际执行指令。

推荐结构：

根据你的 skill 调整这个模板，把括号里的内容替换成你自己的具体信息即可。

---
name: your-skill
description: [...]
---
# Your Skill Name

## Instructions

### Step 1: [First Major Step]
Clear explanation of what happens.

示例：

python scripts/fetch_data.py --project-id PROJECT_ID
Expected output: [describe what success looks like]

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

示例

示例一 【常见场景】

用户表述：“创建一个新的营销活动”

执行动作：

1. 通过 MCP 获取已有活动
2. 使用提供的参数创建新活动

结果：活动已创建，并返回确认链接
（可根据需要添加更多示例）

故障排查

错误：[常见错误信息]

原因：[错误发生的原因]

解决方案：[如何修复]

（可根据需要添加更多错误案例）

编写指令的最佳实践

具体且可执行

✅ 优秀：

Run `python scripts/validate.py --input {filename}` to check
data format.
If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)

❌ 差劲：

Validate the data before proceeding.

包含错误处理：

# Common Issues
### MCP Connection Failed
If you see "Connection refused":
1. Verify MCP server is running: Check Settings > Extensions
2. Confirm API key is valid
3. Try reconnecting: Settings > Extensions > [Your Service] >
Reconnect

清晰引用捆绑资源:

Before writing queries, consult `references/api-patterns.md`
for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handling

采用渐进式信息披露

   保持 SKILL.md 专注于核心指令。将详细文档移至 references/ 并添加链接。（有关三级系统的工作方式，请参阅核心设计原则。）

章节三：Testing and iteration

根据你的需求，可以在不同严格程度上对 skill 进行测试

• 在 Claude.ai 中进行手动测试 —— 直接运行查询并观察行为。迭代快速，无需配置环境
• 在 Claude Code 中进行脚本化测试—— 自动化测试用例，以便在多次变更中实现可重复的验证
• 通过 skills API 进行程序化测试 —— 构建评估套件，针对已定义的测试集系统性运行

   选择与你的质量要求以及 skill 可见范围相匹配的方案。供小型团队内部使用的 skill，与部署给数千名企业用户的 skill，其测试需求截然不同。

专业提示：先在单一任务上迭代优化，再进行扩展。

   我们发现，最高效的 skill 创作者会先针对单个有难度的任务反复迭代，直到 Claude 成功完成，再将这套有效的方案提炼成 skill。这能充分利用 Claude 的上下文学习能力，比大范围测试更快得到有效反馈。一旦你有了可用的基础，再扩展到多个测试用例以覆盖更多场景。

3.1 推荐测试方案

根据早期经验，有效的 skill 测试通常涵盖三个方面：

3.1.1. 触发测试

目标：确保你的 skill 在正确时机加载

测试用例：

・✅ 在明确任务上触发
・✅ 在转述请求上触发
・❌ 不触发无关话题

测试套件示例：

Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"
Should NOT trigger:
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "Create a spreadsheet" (unless ProjectHub skill handles
sheets)

3.1.2 功能测试

目标：验证 skill 生成正确的输出

测试用例：
・生成有效输出
・API 调用成功
・错误处理正常
・覆盖边界场景

示例：

Test: Create project with 5 tasks
Given: Project name "Q4 Planning", 5 task descriptions
When: Skill executes workflow
Then:
 - Project created in ProjectHub
 - 5 tasks created with correct properties
 - All tasks linked to project
 - No API errors

3.1.3 性能对比

目标：证明相较于基准版本，skill 能优化结果

使用来自「定义成功标准」中的指标，以下是对比示例

基准对比：

Without skill:
- User provides instructions each time
- 15 back-and-forth messages
- 3 failed API calls requiring retry
- 12,000 tokens consumed

With skill:
- Automatic workflow execution
- 2 clarifying questions only
- 0 failed API calls
- 6,000 tokens consumed

3.2 使用 skill‑creator skill

   skill‑creator skill 可通过 Claude.ai 的插件目录获取，也可下载用于 Claude Code，它能帮你构建并迭代优化 skill。 如果你有 MCP 服务器，并且明确了最核心的 2–3 个工作流，就能一次性完成并测试出一个可用的 skill—— 通常只需 15–30 分钟。

创建 skill：

- 从自然语言描述生成 skill
- 生成格式规范、带有前置信息（frontmatter）的 SKILL.md
- 提供触发短语与结构建议

审核 skill：

- 标记常见问题（描述模糊、缺少触发条件、结构错误）
- 识别可能的过度触发或触发不足风险
- 根据 skill 的既定用途推荐测试用例

迭代优化：

- 在使用你的 skill 并遇到边界情况或失败场景后，将这些示例反馈给 skill‑creator
- 示例：“用本次对话中发现的问题与解决方案，优化该 skill 处理【特定边界情况】的方式”

使用示例：

- "Use the skill-creator skill to help me build a skill for [your use case]"

   注意：skill‑creator 可帮助你设计和优化 skill，但不会执行自动化测试套件，也不会生成量化评估结果

3.3 基于反馈的迭代

skill 是持续迭代的动态内容。请根据以下情况规划迭代优化：

触发不足信号：

• skill 在应该加载时没有加载
• 用户需要手动启用它
• 收到关于 “何时使用该 skill” 的咨询问题

   解决方法：在描述中补充更多细节与更精细的表述—— 这可以包括补充关键词，尤其是专业技术术语

过度触发信号：

• skill 对无关请求也会加载
• 用户选择禁用他
• 对用途产生疑惑

   解决方法： 添加反向触发条件，描述更具体

执行问题：

• 结果不一致
• API 调用失败
• 需要用户手动修正

   解决方法：优化指令说明，增加错误处理机制

章节四：Distribution and sharing

   Skills 能让你的 MCP 集成更加完整。当用户对比不同连接器时，带有 skill 的方案能更快实现价值，让你相比仅提供 MCP 的替代方案更具优势。

4.1 当前分发模式（2026 年 1 月）

个人用户获取 skills 的方式：

1. 下载 skill 文件夹
2. 将文件夹压缩（如需要）
3. 通过 Claude.ai 内的 设置 > 功能 > 技能 上传
4. 或放入 Claude Code 的技能目录

组织级 skills：

• 管理员可在整个工作区部署 skills（2025 年 12 月 18 日上线）
• 自动更新
• 集中管理

4.2 开放标准

   我们已将 Agent Skills 发布为开放标准。与 MCP 一样，我们认为 skills 应能在不同工具与平台之间可移植—— 同一个 skill 无论在 Claude 还是其他 AI 平台上都应能正常运行。不过，部分 skill 是为充分利用特定平台的能力而设计的；开发者可以在 skill 的兼容性字段中注明这一点。我们一直在与生态伙伴合作推进该标准，也对早期的 adoption 情况感到振奋。

4.3通过 API 使用 skills

   针对程序化使用场景 —— 例如构建基于 skills 的应用、智能体或自动化工作流 ——API 可对 skill 的管理与执行提供直接控制。

核心能力：

• /v1/skills 接口，用于列出和管理 skills
• 可通过 container.skills 参数，将 skills 添加到 Messages API 请求中
• 通过 Claude Console 进行版本控制与管理
• 可与 Claude Agent SDK 配合使用，用于构建自定义智能体

通过 API 使用 skills 与在 Claude.ai 上使用的适用场景对比：

使用场景	最佳使用方式
终端用户直接与 skills 交互	Claude.ai / Claude Code
开发期间的手动测试与迭代	Claude.ai / Claude Code
个人临时工作流	Claude.ai / Claude Code
以编程方式使用 skills 的应用	API
大规模生产环境部署	API
自动化流程与智能体系统	API

注意：API 中的 skills 需要使用 代码执行工具（Code Execution Tool）测试版，它为 skills 提供运行所需的安全环境。

如需了解实现细节，请参阅：

• Skills API 快速入门
• 创建自定义 skills
• 智能体 SDK 中的 skills

4.4 目前推荐的实现方式

先将你的 skill 托管在 GitHub 公共仓库中，提供清晰的 README（面向使用者查看——这与你的 skill 文件夹是分开的，skill 文件夹不应包含 README.md），并附上带截图的使用示例。然后在你的 MCP 文档中增加一个章节，链接到该 skill，说明同时使用 MCP 和 skill 的价值，并提供快速入门指南。

1. 托管至 GitHub

• 开源 skills 采用公共仓库（Public repo）
• 提供清晰的 README，包含安装说明
• 附上使用示例及截图

2. 在你的 MCP 仓库中添加文档

• 在 MCP 文档中添加 skills 相关链接
• 说明 MCP 与 skills 搭配使用的价值
• 提供快速入门指南

3. 编写安装指南

4.5 安装 [你的服务] skill

# 安装 [你的服务] skill
1. 下载 skill：
   - 克隆仓库：`git clone https://github.com/yourcompany/skills`
   - 或从 Releases 中下载 ZIP 压缩包
2. 在 Claude 中安装：
   - 打开 Claude.ai > 设置 > skills
   - 点击「Upload skill」—— 选择 skill 文件夹（已压缩）
3. 启用 skill：
   - 开启 [你的服务] skill 开关
   - 确保你的 MCP 服务器已连接
4. 测试：
   - 向 Claude 提问：“在 [你的服务] 中创建一个新项目”

4.6 定位你的 skill

   你如何描述你的 skill，决定了用户能否理解它的价值并真正去使用。在 README、文档或推广材料中介绍你的 skill 时，请遵循以下原则：

聚焦于使用成果，而非功能本身：

✅ 推荐写法：

   “ProjectHub skill 能让团队在几秒内搭建完整的项目工作区——包括页面、数据库和模板——无需再花费 30 分钟手动配置。”

❌ 不推荐写法：

   “ProjectHub skill 是一个包含 YAML 前置信息和 Markdown 指令的文件夹，会调用我们的 MCP 服务端工具。”

突出 MCP + skills 组合价值：

   “我们的 MCP 服务端让 Claude 能访问你的 Linear 项目。我们的 skills 让 Claude 学习你团队的迭代规划工作流。两者结合，即可实现 AI 驱动的项目管理。”

章节五：Patterns and troubleshooting

   这些模式源自早期使用者与内部团队打造的 skill。它们是我们验证过行之有效的通用思路，并非硬性规定的模板。

选择你的思路：问题优先 vs 工具优先

   可以把它想象成Home Depot，你可能带着问题走进来 ——“我要修厨房橱柜”—— 然后店员会给你指对的工具。也可能你先挑了一把新电钻，再问它该怎么用在你的具体工作上。

Skills 的运作方式也是如此：

• 问题优先（Problem-first）：“我需要搭建一个项目工作区”→ 你的 skill 按正确顺序编排合适的 MCP 调用。用户描述目标结果，由 skill 来调度工具。
• 工具优先（Tool-first）：“我已连接了 Notion MCP”→ 你的 skill 向 Claude 传授最优工作流与最佳实践。用户已具备使用权限，由 skill 提供专业方法。

   大多数 skill 会偏向其中一种方向。明确哪种框架适合你的使用场景，有助于你选择下面合适的模式。

模式 1：顺序工作流编排

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

示例结构：

## 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

关键技术：

• 明确的步骤顺序
• 步骤间的依赖关系
• 各阶段的校验 / 验证
• 故障时的回滚指令

模式 2：多 MCP 协同

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

示例： 从设计到开发的交接

### 第一阶段：设计导出（Figma 控制平面）
1. 从 Figma 导出设计资源
2. 生成设计规范文档
3. 创建资源清单文件

### 第二阶段：资源存储（云盘控制平面）
1. 在云盘中创建项目文件夹
2. 上传所有设计资源
3. 生成可分享链接

### 第三阶段：任务创建（任务管理平台控制平面）
1. 创建开发任务
2. 将资源链接附加到任务
3. 分配给研发团队

### 第四阶段：通知通知（Slack 控制平面）
在 #engineering 频道发布交接汇总
附上资源链接与任务编号

关键技术：

• 清晰的阶段划分
• 各控制平面（MCP）之间的数据传递
• 进入下一阶段前的验证检查
• 集中式错误处理

模式 3：迭代优化

适用场景： 输出质量会随迭代而提升时使用

示例： 报告生成

## 迭代式报告创建

### 初稿阶段
1. 通过 MCP 获取数据
2. 生成报告初稿
3. 保存至临时文件

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

### 优化循环
1. 处理每个已识别的问题
2. 重新生成受影响的章节
3. 重新校验
4. 重复直至满足质量阈值

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

关键技术：

• 明确的质量标准
• 迭代式优化
• 校验脚本
• 知道何时停止迭代

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

适用场景： 目标结果相同，但需根据上下文选用不同工具。

示例： 文件存储

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

### 执行存储
根据决策结果：
	- 调用对应的 MCP 工具
	- 应用服务专属元数据
	- 生成访问链接

### 向用户提供上下文说明
解释选择该存储方式的原因

关键技术：

• 清晰的决策标准
• 备选方案 / 降级方案
• 选择过程透明化

模式 5：领域专属智能

适用场景： 你的能力不仅是调用工具，还能提供专业领域知识时使用。

示例： 财务合规

## 合规支付处理
### 处理前（合规检查）
1. 通过 MCP 获取交易详情
2. 应用合规规则：
   - 核查制裁名单
   - 验证辖区许可
   - 评估风险等级
3. 记录合规审查结果

### 处理流程
若通过合规检查：
   - 调用支付处理 MCP 工具
   - 执行相应欺诈检测
   - 处理交易
否则：
   - 标记待复核
   - 创建合规案件

### 审计追踪
- 记录所有合规检查操作
- 记录处理决策
- 生成审计报告

关键技术：

• 内嵌于逻辑中的领域专业知识
• 操作执行前的合规校验
• 全面的文档记录
• 清晰的治理管控

故障排查

Skill 无法上传

错误：“Could not find SKILL.md in uploaded folder”

原因： 文件未精确命名为 SKILL.md

解决方法：
・重命名为 SKILL.md（区分大小写）
・使用命令验证：ls -la，应显示 SKILL.md

错误：“Invalid frontmatter”

原因： YAML 格式问题

常见错误：

# Wrong - missing delimiters
name: my-skill
description: Does things

# Wrong - unclosed quotes
name: my-skill
description: "Does things

# Correct
---
name: my-skill
description: Does things
---

错误：“Invalid skill name”

原因： 名称包含空格或大写字母

# Wrong
name: My Cool Skill

# Correct
name: my-cool-skill

Skill 未触发

现象： Skill 从未自动加载

解决方法： 修改 description 字段。参考「描述字段」中的正确 / 错误示例。

快速检查清单：
・是否过于笼统？（如 “Helps with projects” 无法生效）
・是否包含用户实际会说的触发短语？
・如适用，是否提及了相关文件类型？

调试方法： 询问 Claude：“When would you use the [skill name] skill?”Claude 会把描述原文返回。根据缺失内容进行调整。

Skill 触发过于频繁

现象： Skill 会对不相关的请求加载

解决方法：

1.添加反向触发词（negative triggers）

description: Advanced data analysis for CSV files. Use for
statistical modeling, regression, clustering. Do NOT use for
simple data exploration (use data-viz skill instead).

2.更具体一点 / 请说得更详细些

# Too broad
description: Processes documents
# More specific
description: Processes PDF legal documents for contract review

3.明确适用范围

description: PayFlow payment processing for e-commerce. Use
specifically for online payment workflows, not for general
financial queries.

MCP 连接问题

现象： Skill 已加载，但 MCP 调用失败

检查清单：

1. 确认 MCP 服务器已连接
   – Claude.ai：Settings > Extensions > [你的服务]
   – 状态应显示为 “Connected”

2. 检查身份验证
   – API 密钥有效且未过期
   – 已授予正确的权限 / 作用域
   – OAuth 令牌已刷新

3. 独立测试 MCP
   – 让 Claude 直接调用 MCP（不通过 Skill）
   – 示例：“Use [Service] MCP to fetch my projects”
   – 如果失败，问题出在 MCP，而非 Skill

4. 核对工具名称
   – Skill 中引用的 MCP 工具名称正确
   – 查阅 MCP 服务器文档
   – 工具名称区分大小写

指令未被执行

现象： Skill 已加载，但 Claude 不按照指令执行

常见原因：

1.指令过于冗长

• 保持指令简洁精炼
• 使用项目符号和编号列表
• 将详细参考内容移至单独文件

2.指令被淹没在内容中

• 把关键指令放在最上方
• 使用 ## Important 或 ## Critical 标题
• 必要时重复重点内容

3.语言表述模糊不清

# Bad
Make sure to validate things properly

# Good
CRITICAL: Before calling create_project, verify:
- Project name is non-empty
- At least one team member assigned
- Start date is not in the past

高级技巧：对于关键校验，可考虑打包一个脚本，以编程方式执行检查，而不是依赖自然语言指令。代码是确定性的；自然语言的理解则不是。可参考 Office 相关 Skill 来了解这种模式的示例。

4.模型 “偷懒”：添加明确的强化指令

# Performance Notes
- Take your time to do this thoroughly
- Quality is more important than speed
- Do not skip validation steps

注意：将此内容添加到用户提示中，比在 SKILL.md 中更有效。

上下文过大问题

现象： Skill 运行缓慢或回复质量下降

原因：
・Skill 内容过大
・同时启用的 Skill 过多
・所有内容一次性加载，而非逐步展示

解决方案：

优化 SKILL.md 大小

• 将详细文档移至 references/ 目录
• 使用引用链接代替直接内联写入
• 将 SKILL.md 控制在 5000 词以内

减少启用的 Skill

• 检查是否同时启用了超过 20–50 个 Skill
• 建议按需选择性启用
• 对相关功能考虑使用 Skill “包” 管理

章节六 Resources and references

   如果你正在构建第一个 Skill，请先从最佳实践指南开始，然后根据需要参考 API 文档

官方文档

Anthropic 资源：

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

博客文章：

• Agent Skills 介绍
• 工程博客：让智能体适配真实场景
• Skills 详解
• 如何为 Claude 创建 Skills
• 为 Claude Code 构建 Skills
• 通过 Skills 优化前端设计

示例 Skills
公开 Skills 仓库：

• GitHub：anthropics/skills
• 包含由 Anthropic 创建、可自定义的 Skills

工具与实用程序

skill-creator skill：

• 内置于 Claude.ai，同时适用于 Claude Code
• 可根据描述生成 Skill
• 提供审核与改进建议
• 使用方式：“Help me build a skill using skill-creator”

校验功能：

• skill-creator 可对你的 Skill 进行评估
• 询问方式：“Review this skill and suggest improvements”

获取支持

技术问题咨询：

• 常规问题：Claude Developers Discord 社区论坛

错误报告提交：

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

参考资料 A：快速检查清单

   使用本检查清单在上传前和上传后验证你的 Skill。如果你希望更快上手，可以使用 skill-creator skill 生成初稿，然后对照此清单逐一确认，确保没有遗漏任何内容。

开始前

• 确定 2-3 个具体用例
• 明确所需工具（内置工具或 MCP）
• 阅读本指南及示例 Skill
• 规划文件夹结构

开发过程中

• 文件夹命名使用 kebab-case（短横线分隔）
• 存在 SKILL.md 文件（拼写必须完全一致）
• YAML 前置元数据使用 --- 作为分隔符
• name 字段使用 kebab-case，无空格、无大写字母
• 描述中包含“做什么（WHAT）”和“何时用（WHEN）”
• 任何位置均不使用 XML 标签（< >）
• 指令清晰、可执行
• 包含错误处理逻辑
• 提供使用示例
• 参考资料链接清晰

上传前

• 在典型任务上测试触发
• 在改写/转述的请求上测试触发
• 验证不会在无关话题上触发
• 功能测试通过
• 工具集成正常（如适用）
• 压缩为 .zip 文件

上传后

• 在真实对话场景中测试
• 监控触发不足/过度触发的情况
• 收集用户反馈
• 迭代优化描述与指令
• 更新元数据中的版本号

参考资料B：YAML 前置头部

必填字段

---
name: skill-name-in-kebab-case
description: What it does and when to use it. Include specific
trigger phrases.
---

所有可选字段

name: skill-name
description: [required description]
license: MIT # Optional: License for open-source
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch" # Optional:
Restrict tool access
metadata: # Optional: Custom fields
 author: Company Name
 version: 1.0.0
 mcp-server: server-name
 category: productivity
 tags: [project-management, automation]
 documentation: https: /example.com/docs
 support: support@exampl

安全说明

允许使用：

• 任何标准 YAML 类型（字符串、数字、布尔值、列表、对象）
• 自定义元数据字段
• 较长的描述（最多 1024 个字符）

禁止使用：

• XML 尖括号（< >）——安全限制
• YAML 中的代码执行（采用安全 YAML 解析）
• 以 “claude” 或 “anthropic” 为前缀命名的 Skill（保留名称）

参考资料C：完整 Skill 示例

如需查看可用于生产环境、且能体现本指南中各类模式的完整 Skill 示例：

• 文档类 Skill —— PDF、DOCX、PPTX、XLSX 文件生成
• 示例 Skill —— 各类工作流模式
• 合作方 Skill 目录 —— 查看来自各合作方的 Skill，包括 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等

这些仓库会持续更新，并包含本指南未覆盖的更多示例。
你可以克隆这些项目，根据自身业务场景修改，并将其作为模板使用。