构建 Claude Skill（技能）完全指南

2026年7月30日

原文：The Complete Guide to Building Skills for Claude
来源：Anthropic（claude.ai）
页数：32 页
翻译说明：全文专业中文翻译。专业术语（如 Progressive Disclosure、Composability、MCP 等）保留英文原文，并在首次出现时附带中文注释。代码、YAML 示例、文件路径等保持原样不翻译。

引言

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

当你拥有可重复的工作流时，Skill 将发挥巨大作用：根据设计稿生成前端界面、采用一致的方法论进行研究、创建遵循团队风格指南的文档，或编排多步骤流程。Skill 与 Claude 的内置能力（如代码执行和文档创建）配合良好。对于那些构建 MCP（Model Context Protocol，模型上下文协议）集成的人来说，Skill 增加了另一个强大的层次，帮助将原始工具访问转化为可靠、优化的工作流。

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

你将学到：

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

目标读者：

希望 Claude 始终如一地遵循特定工作流的开发者
希望 Claude 遵循特定工作流的高级用户
希望在组织内部标准化 Claude 使用方式的团队

本指南的两条路径：

构建独立 Skill？聚焦于基础原理、规划与设计以及类别 1-2。
增强 MCP 集成？“Skills + MCP” 章节和类别 3 适合你。

两条路径共享相同的技术要求，你只需选择与你的用例相关的内容。

你将从本指南中收获什么： 到结尾部分，你将能够一次性构建出一个可用的 Skill。使用 skill-creator（Skill 创建器），预计花费 15-30 分钟即可构建并测试你的第一个可工作的 Skill。

让我们开始吧。

第 1 章 · 基础原理

什么是 Skill？

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

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

核心设计原则

Progressive Disclosure（渐进式信息披露）

Skill 使用三级加载系统：

第一级（YAML 前置元数据）：始终加载在 Claude 的 System Prompt（系统提示词）中。仅提供足够的信息让 Claude 知道何时应使用该 Skill，而不将所有内容加载到上下文中。
第二级（SKILL.md 正文）：当 Claude 认为该 Skill 与当前任务相关时加载。包含完整的指令和指导。
第三级（关联文件）：Skill 目录中捆绑的额外文件，Claude 可以按需选择导航和发现。

这种渐进式信息披露最大程度减少了 Token（令牌）消耗，同时保持了专业化的领域能力。

Composability（可组合性）

Claude 可以同时加载多个 Skill。你的 Skill 应该能与其他 Skill 良好协作，不应假设自己是唯一可用的能力。

Portability（可移植性）

Skill 在 Claude.ai、Claude Code 和 API 上的行为完全一致。一次创建，即可在所有平台上无需修改地运行，前提是环境支持该 Skill 所需的任何依赖。

致 MCP 构建者：Skills + 连接器

如果你正在构建不含 MCP 的独立 Skill？请跳至规划与设计章节——你可以随时返回此处。

如果你已经拥有一个可工作的 MCP 服务器，你已经完成了最困难的部分。Skill 是其上的知识层——捕捉你已知的工作流和最佳实践，使 Claude 能够持续地应用它们。

厨房类比：

MCP 提供了专业厨房：使用工具、食材和设备的权限。
Skill 提供了食谱：关于如何创造有价值成果的分步说明。

二者结合，使用户能够完成复杂任务，而不需要自己摸索每一步。

二者如何协同工作：

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

这对你的 MCP 用户为什么重要：

没有 Skill 时有 Skill 时用户连接了你的 MCP 但不知道下一步做什么预构建的工作流在需要时自动激活支持工单问"我该怎么用你的集成做 X"一致、可靠的工具使用每次对话都从零开始最佳实践嵌入在每一次交互中因用户每次提示方式不同导致结果不一致为你的集成降低了学习曲线用户责怪你的连接器，而真正的问题是缺少工作流指导

第 2 章 · 规划与设计

从用例出发

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

好的用例定义：

code

用例：项目 Sprint（冲刺）规划触发条件：用户说 "help me plan this sprint" 或 "create sprint tasks"步骤：  1. 从 Linear（通过 MCP）获取当前项目状态  2. 分析团队速度和容量  3. 建议任务优先级排序  4. 在 Linear 中创建带有适当标签和估算的任务结果：完整的 sprint 规划及已创建的任务

问自己：

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

常见 Skill 用例类别

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

类别 1：文档与资产创建（Document & Asset Creation）

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

真实案例： frontend-design skill（另见 docx、pptx、xlsx 和 ppt 的 skill）

“Create distinctive, production-grade frontend interfaces with high design quality. Use when building web components, pages, artifacts, posters, or applications.”

关键技术：

嵌入风格指南和品牌标准
用于一致输出的模板结构
最终定稿前的质量检查清单
不需要外部工具——使用 Claude 的内置能力

类别 2：工作流自动化（Workflow Automation）

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

真实案例： skill-creator skill

“Interactive guide for creating new skills. Walks the user through use case definition, frontmatter generation, instruction writing, and validation.”

关键技术：

带有验证关卡的分步工作流
常用结构的模板
内置审核和改进建议
迭代精炼循环

类别 3：MCP 增强（MCP Enhancement）

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

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

“Automatically analyzes and fixes detected bugs in GitHub Pull Requests using Sentry’s error monitoring data via their MCP server.”

关键技术：

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

定义成功标准

你如何知道你的 Skill 在正常工作？

这些都是期望目标——粗略的基准，而非精确的阈值。力求严谨，但要接受评估中会存在一定程度的感性判断。我们正在积极开发更稳健的评估指导和工具。

量化指标：

指标如何衡量Skill 在 90% 的相关查询上触发运行 10-20 个应触发 Skill 的测试查询。追踪自动加载 vs. 需要显式调用的次数。在 X 次工具调用内完成工作流比较启用和未启用 Skill 的同一任务。统计工具调用次数和消耗的总 Token 数。每次工作流 0 次 API 调用失败在测试运行期间监控 MCP 服务器日志。追踪重试率和错误代码。

质性指标：

指标如何评估用户不需要提示 Claude 下一步做什么测试期间，注意你需要重定向或澄清的频率。向 beta 用户征求反馈。工作流完成时无需用户纠正运行同一请求 3-5 次。比较输出的结构一致性和质量。跨会话结果一致新用户能否在第一次尝试时以最少指导完成任务？

技术要求

文件结构

code

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

关键规则

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

YAML 前置元数据是 Claude 决定是否加载你的 Skill 的依据。务必把这部分做好。

最小必需格式

yaml

---name: your-skill-namedescription: What it does. Use when user asks to [specific phrases].---

这就是你开始所需的全部。

字段要求

name（必需）：

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

description（必需）：

必须同时包含：
- Skill 做什么
- 何时使用（触发条件）
不超过 1024 字符
不包含 XML 标签（< 或 >）
包含用户可能说出的具体任务
如相关，提及文件类型

license（可选）：

若将 Skill 开源则使用
常见值：MIT、Apache-2.0

compatibility（可选）：

1-500 字符
标明环境要求：例如适用产品、所需系统包、网络访问需求等

metadata（可选）：

任意自定义键值对
建议字段：author、version、mcp-server
示例：

yaml

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

安全限制

前置元数据中禁止：

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

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

编写有效的 Skill

description 字段

引用自 Anthropic 工程博客：

“This metadata…provides just enough information for Claude to know when each skill should be used without loading all of it into context.”

这是 Progressive Disclosure 的第一级。

结构： [做什么] + [何时使用] + [关键能力]

好的 description 示例：

yaml

# 好 —— 具体且可操作description: Analyzes Figma design files and generates developer handoffdocumentation. Use when user uploads .fig files, asks for "design specs","component documentation", or "design-to-code handoff".# 好 —— 包含触发短语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".# 好 —— 清晰的价值主张description: End-to-end customer onboarding workflow for PayFlow. Handlesaccount creation, payment setup, and subscription management. Use whenuser says "onboard new customer", "set up subscription", or "createPayFlow account".

差的 description 示例：

yaml

# 太模糊description: Helps with projects.# 缺少触发条件description: Creates sophisticated multi-page documentation systems.# 太技术化，没有用户触发条件description: Implements the Project entity model with hierarchicalrelationships.

编写主指令

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

推荐结构： 为你的 Skill 改编此模板。将中括号部分替换为你的具体内容。

code

---name: your-skilldescription: [...]---# Your Skill Name## Instructions### Step 1: [First Major Step]Clear explanation of what happens.Example:```bashpython scripts/fetch_data.py --project-id PROJECT_ID```Expected output: \[describe what success looks like\](Add more steps as needed)## Examples### Example 1: \[common scenario\]User says: "Set up a new marketing campaign"  Actions:1.  Fetch existing campaigns via MCP    2.  Create new campaign with provided parameters      Result: Campaign created with confirmation link    (Add more examples as needed)## Troubleshooting### Error: \[Common error message\]Cause: \[Why it happens\]  Solution: \[How to fix\](Add more error cases as needed)

指令编写最佳实践

要具体且可操作

✅ 好：

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.

包含错误处理

markdown

## Common Issues### MCP Connection FailedIf you see "Connection refused":1. Verify MCP server is running: Check Settings > Extensions2. Confirm API key is valid3. 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/ 并通过链接引用。（参见核心设计原则了解三级系统如何运作。）

第 3 章 · 测试与迭代

Skill 可以根据你的需要，在不同严谨程度上进行测试：

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

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

专家提示：先在一个任务上迭代，再扩展

我们发现，最高效的 Skill 创建者会在单个有挑战性的任务上迭代，直到 Claude 成功，然后将成功的方案提取为 Skill。这利用了 Claude 的上下文学习能力，并且比广泛测试提供更快的反馈信号。一旦有了可工作的基础，再扩展到多个测试用例以获取覆盖率。

使用 skill-creator skill

skill-creator skill——可通过 Claude.ai 插件目录获取或下载用于 Claude Code——可以帮助你构建和迭代 Skill。如果你有一个 MCP 服务器并知道你的前 2-3 个工作流，你可以在一次操作中构建并测试一个可用的 Skill——通常在 15-30 分钟内完成。

创建 Skill：

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

审核 Skill：

标记常见问题（模糊的描述、缺少触发条件、结构性问题）
识别潜在的过度/不足触发风险
基于 Skill 声明目的建议测试用例

迭代改进：

在使用 Skill 并遇到边界情况或失败后，将这些示例带回 skill-creator
示例：“Use the issues & solution identified in this chat to improve how the skill handles [specific edge case]”

使用方式：

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

注意： skill-creator 帮助你设计和打磨 Skill，但不会执行自动化测试套件或产生量化评估结果。

基于反馈进行迭代

Skill 是活的文档。计划根据以下信号进行迭代：

不足触发信号（Undertriggering）：

Skill 在应该加载时未加载
用户手动启用它
关于何时使用它的支持问题

→ 解决方案： 在 description 中添加更多细节和细微差别——这可能包括关键词，特别是技术术语。

过度触发信号（Overtriggering）：

Skill 在不相关的查询中加载
用户禁用它
对用途感到困惑

→ 解决方案： 添加负面触发器，更具体化。

执行问题：

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

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

第 4 章 · 分发与共享

Skill 让你的 MCP 集成更加完整。当用户比较连接器时，那些附带 Skill 的连接器提供了更快的价值实现路径，让你相比仅提供 MCP 的替代方案更有优势。

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

个人用户如何获取 Skill：

下载 Skill 文件夹
压缩文件夹（如需要）
通过 Settings > Capabilities > Skills 上传到 Claude.ai
或放入 Claude Code 的 skills 目录

组织级 Skill：

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

开放标准

我们已将 Agent Skills 作为开放标准发布。与 MCP 一样，我们相信 Skill 应该跨工具和平台可移植——同一 Skill 无论你使用 Claude 还是其他 AI 平台都应该能正常工作。话虽如此，有些 Skill 被设计来充分利用特定平台的能力；作者可以在 Skill 的 compatibility 字段中注明这一点。我们一直在与生态系统中的成员就该标准进行合作，并对早期采纳感到兴奋。

通过 API 使用 Skill

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

关键能力：

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

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

用例最佳平台终端用户直接与 Skill 交互Claude.ai / Claude Code开发期间手动测试和迭代Claude.ai / Claude Code个人、临时工作流Claude.ai / Claude Code应用程序以编程方式使用 SkillAPI规模化生产部署API自动化流水线和 Agent 系统API

注意： API 中的 Skill 需要 Code Execution Tool（代码执行工具）Beta 版，它提供了 Skill 运行所需的安全环境。

实现细节参见：

Skills API Quickstart
Create Custom Skills
Skills in the Agent SDK

当前推荐做法

从在 GitHub 上托管你的 Skill 开始：公开仓库、清晰的 README（供人类访客阅读——这与你的 Skill 文件夹分开，Skill 文件夹不应包含 README.md）以及带有截图的示例用法。然后在你的 MCP 文档中添加一个章节，链接到 Skill，解释为什么二者结合使用有价值，并提供快速入门指南。

1. 托管在 GitHub：

开源 Skill 使用公开仓库
清晰的 README 包含安装说明
示例用法和截图

2. 在你的 MCP 仓库中编写文档：

从 MCP 文档链接到 Skill
解释二者结合使用的价值
提供快速入门指南

3. 创建安装指南：

markdown

## Installing the [Your Service] skill1. Download the skill:   - Clone repo: `git clone https://github.com/yourcompany/skills`   - Or download ZIP from Releases2. 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 connected4. Test:   - Ask Claude: "Set up a new project in [Your Service]"

定位你的 Skill

你如何描述你的 Skill 决定了用户是否理解其价值并真正尝试使用。当撰写关于你的 Skill 的内容时——在 README、文档或推广材料中——请牢记这些原则。

聚焦于结果，而非功能：

✅ 好：

“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 + Skill 的故事：

“Our MCP server gives Claude access to your Linear projects. Our skills teach Claude your team’s sprint planning workflow. Together, they enable AI-powered project management.”

第 5 章 · 模式与故障排除

这些模式源于早期采用者和内部团队创建的 Skill。它们代表了我们所见过的行之有效的常见方法，而非规定性模板。

选择你的方法：问题优先 vs. 工具优先

就像去 Home Depot（家装超市）。你可能带着一个问题走进去——“我需要修理厨房橱柜”——店员会引导你找到合适的工具。或者你可能挑出一把新电钻，然后询问如何用它来完成你的具体工作。

Skill 以同样的方式工作：

Problem-first（问题优先）： “我需要设置一个项目工作区” → 你的 Skill 以正确的顺序编排正确的 MCP 调用。用户描述结果；Skill 处理工具。
Tool-first（工具优先）： “我已连接 Notion MCP” → 你的 Skill 教会 Claude 最佳的工作流和实践。用户拥有访问权限；Skill 提供专业知识。

大多数 Skill 偏向一个方向。知道哪种框架适合你的用例，有助于你选择下面的正确模式。

模式 1：顺序工作流编排（Sequential Workflow Orchestration）

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

示例结构：

markdown

## Workflow: Onboard New Customer### Step 1: Create AccountCall MCP tool: `create_customer`Parameters: name, email, company### Step 2: Setup PaymentCall MCP tool: `setup_payment_method`Wait for: payment method verification### Step 3: Create SubscriptionCall MCP tool: `create_subscription`Parameters: plan_id, customer_id (from Step 1)### Step 4: Send Welcome EmailCall MCP tool: `send_email`Template: welcome_email_template

关键技术：

显式的步骤排序
步骤间的依赖关系
每个阶段的验证
失败时的回滚说明

模式 2：多 MCP 协调（Multi-MCP Coordination）

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

示例：设计到开发交接

markdown

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

关键技术：

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

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

示例：报告生成

markdown

## Iterative Report Creation### Initial Draft1. Fetch data via MCP2. Generate first draft report3. Save to temporary file### Quality Check1. Run validation script: `scripts/check_report.py`2. Identify issues:   - Missing sections   - Inconsistent formatting   - Data validation errors### Refinement Loop1. Address each identified issue2. Regenerate affected sections3. Re-validate4. Repeat until quality threshold met### Finalization1. Apply final formatting2. Generate summary3. Save final version

关键技术：

明确的质量标准
迭代改进
验证脚本
知道何时停止迭代

模式 4：上下文感知工具选择（Context-Aware Tool Selection）

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

示例：文件存储

markdown

## Smart File Storage### Decision Tree1. Check file type and size2. 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 StorageBased on decision:- Call appropriate MCP tool- Apply service-specific metadata- Generate access link### Provide Context to UserExplain why that storage was chosen

关键技术：

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

模式 5：领域特定智能（Domain-Specific Intelligence）

适用场景： 你的 Skill 在工具访问之外增加了专业知识。

示例：金融合规

markdown

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

关键技术：

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

故障排除

Skill 无法上传

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

原因： 文件未精确命名为 SKILL.md
解决方案：
- 重命名为 SKILL.md（大小写敏感）
- 验证：ls -la 应显示 SKILL.md

错误： "Invalid frontmatter"

原因： YAML 格式问题
常见错误：

yaml

# 错误 —— 缺少分隔符name: my-skilldescription: Does things# 错误 —— 引号未闭合name: my-skilldescription: "Does things# 正确---name: my-skilldescription: Does things---

错误： "Invalid skill name"

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

yaml

# 错误name: My Cool Skill# 正确name: my-cool-skill

Skill 不触发

症状： Skill 从不自动加载

修复： 修正你的 description 字段。参见 description 字段中好/差示例。

快速检查清单：

是否太泛泛？（“Helps with projects” 不起作用）
是否包含用户实际会说的触发短语？
是否提到了相关文件类型（如适用）？

调试方法： 问 Claude：“When would you use the [skill name] skill?” Claude 会引用 description 的内容回复你。根据缺失的内容进行调整。

Skill 触发太频繁

症状： Skill 在不相关的查询中加载

解决方案：

1. 添加负面触发器：

yaml

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

2. 更具体化：

yaml

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

3. 明确范围：

yaml

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

MCP 连接问题

症状： Skill 加载但 MCP 调用失败

检查清单：

验证 MCP 服务器已连接
- Claude.ai：Settings > Extensions > [Your Service]
- 应显示 “Connected” 状态
检查认证
- API 密钥有效且未过期
- 适当的权限/作用域已授予
- OAuth Token 已刷新
独立测试 MCP
- 要求 Claude 直接调用 MCP（不使用 Skill）
- “Use [Service] MCP to fetch my projects”
- 如果这也失败，问题在 MCP 而非 Skill
验证工具名称
- Skill 引用的 MCP 工具名称是否正确
- 检查 MCP 服务器文档
- 工具名称大小写敏感

指令未被遵循

症状： Skill 加载但 Claude 未遵循指令

常见原因：

1. 指令过于冗长

保持指令简洁
使用项目符号和编号列表
将详细参考资料移至单独的文件

2. 指令被埋没

将关键指令放在顶部
使用 ## Important 或 ## Critical 标题
必要时重复关键点

3. 语言含糊

markdown

# 差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 Skills 以获取此模式的示例。

4. 模型"惰性"

添加明确的鼓励：

markdown

## 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 太多
所有内容都被加载而不是使用 Progressive Disclosure

解决方案：

1. 优化 SKILL.md 大小

将详细文档移至 references/
使用链接引用而非内联
保持 SKILL.md 在 5,000 词以下

2. 减少启用的 Skill 数量

评估是否同时启用了超过 20-50 个 Skill
建议选择性启用
考虑将相关能力打包为 Skill “包（packs）”

第 6 章 · 资源与参考

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

官方文档

Anthropic 资源：

Best Practices Guide（最佳实践指南）
Skills Documentation（Skills 文档）
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

示例 Skill

公共 Skill 仓库：

GitHub: anthropics/skills
包含 Anthropic 创建的、你可以自定义的 Skill

工具与实用程序

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 的社区论坛

Bug 报告：

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

参考附录 A · 快速检查清单

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

开始前

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

开发期间

文件夹以 kebab-case 命名
SKILL.md 文件存在（精确拼写）
YAML 前置元数据有 --- 分隔符
name 字段：kebab-case，无空格，无大写字母
description 包含 WHAT 和 WHEN
无 XML 标签（< >）出现在任何地方
指令清晰且可操作
包含错误处理
提供了示例
引用已清晰链接

上传前

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

上传后

在真实对话中测试
监控不足/过度触发
收集用户反馈
迭代 description 和指令
更新 metadata 中的版本号

参考附录 B · YAML 前置元数据

必需字段

yaml

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

全部可选字段

yaml

name: skill-namedescription: [required 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 字段
长 description（最多 1024 字符）

禁止：

XML 尖括号（< >）—— 安全限制
YAML 中的代码执行（使用安全 YAML 解析）
名称中含有 claude 或 anthropic 前缀的 Skill（保留）

参考附录 C · 完整 Skill 示例

关于展示本指南中模式的完整、生产就绪的 Skill：

Document Skills —— PDF、DOCX、PPTX、XLSX 创建
Example Skills —— 各种工作流模式
Partner Skills Directory —— 查看来自各合作伙伴的 Skill，如 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等

这些仓库保持最新，并包含超出本文档覆盖范围的额外示例。克隆它们，为你的用例进行修改，并将其用作模板。

原文来源：claude.ai · Anthropic

目录

引言

第 1 章 · 基础原理

什么是 Skill？

核心设计原则

Progressive Disclosure（渐进式信息披露）

Composability（可组合性）

Portability（可移植性）

致 MCP 构建者：Skills + 连接器

第 2 章 · 规划与设计

从用例出发

常见 Skill 用例类别

类别 1：文档与资产创建（Document & Asset Creation）

类别 2：工作流自动化（Workflow Automation）

类别 3：MCP 增强（MCP Enhancement）

定义成功标准

技术要求

文件结构

关键规则

YAML 前置元数据（YAML Frontmatter）：最重要的部分

最小必需格式

字段要求

安全限制

编写有效的 Skill

description 字段

编写主指令

指令编写最佳实践

要具体且可操作

包含错误处理

清晰引用捆绑资源

使用渐进式信息披露

第 3 章 · 测试与迭代

专家提示：先在一个任务上迭代，再扩展

推荐的测试方法

1. 触发测试（Triggering Tests）

2. 功能测试（Functional Tests）

3. 性能对比（Performance Comparison）

使用 skill-creator skill

基于反馈进行迭代

第 4 章 · 分发与共享

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

开放标准

通过 API 使用 Skill

当前推荐做法

定位你的 Skill

第 5 章 · 模式与故障排除

选择你的方法：问题优先 vs. 工具优先

模式 1：顺序工作流编排（Sequential Workflow Orchestration）

模式 2：多 MCP 协调（Multi-MCP Coordination）

模式 3：迭代精炼（Iterative Refinement）

模式 4：上下文感知工具选择（Context-Aware Tool Selection）

模式 5：领域特定智能（Domain-Specific Intelligence）

故障排除

Skill 无法上传

Skill 不触发

Skill 触发太频繁

MCP 连接问题

指令未被遵循

大上下文问题

第 6 章 · 资源与参考

官方文档

示例 Skill

工具与实用程序

获取支持

参考附录 A · 快速检查清单

开始前

开发期间

上传前

上传后

参考附录 B · YAML 前置元数据

必需字段

全部可选字段

安全注意事项

参考附录 C · 完整 Skill 示例