摘要：本文为Anthropic官方33页Claude Skills构建指南中文译版下篇，涵盖测试迭代、发布分享、五大设计模式与完整故障排查四大章节。详解如何用skill-creator工具做触发测试与对比测试，如何通过GitHub和MCP文档分发技能，以及顺序编排、多MCP协调、迭代优化等五种高频设计模式。附录含上传失败、触发异常、MCP连接、指令未遵守等全场景故障排查手册与快速上线检查清单。国内开发者可通过weelinking中转服务稳定访问Claude全系模型，落地企业级AI工作流。

关键词：Claude Skills测试、Skill发布教程、Claude Skill设计模式、MCP工作流协调、skill-creator工具、Claude故障排查、SKILL.md最佳实践、weelinking中转服务、Claude国内使用、AI工作流自动化

📋 段落导航

序号 章节 内容概要
一 第三章：测试与迭代 三种测试方法、skill-creator用法、迭代信号识别
二 第四章：发布与分享 分发方式、GitHub托管、安装指南模板
三 第五章：五大设计模式 顺序编排、多MCP协调、迭代优化等实战模式
四 完整故障排查手册 上传失败、不触发、过度触发、MCP断连等全场景
五 第六章：资源与参考 官方文档、示例仓库、获取支持渠道
六 附录：快速检查清单与YAML参考 上线前必过的完整检查项
七 其他文章推荐 相关往期好文链接

一、第三章：测试与迭代

你可以根据需要选择不同严格程度的测试方式：

  • 在 Claude.ai 里手动测试 — 直接跑查询，看行为。迭代快，零配置。
  • 在 Claude Code 里用脚本测试 — 自动化测试用例，每次改完都能跑一遍验证。
  • 通过技能 API 程序化测试 — 构建系统化的评估套件，针对预定义测试集运行。

按实际需要选。个人用的小技能和面向数千企业用户的技能，测试严格程度自然不一样。

💡 专业技巧：先把一个难题跑通，再推广

我们发现，最高效的做法是：先针对一个最具挑战的任务反复迭代，直到 Claude 成功搞定，再把这个成功方案提炼成技能。这样能充分利用 Claude 的上下文学习能力，比广撒网测试更快得到有效反馈。有了可运行的基础后，再扩展到多个测试用例来验证覆盖面。

推荐测试方法

1. 触发测试

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

应该触发：
- "帮我设置一个新的 ProjectHub 工作区"
- "我需要在 ProjectHub 里创建个项目"
- "为 Q4 规划初始化一个 ProjectHub 项目"

不应该触发：
- "旧金山今天天气怎么样？"
- "帮我写个 Python 脚本"
- "创建一个电子表格"（除非你的技能支持表格）
2. 功能测试

目标：验证技能输出是对的。

测试：创建包含 5 个任务的项目
给定：项目名 "Q4 规划"，5 个任务描述
执行：技能运行工作流
验证：
  - ProjectHub 里创建了项目
  - 5 个任务属性都正确
  - 所有任务都关联到项目
  - 没有 API 报错
3. 对比测试

目标：证明技能比没有技能时更好。

指标 无技能 有技能
用户如何提供指令 每次都要 自动执行
来回消息数 15 条 2 个澄清问题
API 调用失败次数 3 次（需要重试） 0 次
消耗的 token 12,000 6,000

用 skill-creator 工具

skill-creator 是一个特殊的技能，内置于 Claude.ai，也可以下载用于 Claude Code。它能帮你：

创建技能：

  • 从自然语言描述生成技能
  • 自动产生格式正确的 SKILL.md
  • 建议触发词和结构

审查技能：

  • 标出常见问题：描述太模糊、缺少触发条件、结构有问题
  • 识别过度/不足触发的风险
  • 根据技能目的建议测试用例

迭代改进：

  • 遇到边缘案例或失败后，把问题带回 skill-creator，让它帮你改进

使用方法： "使用 skill-creator 帮我为[你的用例]构建一个技能"

⚠️ 注意：skill-creator 帮你设计和打磨技能，但不会跑自动化测试套件，也不会生成量化评估结果。

根据反馈持续迭代

技能是"活文档"，要根据实际使用情况不断调整。

触发不足的信号：

  • 技能该自动加载时没加载
  • 用户手动开启它
  • 有人问"什么时候用这个技能"

→ 解决办法：在 description 里加更多细节和关键词（包括专业术语）

触发过度的信号：

  • 技能在不相关的查询里也触发了
  • 用户禁用了它
  • 用户搞不清它的用途

→ 解决办法：添加负触发词，让描述更具体

执行问题的信号：

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

→ 解决办法：改进指令，加上错误处理

二、第四章：发布与分享

技能能让你的 MCP 集成更完整。当用户在比较不同集成方案时，有技能的产品能更快展现价值，比单纯的 MCP 更有竞争力。

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

个人用户怎么获取技能：

  1. 下载技能文件夹
  2. 压缩成 zip
  3. 通过 Claude.ai 的 设置 > 功能 > 技能 上传
  4. 或放到 Claude Code 的技能目录里

组织级技能：

  • 管理员可以在工作区范围内部署技能（2025 年 12 月 18 日已上线）
  • 支持自动更新和集中管理

开放标准

Anthropic 已将 Agent Skills 作为开放标准发布。和 MCP 一样，技能应该能跨工具和平台使用——同一个技能不管在 Claude 还是其他 AI 平台上都能用。当然，有些技能可能专门利用了特定平台的能力；作者可以在 compatibility 字段里注明这一点。

通过 API 使用技能

如果你需要用程序来调用技能（比如构建应用、AI 代理或自动化工作流）：

  • 用 /v1/skills 接口管理技能
  • 在 Messages API 的 container.skills 参数里添加技能
  • 在 Claude Console 里做版本控制和管理
  • 配合 Claude Agent SDK 构建自定义代理

API 和 Claude.ai 怎么选？

使用场景 推荐方式
用户直接使用技能 Claude.ai / Claude Code
开发时手动测试和迭代 Claude.ai / Claude Code
个人或临时工作流 Claude.ai / Claude Code
程序化调用技能的应用 API
规模化生产部署 API
自动化管道和 AI 代理系统 API

⚠️ API 中使用技能需要 Code Execution Tool（代码执行工具）测试版，它为技能运行提供安全环境。

今天就能做的事

第一步：托管到 GitHub

  • 开源技能用公开仓库
  • 写清楚 README（供人类查看——这个放仓库根目录，不是技能文件夹里）
  • 附上使用示例和截图

第二步：在 MCP 文档里说明

  • 链接到技能
  • 解释 MCP + 技能一起用的价值
  • 提供快速上手指南

安装指南参考模板：

## 安装 [你的服务] 技能

1. 下载技能：
   - 克隆仓库：`git clone https://github.com/yourcompany/skills`
   - 或从 Releases 下载 ZIP

2. 安装到 Claude：
   - 打开 Claude.ai > 设置 > 技能
   - 点击"上传技能"
   - 选择技能文件夹（压缩文件）

3. 启用技能：
   - 打开 [你的服务] 技能的开关
   - 确认 MCP 服务器已连接

4. 测试：
   - 让 Claude："在 [你的服务] 里设置一个新项目"

怎么介绍你的技能

你描述技能的方式，很大程度上决定了用户愿不愿意用它。聚焦结果，而非功能：

✅ 好的写法：

“ProjectHub 技能让团队能在几秒钟内建立完整的项目工作区——包括页面、数据库和模板——而不是花 30 分钟手动配置。”

❌ 不好的写法：

“ProjectHub 技能是一个包含 YAML 前置信息和 Markdown 指令并调用我们 MCP 工具的文件夹。”

讲清楚 MCP + 技能的组合故事：

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

三、第五章：五大设计模式

下面这些模式来自早期采用者和内部团队的真实经验，是我们观察到真正有效的常见做法——不是固定模板，可以灵活用。

选你的出发点：问题优先 vs. 工具优先

想象一下去建材超市。你可能带着问题来——“我需要修厨柜”——店员帮你找合适的工具。或者你拿了个新电钻，再想怎么用它完成你的活儿。技能也是同样的逻辑：

  • 问题优先：“我需要设置项目工作区” → 技能按正确顺序协调 MCP 调用。用户说目标，技能搞定工具。
  • 工具优先：“我已经连上了 Notion MCP” → 技能教 Claude 最佳工作流程和实践。用户有访问权限，技能提供专业知识。

大多数技能会偏向其中一个方向。搞清楚哪种框架适合你的用例，能帮你选对下面的模式。

模式一：顺序工作流编排

适合场景：用户需要按特定顺序执行多个步骤。

## 工作流：引导新客户

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

关键技术：步骤顺序要明确、步骤间依赖关系要写清楚、每个阶段要有验证、失败时要有回滚指令。

模式二：多 MCP 协调

适合场景：工作流需要跨多个服务。

## 设计转开发交接

### 阶段一：设计导出（Figma MCP）
1. 从 Figma 导出设计资产
2. 生成设计规格文档
3. 创建资产清单

### 阶段二：资产存储（Drive MCP）
1. 在 Drive 新建项目文件夹
2. 上传所有资产
3. 生成可分享的链接

### 阶段三：创建任务（Linear MCP）
1. 创建开发任务
2. 把资产链接附到任务
3. 分配给工程团队

### 阶段四：发送通知（Slack MCP）
1. 在 #engineering 频道发布交接摘要
2. 附上资产链接和任务引用

关键技术：阶段分隔要清晰、MCP 间的数据传递要明确、进下一阶段前要验证、错误处理要集中。

模式三：迭代式优化

适合场景：输出质量需要通过多轮迭代来提升。

## 迭代式报告生成

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

### 质量检查
1. 运行验证脚本：`scripts/check_report.py`
2. 找出问题：
   - 缺失的章节
   - 格式不一致
   - 数据验证错误

### 优化循环
1. 逐一解决发现的问题
2. 重新生成受影响的部分
3. 重新验证
4. 重复，直到达到质量标准

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

关键技术：质量标准要明确、迭代改进要有节奏、验证脚本要好用、要知道什么时候停。

💡 进阶技巧：对于关键验证步骤，可以考虑打包一个脚本来做程序化检查，而不是靠自然语言描述。代码的执行是确定的，语言的理解不是。参考 Office 技能系列的示例。

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

适合场景：同一个目标，根据上下文要选不同的工具。

## 智能文件存储

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

### 执行存储
根据决策：
- 调用对应的 MCP 工具
- 应用特定服务的元数据
- 生成访问链接

### 告知用户
说明为什么选了这个存储方式

关键技术：决策标准要清晰、要有备用选项、选择理由要透明。

模式五：特定领域智能

适合场景：你的技能在工具访问之外还需要提供专业知识。

## 合规支付处理

### 处理前（合规检查）
1. 通过 MCP 获取交易详情
2. 应用合规规则：
   - 核查制裁名单
   - 验证司法管辖许可
   - 评估风险等级
3. 记录合规决定

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

### 审计追踪
- 记录所有合规检查
- 记录处理决定
- 生成审计报告

关键技术：领域专业知识要嵌入逻辑、行动前要合规检查、记录要完整、治理边界要清晰。

四、完整故障排查手册

技能上传失败

错误："Could not find SKILL.md in uploaded folder"
原因：文件名不是精确的 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

技能不触发

症状：技能从来不自动加载

解决：修改 description 字段（参考上篇的好/坏示例）

自查清单：

  • 描述是不是太笼统？（"帮助处理项目"不够用）
  • 有没有用户可能实际说的触发词？
  • 如果涉及文件类型，有没有提到？

调试技巧：问 Claude：“你什么时候会用 [技能名] 这个技能？” Claude 会引用 description 里的内容。根据缺失的部分来调整。

技能触发太频繁

症状：技能在不相关的查询里也出现了

解决方法一：加负触发词

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

解决方法二：描述更具体

# 太宽泛
description: 处理文档

# 更好
description: 处理 PDF 法律文件以供合同审查

解决方法三：明确使用范围

description: PayFlow 电子商务支付处理。专门用于在线支付工作流，
  不适用于一般财务查询。

MCP 连接问题

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

检查清单：

  1. 确认 MCP 服务器已连接

    • Claude.ai：设置 > 扩展 > [你的服务]
    • 应显示"已连接"

  2. 检查身份验证

    • API 密钥是否有效、是否过期
    • 权限/范围是否正确
    • OAuth 令牌是否已刷新

  3. 单独测试 MCP（不用技能）

    • 直接让 Claude 调用 MCP：“用 [服务] MCP 获取我的项目”
    • 如果这个也失败，问题在 MCP，不在技能

  4. 核对工具名称

    • 技能里引用的 MCP 工具名称是否正确
    • 工具名称区分大小写，一个字母都不能错

指令没有被遵守

症状：技能加载了，但 Claude 没按指令执行

常见原因及解决方法：

1. 指令太冗长

  • 保持简洁
  • 多用列表和编号
  • 详细参考文档移到单独文件

2. 关键指令被埋没

  • 重要内容放在最前面
  • 用 ## 重要 或 ## 关键 这样的标题
  • 关键点可以重复

3. 语言模糊

# 不好
确保正确验证相关内容

# 好
关键：在调用 create_project 之前，必须确认：
- 项目名称非空
- 至少分配了一个团队成员
- 开始日期不在过去

4. 模型"偷懒" — 加上明确的激励说明：

## 执行说明
- 请花足够时间彻底完成
- 质量比速度更重要
- 不要跳过验证步骤

注意：这段加在用户提示里比加在 SKILL.md 里效果更好。

上下文太大导致响应变慢或质量下降

原因：

  • SKILL.md 内容太多
  • 同时启用的技能太多
  • 所有内容都加载了，没有用渐进式披露

解决方法：

  1. 精简 SKILL.md

    • 详细文档移到 references/
    • 用链接引用而非内联
    • SKILL.md 尽量控制在 5,000 个词以内

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

    • 超过 20-50 个同时启用的技能就要考虑精简了
    • 建议按需选择性启用
    • 相关功能可以打包成技能"组合包"

五、第六章：资源与参考

如果你是第一次做技能，建议先看最佳实践指南，再根据需要查阅 API 文档。

官方文档

Anthropic 官方资源：

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

示例技能

公开技能仓库：

  • GitHub：anthropics/skills
  • 包含 Anthropic 创建的技能，可以直接自定义用

工具和实用程序

skill-creator 技能：

  • 内置于 Claude.ai，也可用于 Claude Code
  • 可以从描述生成技能
  • 提供审查和改进建议
  • 使用方法：“用 skill-creator 帮我构建一个技能”

验证与评审：

  • skill-creator 也可以评估已有的技能
  • 问法：“请审查这个技能，并给出改进建议”

获取支持

  • 技术问题：社区论坛 / Claude Developers Discord
  • Bug 报告：GitHub Issues：anthropics/skills/issues
    • 提交时请包含：技能名称、错误信息、复现步骤

六、附录：快速检查清单与YAML参考

想快点开始的话，可以先用 skill-creator 生成初稿，再过一遍这个清单。

快速检查清单

开始之前

  • 确定了 2-3 个具体用例
  • 确定了所需工具（内置还是 MCP）
  • 看过这份指南和示例技能
  • 规划好了文件夹结构

开发过程中

  • 文件夹用了 kebab-case 命名
  • SKILL.md 文件存在（精确拼写，区分大小写）
  • YAML 前置信息有 --- 分隔符
  • name 字段：kebab-case、无空格、无大写
  • description 同时写了"做什么"和"什么时候用"
  • 没有 XML 标签（< >）
  • 指令清晰、可操作
  • 包含了错误处理
  • 提供了示例
  • 参考资料有清晰的链接

上传前

  • 测试了明显任务的触发
  • 测试了换一种说法的触发
  • 确认不会在不相关主题上触发
  • 功能测试通过
  • 工具集成正常（如果有）
  • 压缩成了 .zip 文件

上传后

  • 在真实对话里测试过
  • 观察了过度/不足触发的情况
  • 收集了用户反馈
  • 根据反馈迭代了 description 和指令
  • 更新了 metadata 里的版本号

YAML 前置信息参考

必填字段：

---
name: skill-name-in-kebab-case
description: 它做什么以及什么时候用。包含具体的触发短语。
---

所有可选字段：

name: skill-name
description: [必填描述]
license: MIT                  # 可选：开源协议，如 MIT 或 Apache-2.0
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"  # 可选：限制工具访问
compatibility: Requires network access  # 可选：运行环境需求（1-500字符）
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” 开头的技能名（保留词）

📖 推荐阅读

如果这篇对你有帮助，以下文章你也会喜欢：

# 人工智能 # python # java
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

多智能体协作实战：我用 3 个 AI 组成了一个开发团队，一周完成了一个月的工作量

avatar AtomGit开源社区
cover

零基础学习因果推断的路线图

avatar AtomGit开源社区
cover

从零复刻Claude Code，深度拆解Agent Harness工程化落地全逻辑

avatar AtomGit开源社区