Anthropic 官方发布的 Claude Skill 构建指南中文翻译版，涵盖技能结构、规划设计、测试迭代与分发共享

Claude 技能构建完整指南

May 9, 2026

42 mins

8333 words

Loading views

引言h2

技能（Skill）是一套指令——以简单文件夹的形式打包——用于教会 Claude 如何处理特定任务或工作流。技能是自定义 Claude 以满足特定需求的最强大方式之一。无需在每次对话中重复解释您的偏好、流程和领域专业知识，技能让您一次性教会 Claude，并在每次使用中获益。

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

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

您将学到：

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

适用人群：

希望 Claude 始终遵循特定工作流的开发者
希望 Claude 始终遵循特定工作流的进阶用户
希望在整个组织内标准化 Claude 使用方式的团队

本指南的两种阅读路径h3

构建独立技能？ 请重点阅读「基础知识」、「规划与设计」以及第 1-2 类用例。

增强 MCP 集成？ 请重点阅读「技能 + MCP」部分以及第 3 类用例。

两种路径共享相同的技术要求，您可根据实际用例选择相关内容。

本指南的学习成果： 学习结束后，您将能够在一次会话中构建一个功能完整的技能。预计使用 skill-creator 构建并测试您的首个可用技能仅需 15–30 分钟。

让我们开始吧。

第 1 章：基础知识h2

什么是技能？h3

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

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

核心设计原则h3

渐进式披露（Progressive Disclosure）h4

技能采用三级系统：

第一级（YAML 前置元数据）： 始终加载到 Claude 的系统提示中。仅提供足够信息，让 Claude 知道何时应使用每个技能，而无需将其全部加载到上下文中。
第二级（SKILL.md 正文）： 当 Claude 认为该技能与当前任务相关时加载。包含完整指令和指导。
第三级（链接文件）： 捆绑在技能目录中的其他文件，Claude 可根据需要选择导航和发现。

这种渐进式披露可在保持专业知识的同时最大限度减少 token 使用量。

可组合性（Composability）h4

Claude 可以同时加载多个技能。您的技能应能与其他技能良好协作，而非假定自己是唯一可用的功能。

可移植性（Portability）h4

技能在 Claude.ai、Claude Code 和 API 中表现完全一致。只需创建一次技能，即可在所有界面上正常运行（前提是环境支持技能所需的任何依赖项）。

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

注意： 构建不含 MCP 的独立技能？请跳至「规划与设计」——您随时可以返回此处。

如果您已经拥有可正常运行的 MCP 服务器，那么最困难的部分已经完成。技能是顶层的知识层——捕捉您已知的工作流和最佳实践，从而让 Claude 能够始终如一地应用它们。

厨房类比

MCP 提供专业厨房：访问工具、食材和设备。
技能提供食谱：创建有价值成果的逐步指令。

两者结合，使用户无需自行梳理每一步即可完成复杂任务。

它们如何协同工作h4

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

为什么这对您的 MCP 用户很重要h4

没有技能时：

用户连接您的 MCP 后不知道下一步该做什么
支持工单询问「如何用您的集成完成 X」
每次对话都从零开始
结果不一致，因为用户每次提示方式不同
用户将问题归咎于您的连接器，而实际原因是缺少工作流指导

有技能时：

预构建的工作流在需要时自动激活
一致、可靠的工具使用
最佳实践嵌入每次交互
降低您的集成的学习曲线

第 2 章：规划与设计h2

从用例开始h3

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

良好的用例定义：

用例： 项目冲刺规划

触发条件： 用户说「帮我规划这个冲刺」或「创建冲刺任务」

步骤：

从 Linear 获取当前项目状态（通过 MCP）
分析团队速度和容量
建议任务优先级
在 Linear 中创建带有正确标签和估算的任务

结果： 完成规划的冲刺，任务已创建

自问：

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

常见技能用例类别h3

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

第 1 类：文档与资产创建h4

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

真实示例： frontend-design 技能（另见 docx、pptx、xlsx 和 ppt 技能）

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

关键技巧：

嵌入样式指南和品牌标准
用于一致输出的模板结构
最终确定前的质量检查清单
无需外部工具——使用 Claude 的内置功能

第 2 类：工作流自动化h4

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

真实示例： skill-creator 技能

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

关键技巧：

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

第 3 类：MCP 增强h4

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

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

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

关键技巧：

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

定义成功标准h3

如何判断您的技能是否正常工作？

这些是理想目标——粗略基准而非精确阈值。目标是严谨，但接受存在基于「感觉」的评估成分。我们正在积极开发更稳健的测量指南和工具。

定量指标：

技能在 90% 的相关查询中触发
- 测量方法： 运行 10–20 个应触发您技能的测试查询。跟踪自动加载次数与需要显式调用的次数。
在 X 个工具调用内完成工作流
- 测量方法： 比较启用和未启用技能时的相同任务。统计工具调用次数和消耗的 token 总量。
每个工作流 0 次失败的 API 调用
- 测量方法： 在测试运行期间监控 MCP 服务器日志。跟踪重试率和错误代码。

定性指标：

用户无需提示 Claude 下一步做什么
- 评估方法： 测试期间记录您需要重定向或澄清的频率。向 Beta 用户征求反馈。
工作流无需用户修正即可完成
- 评估方法： 对同一请求运行 3–5 次。比较输出的结构一致性和质量。
跨会话结果一致
- 评估方法： 新用户能否在首次尝试时仅需最少指导即可完成任务？

技术要求h3

文件结构h4

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

关键规则h4

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 前置元数据：最重要的部分h3

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
- 示例：
```
metadata:
  author: ProjectHub
  version: 1.0.0
  mcp-server: projecthub
```

安全限制

前置元数据中禁止：

XML 尖括号（< >）
名称中包含 “claude” 或 “anthropic” 的技能（保留字）

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

编写有效的技能h3

description 字段h4

根据 Anthropic 工程博客所述：「此元数据……仅提供足够信息，让 Claude 知道何时应使用每个技能，而无需将其全部加载到上下文中。」这是渐进式披露的第一级。

结构：

[技能功能] + [何时使用] + [关键能力]

优质 description 示例：

# 优质 - 具体且可操作
description: 分析 Figma 设计文件并生成开发者交接文档。适用于用户上传 .fig 文件、询问「设计规格」、「组件文档」或「设计转代码交接」时。

# 优质 - 包含触发短语
description: 管理 Linear 项目工作流，包括冲刺规划、任务创建和状态跟踪。适用于用户提及「sprint」、「Linear tasks」、「project planning」或要求「create tickets」时。

# 优质 - 清晰价值主张
description: PayFlow 的端到端客户入职工作流。处理账户创建、支付设置和订阅管理。适用于用户说「onboard new customer」、「set up subscription」或「create PayFlow account」时。

劣质 description 示例：

# 过于模糊
description: Helps with projects.

# 缺少触发条件
description: Creates sophisticated multi-page documentation systems.

# 过于技术化，无用户触发短语
description: Implements the Project entity model with hierarchical relationships.

编写主指令h4

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

推荐结构：

请根据您的技能调整此模板。将方括号部分替换为具体内容。

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

您的技能名称h1

指令h2

步骤 1：[第一个主要步骤]h3

清晰说明发生什么。

示例：

python scripts/fetch_data.py --project-id PROJECT_ID

预期输出：[描述成功时的样子]

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

示例h3

示例 1：[常见场景]

用户说：「Set up a new marketing campaign」

操作：

通过 MCP 获取现有营销活动
使用提供的参数创建新营销活动

结果： 营销活动已创建，附带确认链接

（根据需要添加更多示例）

故障排除h3

错误： [常见错误消息]

原因： [发生原因]

解决方案： [如何修复]

（根据需要添加更多错误情况）

指令编写最佳实践h4

具体且可操作

✅ 优质：

运行 `python scripts/validate.py --input {filename}` 检查数据格式。

如果验证失败，常见问题包括：
- 缺少必填字段（请添加到 CSV 中）
- 日期格式无效（请使用 YYYY-MM-DD）

❌ 劣质：

在继续之前验证数据。

包含错误处理

## 常见问题

### MCP 连接失败

如果看到「Connection refused」：

1. 确认 MCP 服务器正在运行：检查「设置 > 扩展」
2. 确认 API 密钥有效
3. 尝试重新连接：设置 > 扩展 > [您的服务] > 重新连接

清晰引用捆绑资源

在编写查询前，请查阅 references/api-patterns.md 以了解：

速率限制指南
分页模式
错误代码及处理方法

使用渐进式披露

保持 SKILL.md 聚焦核心指令。将详细文档移至 references/ 并链接到它。（详见「核心设计原则」了解三级系统的工作原理。）

第 3 章：测试与迭代h2

技能可根据您的需求以不同严谨程度进行测试：

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

请选择与您的质量要求和技能可见度相匹配的方法。内部小团队使用的技能与部署给数千企业用户的技能，测试需求不同。

专业提示： 先针对单个任务迭代，再扩展
我们发现最有效的技能创建者会先针对单个具有挑战性的任务进行迭代，直到 Claude 成功，然后将获胜方法提取到技能中。这利用了 Claude 的上下文学习能力，比广泛测试提供更快信号。一旦拥有可靠基础，再扩展到多个测试用例以实现覆盖。

使用 skill-creator 技能h3

skill-creator 技能——可在 Claude.ai 的插件目录中使用，或下载用于 Claude Code——可帮助您构建和迭代技能。如果您拥有 MCP 服务器并知道前 2–3 个工作流，通常可在一次会话中（约 15–30 分钟）构建并测试一个功能完整的技能。

创建技能：

从自然语言描述生成技能
生成带前置元数据的格式正确的 SKILL.md
建议触发短语和结构

审查技能：

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

迭代改进：

使用技能后遇到边缘情况或失败时，将这些示例带回 skill-creator
示例：「使用本次对话中识别的问题与解决方案，改进技能处理 [特定边缘情况] 的方式」

使用方法：

「Use the skill-creator skill to help me build a skill for [您的用例]」

执行问题：

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

注意： skill-creator 帮助您设计和改进技能，但不执行自动化测试套件或生成定量评估结果。

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

根据反馈迭代h3

技能是动态文档。请根据以下内容规划迭代：

触发不足信号：

技能未在应触发时加载
用户手动启用
关于何时使用的支持问题

解决方案： 在 description 中添加更多细节和细微差别——可能包括技术术语的关键字

过度触发信号：

技能为无关查询加载
用户禁用
对用途感到困惑

解决方案： 添加否定触发条件，更具体

第 4 章：分发与共享h2

技能让您的 MCP 集成更完整。当用户比较连接器时，带有技能的连接器能更快实现价值，为您带来超越仅 MCP 替代方案的优势。

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

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

下载技能文件夹
压缩文件夹（如果需要）
通过「设置 > 功能 > 技能」上传到 Claude.ai
或放置在 Claude Code 技能目录中

组织级技能：

管理员可工作区范围部署技能（2025 年 12 月 18 日上线）
自动更新
集中管理

通过 API 使用技能h3

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

关键功能：

/v1/skills 端点用于列出和管理技能
通过 container.skills 参数将技能添加到 Messages API 请求
通过 Claude Console 进行版本控制和管理
与 Claude Agent SDK 配合构建自定义代理

何时使用 API vs Claude.ai：

用例	最佳界面
最终用户直接与技能交互	Claude.ai / Claude Code
开发期间手动测试和迭代	Claude.ai / Claude Code
个人、临时工作流	Claude.ai / Claude Code
程序化使用技能的应用	API
大规模生产部署	API
自动化管道和代理系统	API

注意： API 中的技能需要 Code Execution Tool 测试版，该测试版提供技能运行所需的安全环境。

开放标准h3

我们已将 Agent Skills 发布为开放标准。与 MCP 类似，我们相信技能应跨工具和平台可移植——无论您使用 Claude 还是其他 AI 平台，同一技能都应正常工作。不过，某些技能旨在充分利用特定平台的能力；作者可在技能的 compatibility 字段中注明。我们一直在与生态系统成员合作制定该标准，并对早期采用感到兴奋。

今日推荐方法h3

首先在 GitHub 上托管您的技能，使用公开仓库、清晰的 README（供人类访问者使用——这与您的技能文件夹分开，后者不应包含 README.md）以及带截图的使用示例。然后在您的 MCP 文档中添加一节，链接到该技能，解释同时使用两者的价值，并提供快速入门指南。

技能定位

您如何描述技能决定了用户是否理解其价值并真正尝试使用。在编写技能相关内容（README、文档或营销材料）时，请牢记以下原则。

关注结果而非功能：

✅ 优质：

「ProjectHub 技能让团队能够在几秒钟内设置完整的项目工作区——包括页面、数据库和模板——而非手动设置花费 30 分钟。」

❌ 劣质：

「ProjectHub 技能是一个包含 YAML 前置元数据和 Markdown 指令的文件夹，用于调用我们的 MCP 服务器工具。」

突出 MCP + 技能的故事：

「我们的 MCP 服务器让 Claude 能够访问您的 Linear 项目。我们的技能教会 Claude 您团队的冲刺规划工作流。两者结合，实现 AI 驱动的项目管理。」

安装指南（推荐结构）

托管在 GitHub 上
- 面向开源技能的公开仓库
- 清晰的安装说明 README
- 使用示例和截图
在您的 MCP 仓库中记录
- 从 MCP 文档链接到技能
- 解释同时使用两者的价值
- 提供快速入门指南
创建安装指南

安装 [您的服务] 技能
1. 下载技能：
  - 克隆仓库：git clone https://github.com/yourcompany/skills
  - 或从 Releases 下载 ZIP
2. 在 Claude 中安装：
  - 打开 Claude.ai > 设置 > 技能
  - 点击「上传技能」
  - 选择技能文件夹（已压缩）
3. 启用技能：
  - 开启 [您的服务] 技能
  - 确保您的 MCP 服务器已连接
4. 测试：
  - 询问 Claude：「Set up a new project in [您的服务]」

第 5 章：模式与故障排除h2

这些模式来自早期采用者和内部团队创建的技能。它们代表我们观察到的有效常见方法，而非规定性模板。

选择方法：问题优先 vs 工具优先h3

将其想象成 Home Depot。您可能带着问题走进商店——「我需要修理厨房柜子」——员工会为您指出正确的工具。或者您可能先挑选一把新钻头，然后询问如何用于特定工作。

技能的工作方式相同：

问题优先： 「我需要设置项目工作区」→ 您的技能按正确顺序编排正确的 MCP 调用。用户描述结果；技能处理工具。
工具优先： 「我已连接 Notion MCP」→ 您的技能教会 Claude 最优工作流和最佳实践。用户拥有访问权限；技能提供专业知识。

大多数技能偏向一个方向。了解哪种框架适合您的用例，有助于您选择下方合适的模式。

模式 1：顺序工作流编排h3

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

示例结构：

# 工作流：新客户入职

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

关键技巧：

明确的步骤顺序
步骤之间的依赖关系
每阶段验证
失败回滚指令

模式 2：多 MCP 协调h3

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

示例： 设计到开发交接

# 阶段 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 之间的数据传递
进入下一阶段前的验证
集中错误处理

模式 3：迭代优化h3

适用场景： 输出质量通过迭代提升。

示例： 报告生成

# 迭代报告创建

## 初始草稿

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

## 质量检查

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

## 优化循环

1. 解决每个已识别问题
2. 重新生成受影响章节
3. 重新验证
4. 重复直到达到质量阈值

## 最终确定

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

关键技巧：

明确的质

关键技巧：

明确的质

量标准

迭代改进
验证脚本
知道何时停止迭代

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

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

示例： 文件存储

# 智能文件存储

## 决策树

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

## 执行存储

根据决策：
- 调用相应的 MCP 工具
- 应用特定于服务的元数据
- 生成访问链接

## 向用户提供上下文

解释为何选择该存储方式

关键技巧：

清晰的决策标准
回退选项
选择透明度

模式 5：领域特定智能h3

适用场景： 您的技能添加了超出工具访问的专门知识。

示例： 金融合规

# 带合规的支付处理

## 处理前（合规检查）

1. 通过 MCP 获取交易详情
2. 应用合规规则：
   - 检查制裁名单
   - 验证管辖区允许范围
   - 评估风险级别
3. 记录合规决策

## 处理

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

## 审计轨迹

- 记录所有合规检查
- 记录处理决策
- 生成审计报告

关键技巧：

逻辑中嵌入领域专业知识
操作前合规
全面文档
清晰治理

故障排除h3

技能无法上传h4

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

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

解决方案：

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

错误： “Invalid frontmatter”

原因： YAML 格式问题

常见错误：

# 错误 - 缺少分隔符
name: my-skill
description: Does things

# 错误 - 未闭合引号
name: my-skill
description: "Does things

# 正确
---
name: my-skill
description: Does things
---

错误： “Invalid skill name”

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

# 错误
name: My Cool Skill

# 正确
name: my-cool-skill

技能未触发h4

症状： 技能从未自动加载

修复： 修改您的 description 字段。参阅「description 字段」中的优质/劣质示例。

快速检查清单：

是否过于通用？（“Helps with projects” 无法工作）
是否包含用户实际会说的触发短语？
如适用，是否提及相关文件类型？

调试方法：

询问 Claude：「When would you use the [skill name] skill？」Claude 会引用 description 内容。根据缺失部分进行调整。

技能触发过于频繁h4

症状： 技能为无关查询加载

解决方案：

添加否定触发条件

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

更加具体

# 过于宽泛
description: Processes documents

# 更具体
description: Processes PDF legal documents for contract review

澄清范围

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

指令未被遵循h4

症状： 技能加载但 Claude 不遵循指令

常见原因：

指令过于冗长
- 保持指令简洁
- 使用项目符号和编号列表
- 将详细参考移至单独文件
指令被埋没
- 将关键指令放在顶部
- 使用 ## Important 或 ## Critical 标题
- 必要时重复关键点
语言模糊
```
# 劣质
Make sure to validate things properly

# 优质
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 技能中的此模式示例。

模型「偷懒」 —— 添加明确鼓励：

## Performance Notes

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

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

MCP 连接问题h4

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

检查清单：

验证 MCP 服务器已连接
- Claude.ai：设置 > 扩展 > [您的服务]
- 应显示「Connected」状态
检查身份验证
- API 密钥有效且未过期
- 已授予适当权限/范围
- OAuth 令牌已刷新
独立测试 MCP
- 要求 Claude 直接调用 MCP（不使用技能）
- “Use [Service] MCP to fetch my projects”
- 如果失败，问题出在 MCP 而非技能
验证工具名称
- 技能引用正确的 MCP 工具名称
- 检查 MCP 服务器文档
- 工具名称区分大小写

大上下文问题h4

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

原因：

技能内容过大
同时启用的技能过多
加载了全部内容而非渐进式披露

解决方案：

优化 SKILL.md 大小
- 将详细文档移至 references/
- 链接到 references 而非内联
- 保持 SKILL.md 少于 5,000 字
减少启用的技能
- 评估是否同时启用了超过 20–50 个技能
- 建议选择性启用
- 考虑为相关功能创建技能「包」

第 6 章：资源与参考h2

如果您正在构建首个技能，请先从「最佳实践指南」开始，然后根据需要参考 API 文档。

官方文档h3

Anthropic 资源：

最佳实践指南
技能文档
API 参考
MCP 文档

博客文章：

介绍 Agent Skills
工程博客：为真实世界装备代理
技能详解
如何为 Claude 创建技能
为 Claude Code 构建技能
通过技能改进前端设计

示例技能h3

公开技能仓库：

GitHub: anthropics/skills
包含 Anthropic 创建的技能，您可以自定义

skill-creator 技能：

内置于 Claude.ai 并可用于 Claude Code
可从描述生成技能
提供审查和建议
使用：「Help me build a skill using skill-creator」

验证：

skill-creator 可评估您的技能
询问：「Review this skill and suggest improvements」

获取支持h3

技术问题：

一般问题：Claude 开发者 Discord 社区论坛

错误报告：

GitHub Issues: anthropics/skills/issues
请包含：技能名称、错误消息、重现步骤

参考 A：快速检查清单h3

使用此检查清单在上传前后验证您的技能。如果希望更快开始，请使用 skill-creator 技能生成初稿，然后逐项检查以确保无遗漏。

开始前

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

开发期间

上传前

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

上传后

参考 B：YAML 前置元数据h3

必需字段

---
name: skill-name-in-kebab-case
description: 技能功能描述及使用时机。包含具体触发短语。
---

所有可选字段

name: skill-name
description: [必需描述]
license: MIT                    # 可选：开源许可证
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"  # 可选：限制工具访问
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 字符）

禁止：

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

参考 C：完整技能示例h3

以下是展示本指南中模式的完整、生产就绪技能：

文档技能 —— PDF、DOCX、PPTX、XLSX 创建
示例技能 —— 各种工作流模式
合作伙伴技能目录 —— 查看来自 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等合作伙伴的技能

这些仓库会保持更新，并包含本指南未涵盖的更多示例。克隆它们，根据您的用例修改，并将其用作模板。

claude.ai

引言h2

本指南的两种阅读路径h3

第 1 章：基础知识h2

什么是技能？h3

核心设计原则h3

渐进式披露（Progressive Disclosure）h4

可组合性（Composability）h4

可移植性（Portability）h4

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

它们如何协同工作h4

为什么这对您的 MCP 用户很重要h4

第 2 章：规划与设计h2

从用例开始h3

常见技能用例类别h3

第 1 类：文档与资产创建h4

第 2 类：工作流自动化h4

第 3 类：MCP 增强h4

定义成功标准h3

技术要求h3

文件结构h4

关键规则h4

YAML 前置元数据：最重要的部分h3

编写有效的技能h3

description 字段h4

编写主指令h4

您的技能名称h1

指令h2

步骤 1：[第一个主要步骤]h3

示例h3

故障排除h3

指令编写最佳实践h4

第 3 章：测试与迭代h2

推荐测试方法h3

1. 触发测试h4

2. 功能测试h4

3. 性能对比h4

使用 skill-creator 技能h3

根据反馈迭代h3

第 4 章：分发与共享h2

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

通过 API 使用技能h3

开放标准h3

今日推荐方法h3

第 5 章：模式与故障排除h2

选择方法：问题优先 vs 工具优先h3

模式 1：顺序工作流编排h3

模式 2：多 MCP 协调h3

模式 3：迭代优化h3

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

模式 5：领域特定智能h3

故障排除h3

技能无法上传h4

技能未触发h4

技能触发过于频繁h4

指令未被遵循h4

MCP 连接问题h4

大上下文问题h4

第 6 章：资源与参考h2

官方文档h3

示例技能h3

获取支持h3

参考 A：快速检查清单h3

参考 B：YAML 前置元数据h3

参考 C：完整技能示例h3