补充MCP规范文档
This commit is contained in:
1
.gitignore
vendored
1
.gitignore
vendored
@@ -41,3 +41,4 @@ $RECYCLE.BIN/
|
||||
*.swo
|
||||
|
||||
skills/**/test
|
||||
__pycache__
|
||||
903
document/the-complete-guide-to-building-skill.md
Normal file
903
document/the-complete-guide-to-building-skill.md
Normal file
@@ -0,0 +1,903 @@
|
||||
# Claude 技能构建完全指南
|
||||
|
||||
## 引言
|
||||
|
||||
[技能（Skill）](https://claude.com/blog/skills)是一组指令——以简单文件夹的形式打包——用于教会 Claude 如何处理特定任务或工作流程。技能是自定义 Claude 以满足特定需求的最强大方式之一。它让你无需在每次对话中反复解释你的偏好、流程和领域专业知识，而是只需教会 Claude 一次，便可持续受益。
|
||||
|
||||
当你有可重复的工作流程时，技能尤其强大：根据规格生成前端设计、使用一致的方法论进行研究、创建符合团队风格指南的文档，或者编排多步骤流程。它们与 Claude 的内置功能（如代码执行和文档创建）配合良好。对于正在构建 MCP 集成的开发者来说，技能增加了另一个强大的层次，帮助将原始工具访问转化为可靠、优化的工作流程。
|
||||
|
||||
本指南涵盖了构建有效技能所需的一切——从规划、结构到测试和分发。无论你是为自己、团队还是社区构建技能，你都能在全文中找到实用的模式和真实案例。
|
||||
|
||||
### 你将学到：
|
||||
|
||||
- 技能结构的技术要求和最佳实践
|
||||
- 独立技能和 MCP 增强工作流程的模式
|
||||
- 我们在不同用例中观察到的有效模式
|
||||
- 如何测试、迭代和分发你的技能
|
||||
|
||||
### 适用人群：
|
||||
|
||||
- 希望 Claude 一致地遵循特定工作流程的开发者
|
||||
- 希望 Claude 遵循特定工作流程的高级用户
|
||||
- 寻求在整个组织中标准化 Claude 使用方式的团队
|
||||
|
||||
### 本指南的两条路径
|
||||
|
||||
构建独立技能？重点关注"基础知识"、"规划与设计"以及第 1-2 类。增强 MCP 集成？"技能 + MCP"部分和第 3 类适合你。两条路径共享相同的技术要求，但你可以选择与你的用例相关的内容。
|
||||
|
||||
**本指南的收获**：阅读完本指南后，你将能够在一次工作时段内构建一个功能完整的技能。使用 skill-creator 构建和测试你的第一个可用技能大约需要 15-30 分钟。
|
||||
|
||||
让我们开始吧。
|
||||
|
||||
# 第 1 章：基础知识
|
||||
|
||||
## 什么是技能？
|
||||
|
||||
技能是一个包含以下内容的文件夹：
|
||||
|
||||
- **SKILL.md（必需）**：带有 YAML 前置元数据的 Markdown 格式指令
|
||||
- **scripts/（可选）**：可执行代码（Python、Bash 等）
|
||||
- **references/（可选）**：按需加载的文档
|
||||
- **assets/（可选）**：输出中使用的模板、字体、图标
|
||||
|
||||
## 核心设计原则
|
||||
|
||||
### 渐进式披露
|
||||
|
||||
技能采用三级系统：
|
||||
|
||||
- **第一级（YAML 前置元数据）**：始终加载到 Claude 的系统提示中。仅提供足够的信息让 Claude 知道何时应该使用每个技能，而无需将所有内容加载到上下文中。
|
||||
- **第二级（SKILL.md 正文）**：当 Claude 认为该技能与当前任务相关时加载。包含完整的指令和指南。
|
||||
- **第三级（关联文件）**：技能目录中捆绑的附加文件，Claude 可以根据需要选择导航和发现。
|
||||
|
||||
这种渐进式披露在保持专业能力的同时最大限度地减少了 token 使用。
|
||||
|
||||
### 可组合性
|
||||
|
||||
Claude 可以同时加载多个技能。你的技能应该能够与其他技能良好协作，而不是假设它是唯一可用的能力。
|
||||
|
||||
### 可移植性
|
||||
|
||||
技能在 Claude.ai、Claude Code 和 API 中的工作方式完全相同。只需创建一次技能，它就可以在所有平台上无需修改地运行，前提是环境支持技能所需的任何依赖项。
|
||||
|
||||
## 面向 MCP 构建者：技能 + 连接器
|
||||
|
||||
_💡 构建不含 MCP 的独立技能？跳至"规划与设计"——你随时可以回来查阅此部分。_
|
||||
|
||||
如果你已经有一个[可用的 MCP 服务器](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)，那么你已经完成了最困难的部分。技能是其上的知识层——捕获你已经了解的工作流程和最佳实践，以便 Claude 能够一致地应用它们。
|
||||
|
||||
### 厨房比喻
|
||||
|
||||
**MCP 提供专业厨房**：访问工具、食材和设备。
|
||||
|
||||
**技能提供食谱**：关于如何创造有价值产出的分步指令。
|
||||
|
||||
两者结合，使用户能够完成复杂任务，而无需自己弄清楚每一步。
|
||||
|
||||
它们如何协同工作：
|
||||
|
||||
| MCP（连接性） | 技能（知识） |
|
||||
| ---------------------------------------------------------- | ---------------------------- |
|
||||
| （Notion、Asana、Linear 等）有效地将 Claude 连接到你的服务 | 教会 Claude 如何使用你的服务 |
|
||||
| 提供实时数据访问和工具调用 | 捕获工作流程和最佳实践 |
|
||||
| Claude 能做什么 | Claude 应该怎么做 |
|
||||
|
||||
### 这对你的 MCP 用户为何重要
|
||||
|
||||
#### 没有技能时：
|
||||
|
||||
- 用户连接了你的 MCP 但不知道下一步该做什么
|
||||
- 支持工单询问"如何用你的集成做 X"
|
||||
- 每次对话都从零开始
|
||||
- 结果不一致，因为用户每次的提示方式不同
|
||||
- 当真正的问题是工作流程指导时，用户却责怪你的连接器
|
||||
|
||||
#### 有技能时：
|
||||
|
||||
- 预构建的工作流程在需要时自动激活
|
||||
- 一致、可靠的工具使用
|
||||
- 最佳实践嵌入到每次交互中
|
||||
- 降低你的集成的学习曲线
|
||||
|
||||
# 第 2 章：规划与设计
|
||||
|
||||
## 从用例开始
|
||||
|
||||
在编写任何代码之前，确定 2-3 个你的技能应该支持的具体用例。
|
||||
|
||||
### 良好的用例定义：
|
||||
|
||||
```
|
||||
用例：项目冲刺计划
|
||||
触发器：用户说"帮我规划这个冲刺"或"创建冲刺任务"
|
||||
步骤：
|
||||
1. 从 Linear 获取当前项目状态（通过 MCP）
|
||||
2. 分析团队速度和产能
|
||||
3. 建议任务优先级
|
||||
4. 在 Linear 中创建带有适当标签和估算的任务
|
||||
结果：冲刺完全规划完成，任务已创建
|
||||
```
|
||||
|
||||
### 问问自己：
|
||||
|
||||
- 用户想要完成什么？
|
||||
- 这需要哪些多步骤工作流程？
|
||||
- 需要哪些工具（内置的还是 MCP 的）？
|
||||
- 应该嵌入哪些领域知识或最佳实践？
|
||||
|
||||
## 常见技能用例类别
|
||||
|
||||
在 Anthropic，我们观察到三种常见用例：
|
||||
|
||||
### 类别 1：文档与资产创建
|
||||
|
||||
用途：创建一致、高质量的输出，包括文档、演示文稿、应用程序、设计、代码等。
|
||||
|
||||
_真实案例_：[frontend-design 技能](https://github.com/anthropics/skills/tree/main/skills/frontend-design)（另见 [docx、pptx、xlsx 和 ppt 技能](https://github.com/anthropics/skills/tree/main/skills)）
|
||||
|
||||
"创建独特的、生产级的前端界面，具有高设计质量。在构建 Web 组件、页面、产物、海报或应用程序时使用。"
|
||||
|
||||
**关键技术**：
|
||||
|
||||
- 嵌入式风格指南和品牌标准
|
||||
- 用于一致输出的模板结构
|
||||
- 最终确定前的质量检查清单
|
||||
- 无需外部工具——使用 Claude 的内置功能
|
||||
|
||||
### 类别 2：工作流程自动化
|
||||
|
||||
用途：受益于一致方法论的多步骤流程，包括跨多个 MCP 服务器的协调。
|
||||
|
||||
_真实案例_：[skill-creator 技能](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md)
|
||||
|
||||
"用于创建新技能的交互式指南。引导用户完成用例定义、前置元数据生成、指令编写和验证。"
|
||||
|
||||
**关键技术**：
|
||||
|
||||
- 带有验证关卡的分步工作流程
|
||||
- 常见结构的模板
|
||||
- 内置的审查和改进建议
|
||||
- 迭代优化循环
|
||||
|
||||
### 类别 3：MCP 增强
|
||||
|
||||
用途：增强 MCP 服务器提供的工具访问的工作流程指导。
|
||||
|
||||
_真实案例_：[sentry-code-review 技能（来自 Sentry）](https://github.com/getsentry/sentry-for-claude/tree/main/skills)
|
||||
|
||||
"使用 Sentry 通过其 MCP 服务器提供的错误监控数据，自动分析和修复 GitHub Pull Request 中检测到的 bug。"
|
||||
|
||||
**关键技术**：
|
||||
|
||||
- 按顺序协调多个 MCP 调用
|
||||
- 嵌入领域专业知识
|
||||
- 提供用户原本需要指定的上下文
|
||||
- 常见 MCP 问题的错误处理
|
||||
|
||||
## 定义成功标准
|
||||
|
||||
### 你如何知道你的技能正在工作？
|
||||
|
||||
这些是理想目标——粗略的基准而非精确的阈值。追求严谨，但接受会有一定程度的主观评估成分。我们正在积极开发更强大的衡量指导和工具。
|
||||
|
||||
### 定量指标：
|
||||
|
||||
- 技能在 90% 的相关查询上触发
|
||||
- 如何衡量：运行 10-20 个应该触发你技能的测试查询。跟踪它自动加载的次数与需要显式调用的次数。
|
||||
- 在 X 次工具调用内完成工作流程
|
||||
- 如何衡量：比较启用和未启用技能时执行相同任务的情况。计算工具调用次数和消耗的总 token 数。
|
||||
- 每个工作流程 0 次失败的 API 调用
|
||||
- 如何衡量：在测试运行期间监控 MCP 服务器日志。跟踪重试率和错误代码。
|
||||
|
||||
### 定性指标：
|
||||
|
||||
- 用户不需要提示 Claude 下一步
|
||||
- 如何评估：在测试期间，记录你需要重定向或澄清的频率。征求 beta 用户的反馈。
|
||||
- 工作流程完成时无需用户纠正
|
||||
- 如何评估：运行相同的请求 3-5 次。比较输出的结构一致性和质量。
|
||||
- 跨会话的一致结果
|
||||
- 如何评估：新用户能否在第一次尝试时以最少的指导完成任务？
|
||||
|
||||
## 技术要求
|
||||
|
||||
### 文件结构
|
||||
|
||||
```
|
||||
your-skill-name/
|
||||
├── SKILL.md # 必需 - 主技能文件
|
||||
├── scripts/ # 可选 - 可执行代码
|
||||
│ ├── process_data.py # 示例
|
||||
│ └── validate.sh # 示例
|
||||
├── references/ # 可选 - 文档
|
||||
│ ├── api-guide.md # 示例
|
||||
│ └── examples/ # 示例
|
||||
└── assets/ # 可选 - 模板等
|
||||
└── report-template.md # 示例
|
||||
```
|
||||
|
||||
### 关键规则
|
||||
|
||||
#### SKILL.md 命名：
|
||||
|
||||
- 必须完全是 SKILL.md（区分大小写）
|
||||
- 不接受任何变体（skill.md、Skill.md 等）
|
||||
|
||||
#### 技能文件夹命名：
|
||||
|
||||
- 使用 kebab-case：notion-project-setup ✅
|
||||
- 不要有空格：Notion Project Setup ❌
|
||||
- 不要有下划线：notion_project_setup ❌
|
||||
- 不要有大写字母：NotionProjectSetup ❌
|
||||
|
||||
#### 不要包含 README.md：
|
||||
|
||||
- 不要在技能文件夹内包含 README.md
|
||||
- 所有文档都放在 SKILL.md 或 references/ 中
|
||||
- 注意：通过 GitHub 分发时，你仍然需要一个仓库级别的 README 供人类用户阅读——参见"分发与共享"。
|
||||
|
||||
### YAML 前置元数据：最重要的部分
|
||||
|
||||
YAML 前置元数据是 Claude 决定是否加载你的技能的依据。务必做好这一点。
|
||||
|
||||
#### 最小必需格式
|
||||
|
||||
```
|
||||
name: your-skill-name
|
||||
description: 它做什么。当用户要求 [特定短语] 时使用。
|
||||
```
|
||||
|
||||
这就是你开始所需的全部内容。
|
||||
|
||||
### 字段要求
|
||||
|
||||
**name**（必需）：
|
||||
|
||||
- 仅限 kebab-case
|
||||
- 不能有空格或大写字母
|
||||
- 应与文件夹名称匹配
|
||||
|
||||
**description**（必需）：
|
||||
|
||||
- **必须同时包含**：
|
||||
- 技能做什么
|
||||
- 何时使用它（触发条件）
|
||||
- 少于 1024 个字符
|
||||
- 不能有 XML 标签（< 或 >）
|
||||
- 包含用户可能会说的特定任务
|
||||
- 如果相关，提及文件类型
|
||||
|
||||
**license**（可选）：
|
||||
|
||||
- 如果将技能开源则使用
|
||||
- 常见：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"的技能（保留字）
|
||||
|
||||
**原因**：前置元数据出现在 Claude 的系统提示中。恶意内容可能注入指令。
|
||||
|
||||
### 编写有效的技能
|
||||
|
||||
#### description 字段
|
||||
|
||||
根据 Anthropic 的[工程博客](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)："此元数据……提供足够的信息让 Claude 知道何时应该使用每个技能，而无需将所有内容加载到上下文中。"这是渐进式披露的第一级。
|
||||
|
||||
**结构**：
|
||||
|
||||
```
|
||||
[它做什么] + [何时使用] + [关键能力]
|
||||
```
|
||||
|
||||
**好的 description 示例**：
|
||||
|
||||
```
|
||||
# 好 - 具体且可操作
|
||||
description: 分析 Figma 设计文件并生成开发者交接文档。当用户上传 .fig 文件、要求"设计规格"、"组件文档"或"设计到代码交接"时使用。
|
||||
|
||||
# 好 - 包含触发短语
|
||||
description: 管理 Linear 项目工作流程，包括冲刺计划、任务创建和状态跟踪。当用户提到"冲刺"、"Linear 任务"、"项目计划"或要求"创建工单"时使用。
|
||||
|
||||
# 好 - 清晰的价值主张
|
||||
description: PayFlow 的端到端客户入职工作流程。处理账户创建、支付设置和订阅管理。当用户说"引导新客户"、"设置订阅"或"创建 PayFlow 账户"时使用。
|
||||
```
|
||||
|
||||
**差的 description 示例**：
|
||||
|
||||
```
|
||||
# 太模糊
|
||||
description: 帮助处理项目。
|
||||
|
||||
# 缺少触发器
|
||||
description: 创建复杂的多页文档系统。
|
||||
|
||||
# 太技术化，没有用户触发器
|
||||
description: 实现具有层级关系的 Project 实体模型。
|
||||
```
|
||||
|
||||
#### 编写主要指令
|
||||
|
||||
在前置元数据之后，用 Markdown 编写实际的指令。
|
||||
|
||||
**推荐结构**：
|
||||
|
||||
根据你的技能调整此模板。用你的具体内容替换括号中的部分。
|
||||
|
||||
````
|
||||
---
|
||||
name: your-skill
|
||||
description: [...]
|
||||
---
|
||||
|
||||
# 你的技能名称
|
||||
|
||||
## 指令
|
||||
|
||||
### 步骤 1：[第一个主要步骤]
|
||||
清晰解释会发生什么。
|
||||
示例：```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/` 并链接到它。（参见[核心设计原则](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)了解三级系统的工作原理。）
|
||||
|
||||
# 第 3 章：测试与迭代
|
||||
|
||||
技能可以根据你的需求在不同的严格程度下进行测试：
|
||||
|
||||
- **在 Claude.ai 中手动测试** - 直接运行查询并观察行为。快速迭代，无需设置。
|
||||
- **在 Claude Code 中脚本化测试** - 自动化测试用例以在更改间进行可重复的验证。
|
||||
- **通过技能 API 进行程序化测试** - 构建评估套件，针对定义的测试集系统地运行。
|
||||
|
||||
选择与你的质量要求和技能可见度相匹配的方法。一个由小团队内部使用的技能与一个部署给数千企业用户的技能有不同的测试需求。
|
||||
|
||||
> **专业提示**：先在单个任务上迭代，然后再扩展
|
||||
|
||||
我们发现，最有效的技能创建者会在单个具有挑战性的任务上迭代，直到 Claude 成功，然后将成功的方法提取到技能中。这利用了 Claude 的上下文学习能力，比广泛测试提供更快的信号。一旦你有了一个可用的基础，再扩展到多个测试用例以确保覆盖率。
|
||||
|
||||
## 推荐的测试方法
|
||||
|
||||
根据早期经验，有效的技能测试通常涵盖三个领域：
|
||||
|
||||
### 1: 触发测试
|
||||
|
||||
**目标**：确保你的技能在正确的时间加载。
|
||||
|
||||
**测试用例**：
|
||||
|
||||
- ✅ 在明显任务上触发
|
||||
- ✅ 在改述的请求上触发
|
||||
- ❌ 不在无关主题上触发
|
||||
|
||||
**示例测试套件**：
|
||||
|
||||
```
|
||||
应该触发：
|
||||
- "帮我设置一个新的 ProjectHub 工作区"
|
||||
- "我需要在 ProjectHub 中创建一个项目"
|
||||
- "为 Q4 计划初始化一个 ProjectHub 项目"
|
||||
不应该触发：
|
||||
- "旧金山的天气怎么样？"
|
||||
- "帮我写 Python 代码"
|
||||
- "创建一个电子表格"（除非 ProjectHub 技能处理表格）
|
||||
```
|
||||
|
||||
### 2: 功能测试
|
||||
|
||||
**目标**：验证技能产生正确的输出。
|
||||
|
||||
**测试用例**：
|
||||
|
||||
- 生成有效输出
|
||||
- API 调用成功
|
||||
- 错误处理正常工作
|
||||
- 覆盖边缘情况
|
||||
|
||||
**示例**：
|
||||
|
||||
```
|
||||
测试：创建包含 5 个任务的项目
|
||||
给定：项目名称"Q4 计划"，5 个任务描述
|
||||
当：技能执行工作流程
|
||||
那么：
|
||||
- 项目在 ProjectHub 中创建
|
||||
- 5 个任务以正确的属性创建
|
||||
- 所有任务链接到项目
|
||||
- 无 API 错误
|
||||
```
|
||||
|
||||
### 3: 性能比较
|
||||
|
||||
**目标**：证明技能相比基线改善了结果。
|
||||
|
||||
使用"定义成功标准"中的指标。以下是一个比较可能的样子。
|
||||
|
||||
**基线比较**：
|
||||
|
||||
```
|
||||
没有技能时：
|
||||
- 用户每次都提供指令
|
||||
- 15 次来回消息
|
||||
- 3 次失败的 API 调用需要重试
|
||||
- 消耗 12,000 个 token
|
||||
|
||||
有技能时：
|
||||
- 自动工作流程执行
|
||||
- 仅 2 个澄清问题
|
||||
- 0 次失败的 API 调用
|
||||
- 消耗 6,000 个 token
|
||||
```
|
||||
|
||||
## 使用 skill-creator 技能
|
||||
|
||||
skill-creator 技能——可在 Claude.ai 通过插件目录获取，或下载用于 Claude Code——可以帮助你构建和迭代技能。如果你有 MCP 服务器并了解你的前 2-3 个工作流程，你可以在一次工作时段内构建和测试一个功能完整的技能——通常在 15-30 分钟内。
|
||||
|
||||
### 创建技能：
|
||||
|
||||
- 从自然语言描述生成技能
|
||||
- 生成带有前置元数据的正确格式 SKILL.md
|
||||
- 建议触发短语和结构
|
||||
|
||||
### 审查技能：
|
||||
|
||||
- 标记常见问题（模糊的描述、缺失的触发器、结构问题）
|
||||
- 识别潜在的过度/不足触发风险
|
||||
- 根据技能的声明目的建议测试用例
|
||||
|
||||
### 迭代改进：
|
||||
|
||||
- 使用你的技能并遇到边缘情况或失败后，将这些示例带回 skill-creator
|
||||
- 示例："使用此聊天中识别的问题和解决方案来改进技能处理 [特定边缘情况] 的方式"
|
||||
|
||||
**使用方法**：
|
||||
|
||||
```
|
||||
"使用 skill-creator 技能帮我为 [你的用例] 构建一个技能"
|
||||
```
|
||||
|
||||
_注意：skill-creator 帮助你设计和完善技能，但不执行自动化测试套件或产生定量评估结果。_
|
||||
|
||||
## 基于反馈的迭代
|
||||
|
||||
技能是活的文档。计划根据以下情况进行迭代：
|
||||
|
||||
### 触发不足的信号：
|
||||
|
||||
- 技能在应该加载时没有加载
|
||||
|
||||
- 用户手动启用它
|
||||
|
||||
- 关于何时使用它的支持问题
|
||||
|
||||
> **解决方案**：在 description 中添加更多细节和细微差别——这可能包括关键字，特别是技术术语
|
||||
|
||||
### 过度触发的信号：
|
||||
|
||||
- 技能为无关查询加载
|
||||
- 用户禁用它
|
||||
- 对目的感到困惑
|
||||
|
||||
> **解决方案**：添加负面触发器，更加具体
|
||||
|
||||
### 执行问题：
|
||||
|
||||
- 结果不一致
|
||||
- API 调用失败
|
||||
- 需要用户纠正
|
||||
|
||||
> **解决方案**：改进指令，添加错误处理
|
||||
|
||||
# 第 4 章：模式与故障排除
|
||||
|
||||
这些模式来自早期采用者和内部团队创建的技能。它们代表了我们观察到的有效的常见方法，而非规定性模板。
|
||||
|
||||
## 选择你的方法：问题优先 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）
|
||||
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：迭代优化
|
||||
|
||||
**适用场景**：输出质量通过迭代得到改善。
|
||||
|
||||
### 示例：报告生成
|
||||
|
||||
```
|
||||
## 迭代报告创建
|
||||
### 初稿
|
||||
1. 通过 MCP 获取数据
|
||||
2. 生成第一版报告草稿
|
||||
3. 保存到临时文件
|
||||
|
||||
### 质量检查
|
||||
1. 运行验证脚本：`scripts/check_report.py`
|
||||
2. 识别问题：
|
||||
- 缺失的章节
|
||||
- 不一致的格式
|
||||
- 数据验证错误
|
||||
|
||||
### 优化循环
|
||||
1. 解决每个识别的问题
|
||||
2. 重新生成受影响的章节
|
||||
3. 重新验证
|
||||
4. 重复直到达到质量阈值
|
||||
|
||||
### 最终化
|
||||
1. 应用最终格式
|
||||
2. 生成摘要
|
||||
3. 保存最终版本
|
||||
```
|
||||
|
||||
**关键技术**：
|
||||
|
||||
- 明确的质量标准
|
||||
- 迭代改进
|
||||
- 验证脚本
|
||||
- 知道何时停止迭代
|
||||
|
||||
## 模式 4：上下文感知工具选择
|
||||
|
||||
**适用场景**：相同的结果，但根据上下文使用不同的工具。
|
||||
|
||||
### 示例：文件存储
|
||||
|
||||
```
|
||||
## 智能文件存储
|
||||
### 决策树
|
||||
1. 检查文件类型和大小
|
||||
2. 确定最佳存储位置：
|
||||
- 大文件（>10MB）：使用云存储 MCP
|
||||
- 协作文档：使用 Notion/Docs MCP
|
||||
- 代码文件：使用 GitHub MCP
|
||||
- 临时文件：使用本地存储
|
||||
|
||||
### 执行存储
|
||||
基于决策：
|
||||
- 调用适当的 MCP 工具
|
||||
- 应用特定于服务的元数据
|
||||
- 生成访问链接
|
||||
|
||||
### 向用户提供上下文
|
||||
解释为什么选择该存储
|
||||
```
|
||||
|
||||
**关键技术**：
|
||||
|
||||
- 清晰的决策标准
|
||||
- 备用选项
|
||||
- 关于选择的透明度
|
||||
|
||||
## 模式 5：领域特定智能
|
||||
|
||||
**适用场景**：你的技能添加了超越工具访问的专业知识。
|
||||
|
||||
### 示例：金融合规
|
||||
|
||||
```
|
||||
## 带合规的支付处理
|
||||
### 处理前（合规检查）
|
||||
1. 通过 MCP 获取交易详情
|
||||
2. 应用合规规则：
|
||||
- 检查制裁名单
|
||||
- 验证司法管辖区许可
|
||||
- 评估风险级别
|
||||
3. 记录合规决策
|
||||
|
||||
### 处理
|
||||
如果合规通过：
|
||||
- 调用支付处理 MCP 工具
|
||||
- 应用适当的欺诈检查
|
||||
- 处理交易
|
||||
否则：
|
||||
- 标记以供审查
|
||||
- 创建合规案例
|
||||
|
||||
### 审计追踪
|
||||
- 记录所有合规检查
|
||||
- 记录处理决策
|
||||
- 生成审计报告
|
||||
```
|
||||
|
||||
**关键技术**：
|
||||
|
||||
- 领域专业知识嵌入逻辑
|
||||
- 行动前的合规性
|
||||
- 全面的文档记录
|
||||
- 清晰的治理
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 技能不触发
|
||||
|
||||
**症状**：技能从不自动加载
|
||||
|
||||
**修复**：
|
||||
|
||||
修改你的 description 字段。参见"description 字段"中的好/差示例。
|
||||
|
||||
**快速检查清单**：
|
||||
|
||||
- 是否太通用？（"帮助处理项目"不会工作）
|
||||
- 是否包含用户实际会说的触发短语？
|
||||
- 如果适用，是否提到相关文件类型？
|
||||
|
||||
**调试方法**：
|
||||
|
||||
询问 Claude："你什么时候会使用 [技能名称] 技能？"Claude 会引用 description。根据缺失的内容进行调整。
|
||||
|
||||
### 技能触发太频繁
|
||||
|
||||
**症状**：技能为无关查询加载
|
||||
|
||||
**解决方案**：
|
||||
|
||||
1. **添加负面触发器**
|
||||
|
||||
```
|
||||
description: CSV 文件的高级数据分析。用于统计建模、回归、聚类。不要用于简单的数据探索（改用 data-viz 技能）。
|
||||
```
|
||||
|
||||
2. **更加具体**
|
||||
|
||||
```
|
||||
# 太宽泛
|
||||
description: 处理文档
|
||||
|
||||
# 更具体
|
||||
description: 处理用于合同审查的 PDF 法律文档
|
||||
```
|
||||
|
||||
3. **明确范围**
|
||||
|
||||
```
|
||||
description: 用于电子商务的 PayFlow 支付处理。专门用于在线支付工作流程，而非一般财务查询。
|
||||
```
|
||||
|
||||
### MCP 连接问题
|
||||
|
||||
**症状**：技能加载但 MCP 调用失败
|
||||
|
||||
**检查清单**：
|
||||
|
||||
1. **验证 MCP 服务器已连接**
|
||||
- Claude.ai：设置 > 扩展 > [你的服务] 应显示"已连接"状态
|
||||
2. **检查身份验证**
|
||||
- API 密钥有效且未过期
|
||||
- 已授予适当的权限/范围
|
||||
- OAuth 令牌已刷新
|
||||
3. **独立测试 MCP**
|
||||
- 让 Claude 直接调用 MCP（不使用技能）
|
||||
- "使用 [服务] MCP 获取我的项目"
|
||||
- 如果这失败了，问题在 MCP 而非技能
|
||||
4. **验证工具名称**
|
||||
- 技能引用正确的 MCP 工具名称
|
||||
- 检查 MCP 服务器文档
|
||||
- 工具名称区分大小写
|
||||
|
||||
### 指令未被遵循
|
||||
|
||||
**症状**：技能加载但 Claude 不遵循指令
|
||||
|
||||
**常见原因**：
|
||||
|
||||
1. **指令太冗长**
|
||||
- 保持指令简洁
|
||||
- 使用项目符号和编号列表
|
||||
- 将详细参考移至单独的文件
|
||||
|
||||
2. **指令被埋没**
|
||||
- 将关键指令放在顶部
|
||||
- 使用 ## 重要 或 ## 关键 标题
|
||||
- 如果需要，重复关键点
|
||||
|
||||
3. **语言模糊**
|
||||
|
||||
```
|
||||
# 差
|
||||
确保正确验证内容
|
||||
|
||||
# 好
|
||||
关键：在调用 create_project 之前，验证：
|
||||
- 项目名称非空
|
||||
- 至少分配一名团队成员
|
||||
- 开始日期不在过去
|
||||
```
|
||||
|
||||
**高级技术**：对于关键验证，考虑捆绑一个以编程方式执行检查的脚本，而不是依赖语言指令。代码是确定性的；语言解释不是。参见 Office 技能中此模式的示例。
|
||||
|
||||
4. **模型"懒惰"** 添加明确的鼓励：
|
||||
|
||||
```
|
||||
## 性能说明
|
||||
- 花时间彻底完成这项工作
|
||||
- 质量比速度更重要
|
||||
- 不要跳过验证步骤
|
||||
```
|
||||
|
||||
注意：将此添加到用户提示中比添加到 SKILL.md 中更有效
|
||||
|
||||
### 大上下文问题
|
||||
|
||||
**症状**：技能似乎很慢或响应质量下降
|
||||
|
||||
**原因**：
|
||||
|
||||
- 技能内容太大
|
||||
- 同时启用了太多技能
|
||||
- 所有内容都被加载而不是渐进式披露
|
||||
|
||||
**解决方案**：
|
||||
|
||||
1. **优化 SKILL.md 大小**
|
||||
- 将详细文档移至 references/
|
||||
- 链接到引用而不是内联
|
||||
- SKILL.md 保持在 5,000 字以下
|
||||
2. **减少启用的技能**
|
||||
- 评估是否同时启用了超过 20-50 个技能
|
||||
- 建议选择性启用
|
||||
- 考虑为相关功能使用技能"包"
|
||||
@@ -17,9 +17,7 @@ my-skill/
|
||||
技能使用**渐进式披露**来高效管理上下文：
|
||||
|
||||
1. **发现**：在启动时，代理仅加载每个可用技能的名称和描述，足以了解何时可能相关。
|
||||
|
||||
2. **激活**：当任务匹配技能的描述时，代理将完整的 `SKILL.md` 指令读入上下文。
|
||||
|
||||
3. **执行**：代理遵循指令，根据需要可选择性地加载引用文件或执行打包的代码。
|
||||
|
||||
这种方法使代理保持快速，同时能够按需访问更多上下文。
|
||||
@@ -55,11 +53,8 @@ Use this skill when the user needs to work with PDF files...
|
||||
- `description`：何时使用此技能
|
||||
|
||||
Markdown 正文包含实际指令，对结构或内容没有特定限制。
|
||||
|
||||
这种简单格式具有一些关键优势：
|
||||
|
||||
- **自文档化**：技能作者或用户可以阅读 `SKILL.md` 并了解其功能，使技能易于审核和改进。
|
||||
|
||||
- **可扩展**：技能的复杂度可以范围从仅文本指令到可执行代码、资产和模板。
|
||||
|
||||
- **可移植**：技能只是文件，因此易于编辑、版本控制和共享。
|
||||
|
||||
Reference in New Issue
Block a user