第五章模式和故障排除

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

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

可以把它想象成 Home Depot。你可能带着一个问题走进去——"我需要修理厨房橱柜"——然后员工会为你指出合适的工具。或者你可能挑选了一个新电钻，然后询问如何将它用于你的具体工作。

技能的工作方式也是如此：

问题优先："我需要建立一个项目工作空间" → 你的技能会按正确的顺序调度合适的 MCP 调用。用户描述期望的结果，技能负责处理工具。
工具优先："我已经连接了 Notion MCP" → 你的技能教 Claude 最优的工作流程和最佳实践。用户拥有访问权限，技能提供专业知识。

大多数技能会倾向于其中一个方向。了解哪种框架适合你的用例，可以帮助你在下面选择正确的模式。

模式 1：顺序工作流编排

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

示例结构：

## 工作流：新客户入职

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

使用场景: 工作流跨越多个服务。

示例：设计到开发的交接

阶段 1：设计导出（Figma MCP）

从 Figma 导出设计资产
生成设计规范
创建资产清单

阶段 2: 资产存储 (Drive MCP)

在 Drive 中创建项目文件夹
上传所有资产
生成可分享的链接

阶段 3: 任务创建 (Linear MCP)

创建开发任务
将资产链接附加到任务
分配给工程团队

阶段 4：通知 (Slack MCP)

将交接摘要发布到 #engineering
包含资产链接和任务引用

关键技术:

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

模式 3: 迭代优化

使用场景:当输出质量随着迭代而提升时。

示例:报告生成

迭代式报告创建

初始草稿

通过 MCP 获取数据
生成第一版草稿报告
保存到临时文件

质量检查

运行验证脚本：scripts/check_report.py
识别问题：

缺失的章节
不一致的格式
数据验证错误

优化循环

处理每个已识别的问题
重新生成受影响的章节
重新验证
重复直到达到质量阈值

最终完成

应用最终格式
生成摘要
保存最终版本

关键技术:

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

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

使用场景: 相同的结果，根据上下文使用不同的工具。

示例：文件存储

决策树

检查文件类型和大小
确定最佳存储位置：

大文件（>10MB）：使用云存储 MCP
协作文档：使用 Notion/Docs MCP
代码文件：使用 GitHub MCP
临时文件：使用本地存储

执行存储

基于决策:

调用适当的 MCP 工具
应用特定服务的元数据
生成访问链接

向用户提供上下文

解释为什么选择该存储

关键技术：

清晰的决策标准
后备选项
选择的透明性

模式 5：领域专用智能

使用场景：当你的技能添加了超越工具访问的专业知识时。

示例:金融合规

符合合规要求的支付处理

处理前(合规检查)

通过 MCP 获取交易详情
应用合规规则:

检查制裁名单
验证司法管辖区许可
评估风险级别

记录合规决策

处理

如果合规通过：

调用支付处理 MCP 工具
应用相应的欺诈检查
处理交易

否则：

标记待审查
创建合规审查案例

审计追踪

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

关键技术：

将领域专业知识嵌入逻辑中
行动前的合规检查
全面的文档记录
清晰的治理机制

故障排查

Skill 无法上传

错误："在上传的文件夹中找不到 SKILL.md"

**原因：**文件名称不完全是 SKILL.md

解决方案：

重命名为 SKILL.md（区分大小写）
验证方式：ls -la 应该显示 SKILL.md

错误："无效的 frontmatter"

**原因：**YAML 格式问题

常见错误：

# 错误 - 缺少分隔符
name: my-skill
description: 执行某些操作

# 错误 - 引号未闭合
name: my-skill
description: "执行某些操作

# 正确
---
name: my-skill
description: 执行某些操作
---

错误："无效的 skill 名称"

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

# 错误
name: My Cool Skill

# 正确
name: my-cool-skill

技能不触发

症状： 技能从未自动加载

修复：

修订你的描述字段。参见描述字段部分的正确/错误示例。

快速检查清单：

是否过于笼统？（"帮助处理项目"不会起作用）
是否包含用户实际会说的触发短语？
如果适用，是否提到了相关的文件类型？

调试方法：

询问 Claude："你什么时候会使用 [技能名称] 技能？" Claude 会引用描述回答。根据缺失的内容进行调整。

Skill 触发过于频繁

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

解决方案：

添加负面触发器

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

更加具体

过于宽泛
description: 处理文档
# 更具体
description: 处理 PDF 法律文档以进行合同审查

明确范围

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

MCP 连接问题

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

检查清单：

验证 MCP 服务器已连接

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

检查身份验证

API 密钥有效且未过期
已授予适当的权限/范围
OAuth token 已刷新

独立测试 MCP

要求 Claude 直接调用 MCP（不使用 skill）
"使用 [服务] MCP 获取我的项目"
如果失败，问题在于 MCP 而非 skill

验证工具名称

Skill 引用正确的 MCP 工具名称
检查 MCP 服务器文档
工具名称区分大小写

指令未被遵循

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

常见原因：

指令过于冗长

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

指令被埋没

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

语言模糊

# 不好
确保正确验证事项
# 好
关键：在调用 create_project 之前，验证：
- 项目名称非空
- 至少分配一名团队成员
- 开始日期不在过去

高级技巧：对于关键验证，考虑捆绑一个以编程方式执行检查的脚本，而不是依赖语言指令。代码是确定性的；语言解释不是。参见 Office skills 的示例模式。

模型"懒惰" 添加明确的鼓励：

## 性能说明
- 花时间彻底完成此操作
- 质量比速度更重要
- 不要跳过验证步骤

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

大型上下文问题

症状:技能似乎变慢或响应质量下降

原因：

技能内容过大
同时启用了过多技能
加载了所有内容而不是渐进式展示

解决方案：

优化 SKILL.md 文件大小

将详细文档移至 references/
链接到参考文档而非内嵌
保持 SKILL.md 在 5,000 字以内

减少启用的技能

评估你是否同时启用了超过 20 - 50 个技能
建议选择性启用
考虑为相关功能使用技能"包"

第五章 模式和故障排除

第五章模式和故障排除