Claudepedia
所有详情页统一为连续书页布局
Claude 技能构建 完全指南
Claude
译者：maurice_wen@proton.me
目录
引言3
基础知识4
规划与设计7
测试与迭代14
分发与共享18
模式与故障排除21
资源与参考28
2
引言

技能（Skill）是一组打包成简单文件夹的指令，用于教导 Claude 如何处理特定任务或工作流程。技能是根据您的具体需求定制 Claude 的最强大方式之一。无需在每次对话中重新解释您的偏好、流程和领域专业知识，技能让您一次性教导 Claude，每次使用都能从中受益。

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

本指南涵盖构建有效技能所需了解的一切内容——从规划与结构到测试与分发。无论您是为自己、团队还是社区构建技能，您都会在全书中找到实用的模式和真实案例。

您将学到什么

  • 技能结构的技术要求和最佳实践
  • 独立技能与 MCP 增强工作流程的模式
  • 我们在不同用例中观察到的有效模式
  • 如何测试、迭代和分发您的技能

适合哪些人阅读

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

本指南的两条学习路径

构建独立技能？专注于第一章"基础知识"、第二章"规划与设计"以及分类 1-2。要增强 MCP 集成？"技能 + MCP"部分和分类 3 正是为您准备的。两条路径共享相同的技术要求，但您可以选择与自身用例相关的内容。

您将从本指南获得什么

读完本指南，您将能够在一次坐下来的时间里构建一个功能完整的技能。预计使用 skill-creator 构建并测试您的第一个可用技能约需 15—30 分钟。

开始吧。

3
Chapter 1
Fundamentals
第一章

基础知识

什么是技能？

技能是包含以下内容的文件夹：

  • SKILL.md（必须）：包含 YAML 前置元数据的 Markdown 指令文件
  • scripts/（可选）：可执行代码（Python、Bash 等）
  • references/（可选）：按需加载的参考文档
  • assets/（可选）：输出中使用的模板、字体、图标

核心设计原则

渐进式披露

技能使用三层系统：

  • 第一层（YAML 前置元数据）：始终加载到 Claude 的系统提示中。提供足够的信息，让 Claude 知道每项技能何时应该被使用，而无需加载全部内容到上下文中。
  • 第二层（SKILL.md 正文）：当 Claude 认为该技能与当前任务相关时加载。包含完整的指令和指导。
  • 第三层（链接文件）：打包在技能目录中的附加文件，Claude 可以按需导航和发现。

这种渐进式披露机制在保持专业能力的同时，最大程度地减少了 Token 消耗。

可组合性

Claude 可以同时加载多项技能。您的技能应能与其他技能良好协作，而不是假设自己是唯一可用的能力。

可移植性

技能在 Claude.ai、Claude Code 和 API 中完全相同地工作。创建一次技能，无需修改即可在所有平台上使用——前提是环境支持该技能所需的依赖项。

面向 MCP 构建者：技能 + 连接器

💡 构建不依赖 MCP 的独立技能？跳到第二章"规划与设计"——您随时可以回来阅读本节。

如果您已经有一个正常运行的 MCP 服务器，那么最难的部分已经完成了。技能是其上的知识层——捕获您已知的工作流程和最佳实践，让 Claude 能够一致地应用它们。

厨房类比

MCP 提供专业厨房：访问工具、食材和设备。

技能提供食谱：一步步的指令，说明如何创造出有价值的成品。

两者合力，让用户无需自己摸索每一个步骤，就能完成复杂任务。

5

两者如何协同工作

MCP（连接性） 技能（知识）
将 Claude 连接到您的服务（Notion、Asana、Linear 等） 教导 Claude 如何有效使用您的服务
提供实时数据访问和工具调用 捕获工作流程和最佳实践
Claude 能做什么 Claude 应该怎么做

这对您的 MCP 用户意味着什么

没有技能时：

  • 用户连接了您的 MCP 却不知道下一步该做什么
  • 大量支持工单询问"如何用您的集成做 X"
  • 每次对话都从头开始
  • 由于用户提示方式不同，结果参差不齐
  • 用户在真正的问题（工作流程指导缺失）出现时责怪您的连接器

有技能时：

  • 预构建的工作流程在需要时自动激活
  • 一致、可靠的工具使用
  • 最佳实践嵌入每次交互
  • 降低集成的学习曲线
6
Chapter 2
Planning and Design
第二章

规划与设计

从用例出发

在编写任何代码之前，先确定您的技能应支持的 2—3 个具体用例。

优质的用例定义示例：

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

问问自己：

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

常见技能用例分类

Anthropic 观察到三类常见用例：

分类 1：文档与资产创建

适用于：创建高质量的一致性输出，包括文档、演示文稿、应用、设计、代码等。

真实案例：frontend-design 技能（另见 docx、pptx、xlsx、ppt 等文档类技能）

"创建具有高设计质量的独特、生产级前端界面。 适用于构建 Web 组件、页面、制品、海报或 应用程序时。"

核心技术：

  • 内嵌样式指南和品牌规范
  • 用于一致输出的模板结构
  • 定稿前的质量检查清单
  • 无需外部工具——使用 Claude 的内置能力
8

分类 2：工作流自动化

适用于：受益于一致方法论的多步骤流程，包括跨多个 MCP 服务器的协调。

真实案例：skill-creator 技能

"创建新技能的交互式指南。引导用户完成 用例定义、前置元数据生成、指令编写和 验证全流程。"

核心技术：

  • 带有验证关卡的逐步工作流
  • 常见结构的模板
  • 内置审查和改进建议
  • 迭代优化循环

分类 3：MCP 增强

适用于：为 MCP 服务器提供的工具访问提供工作流指导。

真实案例：sentry-code-review 技能（来自 Sentry）

"使用 Sentry 的错误监控数据，通过其 MCP 服务器自动分析并修复 GitHub Pull Request 中检测到的 Bug。"

核心技术：

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

定义成功标准

如何判断您的技能运行良好？

这些是方向性目标——粗略的基准，而非精确的阈值。追求严谨，但也接受主观感受的存在。Anthropic 正在积极开发更完善的测量指南和工具。

量化指标

  • 技能在 90% 的相关查询中触发
    测量方式：运行 10—20 个应该触发技能的测试查询，记录自动加载的次数。
  • 在 X 次工具调用内完成工作流
    测量方式：比较有/无技能时同一任务的工具调用次数和 Token 消耗。
  • 每次工作流的 API 调用失败次数为 0
    测量方式：测试运行期间监控 MCP 服务器日志，跟踪重试率和错误码。

质化指标

  • 用户无需提示 Claude 进行下一步
    评估方式：测试期间记录需要重定向或澄清的频率；向测试用户收集反馈。
  • 工作流无需用户纠正即可完成
    评估方式：运行相同请求 3—5 次，比较输出的结构一致性和质量。
  • 跨会话结果一致
    评估方式：新用户能否在最少指导下首次尝试即完成任务？
9

技术要求

文件结构

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

关键规则

SKILL.md 命名：

  • 必须严格命名为 SKILL.md（区分大小写）
  • 不接受任何变体（SKILL.MD、skill.md 等）

技能文件夹命名：

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

禁止 README.md：

  • 不要在技能文件夹内放 README.md
  • 所有文档放在 SKILL.md 或 references/ 中
  • 注意：通过 GitHub 分发时，仍需在仓库根目录提供 README 供人类用户阅读——详见"分发与共享"章节。

YAML 前置元数据：最关键的部分

YAML 前置元数据决定了 Claude 是否会加载您的技能。务必写好这部分。

最简必填格式

--- name: your-skill-name description: 功能说明。当用户要求 [具体短语] 时使用。 ---

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

字段要求

name（必填）：

  • 仅限 kebab-case
  • 不含空格或大写字母
  • 应与文件夹名称一致

description（必填）：

  • 必须同时包含：
    • 技能的功能说明
    • 使用时机（触发条件）
  • 不超过 1024 个字符
  • 不含 XML 标签（< 或 >）
  • 包含用户可能说出的具体任务描述
  • 如涉及特定文件类型，请注明
10

license（可选）

  • 开源技能时使用
  • 常见：MIT、Apache-2.0

compatibility（可选）

  • 1—500 个字符
  • 说明环境要求：如目标产品、所需系统包、网络访问需求等

metadata（可选）

  • 任意自定义键值对
  • 建议填写：author、version、mcp-server
metadata: author: ProjectHub version: 1.0.0 mcp-server: projecthub

安全限制

前置元数据中禁止的内容：

  • XML 尖括号（< >）
  • 名称中含有"claude"或"anthropic"（保留字）

原因：前置元数据会出现在 Claude 的系统提示中，恶意内容可能注入指令。

编写有效的技能

description 字段

根据 Anthropic 工程博客："这些元数据……提供足够的信息，让 Claude 知道每项技能何时应该被使用，而无需将全部内容加载到上下文中。"这是渐进式披露的第一层。

结构：[功能说明] + [使用时机] + [核心能力]

优质描述示例

# 优 - 具体且可操作 description: 分析 Figma 设计文件并生成开发 交接文档。当用户上传 .fig 文件，或要求 "设计规格"、"组件文档"、"设计转代码 交接"时使用。
# 优 - 包含触发短语 description: 管理 Linear 项目工作流，包括 迭代规划、任务创建和状态跟踪。当用户 提及"迭代"、"Linear 任务"、"项目规划" 或要求"创建工单"时使用。
# 优 - 价值主张清晰 description: PayFlow 端到端客户引导工作流。 处理账户创建、支付设置和订阅管理。当 用户说"引导新客户"、"设置订阅"或"创建 PayFlow 账户"时使用。
11

劣质描述示例

# 差 - 过于模糊 description: 帮助处理项目。 # 差 - 缺少触发词 description: 创建复杂的多页文档系统。 # 差 - 技术性过强，无用户触发词 description: 实现具有层级关系的 Project 实体模型。

编写主体指令

在前置元数据之后，用 Markdown 编写实际指令。

推荐结构

根据您的具体技能调整此模板，将括号内容替换为您的实际内容。

--- name: your-skill description: [...] --- # 技能名称 ## 指令 ### 第一步：[主要步骤] 清晰说明此步骤的操作内容。 ### 第二步：[下一步] 示例： ```bash python scripts/fetch_data.py --project-id PROJECT_ID 预期输出：[描述成功结果] ``` （按需添加更多步骤）

示例部分

## 示例 示例 1：[常见场景] 用户说："为新的营销活动做设置" 操作： 1. 通过 MCP 获取现有活动 2. 使用提供的参数创建新活动 结果：活动已创建，附确认链接 （按需添加更多示例）

故障排除部分

## 故障排除 错误：[常见错误信息] 原因：[发生原因] 解决方案：[修复方法] （按需添加更多错误案例）

提示：模板中的结构是建议，而非强制要求。根据技能的具体需求灵活调整章节和格式。

12

指令编写最佳实践

具体且可操作

✅ 优：

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

❌ 差：

继续之前请验证数据。

包含错误处理

## 常见问题 ### MCP 连接失败 如果出现"Connection refused"： 1. 确认 MCP 服务器正在运行： 检查 Settings > Extensions 2. 确认 API Key 有效 3. 尝试重连： Settings > Extensions > [您的服务] > 重连

明确引用捆绑资源

在编写查询之前，请参阅 `references/api-patterns.md`，其中包含： - 限速指南 - 分页模式 - 错误码及处理方式

使用渐进式披露

保持 SKILL.md 专注于核心指令。将详细文档移至 references/ 并提供链接。（参见"核心设计原则"中三层系统的工作原理。）

小结

最有效的技能往往是最具体的技能。模糊的指令会导致不一致的结果；精确的指令会带来可预期的行为。在不确定时，宁可过于具体，也不要模棱两可。

13
Chapter 3
Testing and Iteration
第三章

测试与迭代

技能可以根据实际需求，以不同严格程度进行测试：

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

根据质量要求和技能受众规模，选择最匹配的测试方式。供小团队内部使用的技能与面向数千名企业用户部署的技能，测试需求截然不同。

专家提示

在扩展之前，先针对单一任务迭代。我们发现，最高效的技能创建者会反复迭代一项有挑战性的任务，直到 Claude 成功完成，再将成功的方法提炼进技能。这充分利用了 Claude 的上下文学习能力，比广撒网式测试能更快地得到反馈。有了可用的基础之后，再扩展到多个测试用例，提升覆盖率。

推荐测试方法

根据早期实践，有效的技能测试通常涵盖三个方面：

1. 触发测试

目标：确保技能在正确时机加载。

测试用例：

  • ✅ 触发显而易见任务的查询
  • ✅ 触发不同表述方式的请求
  • ❌ 不触发无关话题

测试套件示例：

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)
15

2. 功能测试

目标：验证技能能产出正确的输出结果。

测试用例：

  • 生成有效输出
  • 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. 性能对比

目标：证明技能相比基准线能提升结果。

使用来自定义成功标准的评估指标。以下是对比示例。

基线对比：

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

使用 skill-creator 技能

skill-creator 技能——可通过插件目录在 Claude.ai 获取，或在 Claude Code 中下载使用——能帮助您构建和迭代技能。如果您拥有 MCP 服务器并明确了2—3 个核心工作流，就可以在单次会话中构建并测试一个可用技能，通常仅需 15—30 分钟。

创建技能：

  • 从自然语言描述生成技能
  • 生成格式规范的 SKILL.md（含前置元数据）
  • 建议触发短语和结构

审查技能：

  • 标记常见问题（描述模糊、缺少触发词、结构问题）
  • 识别潜在的触发不足/触发过度风险
  • 根据技能的既定目的建议测试用例

迭代改进：

  • 在使用过程中遇到边缘情况或失败后，将这些示例带回 skill-creator
  • 示例：“请使用本次对话中发现的问题与解决方案，改进技能对[具体边缘情况]的处理方式”
16

使用方法：

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

注：skill-creator 可帮助您设计和完善技能，但不会执行自动化测试套件或输出量化评估结果。

根据反馈迭代

技能是活文档，应根据以下信号持续迭代：

触发不足信号：

  • 技能在应激活时未加载
  • 用户手动启用技能
  • 收到关于使用时机的支持咨询

解决方案：在描述中添加更多细节和层次——可以包含关键词，尤其是技术术语

触发过度信号：

  • 技能在不相关查询中加载
  • 用户将其禁用
  • 对技能用途产生困惑

解决方案：添加负向触发词，使描述更精准具体

执行问题：

  • 结果不稳定
  • API 调用失败
  • 用户需要纠正

解决方案：改进指令，添加错误处理

17
Chapter 4
Distribution and Sharing
第四章

分发与共享

技能让您的 MCP 集成更加完整。当用户比较各类连接器时，拥有技能的方案能更快创造价值，相比纯 MCP 方案更具竞争优势。

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

个人用户获取技能的方式：

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

组织级技能：

  • 管理员可在全工作区范围内部署技能（2025年12月18日发布）
  • 自动更新
  • 集中管理

开放标准

我们将 Agent Skills 作为开放标准发布。与 MCP 一样，我们相信技能应该能够跨工具和平台移植——同一个技能，无论是用 Claude 还是其他 AI 平台都应能正常工作。当然，部分技能专为充分利用特定平台能力而设计，作者可在技能的 compatibility 字段中注明。我们一直与生态系统成员协作推动该标准，并对早期采用者的热情感到振奋。

通过 API 使用技能

对于以编程方式使用技能的场景——例如构建应用程序、Agent 或利用技能的自动化工作流——API 提供了对技能管理与执行的直接控制。

关键能力：

  • 通过 /v1/skills 端点列出和管理技能
  • 使用 container.skills 参数将技能添加到 Messages API 请求中
  • 通过 Claude 控制台进行版本控制和管理
  • 与 Claude Agent SDK 集成，构建自定义 Agent

何时通过 API vs. Claude.ai 使用技能：

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

注意：API 中的技能需要代码执行工具（Code Execution Tool）Beta，它为技能运行提供安全沙箱环境。

如需实现细节，请参阅：

  • Skills API 快速入门
  • 创建自定义技能
  • 在 Agent SDK 中使用技能

推荐的分发方式

首先在 GitHub 上以公开仓库托管技能，附上清晰的 README（面向人类访客——这与技能文件夹是分开的，技能文件夹本身不应包含 README.md），并提供带截图的使用示例。然后在您的 MCP 文档中新增一个章节，链接到该技能、说明两者结合的价值，并提供快速入门指南。

1. 托管在 GitHub

  • 在公开仓库中发布开源技能
  • 编写清晰的 README 并附上安装说明
  • 提供使用示例与截图

2. 在 MCP 仓库中说明

  • 在 MCP 文档中链接到对应技能
  • 讲清楚两者如何配合使用
  • 提供快速入门指南

3. 创建安装指南

## Installing the [Your Service] skill 1. Download the skill: - Clone repo: `git clone https://github.com/yourcompany/skills` - Or download ZIP from Releases 2. Install in Claude: - Open Claude.ai > Settings > skills - Click "Upload skill" - Select the skill folder (zipped) 3. Enable the skill: - Toggle on the [Your Service] skill - Ensure your MCP server is connected 4. Test: - Ask Claude: "Set up a new project in [Your Service]"

定位您的技能

如何推广您的技能与如何构建同样重要。当用户理解技能能为他们做什么时，他们才更可能去安装和使用它。

聚焦成果，而非功能：

✅ 好的示例：

"The ProjectHub skill enables teams to set up complete project workspaces in seconds — including pages, databases, and templates — instead of spending 30 minutes on manual setup."

✗ 差的示例：

"The ProjectHub skill is a folder containing YAML frontmatter and Markdown instructions that calls our MCP server tools."

突出 MCP + 技能的组合价值：

"Our MCP server gives Claude access to your Linear projects. Our skill teaches Claude your team's sprint planning workflow. Together, they enable AI-powered project management."
20
{ ! }
Chapter 5
Patterns and Troubleshooting
第五章

模式与故障排除

这些模式来源于早期用户和 Anthropic 内部团队创建的技能，代表了经过验证的常见实践方法，而非一成不变的规定模板。

选择框架：问题优先 vs. 工具优先

想象一下走进家得宝（Home Depot）。您可能带着一个问题进去——“我需要修厨柜”——然后由员工为您指路找到合适的工具。也可能是您先挑好一把新钻头，再询问如何用它完成具体工程。

技能同理：

  • 问题优先：“我需要搭建一个项目工作区”——技能按正确顺序编排 MCP 调用。用户描述目标，技能负责处理工具。
  • 工具优先：“我已连接了 Notion MCP”——技能教会 Claude 最佳工作流和使用实践。用户拥有访问权限，技能提供专业知识。

大多数技能倾向于其中一种方式。了解哪种框架适合您的场景，有助于选择下方合适的模式。

模式一：顺序工作流编排

适用场景：需要以特定顺序完成多个步骤，且每一步的输出会影响下一步的任务。

示例结构：

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

关键技术：

  • 明确的步骤排序
  • 步骤之间的依赖关系
  • 每个阶段的验证
  • 失败时的回滚说明
22

模式二：多 MCP 协调

适用场景：工作流横跨多个外部服务，且需要在它们之间协调操作时。

示例：设计到开发的交接

### Phase 1: Design Export (Figma MCP) 1. Export design assets from Figma 2. Generate design specifications 3. Create asset manifest ### Phase 2: Asset Storage (Drive MCP) 1. Create project folder in Drive 2. Upload all assets 3. Generate shareable links ### Phase 3: Task Creation (Linear MCP) 1. Create development tasks 2. Attach asset links to tasks 3. Assign to engineering team ### Phase 4: Notification (Slack MCP) 1. Post handoff summary to #engineering 2. Include asset links and task references

关键技术：

  • 清晰的阶段划分
  • MCP 间的数据传递
  • 进入下一阶段前的验证
  • 集中式错误处理

模式三：迭代精化

适用场景：输出需要经过多轮生成、评估和改进，直至满足质量标准。

示例：报告生成

## Iterative Report Creation ### Initial Draft 1. Fetch data via MCP 2. Generate first draft report 3. Save to temporary file ### Quality Check 1. Run validation script: `scripts/check_report.py` 2. Identify issues: - Missing sections - Inconsistent formatting - Data validation errors ### Refinement Loop 1. Address each identified issue 2. Regenerate affected sections 3. Re-validate 4. Repeat until quality threshold met ### Finalization 1. Apply final formatting 2. Generate summary 3. Save final version

关键技术：

  • 明确的质量标准
  • 迭代改进
  • 验证脚本
  • 适时停止迭代
23

模式四：情境感知工具选择

适用场景：根据输入特征或上下文条件，应选择不同工具或不同处理路径时。

示例：文件存储

## Smart File Storage ### 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 ### Execute Storage Based on decision: - Call appropriate MCP tool - Apply service-specific metadata - Generate access link ### Provide Context to User Explain why that storage was chosen

关键技术：

  • 明确的决策标准
  • 回退方案
  • 向用户说明选择依据

模式五：领域专属智能

适用场景：任务需要特定领域知识、合规要求或专业判断，而这些并非模型的通用能力。

示例：金融合规

## Payment Processing with Compliance ### Before Processing (Compliance Check) 1. Fetch transaction details via MCP 2. Apply compliance rules: - Check sanctions lists - Verify jurisdiction allowances - Assess risk level 3. Document compliance decision ### Processing IF compliance passed: - Call payment processing MCP tool - Apply appropriate fraud checks - Process transaction ELSE: - Flag for review - Create compliance case ### Audit Trail - Log all compliance checks - Record processing decisions - Generate audit report

关键技术：

  • 将领域专业知识内嵌于逻辑中
  • 行动前先完成合规检查
  • 全面的操作记录
  • 明确的治理规范
24

故障排除

技能无法上传

错误：“在上传的文件夹中找不到 SKILL.md”

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

解决方案：

  • 重命名为 SKILL.md（区分大小写）
  • 验证：ls -la 应显示 SKILL.md

错误：“无效的 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 ---

错误：“无效的技能名称”

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

# Wrong name: My Cool Skill # Correct name: my-cool-skill

技能不触发

症状：技能从不自动加载

修复：修改技能的描述字段。参见“描述字段”章节中的好/差示例。

快速检查清单：

  • 描述是否过于宽泛？（“帮助完成项目”这类描述无法生效）
  • 是否包含用户实际可能说出的触发短语？
  • 是否在适用时提到了相关文件类型？

调试方法：询问 Claude：“你什么时候会使用 [技能名称] 这个技能？”Claude 会复述描述内容，根据缺失的信息进行调整。

技能触发过于频繁

症状：技能在不相关的任务中被激活

解决方案：添加负触发词，明确说明不适用的场景。

1. 添加负触发词

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).
25

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 连接问题

症状：技能加载成功，但 MCP 调用失败

排查清单：

1. 验证 MCP 服务器已连接

  • Claude.ai：设置 > 扩展 > [您的服务]
  • 状态应显示"Connected（已连接）"

2. 检查认证

  • API Key 有效且未过期
  • 已正确授予权限/范围
  • OAuth 令牌已刷新

3. 独立测试 MCP

  • 让 Claude 直接调用 MCP（不使用技能）
  • "使用 [服务] MCP 获取我的项目"
  • 若此步失败，说明问题出在 MCP 而非技能

4. 核对工具名称

  • 技能中引用的工具名称须与 MCP 一致
  • 查阅 MCP 服务器文档
  • 工具名称区分大小写

指令未被遵循

症状：技能加载成功，但 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

4. 模型"惰性"：添加明确的鼓励性说明：

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

进阶技巧：对于关键验证逻辑，可在技能中打包一个脚本——代码是确定性的。参见 Office skills 示例。

注：将此类说明加入用户提示词比写入 SKILL.md 更为有效。

26

大上下文问题

症状：技能响应变慢或质量下降

原因：

  • 技能内容体积过大
  • 同时启用的技能过多
  • 全量加载内容，而非按需渐进式披露

解决方案：

1. 优化 SKILL.md 体积

  • 将详细文档移至 references/ 目录
  • 在 SKILL.md 中使用链接引用，而非内联全部内容
  • 将 SKILL.md 控制在 5,000 字以内

2. 减少同时启用的技能数量

  • 评估是否同时启用了超过 20–50 个技能
  • 建议按需选择性启用
  • 考虑将相关功能组合为"技能包"
27
Chapter 6
Resources and References
第六章

资源与参考

如果您正在构建第一个技能，建议先阅读最佳实践指南，再根据需要参阅 API 文档。

官方文档

Anthropic 资源：

博客文章：

示例技能

公开技能仓库：

工具与实用程序

skill-creator 技能：

  • 已内置于 Claude.ai，同时支持 Claude Code
  • 可根据描述自动生成技能
  • 提供审查和改进建议
  • 使用方法：向 Claude 说"帮我用 skill-creator 构建一个技能"

校验：

  • skill-creator 可对您的技能进行评估
  • 询问 Claude："请审查这个技能并给出改进建议"

获取支持

技术问题：

报告 Bug：

29
附录 A

快速检查清单

使用此清单在上传前后验证您的技能。如果希望快速入门，可使用 skill-creator 技能生成初稿，然后对照此清单确保没有遗漏。

开始之前

  • 已确定 2–3 个具体使用场景
  • 已识别所需工具（内置工具或 MCP）
  • 已阅读本指南和示例技能
  • 已规划文件夹结构

开发过程中

  • 文件夹命名使用 kebab-case
  • SKILL.md 文件已存在（拼写完全正确）
  • YAML 前置元数据包含 --- 分隔符
  • name 字段：kebab-case，无空格，无大写字母
  • description 包含"是什么"和"何时使用"
  • 没有 XML 标签（< >）
  • 指令清晰且可操作
  • 包含错误处理
  • 提供了示例
  • 参考文件已正确链接

上传之前

  • 已测试明显任务的触发情况
  • 已测试改写请求的触发情况
  • 已验证不会在无关话题上触发
  • 功能测试通过
  • 工具集成可用（如适用）
  • 已压缩为 .zip 文件

上传之后

  • 在真实对话中测试
  • 监控过度/不足触发的情况
  • 收集用户反馈
  • 迭代优化描述和指令
  • 在元数据中更新版本号
30
附录 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@example.com

安全说明

允许：

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

禁止：

  • XML 尖括号（< >）— 安全限制
  • 在 YAML 中执行代码（使用安全 YAML 解析）
  • 以 "claude" 或 "anthropic" 作为技能名称前缀（已保留）
31
附录 C

完整技能示例

以下仓库提供完整的、可用于生产环境的技能示例，体现了本指南所介绍的各类模式：

这些仓库持续更新，收录了超出本指南范围的更多示例。您可以克隆它们，根据自己的使用场景进行修改，并将其作为模板直接使用。

32
Claude
claude.ai