| 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。
开始前准备
- 意图确认：用户要创建新 Skill（非讨论概念、非修改已有 Skill）
- 模糊度判断：
- 用户能说清「触发条件 + 交付物 + 质量标准」→ 跳过澄清，直接 Phase 2
- 用户只说"我想要一个 XXX 的 skill"→ 完整走 Phase 1-5
- 位置确认：在 Phase 1 中询问 Skill 放在项目 skills/ 还是全局 skills/
工作流程
Phase 1: 需求澄清
原则：每次只问一组（≤ 3 个），等用户回答再继续。用户说"不知道"时给具体建议。
Group A: 核心任务（必须先问）
- 这个 Skill 替你重复做哪一件具体的事？
- 说清语言、粒度、输出格式。无法一句话说清交付物 → 还不该写成 Skill
- 用户怎么触发它？
- 中英文话术、最短触发词，如 "review this PR" "帮我审查代码"
- 最终交付什么？
产出：一句话任务定义 + 触发词列表 + 交付物格式
Group B: 边界（等 Group A 答完再问）
- 什么情况下绝对不该触发？
- 如 "只改了一个标点符号的 PR" "问代码库用什么框架而非审查意图"
- 需要什么输入才能开始？
- 必须有文件路径？必须有上下文？没拿到时必须停下来问
- 需要调用什么外部工具/API/脚本？
产出：排除场景清单 + 必需输入清单 + 依赖清单
Group C: 质量标准（等 Group B 答完再问）
- 什么算"做得好"？什么算"搞砸了"？
- 可验证标准，如 "PR 审查列 ≥3 个具体问题" "代码能通过 lint"
- 最常见的失败模式是什么？
- 每次都要纠正的漏掉/错误 → Skill 里重点防御
- 什么情况下必须停下来问你？
- 如 "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
---
name: skill-name
description: >
[只写触发条件，不写工作流程！
包含：什么场景触发 + 用户会说什么 + 什么场景不触发。
前50字符必须独立可读（Skill 列表可能被截断）。
用祈使语气。]
---
Description 检查清单：
3.2 Body 结构
# [Skill 名称]
## 目标
[一句话说明最终成果]
## 开始前准备
- [检查所需输入是否齐全，仅在缺失导致无法开展时提问]
- [确认环境/依赖可用]
## 工作流程
### Step 1: [步骤名]
[可执行动作，每步有明确产出物。最后一步必须是交付确认。]
## 质量标准
- [具体、可验证，每条能用"是/否"判断]
- [✅ "输出包含引用来源" ❌ "输出质量要高"]
## 最终反馈
[任务结果、生成文件路径、核验状态、已知局限、下一步建议]
3.3 脚本 vs Markdown 分工
| 放 scripts/ | 放 references/ | 留在 body |
|---|
| 统计、校验、格式转换 | API 文档、数据库 schema | 判断逻辑、工作流程 |
| 重复计算的确定性操作 | 长模板、规范文档 | 质量门槛、退出标准 |
| 跨平台工具代码 | 领域知识、术语表 | 触发条件、依赖说明 |
3.4 正文编写原则
- 默认 Agent 已经聪明：不解释基础概念，只写这项任务必须遵守的
- 可执行 > 百科式：每步有产出物，不写"分析一下""检查一下"
- 克制行数：正文 ≤ 200 行，内容多就拆到 references
- 跨平台兼容：用能力描述而非工具名（如"检索匹配的内容模式"而非"grep -r"）
Phase 4: 质量审查
生成 SKILL.md 后逐项检查，任一项不通过则回修。
| # | 检查项 | 标准 |
|---|
| 🔴 1 | Description 纯触发 | 只写触发条件，不总结工作流程 |
| 🔴 2 | 四块结构完整 | 目标、开始前准备、工作流程、质量标准、最终反馈 |
| 🔴 3 | 步骤可执行 | 每步有明确产出物 |
| 🔴 4 | 质量标准可验证 | 每条可用"是/否"判断 |
| 🔴 5 | 退出标准明确 | 知道最后交付什么、什么时候停 |
| 🔴 6 | 行数克制 | Body ≤ 200 行，长资料拆到 references |
Phase 5: 测试场景建议
为生成的 Skill 建议 3 类测试场景，附在 SKILL.md 后：
- 标准场景：用户说得很清楚，素材齐全。验证主流程能跑通
- 缺口场景：用户只给半截信息。验证缺关键信息时会不会乱猜
- 诱惑场景：用户催得急 / 要求跳过验证 / 让直接给结论。验证质量门槛能不能顶住
质量标准
防偷懒规则
| 借口 | 事实 |
|---|
| "用户说清楚了，直接写" | 至少确认 Group A 3 个问题。看起来清楚 ≠ 真对齐 |
| "任务卡我直接填" | 任务卡必须用户确认，自填 = 自猜 |
| "description 顺便总结工作流程" | 禁止。会导致跳过阅读正文，经过验证的反模式 |
| "这个 Skill 很简单，省掉质量标准" | 最简单的事也有搞砸方式，至少 3 条质量标准 |
| "用户让我快点，跳过审查" | 至少完成 Phase 4 的 4 项 Critical（🔴 1-4） |
| "测试场景用户自己会想" | 3 类测试场景是标准交付物，不省略 |
退出标准
- ✅ 用户确认的任务卡
- ✅ 完整的 SKILL.md（通过 Phase 4 全部 6 项检查）
- ✅ 3 类测试场景建议
- ✅ 输出摘要：名称、位置、行数、通过检查数、已知局限
- ⚠️ 标注仍存在的风险和下一步建议（如有）
参考资料
- 设计模式选择指南：见
references/design-patterns.md
