skill-builder · diff
git:20260604.010b92e to v1.0.0
103 added, 156 removed. Audit A to A.
---
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.
+ 通过渐进式需求澄清、工作流设计、资源拆分、实现和评测，创建或优化高质量 Agent Skill。适用于“创建一个 skill”“把工作流封装成 skill”“优化 SKILL.md”“补充 scripts、references、assets 或 evals”等请求。Use when a user wants a standards-compliant, maintainable, testable Agent Skill package rather than prompt text alone.
+ license: MIT
+ compatibility: Requires local filesystem access and Python 3 for repository validation; optional external tools depend on the skill being built.
+ metadata:
+ author: "sanqi-cd"
+ version: "1.0.0"
+ emoji: "🧰"
+ description_zh: "把模糊想法打磨成符合规范、可执行、可维护、可评测的 Agent Skill。"
+ description_en: "Turn a rough idea into a standards-compliant, executable, maintainable, and evaluable Agent Skill."
+ overview_zh: "从需求到实现与评测，完整构建高质量 Agent Skill。"
+ overview_en: "Build high-quality Agent Skills from requirements through implementation and evaluation."
+ platforms: "Claude Code · Codex · OpenCode · OpenClaw"
---
- # Skill Builder
+ # Agent Skill 构建器
## 目标
- 把模糊的 Skill 想法，通过结构化访谈收敛为可执行任务卡，再生成高质量 SKILL.md。
+ 把一个想法或已有 Skill 直接推进到结构合规、指令清晰、资源克制、脚本可靠、评测可复现的完整能力包。除非关键信息确实无法推断，不要停在建议或模板阶段。
- ## 开始前准备
+ ## 核心原则
- 1. **意图确认**：用户要创建新 Skill（非讨论概念、非修改已有 Skill）
- 2. **模糊度判断**：
- - 用户能说清「触发条件 + 交付物 + 质量标准」→ 跳过澄清，直接 Phase 2
- - 用户只说"我想要一个 XXX 的 skill"→ 完整走 Phase 1-5
- 3. **位置确认**：在 Phase 1 中询问 Skill 放在项目 skills/ 还是全局 skills/
+ - 先读现状：修改已有 Skill 时，先完整读取 `SKILL.md`、已引用资源、脚本、测试和仓库约定。
+ - 只问阻塞问题：能从上下文合理推断的内容直接处理；必须提问时每轮不超过 3 个。
+ - 渐进披露：主文件保留触发、决策、流程和质量门槛，长知识放 references，确定性操作放 scripts。
+ - 验证比例随风险增长：至少覆盖正常输入、缺失输入和边界输入；共享脚本需要单元测试。
+ - 描述决定发现：`description` 同时写清任务、典型触发、边界和交付结果，不塞入完整工作流。
+ - 自动推进：用户已经授权实施时，各阶段通过后直接进入下一阶段，不重复索要确认。
## 工作流程
- ### 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 答完再问）
+ ### 1. 建立任务契约
- 7. 什么算"做得好"？什么算"搞砸了"？
- - 可验证标准，如 "PR 审查列 ≥3 个具体问题" "代码能通过 lint"
- 8. 最常见的失败模式是什么？
- - 每次都要纠正的漏掉/错误 → Skill 里重点防御
- 9. 什么情况下必须停下来问你？
- - 如 "PR 超过 500 行" "依赖不明确" "用户要求跳过测试"
+ 从用户输入和现有文件中提取：
- **产出**：≥3 条可验证质量标准 + 失败模式列表 + 停止条件
+ - 用户要反复完成的具体任务。
+ - 典型触发话术与相邻但不应触发的请求。
+ - 必需输入、可选输入和合理默认值。
+ - 最终交付物、保存位置和完成信号。
+ - 依赖的工具、网络、凭据、运行时或应用。
+ - 至少 3 条可判定的质量标准和主要失败模式。
- **防跳过**：即使用户说得很清楚，至少确认 Group A 的 3 个问题。用户说"随便"时给具体建议并要求确认。
+ 只有触发边界、交付格式或高风险行为仍不明确时才提问。用户给出完整规格时直接进入设计；用户只给一句模糊想法时，优先询问“最终交付什么”“谁会在什么场景触发”“什么算成功”。
- ### Phase 2: 任务卡生成
+ 产出一份内部任务契约。只有存在会改变实现方向的互斥选择时才展示给用户确认，不把确认仪式当成固定门槛。
- 将 Phase 1 信息整理为结构化任务卡，**用户确认后才能进入 Phase 3**。
+ ### 2. 设计最小能力包
- **任务卡模板**：
+ 默认结构：
- | 维度 | 内容 |
- |------|------|
- | **任务** | [一句话说清做什么、交付什么] |
- | **触发** | [用户话术（中英文），含关键词] |
- | **不触发** | [明确排除的场景] |
- | **输入** | [必须从用户获取的信息] |
- | **输出** | [最终交付物及其格式] |
- | **质量门槛** | [≥3 条可验证标准] |
- | **失败信号** | [最常见失败模式和防御策略] |
- | **停止条件** | [什么情况必须停下来问人] |
- | **依赖** | [工具、API、脚本、外部资源] |
- | **放置位置** | [项目/全局 skills/] |
+ ```text
+ skill-name/
+ ├── SKILL.md
+ ├── agents/
+ │ └── openai.yaml
+ ├── scripts/ # 仅在确定性操作能提高可靠性时添加
+ ├── references/ # 仅放按需读取的领域知识或长规范
+ ├── assets/ # 仅放最终输出会直接使用的模板或素材
+ └── evals/
+ ├── evals.json
+ └── trigger-evals.json
+ ```
- **防跳过**：必须等用户说"确认""OK""没问题"后才能继续。
+ 不要为了目录完整而创建空目录。脚本、引用和资产必须在主文件中说明何时使用；每个引用从 `SKILL.md` 直接链接，避免多层引用链。
- ### Phase 3: SKILL.md 生成
+ 选择适合的工作流模式时读取 `references/design-patterns.md`。
- 按以下规范生成完整的 SKILL.md。
+ ### 3. 编写标准元数据
- #### 3.1 YAML Frontmatter
+ 顶层只使用 Agent Skills 标准字段：
```yaml
---
- name: skill-name # 1-64字符，仅小写字母/数字/连字符
+ name: skill-name
description: >
- [只写触发条件，不写工作流程！
- 包含：什么场景触发 + 用户会说什么 + 什么场景不触发。
- 前50字符必须独立可读（Skill 列表可能被截断）。
- 用祈使语气。]
+ [做什么；用户何时会需要；典型话术；相邻边界；最终交付什么。]
+ license: MIT
+ compatibility: [运行时、工具、网络或应用要求。]
+ metadata:
+ author: "author-name"
+ version: "1.0.0"
---
```
- **Description 检查清单**：
- - [ ] 只描述触发条件，没有总结工作流程
- - [ ] 包含用户会说的具体话术关键词（中英文）
- - [ ] 明确排除了不该触发的场景
- - [ ] 前 50 字符独立可读
- - [ ] 无"助力""赋能"等空洞词
- - [ ] 读完能回答：何时用、何时不用、交付什么
-
- #### 3.2 Body 结构
-
- ```
- # [Skill 名称]
-
- ## 目标
- [一句话说明最终成果]
-
- ## 开始前准备
- - [检查所需输入是否齐全，仅在缺失导致无法开展时提问]
- - [确认环境/依赖可用]
+ 要求：
- ## 工作流程
- ### Step 1: [步骤名]
- [可执行动作，每步有明确产出物。最后一步必须是交付确认。]
+ - `name` 与目录名完全一致，只含小写字母、数字和单连字符，长度不超过 64。
+ - `description` 非空且不超过 1024 字符，使用具体名词和用户话术，不依赖只有作者懂的简称。
+ - 自定义展示信息放进 `metadata`，所有值使用字符串。
+ - 仅在 Skill 确实需要时声明 `allowed-tools`；不要用它掩盖未说明的依赖。
- ## 质量标准
- - [具体、可验证，每条能用"是/否"判断]
- - [✅ "输出包含引用来源" ❌ "输出质量要高"]
+ 为支持相应客户端的仓库补充 `agents/openai.yaml`。所有字符串加引号，`default_prompt` 必须明确提到 `$skill-name`；只有用户或项目规范明确要求时才加入品牌色等可选字段。
- ## 最终反馈
- [任务结果、生成文件路径、核验状态、已知局限、下一步建议]
- ```
+ ### 4. 编写可执行指令
- #### 3.3 脚本 vs Markdown 分工
+ 正文使用祈使语气，包含：
- | 放 scripts/ | 放 references/ | 留在 body |
- |---|---|---|
- | 统计、校验、格式转换 | API 文档、数据库 schema | 判断逻辑、工作流程 |
- | 重复计算的确定性操作 | 长模板、规范文档 | 质量门槛、退出标准 |
- | 跨平台工具代码 | 领域知识、术语表 | 触发条件、依赖说明 |
+ 1. 一句话目标。
+ 2. 开始条件和输入缺失策略。
+ 3. 有顺序、分支和产出物的工作流。
+ 4. 错误、降级、重试和停止条件。
+ 5. 可用“通过/不通过”判断的质量标准。
+ 6. 最终交付内容、文件路径和已知局限。
- #### 3.4 正文编写原则
+ 避免重复常识、空泛角色扮演和无法验证的“高质量”“深入分析”。正文接近 500 行时必须拆分；引用文件只保留完成任务所需的信息。
- 1. **默认 Agent 已经聪明**：不解释基础概念，只写这项任务必须遵守的
- 2. **可执行 > 百科式**：每步有产出物，不写"分析一下""检查一下"
- 3. **克制行数**：正文 ≤ 200 行，内容多就拆到 references
- 4. **跨平台兼容**：用能力描述而非工具名（如"检索匹配的内容模式"而非"grep -r"）
+ ### 5. 实现确定性资源
- ### Phase 4: 质量审查
+ 以下内容优先写成脚本：解析、转换、命名、批处理、结构验证、统计和可重复渲染。脚本必须：
- 生成 SKILL.md 后逐项检查，**任一项不通过则回修**。
+ - 使用明确参数和非零失败码。
+ - 不依赖作者机器上的固定绝对路径。
+ - 对覆盖文件、网络失败、无效输入和缺失依赖给出可执行错误信息。
+ - 在至少一个正常案例和一个失败案例上实际运行。
- | # | 检查项 | 标准 |
- |---|--------|------|
- | 🔴 1 | Description 纯触发 | 只写触发条件，不总结工作流程 |
- | 🔴 2 | 四块结构完整 | 目标、开始前准备、工作流程、质量标准、最终反馈 |
- | 🔴 3 | 步骤可执行 | 每步有明确产出物 |
- | 🔴 4 | 质量标准可验证 | 每条可用"是/否"判断 |
- | 🔴 5 | 退出标准明确 | 知道最后交付什么、什么时候停 |
- | 🔴 6 | 行数克制 | Body ≤ 200 行，长资料拆到 references |
+ 领域知识、API 规范、长模板和评分量表放 references。输出模板或二进制素材放 assets。删除未被工作流使用的资源。
- ### Phase 5: 测试场景建议
+ ### 6. 建立评测
- 为生成的 Skill 建议 3 类测试场景，附在 SKILL.md 后：
+ 每个 Skill 至少提供：
- - **标准场景**：用户说得很清楚，素材齐全。验证主流程能跑通
- - **缺口场景**：用户只给半截信息。验证缺关键信息时会不会乱猜
- - **诱惑场景**：用户催得急 / 要求跳过验证 / 让直接给结论。验证质量门槛能不能顶住
+ - 触发评测：不少于 6 个正例和 6 个难负例，覆盖中英文、口语化请求和相邻能力混淆。
+ - 输出评测：不少于 3 个案例，包含标准场景、缺口场景和失败/边界场景。
+ - 每个输出案例包含可观察 assertions，不以“看起来不错”作为标准。
- ## 质量标准
+ 条件允许时，对代表性案例做启用 Skill 与不启用 Skill 的对照运行，记录成功率、遗漏和副作用。没有模型或凭据时仍要校验评测 JSON 的结构，并明确说明尚未运行模型评测。
- - [ ] 每个 Phase 产生明确产出物，无"分析一下""检查一下"
- - [ ] 任务卡经用户明确确认后才进入 Phase 3
- - [ ] 生成的 SKILL.md 通过 Phase 4 全部 6 项检查
- - [ ] Description 只写触发条件，不总结工作流程
- - [ ] 3 类测试场景完整，不省略
- - [ ] 交付摘要含：名称、位置、行数、通过检查数、已知局限
+ ### 7. 验证并回修
- ## 防偷懒规则
+ 按仓库已有工具优先执行：
- | 借口 | 事实 |
- |------|------|
- | "用户说清楚了，直接写" | 至少确认 Group A 3 个问题。看起来清楚 ≠ 真对齐 |
- | "任务卡我直接填" | 任务卡必须用户确认，自填 = 自猜 |
- | "description 顺便总结工作流程" | 禁止。会导致跳过阅读正文，经过验证的反模式 |
- | "这个 Skill 很简单，省掉质量标准" | 最简单的事也有搞砸方式，至少 3 条质量标准 |
- | "用户让我快点，跳过审查" | 至少完成 Phase 4 的 4 项 Critical（🔴 1-4） |
- | "测试场景用户自己会想" | 3 类测试场景是标准交付物，不省略 |
+ 1. 官方或仓库级 Skill 结构校验。
+ 2. 所有脚本的语法检查和单元测试。
+ 3. 所有本地引用路径存在性检查。
+ 4. 评测数据 schema 检查。
+ 5. README、目录或清单同步检查。
+ 6. Git diff 审查，确认没有缓存、密钥、用户产物和无关改动。
- ## 退出标准
+ 任一确定性门禁失败时直接回修并重跑。外部服务、凭据或视觉人工判断无法自动验证时，列为残余风险，不伪造通过结果。
- 1. ✅ 用户确认的任务卡
- 2. ✅ 完整的 SKILL.md（通过 Phase 4 全部 6 项检查）
- 3. ✅ 3 类测试场景建议
- 4. ✅ 输出摘要：名称、位置、行数、通过检查数、已知局限
- 5. ⚠️ 标注仍存在的风险和下一步建议（如有）
+ ## 质量标准
- ---
+ - [ ] 触发描述能区分至少一个相邻但不应触发的请求。
+ - [ ] 顶层元数据符合开放标准，名称与目录一致。
+ - [ ] 主流程、降级路径、失败条件和最终交付都明确。
+ - [ ] 所有引用存在，脚本可独立执行且有失败码。
+ - [ ] 至少 12 个触发案例和 3 个输出案例通过结构校验。
+ - [ ] 确定性测试与仓库发布门禁全部通过。
+ - [ ] 最终报告区分“已验证”“需外部环境验证”和“已知局限”。
- ## 参考资料
+ ## 最终反馈
- - 设计模式选择指南：见 `references/design-patterns.md`
+ 向用户报告 Skill 名称、实际改动、关键设计决策、测试命令与结果、未运行的模型/外部集成评测，以及生成文件的完整路径。不要重复整份任务契约，也不要在任务已经完成后强制追加确认步骤。