<!-- zh-only -->

# 技能创建器（Skill Creator）

用于**新建技能**、**迭代改进已有技能**，并**衡量技能效果**（定性 / 定量）。适用于：从零写技能、改技能、跑评测、做方差分析、优化 `description` 以提升触发率等。

## 总流程（鸟瞰）

1. 想清楚技能要做什么、大致怎么做  
2. 写一版草稿  
3. 准备若干真实用户口吻的测试提示，用「能访问该技能」的 Claude 跑一遍  
4. 帮用户**定性 + 定量**看结果  
   - 跑任务在后台进行时，可起草定量评测项（若已有可沿用或微调），并向用户解释指标含义  
   - 用 `eval-viewer/generate_review.py` 等脚本展示结果与图表  
5. 根据反馈（以及指标里暴露的明显问题）重写技能  
6. 不满意则扩大测试集、再跑  
7. 技能稳定后，可再跑「描述优化」脚本，改善触发准确度  

你的职责是判断用户卡在流程哪一步，并协助推进。例如用户说「想做个关于 X 的技能」——先收窄需求、写草稿、写用例、定评估方式、跑提示、再迭代。若用户已有草稿，可直接进入评测循环。若用户不想大规模跑 eval，也可按对方节奏「轻量协作」。

完成后（顺序可灵活）可运行**技能描述优化器**脚本，专门打磨触发文案。

---

## 与用户沟通

使用者背景差异很大：有人刚会用终端，有人非常熟悉开发。请根据对话判断用语深度。

- 「评估」「基准」一般可接受  
- 「JSON」「断言」等词，除非用户明显熟悉，否则先简短解释再使用  

拿不准时，宁可多一句定义，也不要默认对方懂行。

---

## 创建技能

### 1. 捕获意图

先理解用户要什么。若对话里已有可沉淀的工作流（例如「把刚才这套做成技能」），先从历史里抽取：用了哪些工具、步骤顺序、用户纠正过什么、输入输出长什么样；再请用户补洞并**确认**后再往下。

建议澄清：

1. 技能要让模型**具体能做什么**？  
2. **何时**应触发？（用户原话、场景）  
3. 期望**输出形态**？  
4. 要不要测试用例？——**可客观验证**的（文件转换、抽取、固定流水线）适合加；**偏主观**的（文风、美术）可省略。给出默认建议，由用户拍板。

### 2. 访谈与调研

主动问边界情况、输入输出格式、样例文件、成功标准、依赖。在信息不足前**先别**写测试提示。

可查可用 MCP 做文档检索、找类似技能、最佳实践；有子代理可并行调研。

### 3. 编写 SKILL.md

根据访谈填充：

- **name**：技能标识  
- **description**：**何时触发、做什么**。这是主要触发信号——既要写能力，也要写**具体触发语境**。注意：模型容易「欠触发」（该用时不用），因此描述可略**主动**一点。例如不要只写「如何做某仪表盘」，而要写「每当用户提到仪表盘、可视化、内部指标、公司数据展示等，即应使用本技能，即使用户没说『仪表盘』三个字」。  
- **compatibility**：工具与依赖（可选，少用）  
- **正文**：其余指令与结构  

### 技能写作要点

#### 目录结构

```
skill-name/
├── SKILL.md（必填）
│   ├── YAML 头（name、description 必填）
│   └── Markdown 正文
└── 捆绑资源（可选）
    ├── scripts/    — 可执行、确定性步骤
    ├── references/ — 按需加载的文档
    └── assets/     — 模板、图标、字体等
```

#### 渐进加载（三层）

1. **元数据**（name + description）— 始终在上下文（约百词级）  
2. **SKILL.md 正文** — 触发后加载（理想 &lt;500 行）  
3. **捆绑资源** — 按需（可很长；脚本可执行而无需整文件进上下文）  

**实践建议：**

- 正文逼近 500 行时，拆层级并写明「下一步应读哪份 reference」  
- 从正文用明确路径指向 reference，并说明**何时**读  
- 超大 reference（&gt;300 行）请加目录  

**多领域**：可按变体拆文件，例如 `references/aws.md`、`gcp.md`，模型只读相关篇。

#### 安全与预期

技能不得包含恶意软件、利用代码或误导性意图。不要协助制作用于未授权访问、窃数等用途的技能。「角色扮演」类若无害则可接受。

#### 写法

正文多用**祈使句**。需要固定输出格式时，直接给出模板，例如：

```markdown
## 报告结构
始终使用此模板：
# [标题]
## 执行摘要
## 主要发现
## 建议
```

示例可写成「输入 / 输出」对，便于模型模仿。

#### 文风

多解释**为什么**重要，少堆砌生硬 MUST。技能应**可泛化**，不要过度绑死单一例子。写完草稿后换视角再改一版。

### 测试用例

草稿完成后，拟 **2–3 条**真实用户会说的话，与用户确认后执行。

将用例写入 `evals/evals.json`（先只写 `prompt` 等，断言下一步再加）：

```json
{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "用户的任务描述",
      "expected_output": "期望结果说明",
      "files": []
    }
  ]
}
```

完整字段与 `assertions` 见上游 `references/schemas.md`。

---

## 运行与评估（概要）

**不要**使用 `/skill-test` 或其它测试类技能替代本流程。

结果放在与技能目录**同级**的 `-workspace/` 下，按轮次 `iteration-1/`、`iteration-2/`…，每轮内每个 eval 一个目录（`eval-0/`…）。**不要**一次性建空壳，做到哪建到哪。

### 第一步：同一轮次内并行拉起「带技能」与「基线」

对每个测试用例，**在同一轮对话里**各起一个子代理：

- **带技能**：指定技能路径、任务、输入文件、输出保存路径、要保留的产物类型。  
- **基线**：  
  - **新技能**：不带技能，同提示，输出到 `without_skill/outputs/`。  
  - **改旧技能**：先把旧版快照复制到 `skill-snapshot/`，基线指向快照，输出到 `old_skill/outputs/`。

每个 eval 写 `eval_metadata.json`（断言可先空），目录名用**描述性名称**，不要只用 `eval-0`。

### 第二步：任务跑时起草断言

根据期望行为写可自动检查的断言（具体字段与工具见上游英文 SKILL 与 `schemas.md`）。

### 第三步：汇总与迭代

用 `eval-viewer/generate_review.py` 等工具展示对比与指标；根据失败用例改 SKILL.md，再开新一轮 `iteration-N`。

（子代理提示词模板、JSON 字段细节、描述优化器调用方式等，以官方仓库英文版 `SKILL.md` 与 `references/` 为准。）

---

## 小结

- **description** 是触发核心，要写清场景并略「主动」  
- **正文**控制体量，长内容进 `references/`  
- **eval** 用并行「带技能 / 基线」对比，结果落盘可追溯  
- 术语对用户透明，按背景调节深度