--- title: Claude Skills 完整构建指南 description: 从基础到高级，全面介绍如何为 Claude 构建自定义 Skills，包括设计模式、测试方法和分发策略 date: 2026-01-15 author: Anthropic source: https://docs.anthropic.com/en/docs/build-with-claude/skills category: 03-toolchain-frameworks tags: - Claude - Skills - AI ??? - MCP - 工作流 --- # Claude Skills 完整构建指南 **作者：Anthropic** **原文：[查看原文](https://docs.anthropic.com/en/docs/build-with-claude/skills)** ## 目录 - [简介](#简介) - [基础知识](#基础知识) - [规划与设计](#规划与设计) - [测试与迭代](#测试与迭代) - [分发与共享](#分发与共享) - [模式与故障排除](#模式与故障排除) - [资源与参考](#资源与参考) ## 简介 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 分钟。 让我们开始吧。 ## 基础知识 ### 什么是 Skill？ 一个 skill 是一个包含以下内容的文件夹： - **SKILL.md**（必需）：带有 YAML frontmatter 的 Markdown 指令 - **scripts/**（可选）：可执行代码（Python、Bash 等） - **references/**（可选）：按需加载的文档 - **assets/**（可选）：输出中使用的模板、字体、图标 ### 核心设计原则 #### 渐进式披露 Skills 使用三级系统： - **第一级（YAML frontmatter）**：始终加载在 Claude 的系统提示中。提供足够的信息让 Claude 知道何时应该使用每个 skill，而无需将所有内容加载到上下文中。 - **第二级（SKILL.md 正文）**：当 Claude 认为 skill 与当前任务相关时加载。包含完整的指令和指导。 - **第三级（链接文件）**：skill 目录中捆绑的其他文件，Claude 可以选择仅在需要时导航和发现。 这种渐进式披露最小化了 token 使用，同时保持了专业知识。 #### 可组合性 Claude 可以同时加载多个 skills。你的 skill 应该与其他 skills 配合良好，而不是假设它是唯一可用的功能。 #### 可移植性 Skills 在 Claude.ai、Claude Code 和 API 上的工作方式完全相同。创建一次 skill，它就可以在所有平台上工作而无需修改，前提是环境支持 skill 所需的任何依赖项。 ### 对于 MCP 构建者：Skills + 连接器 > 💡 构建不带 MCP 的独立 skills？跳到规划与设计 ?? 你以后可以随时回到这里。 如果你已经有一个工作的 MCP 服务器，你已经完成了困难的部分。Skills 是顶层的知识层 ?? 捕获你已经知道的工作流和最佳实践，以便 Claude 可以一致地应用它们。 #### 厨房类比 - **MCP 提供专业厨房**：访问工具、食材和设备 - **Skills 提供食谱**：如何创造有价值东西的分步说明 它们一起使用户能够完成复杂的任务，而无需自己弄清楚每一步。 #### 它们如何协同工作 | MCP（连接性） | Skills（知识） | | ---------------------------------------------------- | ------------------------------ | | 将 Claude 连接到你的服务（Notion、Asana、Linear 等） | 教 Claude 如何有效使用你的服务 | | 提供实时数据访问和工具调用 | 捕获工作流和最佳实践 | | Claude 能做什么 | Claude 应该如何做 | #### 为什么这对你的 MCP 用户很重要 **没有 skills**： - 用户连接你的 MCP 但不知道下一步该做什么 - 支持工单询问"如何使用你的集成做 X" - 每次对话都从头开始 - 结果不一致，因为用户每次提示都不同 - 用户责怪你的连接器，而真正的问题是工作流指导 **有了 skills**： - 预构建的工作流在需要时自动激活 - 一致、可靠的工具使用 - 最佳实践嵌入在每次交互中 - 降低集成的学习曲线 ## 规划与设计 ### 从用例开始 在编写任何代码之前，确定你的 skill 应该启用的 2-3 个具体用例。 #### 良好的用例定义示例 **用例：项目冲刺规划** - **触发器**：用户说"帮我规划这个冲刺"或"创建冲刺任务" - **步骤**： 1. 从 Linear 获取当前项目状态（通过 MCP） 2. 分析团队速度和容量 3. 建议任务优先级 4. 在 Linear 中创建带有适当标签和估算的任务 - **结果**：完全规划的冲刺，任务已创建 #### 问自己 - 用户想要完成什么？ - 这需要哪些多步骤工作流？ - 需要哪些工具（内置或 MCP）？ - 应该嵌入哪些领域知识或最佳实践？ ### 常见 Skill 用例类别 在 Anthropic，我们观察到三种常见用例： #### 类别 1：文档和资产创建 **用途**：创建一致、高质量的输出，包括文档、演示文稿、应用、设计、代码等。 **真实示例：frontend-design skill**（另见 docx、pptx、xlsx 和 ppt 的 skills） "创建具有高设计质量的独特、生产级前端界面。在构建 Web 组件、页面、工件、海报或应用时使用。" **关键技术**： - 嵌入式风格指南和品牌标准 - 一致输出的模板结构 - 最终确定前的质量检查清单 - 无需外部工具 ?? 使用 Claude 的内置功能 #### 类别 2：工作流自动化 **用途**：受益于一致方法的多步骤流程，包括跨多个 MCP 服务器的协调。 **真实示例：skill-creator skill** "创建新 skills 的交互式指南。引导用户完成用例定义、frontmatter 生成、指令编写和验证。" **关键技术**： - 带验证门的分步工作流 - 常见结构的模板 - 内置审查和改进建议 - 迭代改进循环 #### 类别 3：MCP 增强 **用途**：工作流指导，以增强 MCP 服务器提供的工具访问。 **真实示例：sentry-code-review skill**（来自 Sentry） "使用 Sentry 的错误监控数据通过其 MCP 服务器自动分析和修复 GitHub Pull Requests 中检测到的错误。" **关键技术**： - 按顺序协调多个 MCP 调用 - 嵌入领域专业知识 - 提供用户否则需要指定的上下文 - 常见 MCP 问题的错误处理 ### 定义成功标准 #### 如何知道你的 skill 是否有效？ 这些是理想目标 ?? 粗略的基准而不是精确的阈值。追求严谨但接受会有基于感觉的评估元素。我们正在积极开发更强大的测量指导和工具。 #### 定量指标 **Skill 在 90% 的相关查询上触发** - 如何测量：运行 10-20 个应该触发你的 skill 的测试查询。跟踪它自动加载的次数与需要显式调用的次数。 **在 X 次工具调用中完成工作流** - 如何测量：比较启用和不启用 skill 的相同任务。计算工具调用和消耗的总 tokens。 **每个工作流 0 次失败的 API 调用** - 如何测量：在测试运行期间监控 MCP 服务器日志。跟踪重试率和错误代码。 #### 定性指标 **用户无需提示 Claude 下一步** - 如何评估：在测试期间，注意你需要重定向或澄清的频率。向 beta 用户征求反馈。 **工作流无需用户更正即可完成** - 如何评估：运行相同请求 3-5 次。比较输出的结构一致性和质量。 **跨会话的一致结果** - 如何评估：新用户能否在第一次尝试时以最少的指导完成任务？ ### 技术要求 #### 文件结构 ``` 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 Frontmatter：最重要的部分 YAML frontmatter 是 Claude 决定是否加载你的 skill 的方式。把这个做对。 #### 最小必需格式 ```yaml --- name: your-skill-name description: ?? skill ???????????????????? --- ``` 这就是你开始所需的全部。 #### 字段要求 **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 ``` #### 安全限制 **Frontmatter 中禁止**： - XML 尖括号（< >） - 名称中带有"claude"或"anthropic"的 skills（保留） 为什么：Frontmatter 出现在 Claude 的系统提示中。恶意内容可能注入指令。 ### 编写有效的 Skills #### Description 字段 根据 Anthropic 的工程博客："这些元数据...提供足够的信息让 Claude 知道何时应该使用每个 skill，而无需将所有内容加载到上下文中。" 这是渐进式披露的第一级。 **结构**： ``` [它做什么] + [何时使用它] + [关键功能] ``` **良好描述的示例**： ✅ **好 ?? 具体且可操作** ```yaml description: 分析 Figma 设计文件并生成开发者交接文档。当用户上传 .fig 文件、询问"设计规格"、"组件文档"或"设计到代码交接"时使用。 ``` ✅ **好 ?? 包含触发短语** ```yaml description: 管理 Linear 项目工作流，包括冲刺规划、任务创建和状态跟踪。当用户提到"冲刺"、"Linear 任务"、"项目规划"或要求"创建工单"时使用。 ``` ✅ **好 ?? 清晰的价值主张** ```yaml description: PayFlow 的端到端客户入职工作流。处理账户创建、支付设置和订阅管理。当用户说"入职新客户"、"设置订阅"或"创建 PayFlow 账户"时使用。 ``` **不良描述的示例**： ❌ **太模糊** ```yaml description: 帮助处理项目。 ``` ❌ **缺少触发器** ```yaml description: 创建复杂的多页文档系统。 ``` ❌ **太技术化，没有用户触发器** ```yaml description: 实现具有层次关系的 Project 实体模型。 ``` #### 编写主要指令 在 frontmatter 之后，用 Markdown 编写实际指令。 **推荐结构**： 为你的 skill 调整此模板。用你的特定内容替换括号部分。 ````markdown --- name: your-skill description: [???????????] --- # Your Skill Name ## 指令 ### 步骤 1：[第一个主要步骤] 清楚解释发生了什么。 示例： ```bash python scripts/fetch_data.py --project-id PROJECT_ID ``` ```` 预期输出：[描述成功是什么样子] ### 步骤 2：[第二个主要步骤] （根据需要添加更多步骤） ## 示例 ### 示例 1：[常见场景] 用户说："设置新的营销活动" 操作： 1. 通过 MCP 获取现有活动 2. 使用提供的参数创建新活动 结果：活动已创建，带有确认链接 （根据需要添加更多示例） ## 故障排除 ### 错误：[常见错误消息] 原因：[为什么会发生] 解决方案：[如何修复] （根据需要添加更多错误案例） ```` #### 指令的最佳实践 **具体且可操作** ✅ **好**： ```markdown 运行 `python scripts/validate.py --input {filename}` 检查数据格式。 如果验证失败，常见问题包括： - 缺少必需字段（将它们添加到 CSV） - 无效的日期格式（使用 YYYY-MM-DD） ```` ❌ **不好**： ```markdown 在继续之前验证数据。 ``` **包含错误处理** ```markdown ## 常见问题 ### MCP 连接失败 如果你看到"连接被拒绝"： 1. 验证 MCP 服务器正在运行：检查设置 > 扩展 2. 确认 API 密钥有效 3. 尝试重新连接：设置 > 扩展 > [你的服务] > 重新连接 ``` **清楚地引用捆绑资源** ```markdown 在编写查询之前，请查阅 `references/api-patterns.md` 以获取： - 速率限制指导 - 分页模式 - 错误代码和处理 ``` **使用渐进式披露** 保持 SKILL.md 专注于核心指令。将详细文档移至 `references/` 并链接到它。（有关三级系统如何工作，请参阅核心设计原则。） ## 测试与迭代 Skills 可以根据你的需求在不同的严格程度上进行测试： - **Claude.ai 中的手动测试** - 直接运行查询并观察行为。快速迭代，无需设置。 - **Claude Code 中的脚本测试** - 自动化测试用例，以便在更改之间进行可重复验证。 - **通过 skills API 进行程序化测试** - 构建针对定义的测试集系统运行的评估套件。 选择与你的质量要求和 skill 可见性相匹配的方法。小团队内部使用的 skill 与部署给数千企业用户的 skill 有不同的测试需求。 > 💡 **专业提示：在扩展之前迭代单个任务** > > 我们发现最有效的 skill 创建者会迭代单个具有挑战性的任务，直到 Claude 成功，然后将获胜的方法提取到 skill 中。这利用了 Claude 的上下文学习，并提供比广泛测试更快的信号。一旦你有了一个工作基础，就扩展到多个测试用例以获得覆盖率。 ### 推荐的测试方法 基于早期经验，有效的 skills 测试通常涵盖三个领域： #### 1. 触发测试 **目标**：确保你的 skill 在正确的时间加载。 **测试用例**： - ✅ 在明显任务上触发 - ✅ 在改述请求上触发 - ❌ 不在不相关主题上触发 **示例测试套件**： 应该触发： - "帮我设置一个新的 ProjectHub 工作区" - "我需要在 ProjectHub 中创建一个项目" - "为 Q4 规划初始化一个 ProjectHub 项目" 不应该触发： - "旧金山的天气如何？" - "帮我写 Python 代码" - "创建一个电子表格"（除非 ProjectHub skill 处理表格） #### 2. 功能测试 **目标**：验证 skill 产生正确的输出。 **测试用例**： - 生成有效输出 - API 调用成功 - 错误处理有效 - 覆盖边缘情况 **示例**： ``` 测试：创建包含 5 个任务的项目 给定：项目名称"Q4 规划"，5 个任务描述 当：Skill 执行工作流 那么： - 在 ProjectHub 中创建项目 - 创建 5 个具有正确属性的任务 - 所有任务链接到项目 - 无 API 错误 ``` #### 3. 性能比较 **目标**：证明 skill 相对于基线改进了结果。 使用定义成功标准中的指标。以下是比较可能的样子。 **基线比较**： ``` 没有 skill： - 用户每次都提供指令 - 15 次来回消息 - 3 次失败的 API 调用需要重试 - 消耗 12?000 tokens ``` ``` 有 skill： - 自动工作流执行 - 仅 2 个澄清问题 - 0 次失败的 API 调用 - 消耗 6?000 tokens ``` ### 使用 skill-creator skill skill-creator skill - 可通过 Claude.ai 的插件目录获得或下载用于 Claude Code - 可以帮助你构建和迭代 skills。如果你有一个 MCP 服务器并知道你的前 2-3 个工作流，你可以在一次会议中构建和测试一个功能性 skill - 通常在 15-30 分钟内。 **创建 skills**： - 从自然语言描述生成 skills - 生成格式正确的带有 frontmatter 的 SKILL.md - 建议触发短语和结构 **审查 skills**： - 标记常见问题（模糊描述、缺少触发器、结构问题） - 识别潜在的过度/不足触发风险 - 根据 skill 的既定目的建议测试用例 **迭代改进**： - 使用你的 skill 并遇到边缘情况或失败后，将这些示例带回 skill-creator - 示例："使用此聊天中识别的问题和解决方案来改进 skill 如何处理 [特定边缘情况]" **使用方法**： ``` "使用 skill-creator skill 帮我为 [你的用例] 构建一个 skill" ``` 注意：skill-creator 帮助你设计和完善 skills，但不执行自动化测试套件或产生定量评估结果。 ### 基于反馈的迭代 Skills 是活文档。计划根据以下内容进行迭代： **触发不足的信号**： - Skill 在应该加载时不加载 - 用户手动启用它 - 关于何时使用它的支持问题 解决方案：向描述添加更多细节和细微差别 - 这可能包括关键字，特别是技术术语 **过度触发的信号**： - Skill 为不相关的查询加载 - 用户禁用它 - 对目的感到困惑 解决方案：添加负面触发器，更具体 **执行问题**： - 结果不一致 - API 调用失败 - 需要用户更正 解决方案：改进指令，添加错误处理 解决方案：改进指令，添加错误处理 ## 分发与共享 Skills 使你的 MCP 集成更加完整。当用户比较连接器时，那些带有 skills 的连接器提供了更快的价值路径，使你比仅 MCP 的替代方案更具优势。 ### 当前分发模型（2026 年 1 月） #### 个人用户如何获取 skills 1. 下载 skill 文件夹 2. 压缩文件夹（如果需要） 3. 通过设置 > 功能 > Skills 上传到 Claude.ai 4. 或放置在 Claude Code skills 目录中 #### 组织级别的 skills - 管理员可以在工作区范围内部署 skills（2025 年 12 月 18 日发布） - 自动更新 - 集中管理 ### 开放标准 我们已将 Agent Skills 发布为开放标准。像 MCP 一样，我们相信 skills 应该可以跨工具和平台移植 - 无论你使用 Claude 还是其他 AI 平台，相同的 skill 都应该有效。也就是说，某些 skills 旨在充分利用特定平台的功能；作者可以在 skill 的兼容性字段中注明这一点。我们一直在与生态系统成员就该标准进行合作，我们对早期采用感到兴奋。 ### 通过 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 需要代码执行工具 beta，它提供 skills 运行所需的安全环境。 有关实现详细信息，请参阅： - Skills API 快速入门 - 创建自定义 skills - AI ??? SDK 中的 Skills ### 今天推荐的方法 首先在 GitHub 上托管你的 skill，使用公共仓库、清晰的 README（供人类访问者使用 - 这与你的 skill 文件夹分开，不应包含 README.md）和带有屏幕截图的示例用法。然后在你的 MCP 文档中添加一个部分，链接到 skill，解释为什么一起使用两者有价值，并提供快速入门指南。 #### 1. 在 GitHub 上托管 - 开源 skills 的公共仓库 - 带有安装说明的清晰 README - 示例用法和屏幕截图 #### 2. 在你的 MCP 仓库中记录 - 从 MCP 文档链接到 skills - 解释一起使用两者的价值 - 提供快速入门指南 #### 3. 创建安装指南 ```markdown ## 安装 [你的服务] skill 1. 下载 skill： - 克隆仓库：`git clone https://github.com/yourcompany/skills` - 或从 Releases 下载 ZIP 2. 在 Claude 中安装： - 打开 Claude.ai > 设置 > Skills - 点击"上传 skill" - 选择 skill 文件夹（压缩） 3. 启用 skill： - 打开 [你的服务] skill - 确保你的 MCP 服务器已连接 4. 测试： - 询问 Claude："在 [你的服务] 中设置一个新项目" ``` ### 定位你的 skill 你如何描述你的 skill 决定了用户是否理解其价值并实际尝试它。在撰写关于你的 skill 的内容时 - 在你的 README、文档或营销中 - 请记住这些原则。 #### 关注结果，而不是功能 ✅ **好**： ``` "ProjectHub skill 使团队能够在几秒钟内设置完整的项目工作区 ?? 包括页面、数据库和模板 ?? 而不是花 30 分钟进行手动设置。" ``` ❌ **不好**： ``` "ProjectHub skill 是一个包含 YAML frontmatter 和 Markdown 指令的文件夹，它调用我们的 MCP 服务器工具。" ``` #### 突出 MCP + skills 的故事 ``` "我们的 MCP 服务器让 Claude 访问你的 Linear 项目。我们的 skills 教 Claude 你团队的冲刺规划工作流。它们一起实现 AI 驱动的项目管理。" ``` ## 模式与故障排除 这些模式来自早期采用者和内部团队创建的 skills。它们代表我们看到的有效的常见方法，而不是规定性模板。 ### 选择你的方法：问题优先 vs. 工具优先 把它想象成家得宝。你可能带着一个问题走进去 -"我需要修理厨房橱柜"- 员工会为你指出正确的工具。或者你可能挑选一个新钻头并询问如何将其用于你的特定工作。 Skills 以同样的方式工作： - **问题优先**："我需要设置一个项目工作区" 你的 skill 以正确的顺序编排正确的 MCP 调用。用户描述结果；skill 处理工具。 - **工具优先**："我已连接 Notion MCP" 你的 skill 教 Claude 最佳工作流和最佳实践。用户有访问权限；skill 提供专业知识。 大多数 skills 倾向于一个方向。知道哪种框架适合你的用例有助于你选择下面的正确模式。 ### 模式 1：顺序工作流编排 **使用时机**：你的用户需要按特定顺序执行多步骤流程。 **示例结构**： ```markdown ## 工作流：入职新客户 ### 步骤 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 协调 **使用时机**：工作流跨越多个服务。 **示例：设计到开发交接** ```markdown ## 阶段 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：迭代改进 **使用时机**：输出质量通过迭代改进。 **示例：报告生成** ```markdown ## 迭代报告创建 ### 初始草稿 1. 通过 MCP 获取数据 2. 生成第一份草稿报告 3. 保存到临时文件 ### 质量检查 1. 运行验证脚本：`scripts/check_report.py` 2. 识别问题： - 缺少部分 - 格式不一致 - 数据验证错误 ### 改进循环 1. 解决每个识别的问题 2. 重新生成受影响的部分 3. 重新验证 4. 重复直到达到质量阈值 ### 最终确定 1. 应用最终格式 2. 生成摘要 3. 保存最终版本 ``` **关键技术**： - 明确的质量标准 - 迭代改进 - 验证脚本 - 知道何时停止迭代 ### 模式 4：上下文感知工具选择 **使用时机**：相同结果，根据上下文使用不同工具。 **示例：文件存储** ```markdown ## 智能文件存储 ### 决策树 1. 检查文件类型和大小 2. 确定最佳存储位置： - 大文件（>10MB）：使用云存储 MCP - 协作文档：使用 Notion/Docs MCP - 代码文件：使用 GitHub MCP - 临时文件：使用本地存储 ### 执行存储 基于决策： - 调用适当的 MCP 工具 - 应用特定于服务的元数据 - 生成访问链接 ### 向用户提供上下文 解释为什么选择该存储 ``` **关键技术**： - 清晰的决策标准 - 后备选项 - 选择的透明度 ### 模式 5：领域特定智能 **使用时机**：你的 skill 添加超越工具访问的专业知识。 **示例：金融合规** ```markdown ## 符合合规的支付处理 ### 处理前（合规检查） 1. 通过 MCP 获取交易详情 2. 应用合规规则： - 检查制裁名单 - 验证管辖区许可 - 评估风险级别 3. 记录合规决策 ### 处理 如果合规通过： - 调用支付处理 MCP 工具 - 应用适当的欺诈检查 - 处理交易 否则： - 标记以供审查 - 创建合规案例 ### 审计跟踪 - 记录所有合规检查 - 记录处理决策 - 生成审计报告 ``` **关键技术**： - 逻辑中嵌入的领域专业知识 - 行动前的合规 - 全面的文档 - 清晰的治理 ### 故障排除 #### Skill 无法上传 **错误："在上传的文件夹中找不到 SKILL.md"** 原因：文件名不完全是 SKILL.md 解决方案： - 重命名为 SKILL.md（区分大小写） - 验证：`ls -la` 应显示 SKILL.md **错误："无效的 frontmatter"** 原因：YAML 格式问题 常见错误： ```yaml # 错误 ?? 缺少分隔符 name: my-skill description: ???? skill ????? # 错误 ?? 未闭合引号 name: my-skill description: "???? skill ????? # 正确 --- name: my-skill description: ???? skill ????? --- ``` **错误："无效的 skill 名称"** 原因：名称有空格或大写 ```yaml # 错误 name: My Cool Skill # 正确 name: my-cool-skill ``` #### Skill 不触发 **症状**：Skill 从不自动加载 修复：修改你的 description 字段。有关好/坏示例，请参阅 Description 字段。 **快速检查清单**： - 是否太通用？（"帮助处理项目"不起作用） - 是否包含用户实际会说的触发短语？ - 如果适用，是否提及相关文件类型？ **调试方法**： 询问 Claude："你什么时候会使用 [skill 名称] skill？" Claude 会引用描述。根据缺少的内容进行调整。 #### Skill 触发过于频繁 **症状**：Skill 为不相关的查询加载 **解决方案**： 1. **添加负面触发器** ```yaml description: CSV 文件的高级数据分析。用于统计建模、回归、聚类。不要用于简单的数据探索（改用 data-viz skill）。 ``` 2. **更具体** ```yaml # 太宽泛 description: 处理文档 # 更具体 description: 处理 PDF 法律文档以进行合同审查 ``` 3. **澄清范围** ```yaml description: 电子商务的 PayFlow 支付处理。专门用于在线支付工作流，而不是一般财务查询。 ``` #### MCP 连接问题 **症状**：Skill 加载但 MCP 调用失败 **检查清单**： 1. 验证 MCP 服务器已连接 - Claude.ai：设置 > 扩展 > [你的服务] - 应显示"已连接"状态 2. 检查身份验证 - API 密钥有效且未过期 - 授予适当的权限/范围 - OAuth tokens 已刷新 3. 独立测试 MCP - 要求 Claude 直接调用 MCP（不使用 skill） - "使用 [服务] MCP 获取我的项目" - 如果失败，问题在于 MCP 而不是 skill 4. 验证工具名称 - Skill 引用正确的 MCP 工具名称 - 检查 MCP 服务器文档 - 工具名称区分大小写 #### 指令未遵循 **症状**：Skill 加载但 Claude 不遵循指令 **常见原因**： 1. **指令过于冗长** - 保持指令简洁 - 使用项目符号和编号列表 - 将详细参考移至单独的文件 2. **指令被埋没** - 将关键指令放在顶部 - 使用 ## 重要 或 ## 关键 标题 - 如果需要，重复关键点 3. **模糊的语言** ❌ **不好** ``` 确保正确验证事物 ``` ✅ **好** ``` 关键：在调用 create_project 之前，验证： - 项目名称非空 - 至少分配一名团队成员 - 开始日期不在过去 ``` 高级技术：对于关键验证，考虑捆绑一个以编程方式执行检查的脚本，而不是依赖语言指令。代码是确定性的；语言解释不是。有关此模式的示例，请参阅 Office skills。 4. **模型"懒惰"** 添加明确的鼓励： ```markdown ## 性能说明 - 花时间彻底完成此操作 - 质量比速度更重要 - 不要跳过验证步骤 ``` 注意：将此添加到用户提示比在 SKILL.md 中更有效 #### 大上下文问题 **症状**：Skill 似乎很慢或响应降级 **原因**： - Skill 内容太大 - 同时启用太多 skills - 加载所有内容而不是渐进式披露 **解决方案**： 1. **优化 SKILL.md 大小** - 将详细文档移至 references/ - 链接到引用而不是内联 - 保持 SKILL.md 少于 5,000 字 2. **减少启用的 skills** - 评估是否同时启用了超过 20-50 个 skills - 建议选择性启用 - 考虑相关功能的 skill"包" ## 资源与参考 如果你正在构建你的第一个 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 - 可以从描述生成 skills - 审查并提供建议 - 使用："使用 skill-creator 帮我构建一个 skill" **验证**： - skill-creator 可以评估你的 skills - 询问："审查此 skill 并提出改进建议" ### 获取支持 **技术问题**： - 一般问题：Claude Developers Discord 的社区论坛 **错误报告**： - GitHub Issues: anthropics/skills/issues - 包括：Skill 名称、错误消息、重现步骤 ### 参考 A：快速检查清单 在上传之前和之后使用此检查清单验证你的 skill。如果你想更快开始，请使用 skill-creator skill 生成你的第一个草稿，然后运行此列表以确保你没有遗漏任何内容。 **开始之前** - [ ] 确定了 2-3 个具体用例 - [ ] 确定了工具（内置或 MCP） - [ ] 审查了本指南和示例 skills - [ ] 计划了文件夹结构 **开发期间** - [ ] 文件夹以 kebab-case 命名 - [ ] SKILL.md 文件存在（精确拼写） - [ ] YAML frontmatter 有 --- 分隔符 - [ ] name 字段：kebab-case，无空格，无大写 - [ ] description 包括什么和何时 - [ ] 任何地方都没有 XML 标签（< >） - [ ] 指令清晰且可操作 - [ ] 包含错误处理 - [ ] 提供了示例 - [ ] 清楚地链接了引用 **上传前** - [ ] 在明显任务上测试触发 - [ ] 在改述请求上测试触发 - [ ] 验证不在不相关主题上触发 - [ ] 功能测试通过 - [ ] 工具集成有效（如果适用） - [ ] 压缩为 .zip 文件 **上传后** - [ ] 在真实对话中测试 - [ ] 监控触发不足/过度 - [ ] 收集用户反馈 - [ ] 迭代描述和指令 - [ ] 更新元数据中的版本 ### 参考 B：YAML Frontmatter **必需字段** ```yaml --- name: skill-name-in-kebab-case description: ?????????????????????? --- ``` **所有可选字段** ```yaml --- 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 类型（字符串、数字、布尔值、列表、对象） - 自定义元数据字段 - 长描述（最多 1024 个字符） 禁止： - XML 尖括号（< >）- 安全限制 - YAML 中的代码执行（使用安全 YAML 解析） - 以"claude"或"anthropic"前缀命名的 Skills（保留） ### 参考 C：完整 Skill 示例 有关演示本指南中模式的完整、生产就绪的 skills： - 文档 Skills - PDF、DOCX、PPTX、XLSX 创建 - 示例 Skills - 各种工作流模式 - 合作伙伴 Skills 目录 - 查看来自 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等各种合作伙伴的 skills 这些仓库保持最新，并包含本文涵盖之外的其他示例。克隆它们，为你的用例修改它们，并将它们用作模板。 --- **原文链接**：[The Complete Guide to Building Skills for Claude](https://www.anthropic.com/) **发布日期**：2026 年 1 月 **标签**：#Claude #Skills #AI智能体 #MCP #工作流自动化