技能创建器

技能创建器 是做什么的？

一个用于创建新技能并迭代改进它们的技能。

在高层面上，创建技能的过程如下：

• 确定你希望技能做什么以及大致如何实现
• 编写技能草稿
• 创建几个测试提示，并运行带有该技能的Claude
• 帮助用户定性和定量地评估结果
  • 在后台运行的同时，如果还没有定量的评估，请草拟一些；如果已有评估，你可以按原样使用，或者根据需要进行修改。然后向用户解释这些评估（如果已经存在，解释已有的那些）
  • 使用 eval-viewer/generate_review.py 脚本向用户展示结果供其查看，同时让他们查看定量指标
• 根据用户对结果的评估反馈重写技能（如果定量基准暴露了明显缺陷，也要进行修改）
• 重复直到满意
• 扩展测试集并以更大规模再次尝试

使用此技能时，你的工作是判断用户处于此过程的哪个阶段，然后介入并帮助他们推进这些阶段。例如，用户可能说“我想为X创建一个技能”。你可以帮助他们缩小范围，编写草稿，编写测试用例，确定评估方式，运行所有提示，然后重复。

另一方面，如果用户已经有技能草稿，你可以直接进入评估/迭代循环。

当然，你应始终灵活应变，如果用户说“不需要运行一堆评估，就跟我一起找感觉吧”，你也可以这样做。

技能完成后（但顺序是灵活的），你还可以运行技能描述优化器——我们有单独的脚本——来优化技能的触发。

酷吧？酷。

与用户沟通

技能创建器可能被熟悉各种编程行话程度的人使用。如果你还没听说（怎么可能，这是最近才开始的），现在有一股趋势，Claude的强大功能正激励着水管工打开终端，父母和祖父母们搜索“如何安装npm”。另一方面，大部分用户可能计算机素养相当高。

所以请注意上下文线索，以理解如何措辞！在默认情况下，给你一些参考：

• “评估”和“基准”是临界词汇，但可以使用
• 对于“JSON”和“断言”，你需要看到用户明显的线索表明他们知道这些是什么，才能不经解释直接使用

如果你不确定，简要解释术语是可以的，如果你不确定用户是否能理解，请放心地用简短定义澄清术语。

---

创建技能

捕获意图

首先理解用户的意图。当前对话可能已经包含用户想要捕获的工作流（例如，他们说“把这个变成技能”）。如果是这样，首先从对话历史中提取答案——使用的工具、步骤顺序、用户所做的更正、观察到的输入/输出格式。用户可能需要填补空白，并且在进入下一步之前应确认。

1. 这个技能应该让Claude做什么？
2. 什么时候应该触发这个技能？（什么用户短语/上下文）
3. 预期的输出格式是什么？
4. 我们是否应该设置测试用例来验证技能是否工作？具有客观可验证输出（文件转换、数据提取、代码生成、固定工作流步骤）的技能适合测试用例。具有主观输出（写作风格、艺术）的技能通常不需要。根据技能类型建议适当的默认值，但让用户决定。

访谈与研究

主动询问关于边缘情况、输入/输出格式、示例文件、成功标准和依赖关系的问题。等到这部分确定后再编写测试提示。

检查可用的MCP——如果对研究有用（搜索文档、查找类似技能、查阅最佳实践），如果可能通过子代理并行研究，否则内联。准备好上下文以减少用户的负担。

编写SKILL.md

根据用户访谈，填写以下组件：

• 名称：技能标识符
• 描述：何时触发，做什么。这是主要的触发机制——包括技能做什么以及在什么特定上下文中使用。所有“何时使用”信息都放在描述中，而不是正文中。注意：目前Claude倾向于“触发不足”——当技能有用时却不使用它们。为了对抗这一点，请使技能描述稍微“主动”一些。例如，不要写“如何构建一个简单的快速仪表板来显示内部Anthropic数据。”而是写“如何构建一个简单的快速仪表板来显示内部Anthropic数据。确保每当用户提到仪表板、数据可视化、内部指标或想要显示任何类型的公司数据时，即使他们没有明确要求‘仪表板’，也要使用此技能。”
• 兼容性：所需的工具、依赖（可选，很少需要）
• 技能的其余部分:)

技能编写指南

技能的组成部分

skill-name/
├── SKILL.md (必需)
│   ├── YAML前置元数据（名称、描述必需）
│   └── Markdown指令
└── 捆绑资源（可选）
    ├── scripts/    - 用于确定性/重复性任务的可执行代码
    ├── references/ - 根据需要加载到上下文中的文档
    └── assets/     - 输出中使用的文件（模板、图标、字体）

渐进式披露

技能使用三级加载系统：

1. 元数据（名称+描述） - 始终在上下文中（约100个词）
2. SKILL.md正文 - 技能触发时在上下文中（理想小于500行）
3. 捆绑资源 - 根据需要（无限制，脚本可以无需加载执行）

这些字数是大致的，如果需要，你可以自由扩展。

关键模式：

• 保持SKILL.md在500行以下；如果接近此限制，添加额外的层级结构，并明确指示使用技能的模型下一步去哪里跟进。
• 从SKILL.md中清晰引用文件，并附上何时阅读它们的指导
• 对于大型引用文件（超过300行），包含目录

领域组织：当技能支持多个领域/框架时，按变体组织：

cloud-deploy/
├── SKILL.md（工作流+选择）
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude只读取相关的引用文件。

不意外原则

不言而喻，技能不得包含恶意软件、利用代码或任何可能危及系统安全的内容。技能的内容在意图上不应让用户感到意外。不要同意创建误导性技能或旨在促进未经授权访问、数据泄露或其他恶意活动的技能。像“角色扮演为某物”之类的则是可以的。

编写模式

在指令中优先使用祈使句。

定义输出格式 - 你可以这样做：

## 报告结构
始终使用此确切模板：
# [标题]
## 执行摘要
## 关键发现
## 建议

示例模式 - 包含示例是有用的。你可以这样格式化（但如果示例中有“输入”和“输出”，你可能想稍微调整）：

## 提交信息格式
**示例1：**
输入：使用JWT令牌添加用户认证
输出：feat(auth): 实现基于JWT的认证

写作风格

尝试向模型解释为什么事情重要，而不是使用生硬的“必须”。使用心智理论，尽量使技能通用，不要过于狭窄地针对特定示例。先写草稿，然后以新眼光审视并改进它。

测试用例

编写技能草稿后，提出2-3个真实的测试提示——真实用户可能会说的话。与用户分享：[你不必使用这些确切的语言]“以下是一些我想尝试的测试用例。这些看起来对吗，还是你想添加更多？”然后运行它们。

将测试用例保存到 evals/evals.json。暂时不要编写断言——只写提示。你将在下一步（运行进行时）草拟断言。

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "用户的任务提示",
      "expected_output": "预期结果的描述",
      "files": []
    }
  ]
}

完整模式请参见 references/schemas.md（包括 assertions 字段，你将在之后添加）。

运行和评估测试用例

本节是一个连续序列——不要中途停止。不要使用 /skill-test 或其他测试技能。

将结果放在 <skill-name>-workspace/ 中，作为技能目录的兄弟目录。在工作空间内，按迭代组织结果（iteration-1/、iteration-2/ 等），在每个迭代内，每个测试用例对应一个目录（eval-0/、eval-1/ 等）。不要预先创建所有目录——只在你进行时创建。

步骤1：在同一回合中启动所有运行（带技能和基准）

对于每个测试用例，在同一回合中启动两个子代理——一个带技能，一个不带。这很重要：不要先启动带技能的运行，然后返回进行基准运行。一次性启动所有东西，这样它们大约同时完成。

带技能运行：

执行此任务:
- 技能路径: <path-to-skill>
- 任务: <eval prompt>
- 输入文件: <eval files if any, or "none">
- 将输出保存到: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- 要保存的输出: <what the user cares about — e.g., "the .docx file", "the final CSV">

基准运行（相同提示，但基准取决于上下文）：

• 创建新技能：根本不带技能。相同提示，没有技能路径，保存到 without_skill/outputs/。
• 改进现有技能：旧版本。在编辑之前，快照技能（cp -r <skill-path> <workspace>/skill-snapshot/），然后将基准子代理指向快照。保存到 old_skill/outputs/。

为每个测试用例编写一个 eval_metadata.json（断言可以为空）。根据测试的内容为每个评估起一个描述性的名称——不仅仅是“eval-0”。目录也使用这个名称。如果此迭代使用新的或修改的评估提示，为每个新的评估目录创建这些文件——不要假设它们从之前的迭代继承。

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "用户的任务提示",
  "assertions": []
}

步骤2：在运行进行时，草拟断言

不要只是等待运行完成——你可以高效利用这段时间。为每个测试用例草拟定量的断言并向用户解释。如果 evals/evals.json 中已经存在断言，请审查它们并解释它们检查什么。

好的断言是客观可验证的，并且具有描述性的名称——它们应该在基准查看器中清晰可读，使浏览结果的人立即理解每个断言检查什么。主观技能（写作风格、设计质量）更适合定性评估——不要将断言强加于需要人类判断的事情上。

草拟完成后，更新 eval_metadata.json 文件和 evals/evals.json 以包含断言。同时向用户解释他们将在查看器中看到什么——包括定性输出和定量基准。

步骤3：随着运行完成，捕获时序数据

当每个子代理任务完成时，你会收到一个包含 total_tokens 和 duration_ms 的通知。立即将此数据保存到运行目录中的 timing.json：

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

这是捕获此数据的唯一机会——它通过任务通知传来，不会持久保存在其他地方。逐个处理每个通知，而不是尝试批量处理。

步骤4：评分、聚合和启动查看器

一旦所有运行完成：

1. 为每个运行评分——启动一个评分子代理（或内联评分），读取 agents/grader.md 并根据输出评估每个断言。将结果保存到每个运行目录的 grading.json 中。grading.json 的 expectations 数组必须使用字段 text、passed 和 evidence（而不是 name/met/details 或其他变体）——查看器依赖于这些确切的字段名。对于可以通过程序检查的断言，编写并运行脚本，而不是目测——脚本更快、更可靠，并且可以在迭代之间重用。

2. 聚合为基准——从技能创建器目录运行聚合脚本：

   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   

   这将生成 benchmark.json 和 benchmark.md，其中包含每种配置的通过率、时间和令牌数，以及均值±标准差和差异。如果手动生成 benchmark.json，请参阅 references/schemas.md 查看查看器所期望的确切模式。将每个带技能版本放在其基准对应版本之前。

3. 进行分析员检查——读取基准数据并揭示聚合统计可能隐藏的模式。参见 agents/analyzer.md（“分析基准结果”部分）了解需要关注的内容——比如无论技能如何总是通过的断言（非区分性）、高方差的评估（可能不稳定）以及时间/令牌权衡。

4. 启动查看器，显示定性输出和定量数据：

   nohup python <skill-creator-path>/eval-viewer/generate_review.py
   

…

[为翻译而截断]