skill-builder

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

---
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