2026年[译] Claude Skill 构建完全指南

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

引言
第一章：基础知识
第二章：规划与设计
第三章：测试与迭代
第四章：分发与共享
第五章：模式与故障排查
第六章：资源与参考
附录 A：快速检查清单
附录 B：YAML 前置元数据
附录 C：完整 Skill 示例

Skill 是以文件夹的形式打包的一组指令，用来教会 Claude 怎么处理特定任务或工作流。这是针对自己需求定制 Claude 最直接的方式之一。每次对话都要重新解释偏好、流程和背景知识太低效了，而用 Skill 一次性教会 Claude，之后每次都能直接用。

Skill 非常擅长处理高频、重复的工作流。比如，你可以用它来根据需求文档输出前端代码、基于统一的分析框架做调研、套用团队规范生成文档，或者串联起复杂的多步流程。它们能与 Claude 内置的代码执行、文档创建等能力无缝配合。对于做 MCP 集成的开发者来说，Skill 是额外一层，把原始的工具访问变成可靠、可复用的工作流。

本指南涵盖了从规划设计到测试与分发环节构建高效 Skill 所需的全部知识。不管你是为自己、团队还是开发者社区构建 Skill，都能在本指南中找到实用的设计模式与真实案例。

你将学到：
- Skill 结构的技术要求和**实践
- 独立 Skill 和 MCP 增强型工作流的设计模式
- 在不同场景下实际有效的做法
- 如何测试、迭代和分发你的 Skill

适合人群：
- 希望 Claude 持续遵循特定工作流的开发者
- 想让 Claude 记住自己偏好和流程的高级用户
- 希望在团队或组织里统一 Claude 工作方式的人

本指南的两条路径

构建独立 Skill，重点看基础知识、规划与设计，以及类别 1-2。增强 MCP 集成，看「Skill + MCP」章节和类别 3。两条路径的技术要求是一样的，按自己用例选读就行。

看完本指南，你应该能在一次坐下来的时间内做出一个可运行的 Skill。用 skill-creator 构建并测试第一个 Skill 大概需要 15-30 分钟。

适合人群：
- 希望 Claude 持续遵循特定工作流的开发者
- 想让 Claude 记住自己偏好和流程的高级用户
- 希望在团队或组织里统一 Claude 工作方式的人

本指南的两条路径

看完本指南，你应该能在一次坐下来的时间内做出一个可运行的 Skill。用 skill-creator 构建并测试第一个 Skill 大概需要 15-30 分钟。

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

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

渐进式披露（Progressive Disclosure）

Skill 采用三级结构：

第一级（YAML 前置元数据）：始终加载到 Claude 的系统提示里。只提供足够的信息让 Claude 判断是否要用这个 Skill，不会把所有内容都塞进上下文。
第二级（SKILL.md 正文）：Claude 判断 Skill 与当前任务相关时才加载，包含完整的指令和说明。
第三级（链接文件）：Skill 目录里的附加文件，Claude 可以按需去查。

这种分级结构在保持专业能力的同时，把 token 消耗控制到最低。

译者注：官方给过具体数字——Level 1 元数据大约只消耗 ~100 tokens，Level 2 的 SKILL.md 正文建议控制在 5,000 tokens 以内，Level 3 的文件只要没被读取就不占任何 token。这意味着你装几十个 Skill 也不会撑爆上下文，性能损耗主要来自 Level 2 被触发的那一刻。

可组合性（Composability）

Claude 可以同时加载多个 Skill。你的 Skill 要能和其他 Skill 配合运行，不要假设自己是唯一可用的。

可移植性（Portability）

Skill 在 Claude.ai、Claude Code 和 API 上行为完全一致。做一次，所有平台都能用——前提是运行环境支持该 Skill 所需的依赖。

💡 构建不依赖 MCP 的独立 Skill？跳到「规划与设计」章节，这部分随时可以回来看。

如果你已经有一个跑起来的 MCP 服务器，最难的部分已经完成了。Skill 是叠在上面的知识层——把你已知的工作流和**实践固化下来，让 Claude 每次都能稳定地执行。

厨房类比

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

Skill 提供食谱：一步步说明怎么做出有价值的成果。

两者结合，用户不用自己摸索每个步骤就能完成复杂任务。

两者如何分工：

为什么 MCP 用户需要 Skill

动手写之前，先确定你的 Skill 要支持哪 2-3 个具体用例。

好的用例定义示例：

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

Anthropic 观察到三类常见用例：

类别 1：文档与资产创建

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

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

「创建具有高设计质量的独特、生产级前端界面。在构建 Web 组件、页面、制品、海报或应用时使用。」

类别 2：工作流自动化

用途： 需要固定方法论的多步骤流程，包括跨多个 MCP 服务器的协调。

真实案例： skill-creator skill

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

类别 3：MCP 增强

用途： 在 MCP 服务器提供的工具访问之上，加一层工作流指导。

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

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

怎么判断 Skill 是否有效？

下面是一些参考目标——是粗略基准，不是精确阈值。追求严谨，但也接受有主观判断的部分。我们正在积极开发更完善的度量工具。

量化指标：

Skill 在 90% 的相关查询中触发
测量方法：运行 10-20 个应该触发 Skill 的测试查询，追踪自动加载与需要手动调用的比例。
在 X 次工具调用内完成工作流
测量方法：对比开启和关闭 Skill 时完成同一任务的情况，统计工具调用次数和消耗的总 token 数。
每个工作流 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——Skill 文件夹和仓库根目录是两回事，别搞混了。详见「分发与共享」章节。

YAML 前置元数据决定了 Claude 是否加载你的 Skill，必须写好。

最简必要格式：

--- name: your-skill-name description: 它做什么。当用户询问 [具体短语] 时使用。 ---

这就是起步所需的全部内容。

字段要求

name（必须）：
- 只用 kebab-case
- 不能有空格或大写
- 和文件夹名称保持一致

description（必须）：
- 必须同时写清楚：
- Skill 做什么
- 什么时候用（触发条件）
- 不超过 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

安全限制

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

description 字段

根据 Anthropic 工程博客：「这些元数据……只提供足够的信息让 Claude 判断何时该用这个 Skill，而不会把全部内容加载到上下文中。」这是渐进式披露的第一级。

译者注：description 字段决定了 Skill 的「可发现性」，是整个文件里最值得花时间的地方。它写得好不好，直接决定 Skill 会不会在对的时机被触发。很多人把大量精力放在 SKILL.md 正文，却随便写了两个字的 description——这是典型的本末倒置。

结构：

[它做什么] + [何时用] + [核心能力]

好的 description 示例：

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

不好的 description 示例：

# 太模糊 description: 帮助处理项目。 # 缺少触发条件 description: 创建复杂的多页文档系统。 # 太技术化，没有用户会说的词 description: 实现具有层级关系的 Project 实体模型。

编写主体指令

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

推荐结构：

--- name: your-skill description: [...] --- # Skill 名称 指令 第一步：[第一个主要步骤] 清晰说明要做什么。 示例： bash python scripts/fetch_data.py --project-id PROJECT_ID 预期输出：[描述成功是什么样子] （按需添加更多步骤） 示例 示例 1：[常见场景] 用户说：「建立一个新的营销活动」 操作： 1. 通过 MCP 获取现有活动 2. 用提供的参数创建新活动 结果：活动已创建，附带确认链接 故障排查 错误：[常见错误信息] 原因：[为什么会出现] 解决方案：[怎么修]

指令**实践

具体且可操作

✅ 好的：

运行 `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/ 里并加链接。（参见核心设计原则，了解三级结构的工作方式。）

Skill 的测试可以按你需要的严格程度来：

在 Claude.ai 里手动测试：直接跑查询，看行为。迭代最快，不需要任何配置。
在 Claude Code 里写脚本测试：自动化测试用例，变更时可以重复验证。
通过 Skills API 编程测试：构建评估套件，针对预设测试集系统性地跑。

按你的质量要求和 Skill 的受众规模选合适的方式。给小团队内部用的 Skill，和部署给几千名企业用户的 Skill，测试需求差距很大。

有效做法：先在一个任务上迭代，再扩展范围

实践表明，做 Skill 最高效的方式是先盯着一个有挑战性的任务反复跑，跑通之后再把有效的方法提炼成 Skill。这充分利用了 Claude 的上下文学习能力，比大范围撒网测试得到信号要快得多。有了能跑的基础版之后，再扩展测试用例来提高覆盖率。

译者注：我自己也是这么干的——先找一个卡点最多的任务反复折腾，而不是一上来就写一堆覆盖场景。把 Claude 真正搞定一件难事的过程记录下来，比凭空设计测试用例靠谱得多。

根据早期实践经验，有效的 Skill 测试通常覆盖三个方面：

1. 触发测试

目标： 确保 Skill 在对的时机加载。

示例测试套件：

应该触发： - 「帮我建立一个新的 ProjectHub 工作区」 - 「我需要在 ProjectHub 中创建一个项目」 - 「为 Q4 规划初始化一个 ProjectHub 项目」 不应该触发： - 「旧金山今天天气怎么样？」 - 「帮我写 Python 代码」 - 「创建一个电子表格」（除非 ProjectHub Skill 处理表格）

2. 功能测试

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

示例：

测试：创建包含 5 个任务的项目 前提：项目名称「Q4 Planning」，5 个任务描述 执行：Skill 运行工作流 预期结果： - 在 ProjectHub 中创建了项目 - 创建了 5 个属性正确的任务 - 所有任务都挂在项目下 - 无 API 错误

3. 性能对比

目标： 验证 Skill 相比没有 Skill 的基线有实际提升。

用「定义成功标准」里的指标来量化。对比示例：

基线对比： 没有 Skill： - 用户每次都要手动给指令 - 15 轮来回对话 - 3 次 API 调用失败需要重试 - 消耗 12,000 个 token 有了 Skill： - 自动执行工作流 - 仅 2 个澄清问题 - 0 次 API 调用失败 - 消耗 6,000 个 token

skill-creator 在 Claude.ai 的插件目录里，也可以下载用于 Claude Code，帮你构建和打磨 Skill。如果你有 MCP 服务器，清楚自己的 2-3 个核心工作流，通常一次坐下来（15-30 分钟）就能做出一个可用的 Skill。

译者注：skill-creator 本身也是一个 Skill，在 Claude.ai 的插件目录里直接搜就能找到。Claude Code 用户可以把它下载到本地 skills 目录。API 用户也能用，通过 /v1/skills 端点上传后直接调用。

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

审查 Skill：
- 找出常见问题（描述模糊、缺少触发词、结构有问题）
- 识别可能过度触发或触发不足的风险
- 根据 Skill 的目的建议测试用例

迭代改进：
- 用 Skill 过程中遇到边界情况或失败，把这些案例带回 skill-creator
- 示例：「用这次对话中发现的问题和解决方案，改进 Skill 处理 [特定边界情况] 的方式」

用法：

「使用 skill-creator Skill 帮我为 [你的用例] 构建一个 Skill」

注意：skill-creator 帮你设计和优化 Skill，但不跑自动化测试套件，也不产出量化评估结果。

Skill 是活文档，要根据实际使用中的信号持续调整：

触发太少：
- 该加载时没有加载
- 用户要手动启用
- 收到「这个 Skill 什么时候用」的支持问题

解决：在 description 里补充更多细节和关键词，特别是技术术语。

触发太多：
- 在无关查询时加载
- 用户关掉了它
- 用户搞不清楚它是干嘛的

解决：加负面触发词，把描述写得更精确。

执行有问题：
- 结果不稳定
- API 调用失败
- 需要用户来纠正

解决：改进指令，加错误处理。

有了 Skill，你的 MCP 集成才算完整。用户在选择工具时，带 Skill 的方案能更快跑通流程，这是纯 MCP 方案711 给不了的。

个人用户的安装方式：
1. 下载 Skill 文件夹
2. 压缩成 zip（如果还没压缩的话）
3. 打开 Claude.ai「设置 > 能力 > Skills」上传
4. 或者直接放到 Claude Code 的 Skills 目录里

组织级部署：
- 管理员可以全工作区一键部署 Skill（2025 年 12 月 18 日上线）
- 支持自动更新和集中管理

我们把 Agent Skills 作为开放标准发布了。和 MCP 一样，Skill 应该能跨工具、跨平台用——同一个 Skill 无论在 Claude 还是其他 AI 平台上都应该能跑。当然，有些 Skill 是专门为某个平台设计的，作者可以在 compatibility 字段里说明。这个标准正在和生态里的伙伴一起推进，目前看来采用情况挺不错。

译者注：「开放标准」意味着你现在给 Claude 写的 Skill，理论上未来可以直接用在其他 AI 平台上，不用重写。这和 MCP 的设计思路是一脉相承的——Anthropic 在有意识地构建可移植的基础设施。

如果你在用代码调用 Skill——比如构建应用、Agent 或自动化流水线——API 提供了直接管理和执行 Skill 的能力。

核心接口：
- /v1/skills 端点，用来列出和管理 Skill
- 通过 container.skills 参数把 Skill 挂到 Messages API 请求上
- 在 Claude Console 里做版本管理
- 配合 Claude Agent SDK 构建自定义 Agent

什么时候用 API，什么时候用 Claude.ai：

注意：API 里的 Skill 依赖 Code Execution Tool 的 Beta 版，这是 Skill 运行需要的安全环境。目前还在 Beta，正式用之前建议先确认自己账号有这个权限。

译者注：通过 API 使用 Skill 有一个很重要的限制——没有网络访问。Skill 在 API 里跑的沙箱环境里，不能调外部 API、不能访问互联网。但在 Claude.ai 和 Claude Code 里是有网络访问的（Claude Code 甚至是完整的本地网络权限）。如果你的 Skill 依赖外部接口，部署到 API 环境之前要确认这一点。

先在 GitHub 上建一个公开仓库，写好 README（供人阅读——这跟 Skill 文件夹是分开的，Skill 文件夹里不放 README.md），加上带截图的使用示例。然后在你的 MCP 文档里加一节，链接过去，说清楚两者配合用的价值，并给个快速上手指南。

译者注：这套分发流程现在还比较手动，Anthropic 明显在逐步完善这块的基础设施。如果你在做面向团队内部的 Skill，可以直接走组织级部署，不用每个人手动安装；如果是开源给社区用，现在 GitHub + README 这套是最稳的路径。

译者注补充：有一个容易踩的坑——「组织级部署」目前只在 API 层面支持。Claude.ai 上的 Skill 是个人级的，即使是 Enterprise 账号，管理员也没办法统一给全组织推送 Skill，每个人必须自己上传。做企业内部工具的话，走 API + Agent SDK 那条路才能真正实现统一管理。

1. 放到 GitHub 上
- 开源 Skill 用公开仓库
- README 里写清楚怎么安装
- 加上使用示例和截图

2. 在 MCP 文档里记录
- 从 MCP 文档链接到 Skill
- 说清楚两者配合有什么好处
- 给个快速上手步骤

3. 写一份安装指南

 安装 [你的服务] 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 的方式，决定了用户有没有兴趣去试。写 README、文档或推广文案时，记住一点：

讲结果，别讲功能：

✅ 好的：

「ProjectHub Skill 让团队几秒内就能建好完整的项目工作区——页面、数据库、模板一起来——而不是手动捣鼓 30 分钟。」

❌ 没用的：

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

讲 MCP + Skill 的完整故事：

「我们的 MCP 服务器让 Claude 能访问你的 Linear 项目。我们的 Skill 教会 Claude 你团队的 Sprint 规划流程。两者结合，项目管理就交给 AI 了。」

这些模式来自早期用户和内部团队的实践，是我们观察到的有效做法，不是模板。

去五金店有两种方式——带着问题去（「我得修厨房橱柜」），让店员帮你找工具；或者先看上了一把新电钻，再想怎么用它干活。

Skill 也一样：

从问题出发：「我要建一个项目工作区」→ Skill 按顺序编排好 MCP 调用，用户说目标，Skill 搞定工具。
从工具出发：「我已经连了 Notion MCP」→ Skill 教会 Claude 怎么用这个工具，最优流程是什么。用户有权限，Skill 提供经验。

大多数 Skill 偏向其中一种。搞清楚你的场景更接近哪边，有助于选下面合适的模式。

适合场景： 用户需要按固定顺序完成多个步骤。

示例结构：

 工作流：入职新客户 第一步：创建账户 调用 MCP 工具：`create_customer` 参数：name, email, company 第二步：设置支付 调用 MCP 工具：`setup_payment_method` 等待：支付方式验证 第三步：创建订阅 调用 MCP 工具：`create_subscription` 参数：plan_id, customer_id（来自第一步） 第四步：发送欢迎邮件 调用 MCP 工具：`send_email` 模板：welcome_email_template

适合场景： 流程跨越多个服务。

示例：设计到开发的交接

 阶段 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. 附上资产链接和任务引用

适合场景： 输出质量需要多轮打磨。

示例：报告生成

 迭代报告创建 初稿 1. 通过 MCP 拉取数据 2. 生成第一版报告草稿 3. 保存到临时文件 质量检查 1. 运行验证脚本：`scripts/check_report.py` 2. 找出问题： - 缺少章节 - 格式不一致 - 数据校验失败 优化循环 1. 逐一解决发现的问题 2. 重新生成受影响的章节 3. 再次验证 4. 重复直到达到质量标准 最终确定 1. 应用最终格式 2. 生成摘要 3. 保存终版

适合场景： 目标相同，但用哪个工具取决于情况。

示例：文件存储

 智能文件存储 判断逻辑 1. 检查文件类型和大小 2. 选择最合适的存储位置： - 大文件（>10MB）：云存储 MCP - 协作文档：Notion/Docs MCP - 代码文件：GitHub MCP - 临时文件：本地存储 执行存储 按判断结果： - 调用对应的 MCP 工具 - 加上这个服务需要的元数据 - 生成访问链接 告诉用户 解释为什么选了这个存储方式

适合场景： 你的 Skill 不只是调工具，还带有专业判断。

示例：金融合规

 支付处理（含合规检查） 处理前（合规检查） 1. 通过 MCP 获取交易详情 2. 走合规规则： - 核查制裁名单 - 确认所在地区是否允许 - 评估风险等级 3. 记录合规决策 处理 合规通过： - 调用支付处理 MCP 工具 - 做欺诈检查 - 处理交易 未通过： - 标记待审查 - 建合规案例 审计追踪 - 记录每次合规检查 - 记录处理决策 - 生成审计报告

Skill 上传失败

「Could not find SKILL.md in uploaded folder」

文件名不对。重命名为 SKILL.md（大小写敏感），用 ls -la 确认一下。

「Invalid frontmatter」

YAML 格式有问题。常见错误：

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

错误 - 引号没闭合

正确

description: Does things

「Invalid skill name」

名字里有空格或大写：

# 错误 name: My Cool Skill

正确

Skill 不自动触发

描述是不是太泛？（「帮助处理项目」这种没用）
有没有用户真会说的触发短语？
涉及特定文件类型的话，有没有提到？

调试方法：直接问 Claude「你什么时候会用 [Skill 名称] 这个 Skill？」Claude 会把 description 复述给你，对比一下缺什么再调整。

Skill 触发太频繁

加负面触发词：

description: 用于 CSV 文件的高级数据分析。适合统计建模、回归、聚类。 不要用于简单数据探索（那用 data-viz Skill）。

描述更精确：

# 太宽泛 description: 处理文档 更好
 description: 处理 PDF 法律文件进行合同审查

限定范围：

description: PayFlow 电商支付处理。只用于在线支付流程， 一般金融问题不适用。

MCP 连接问题

Skill 加载了但 MCP 调用出错，按顺序排查：

确认 MCP 服务器已连接
- Claude.ai：设置 > 扩展 > [你的服务]，状态应显示「已连接」
- 检查认证
- API 密钥有没有过期，权限/范围是否正确，OAuth token 是否需要刷新
- 单独测试 MCP
- 让 Claude 不用 Skill 直接调用：「用 [服务] MCP 拉一下我的项目」
- 如果这步也失败，问题在 MCP 本身，不在 Skill
- 确认工具名称
- Skill 里引用的工具名和 MCP 文档一致吗？工具名区分大小写

Claude 不按指令来

指令写太长了

保持简洁，用列表和编号

详细参考资料放到独立文件

关键指令被埋了

重要的放最前面

用 重要 或 关键 这类标题

必要时重复关键点

表达含糊

# 差 确保正确验证相关内容 好
 关键：调用 create_project 之前，必须验证： 
          
    
             
             项目名称不能为空 
             至少要分配一名团队成员 
             开始日期不能是过去的日期

进阶做法： 关键验证逻辑如果直接写成脚本，比写语言指令可靠得多。代码结果是确定的，语言理解有偏差。Office Skill 里有这种做法的示例。

译者注：这个思路值得重视——越是核心的校验逻辑，越不该靠「说」来约束 Claude，而是直接用代码锁死。语言指令本质上是概率性的，脚本才是确定性的。

Claude 偷懒，加一段鼓励：

 注意 请认真完成，不要走捷径
 质量优先，速度其次
 验证步骤不能跳过

注意：这段话加在用户提示里比放在 SKILL.md 里更有效。原因很简单——用户消息离当前推理更近，Claude 更容易「听进去」。

Skill 变慢或质量下降

原因通常是：Skill 文件太大、同时开太多 Skill、没有用到渐进式披露导致全量加载。

解决方法：

精简 SKILL.md
- 详细文档移到 references/ 里，用链接引用
- SKILL.md 控制在 5,000 字以内
减少开启的 Skill 数量
同时开 20-50 个以上就要注意了
按需开启，别全开
相关功能可以打包成一个 Skill「合集」

第一次构建 Skill，先看**实践指南，API 文档用到时再查。

Anthropic 资源：
- **实践指南
- Skills 文档
- API 参考
- MCP 文档

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

公开 Skill 仓库：
- GitHub：anthropics/skills
- 包含 Anthropic 做的可以直接改用的 Skill

skill-creator Skill：
- 内置于 Claude.ai，也可以用于 Claude Code
- 能从描述直接生成 Skill
- 可以帮你审查和改进
- 用法：「用 skill-creator 帮我做一个 Skill」

验证：
- skill-creator 也可以评估已有的 Skill
- 直接问：「帮我审查一下这个 Skill，给点改进建议」

技术问题：
- Claude Developers Discord 社区论坛

发现 Bug：
- GitHub Issues：anthropics/skills/issues
- 提交时附上：Skill 名称、错误信息、复现步骤

上传前后用这个清单验一遍你的 Skill。想快速入门的话，可以先用 skill-creator Skill 生成第一版，再逐项检查有没有遗漏。

[ ] 确定了 2-3 个具体用例
[ ] 确定了需要哪些工具（内置或 MCP）
[ ] 看了本指南和示例 Skill
[ ] 想好文件夹结构

[ ] 文件夹名称用 kebab-case
[ ] 有 SKILL.md 文件（大小写要对）
[ ] YAML 前置元数据有 --- 分隔符
[ ] name 字段：kebab-case，无空格，无大写
[ ] description 说清楚「做什么」和「什么时候用」
[ ] 没有 XML 标签（< >）
[ ] 指令清晰可操作
[ ] 有错误处理
[ ] 有示例
[ ] 参考资源有清晰链接

[ ] 测试了明显相关的任务能否触发
[ ] 测试了换个说法的请求能否触发
[ ] 确认了无关话题不会触发
[ ] 功能测试通过
[ ] 工具集成正常（如果用了的话）
[ ] 已压缩成 .zip

[ ] 在真实对话里测试过
[ ] 留意过触发太多或太少的情况
[ ] 收集了用户反馈
[ ] 根据反馈调整了 description 和指令
[ ] metadata 里的版本号更新了

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

允许：

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

禁止：

XML 尖括号（< >）——安全限制

YAML 中的代码执行（使用安全 YAML 解析）

名称以「claude」或「anthropic」开头的 Skill（保留字）

完整的、可直接用于生产的 Skill 示例：

Document Skills：PDF、DOCX、PPTX、XLSX 创建
Example Skills：各种工作流模式
Partner Skills 目录：Asana、Atlassian、Canva、Figma、Sentry、Zapier 等合作伙伴的 Skill

这些仓库持续更新，示例比本指南里的更多。直接 clone 下来，按你的需求改，当模板用。