skill-builder git:20260604.010b92eA

Immutable. This exact content never changes and is served at /api/v1/blob/1e11271d9d65f68b.

---
name: skill-builder
description: >
  当用户想创建一个新的 Skill 但需求模糊、不完整或过于宽泛时使用。
  典型触发："帮我写一个写公众号的skill""做一个数据分析的skill""我想写个代码审查的skill"
  "build a skill for code review""create a skill"。也适用于用户说"写一个skill"
  "创建一个skill""设计一个skill""做一个skill"等场景。不要用于：用户问 Skill
  概念性问题（"什么是Skill""Skill怎么写"）、用户已有详细任务卡或规格、用户要修改
  已有 Skill。
description_en: >
  Guide vague Skill ideas into executable task cards and high-quality SKILL.md files
overview_en: >
  Turns vague Skill ideas into executable task cards through structured interviews, then generates high-quality SKILL.md files.
---

# Skill Builder

## 目标

把模糊的 Skill 想法，通过结构化访谈收敛为可执行任务卡，再生成高质量 SKILL.md。

## 开始前准备

1. **意图确认**：用户要创建新 Skill（非讨论概念、非修改已有 Skill）
2. **模糊度判断**：
   - 用户能说清「触发条件 + 交付物 + 质量标准」→ 跳过澄清，直接 Phase 2
   - 用户只说"我想要一个 XXX 的 skill"→ 完整走 Phase 1-5
3. **位置确认**：在 Phase 1 中询问 Skill 放在项目 skills/ 还是全局 skills/

## 工作流程

### Phase 1: 需求澄清

**原则**：每次只问一组（≤ 3 个），等用户回答再继续。用户说"不知道"时给具体建议。

#### Group A: 核心任务（必须先问）

1. 这个 Skill 替你重复做哪一件具体的事？
   - 说清语言、粒度、输出格式。无法一句话说清交付物 → 还不该写成 Skill
2. 用户怎么触发它？
   - 中英文话术、最短触发词，如 "review this PR" "帮我审查代码"
3. 最终交付什么？
   - 一个文件？一份报告？一个 JSON？一组文件？

**产出**：一句话任务定义 + 触发词列表 + 交付物格式

#### Group B: 边界（等 Group A 答完再问）

4. 什么情况下绝对不该触发？
   - 如 "只改了一个标点符号的 PR" "问代码库用什么框架而非审查意图"
5. 需要什么输入才能开始？
   - 必须有文件路径？必须有上下文？没拿到时必须停下来问
6. 需要调用什么外部工具/API/脚本？
   - 列出具体的，不写"需要工具支持"

**产出**：排除场景清单 + 必需输入清单 + 依赖清单

#### Group C: 质量标准（等 Group B 答完再问）

7. 什么算"做得好"？什么算"搞砸了"？
   - 可验证标准，如 "PR 审查列 ≥3 个具体问题" "代码能通过 lint"
8. 最常见的失败模式是什么？
   - 每次都要纠正的漏掉/错误 → Skill 里重点防御
9. 什么情况下必须停下来问你？
   - 如 "PR 超过 500 行" "依赖不明确" "用户要求跳过测试"

**产出**：≥3 条可验证质量标准 + 失败模式列表 + 停止条件

**防跳过**：即使用户说得很清楚，至少确认 Group A 的 3 个问题。用户说"随便"时给具体建议并要求确认。

### Phase 2: 任务卡生成

将 Phase 1 信息整理为结构化任务卡，**用户确认后才能进入 Phase 3**。

**任务卡模板**：

| 维度 | 内容 |
|------|------|
| **任务** | [一句话说清做什么、交付什么] |
| **触发** | [用户话术（中英文），含关键词] |
| **不触发** | [明确排除的场景] |
| **输入** | [必须从用户获取的信息] |
| **输出** | [最终交付物及其格式] |
| **质量门槛** | [≥3 条可验证标准] |
| **失败信号** | [最常见失败模式和防御策略] |
| **停止条件** | [什么情况必须停下来问人] |
| **依赖** | [工具、API、脚本、外部资源] |
| **放置位置** | [项目/全局 skills/] |

**防跳过**：必须等用户说"确认""OK""没问题"后才能继续。

### Phase 3: SKILL.md 生成

按以下规范生成完整的 SKILL.md。

#### 3.1 YAML Frontmatter

```yaml
---
name: skill-name        # 1-64字符，仅小写字母/数字/连字符
description: >
  [只写触发条件，不写工作流程！
   包含：什么场景触发 + 用户会说什么 + 什么场景不触发。
   前50字符必须独立可读（Skill 列表可能被截断）。
   用祈使语气。]
---
```

**Description 检查清单**：
- [ ] 只描述触发条件，没有总结工作流程
- [ ] 包含用户会说的具体话术关键词（中英文）
- [ ] 明确排除了不该触发的场景
- [ ] 前 50 字符独立可读
- [ ] 无"助力""赋能"等空洞词
- [ ] 读完能回答：何时用、何时不用、交付什么

#### 3.2 Body 结构

```
# [Skill 名称]

## 目标
[一句话说明最终成果]

## 开始前准备
- [检查所需输入是否齐全，仅在缺失导致无法开展时提问]
- [确认环境/依赖可用]

## 工作流程
### Step 1: [步骤名]
[可执行动作，每步有明确产出物。最后一步必须是交付确认。]

## 质量标准
- [具体、可验证，每条能用"是/否"判断]
- [✅ "输出包含引用来源"  ❌ "输出质量要高"]

## 最终反馈
[任务结果、生成文件路径、核验状态、已知局限、下一步建议]
```

#### 3.3 脚本 vs Markdown 分工

| 放 scripts/ | 放 references/ | 留在 body |
|---|---|---|
| 统计、校验、格式转换 | API 文档、数据库 schema | 判断逻辑、工作流程 |
| 重复计算的确定性操作 | 长模板、规范文档 | 质量门槛、退出标准 |
| 跨平台工具代码 | 领域知识、术语表 | 触发条件、依赖说明 |

#### 3.4 正文编写原则

1. **默认 Agent 已经聪明**：不解释基础概念，只写这项任务必须遵守的
2. **可执行 > 百科式**：每步有产出物，不写"分析一下""检查一下"
3. **克制行数**：正文 ≤ 200 行，内容多就拆到 references
4. **跨平台兼容**：用能力描述而非工具名（如"检索匹配的内容模式"而非"grep -r"）

### Phase 4: 质量审查

生成 SKILL.md 后逐项检查，**任一项不通过则回修**。

| # | 检查项 | 标准 |
|---|--------|------|
| 🔴 1 | Description 纯触发 | 只写触发条件，不总结工作流程 |
| 🔴 2 | 四块结构完整 | 目标、开始前准备、工作流程、质量标准、最终反馈 |
| 🔴 3 | 步骤可执行 | 每步有明确产出物 |
| 🔴 4 | 质量标准可验证 | 每条可用"是/否"判断 |
| 🔴 5 | 退出标准明确 | 知道最后交付什么、什么时候停 |
| 🔴 6 | 行数克制 | Body ≤ 200 行，长资料拆到 references |

### Phase 5: 测试场景建议

为生成的 Skill 建议 3 类测试场景，附在 SKILL.md 后：

- **标准场景**：用户说得很清楚，素材齐全。验证主流程能跑通
- **缺口场景**：用户只给半截信息。验证缺关键信息时会不会乱猜
- **诱惑场景**：用户催得急 / 要求跳过验证 / 让直接给结论。验证质量门槛能不能顶住

## 质量标准

- [ ] 每个 Phase 产生明确产出物，无"分析一下""检查一下"
- [ ] 任务卡经用户明确确认后才进入 Phase 3
- [ ] 生成的 SKILL.md 通过 Phase 4 全部 6 项检查
- [ ] Description 只写触发条件，不总结工作流程
- [ ] 3 类测试场景完整，不省略
- [ ] 交付摘要含：名称、位置、行数、通过检查数、已知局限

## 防偷懒规则

| 借口 | 事实 |
|------|------|
| "用户说清楚了，直接写" | 至少确认 Group A 3 个问题。看起来清楚 ≠ 真对齐 |
| "任务卡我直接填" | 任务卡必须用户确认，自填 = 自猜 |
| "description 顺便总结工作流程" | 禁止。会导致跳过阅读正文，经过验证的反模式 |
| "这个 Skill 很简单，省掉质量标准" | 最简单的事也有搞砸方式，至少 3 条质量标准 |
| "用户让我快点，跳过审查" | 至少完成 Phase 4 的 4 项 Critical（🔴 1-4） |
| "测试场景用户自己会想" | 3 类测试场景是标准交付物，不省略 |

## 退出标准

1. ✅ 用户确认的任务卡
2. ✅ 完整的 SKILL.md（通过 Phase 4 全部 6 项检查）
3. ✅ 3 类测试场景建议
4. ✅ 输出摘要：名称、位置、行数、通过检查数、已知局限
5. ⚠️ 标注仍存在的风险和下一步建议（如有）

---

## 参考资料

- 设计模式选择指南：见 `references/design-patterns.md`