第二章 规划和设计

第二章 规划和设计

Written By
Gona小译
Gona小译您忠实的翻译官

从用例开始

在编写任何代码之前，确定你的技能应该实现的 2-3 个具体用例。

好的用例定义：

用例：项目冲刺规划
触发条件：用户说"帮我规划这个冲刺"或"创建冲刺任务"
步骤：
1. 从 Linear 获取当前项目状态（通过 MCP）
2. 分析团队速率和产能
3. 建议任务优先级排序
4. 在 Linear 中创建带有适当标签和工作量估算的任务
结果：完全规划好的冲刺，任务已创建

问问自己：

  • 用户想要完成什么？
  • 这需要哪些多步骤工作流？
  • 需要哪些工具 (内置的还是 MCP?)
  • 应该嵌入哪些领域知识或最佳实践？

常见的技能使用场景类别

在 Anthropic，我们观察到三种常见的使用场景：

类别 1：文档与资产创建

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

真实示例： frontend-design 技能（另请参阅 docx、pptx、xlsx 和 ppt 的技能）

"创建独特的、生产级别的前端界面，具有高设计质量。在构建 Web 组件、页面、artifact、海报或应用程序时使用。"

关键技术：

  • 嵌入式风格指南和品牌标准
  • 用于一致输出的模板结构
  • 完成前的质量检查清单
  • 无需外部工具——使用 Claude 的内置功能

类别 2：工作流自动化

用于：受益于一致方法论的多步骤流程，包括跨多个 MCP 服务器的协调。

真实示例：skill-creator 技能

"创建新技能的交互式指南。引导用户完成用例定义、前置信息生成、指令编写和验证。"

关键技术：

  • 带有验证节点的逐步工作流
  • 常见结构的模板
  • 内置审查和改进建议
  • 迭代改进循环

类别 3：MCP 增强

用途：工作流指导，增强工具对 MCP 服务器的访问能力。

真实示例：sentry-code-review skill (来自 Sentry)

"通过 Sentry 的 MCP 服务器，使用 Sentry 的错误监控数据自动分析和修复 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 等）

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 决定是否加载你的技能的关键。务必把这部分做对。

最小必需格式

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

这就是你开始所需的全部内容。

字段要求

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

安全限制

在 frontmatter 中禁止使用：

  • XML 尖括号 (< >)
  • 名称中包含 "claude" 或 "anthropic" 的技能（保留）

原因：Frontmatter 会出现在 Claude 的系统提示词中。恶意内容可能会注入指令。

编写有效的技能

description 字段

根据 Anthropic 的工程博客："这个元数据……提供了足够的信息，让 Claude 知道何时应该使用每个技能，而无需将所有内容加载到上下文中。"这是渐进式披露的第一层。

结构：

[它做什么] + [何时使用它] + [关键能力]

好的描述示例：

# 好 - 具体且可操作
description: 分析 Figma 设计文件并生成开发者交接文档。当用户上传 .fig 文件、询问"设计规范"、"组件文档"或"设计到代码交接"时使用。

# 好 - 包含触发短语
description: 管理 Linear 项目工作流，包括冲刺规划、任务创建和状态跟踪。当用户提到"冲刺"、"Linear 任务"、"项目规划"或要求"创建工单"时使用。

# 好 - 清晰的价值主张
description: PayFlow 的端到端客户入职工作流。处理账户创建、支付设置和订阅管理。当用户说"入职新客户"、"设置订阅"或"创建 PayFlow 账户"时使用。

不好的描述示例：

# 太模糊
描述：帮助处理项目。

# 缺失的触发器
描述：创建复杂的多页面文档系统。

# 过于技术化，无用户触发器
描述：实现具有层次关系的 Project 实体模型。

编写主要说明

在 frontmatter 之后，用 Markdown 编写实际的说明。

推荐结构：

根据你的技能调整此模板。用你的具体内容替换括号中的部分。

---
name: your-skill
description: [...]
---

# 你的技能名称

## Instructions

### 步骤 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）

Bad:

在继续之前验证数据。

包含错误处理

## 常见问题
### MCP 连接失败
如果看到"Connection refused"：
1. 验证 MCP 服务器正在运行：检查设置 &gt; 扩展
2. 确认 API 密钥有效
3. 尝试重新连接：设置 &gt; 扩展 &gt; [你的服务] &gt; 重新连接

清晰地引用打包资源

在编写查询之前，请查阅 `references/api-patterns.md` 以了解：
- 请求速率限制指导
- 分页模式
- 错误代码和处理

使用渐进式披露

保持 SKILL.md 专注于核心指令。将详细文档移至 references/ 并链接到它。（参见核心设计原则以了解三级系统的工作原理。）

下一部分第三章 测试和迭代