Skill Creator

Skill Creator — WorkBuddy 技能包生成器

概述

本技能是 SkillHub 公益专家团内部工具，由解决方案专家（帅帅/SY）调用，按 WorkBuddy Skill 标准通过交互式采集生成完整的 Skill 包目录。产出物直接交付给专家团主理人（星星），不经过公开市场上架流程。

核心原则：Skill 是纯文本的提示词工程，不需要写代码。本工具将用户需求转化为结构化的 Markdown 技能定义。

能力边界

✅ 能做什么

• 按 PDF 标准生成完整 Skill 包目录（SKILL.md + references/+ scripts/）
• 引导分阶段采集 Skill 信息（元数据、能力边界、工作流、参考资料）
• 应用 PDF §3.3 的 5 项最佳实践（明确边界、拆分步骤、补充资料、增加示例、本地验证提醒）
• 按 PDF §4.1 准入标准做质量验证（SKILL.md 完整性、能力边界清晰、指令可执行、中文友好等）
• 自动注入默认安全基线（API 密钥不硬编码、敏感信息脱敏、权限说明）

❌ 不做什么

• 不创建专家包（请使用 expert-creator）
• 不直接对终端用户提供服务（本工具由专家团内部调用，产出物经主理人审核后交付）
• 不替代 PDF 中规定的"本地反复验证"环节（最佳 3-5 轮迭代仍需用户自行测试）
• 不生成代码 Skill 中的具体业务逻辑代码（仅提供脚本目录结构与样板）

核心约束

1. Skill 包目录结构（对齐 WorkBuddy 市场标准上架结构，红线）：产物为一个完整目录，必须包含以下 5 个文件（不是可选项）：
   • SKILL.md（必须）— 主定义与对话工作流程
   • README.md（必须）— 面向开发者/审核者的技术说明文档（概览、目录结构、安装方式、参数说明、依赖与降级策略）
   • GUIDE.md（必须）— 面向终端用户的使用指南（适用场景、安装配置、效果案例、常见误区 Tips）
   • CASES.md（必须）— 至少 2-3 个完整实践案例（场景背景→问题→解决方案→输入样本→输出结果）
   • Prompt.md（必须）— 至少 5 条示例提示词（中英对照）
   • references/（按技能场景按需生成，非必需）
   • scripts/（按技能场景按需生成，非必需）
   • icons/（由图标设计专家在 Phase 2.5 独立完成，不在本工具职责范围内）
2. 元数据必填（PDF §4.1）：name / description / category / version / author 五项不可缺失
3. 正文 ≥ 200 字（PDF §4.1）：SKILL.md 指令正文部分必须不少于 200 字，否则审核不通过
4. 中文友好（PDF §4.1）：面向中文用户场景时，描述和指令应以中文为主
5. 能力边界清晰（PDF §3.3）：在 SKILL.md 开头清晰定义 Skill 能做什么、不能做什么
6. API 密钥不硬编码（PDF §4.2）：涉及 API 调用时不可在 SKILL.md 或 scripts 中硬编码密钥，需通过环境变量或 MCP 配置引入
7. 权限说明（PDF §4.2）：如涉及文件读写、网络请求等，需在元数据或正文中显式声明
8. 拆分步骤（PDF §3.3）：复杂任务必须分成清晰的多步执行流程，每步有明确的输入和输出
9. 存储路径：默认输出至 ~/.workbuddy/skills/{name}/（用户级）或用户指定的项目目录

工作流程

⚠️ 调用模式说明（红线·必读）

本工具设计文档里的 Phase 1-6 沿用了 WorkBuddy 官方 Skill 创建规范的表述习惯，字面写的是"使用 AskUserQuestion 采集"——但这是面向"直接对话式创建"场景的表述，不适用于本工具在专家团内部被解决方案专家（帅帅）调用的场景：

• 帅帅是被主理人 spawn 的团队成员（子会话），不能自己调用 AskUserQuestion（自行调用不会呈现给用户、会导致流程卡死）——这在 skillhub-solution-architect.md 中已是明确红线
• 帅帅调用本工具时，手上已经有：① 主理人任务卡里的用户需求摘要 ② 步骤3设计思路选型后用户已确认的设计方向 ③ 前序对话中用户透露的所有上下文
• 因此本工具被内部调用时，Phase 1-6 各"采集"环节的正确执行方式是：帅帅基于已有信息自动推导生成对应字段，不逐项询问用户；只有在推导后仍存在关键性缺失（如技能命名冲突、category 无法判断、涉及需要用户主观选择的边界性问题）时，才整理成清单交主理人弹卡向用户确认——这与解决方案专家自身文档里"步骤2需求细化"的定位一致（先自行判断，缺失关键信息才走用户确认这条通道）。
• 下文 Phase 1-6 中出现的"使用 AskUserQuestion 采集"，在内部调用场景下应理解为"基于已知上下文自动推导生成，缺失时才整理为确认清单交主理人"，而非逐字段发问

Phase 0：前置准备（内部调用时自动确定，不询问）

1. 内部调用时固定按 PDF v2026.4 标准生成
2. 输出目录固定为任务卡指定的技能目录（主理人已在任务卡中给出绝对路径），不询问、不使用默认路径

Phase 1：基础元数据（内部调用时自动推导生成）

基于任务卡的用户需求摘要 + 用户已确认的设计方向，自动推导生成 PDF §4.1 必填字段，不逐项询问：

⚠️ 仅当以下情况才需交主理人整理清单向用户确认：name 疑似与已有技能重名、category 完全无法归类、用户需求本身存在歧义导致无法推导 description。其余情况下必须自动填充完整，不得留空或跳过——这是本次修复的核心：此前因照搬"使用 AskUserQuestion 采集"的字面表述，实际执行时既无法真弹卡、又没有自动推导兜底，导致元数据字段缺失或敷衍填充。

Phase 2：能力边界与触发词（内部调用时自动推导生成）

按 PDF §3.3 第 1 条原则：明确能力边界 — 在 SKILL.md 开头清晰定义 Skill 能做什么、不能做什么

基于用户需求摘要 + 设计方向 + U1/U2 质量要求，自动推导生成：

1. 能做什么（3-6 条具体能力）— 从设计方向的核心工作流拆解出具体能力点，写入 ## 能力边界 → ✅ 能做什么
2. 不做什么（3-5 条明确边界）— 基于该技能主题下常见的相邻易混淆场景推导（如"志愿者工时记录"技能，边界应排除"志愿者招募""捐赠财务对账"等相邻场景），写入 ## 能力边界 → ❌ 不做什么
3. 触发关键词（用户输入哪些词时该 Skill 应该被激活）— 从技能名称、核心功能、用户原话中提炼，用于 description 字段写作（含 U1 要求的负向排除）
4. 典型用户场景（2-3 个"何时使用"场景）— 从用户需求摘要中的具体场景描述提炼

⚠️ 若用户需求摘要信息量不足以支撑以上推导（如过于模糊，仅一句话未展开），先基于设计方向做合理假设并标注 [假设：{依据}]，不因信息不足而跳过整个 Phase；假设内容在后续如与用户实际反馈冲突，属于正常整改范畴（见步骤6）。

Phase 3：核心约束与安全要求（内部调用时自动推导生成，安全基线强制注入）

按 PDF §4.2 安全要求：

自动推导生成：

1. 数据来源标准（如有）— 从任务卡上下文推导数据从哪里获取
2. 权限声明（PDF §4.2）：按技能实际工作流判断是否需要文件读写/网络请求/API 密钥，不臆造不需要的权限（最小权限原则）
3. 铁律 / 强制规则（1-3 条最重要的行为约束）— 从技能核心场景的风险点推导（如涉及个人信息的技能，铁律应包含"不外泄用户隐私"）
4. 降级策略（外部依赖不可用时如何降级）— 按 U5 通用降级机制表格套用

安全基线强制注入，不因信息不足而省略：下方"默认安全基线"章节内容必须原样注入 SKILL.md，这一步不依赖任何用户输入，无需推导也无需确认。

Phase 4：工作流程与步骤拆分（内部调用时自动推导生成）

按 PDF §3.3 第 2 条原则：拆分步骤 — 复杂任务分成清晰的多步执行流程，每步有明确的输入和输出

自动推导生成：

1. 工作流阶段数（建议 3-6 个）— 从设计方向的核心工作流直接映射为阶段划分
2. 每个阶段的核心动作 + 输入 + 输出— 基于用户需求摘要中的具体场景描述展开
3. 是否需要交互式选项（用 AskUserQuestion 选项卡）——这里指的是该技能未来面向其终端用户运行时的交互设计，与本工具自身"内部调用不弹卡"是两个不同层面的问题，不要混淆；按技能场景是否天然需要用户选择来判断
4. 降级路径（如某步失败如何处理）— 按 U5 通用降级机制表格套用

Phase 5：参考资料、脚本与示例（内部调用时自动推导生成）

按 PDF §3.3 第 3-4 条原则：补充参考资料 + 增加示例

自动推导生成：

1. 是否需要 references/ 目录？ 按技能场景是否涉及以下内容自动判断，无需询问：
   • API 文档 / 字段类型说明
   • 知识库快照（必须标注快照日期）
   • 模板（合同、报告、表单等）
   • 工作流详细模板
2. 是否需要 scripts/ 目录？（仅在需要执行命令行工具或数据处理时，按技能场景自动判断）。若需要，脚本及 SKILL.md 中的调用命令必须满足跨平台兼容（macOS / Linux / Windows 均可执行）：优先用 Python 实现，避免 .sh + Unix 专属命令作为唯一方案，调用命令需注明 Windows 下 python3 → python 的替代写法；具体约束见 references/skill-template.md §4.2.1「跨平台兼容约束」
3. 示例（input → output）：建议在 SKILL.md 中加入 1-2 组 input → output 示例

Phase 5.5：配套文档生成（红线·必做，不可省略）

⚠️ 本 Phase 是本次修复新增的必做环节：此前因核心约束条目未提及以下 4 个文件，导致产出的技能包结构性缺失。下述 4 个文件是每个 Skill 包的标配交付物，与 SKILL.md 同等地位，不因"用户没要求"而省略——它们全部基于 SKILL.md 已生成的内容自动映射展开，不需要额外询问用户：

1. README.md（技术说明文档，面向开发者/审核者）：按下方「README.md 标准模板」，从已生成的 SKILL.md 中提取 name/version/能力边界/工作流阶段/依赖降级策略等字段直接映射填充
2. GUIDE.md（使用指南，面向终端用户）：按下方「GUIDE.md 标准模板」，把 SKILL.md 的能力边界和工作流转译为终端用户视角的"适用场景/安装步骤/效果说明/常见误区"
3. CASES.md（实践案例）：按下方「CASES.md 标准模板」，基于任务卡的用户需求场景，构造 2-3 个完整案例（场景背景→问题描述→解决方案→输入样本→输出结果），案例中的机构名/项目名等具体信息如无真实素材可参照，按 U6 数据真实性原则标注为示例性质，不得声称是真实发生的案例
4. Prompt.md（示例提示词）：按下方「Prompt.md 标准模板」，从任务卡用户需求 + Phase 2 的典型用户场景中提炼至少 5 条中英对照的示例 Prompt

💡 参照样例：charity/skills/公益文书助手/（README.md、GUIDE.md、CASES.md、Prompt.md 均可作为格式参照）

Phase 6：汇总确认 + 生成 Skill 包

1. 展示完整信息摘要：以结构化表格展示所有自动推导生成的字段，附在回报主理人的消息中（供主理人审阅，非向用户弹卡确认）
2. 仅当 Phase 1-5 中标注了 [假设：...] 或存在关键性缺失时，才整理成清单交主理人弹卡向用户确认；其余情况下不产生确认环节，直接进入下一步生成
3. 生成目录结构：
   • 创建 {name}/ 根目录
   • 生成 SKILL.md（按 references/skill-template.md §二「SKILL.md 完整模板」填充，完整模板不在本文件重复展开，仅下方保留章节结构地图用于核对）
   • 生成 README.md / GUIDE.md / CASES.md / Prompt.md（按 Phase 5.5 生成，红线·不可省略）
   • 创建 references/（如有内容）+ 默认子文件
   • 创建 scripts/（如有需要）
4. 质量验证：执行下方"质量验证清单"逐项检查（含目录结构完整性检查，5 个必需文件缺一不可）
5. 产出物直接交付主理人，由主理人协调后续流程

SKILL.md 模板（唯一权威版在 references，本文件不重复展开）

⚠️ 与下方 Phase 5.5 辅助文档模板同一约定：SKILL.md 的完整模板以 references/skill-template.md §二「SKILL.md 完整模板」为唯一权威版本，生成时直接读取该文件按层级填充，本文件不再内联完整模板（历史上内联副本曾与 references 版本发生漂移——frontmatter 风格与 U 章节均不一致，故改为单份维护）。此处仅保留章节结构地图，供生成后快速核对：

必备章节结构（顺序固定，完整占位符与注释见 references/skill-template.md §二）：

1. frontmatter：name / display_name / display_name_en / description / description_zh / description_en / category / version / author / license——description 末尾必须附"⚠️ 不适用于 ×2-3"负向排除（U1）
2. 概述
3. 🎯 能力边界：✅ 能做什么 / ❌ 不做什么 + 越界拒绝模板（U2）
4. 🛠️ 工具能力契约（按需：依赖受限工具/MCP/外部 API 时必备，U3）
5. 核心约束
6. 工作流程：3-6 步，每步含输入 / 输出 / 交互点 / 降级
7. 🛡️ 实战质量规则（不可删减）：U4 前置校验 / U5 失败降级阈值表 / U6 数据真实性 / U7 完整交付保障
8. 参考资料（如有）
9. 示例：至少 1 组 input → output
10. 安全要求：含 API 密钥不硬编码、禁止读取 /.ssh、/.aws 等敏感目录
11. 降级策略
12. 质量目标：可量化指标

正文必须 ≥ 200 字（PDF §4.1）。按完整模板填充后通常 800-1500 字，已远超下限。

README.md / GUIDE.md / CASES.md / Prompt.md 标准模板

Phase 5.5 生成这 4 个文件时，按 references/companion-docs-templates.md 中的模板填充（含 README/GUIDE/CASES/Prompt 四份完整模板），不在本文件内重复展开。

category 候选值（内部参考）

默认安全基线

当用户不知道如何设计安全要求时，按以下基线注入到 SKILL.md：

## 安全要求

- **API 密钥**：本 Skill 不直接处理 API 密钥；如调用第三方服务，需通过环境变量或 MCP 配置引入，禁止在 SKILL.md / scripts/ 中硬编码
- **敏感信息**：涉及身份证号、手机号、签字盖章件等内容时，必须以占位符或脱敏后形式处理，不在对话中直接展示完整内容
- **文件读写**：仅在用户明确指定的范围内读写文件；禁止读取 ~/.ssh、~/.aws 等敏感目录
- **网络请求**：仅访问 SKILL.md 中明示的官方域名（如 {示例：techforgood.qq.com}），不向未声明的域名发起请求
- **数据可追溯**：涉及法规、案例、关键数字时附数据来源或快照日期；禁止编造"看似合理"的事实

通用质量原则（U1-U7，跨场景必备）— 摘要

💡 以下 7 项原则来自 WorkBuddy 官方对多个已上架 Skill 质量反馈的抽象提炼，适用于任何类型的 Skill。完整版（含每条原则的 SKILL.md 必备代码块模板）见 references/quality-principles-u1-u7.md，生成 Skill 正文时按需读取对应章节。

兼容映射（旧 Q1-Q6 → 新 U1-U7）及各原则的详细规则模板，见 references/quality-principles-u1-u7.md。

一键检查清单（生成 Skill 时使用）

调用 skill-creator 生成 Skill 后，必须逐项确认：

• U1 触发精准性：description 含限定关键词 + 负向排除（≥ 2 个相邻易混淆场景）
• U2 能力边界：「✅ 能做什么 / ❌ 不做什么」≥ 3 条具体边界 + 越界拒绝模板
• U3 工具能力契约：每个带限定的工具/MCP/API 都有正文说明 + 不可用时的处置
• U4 前置校验：所有涉及外部资源的步骤都有"校验 → 告知 → 执行"三阶段
• U5 失败降级：所有失败类型（工具/资源/连续否定/创意瓶颈/限流）都有阈值 + 降级动作
• U6 数据真实性：提取型/生成型场景都有禁止编造规则 + 用户审核闸门（如适用）
• U7 完整交付：长文本分段 + 错误友好处理 + 结构化输出质量自检
• 跨平台兼容（仅当含 scripts/ 或 SKILL.md 正文含命令行调用时）：脚本不依赖 macOS/Linux 专属命令（sips/cp/grep/sed 等）且无 Windows 不可用的安装 flag（如 --break-system-packages），python3/pip3 调用已注明 Windows 下改用 python/pip 的替代写法（依据 references/skill-template.md §4.2.1）

未通过的项目 → 由帅帅自行补充完善后再交付（不属于需要用户确认的关键性缺失），不因此产生额外的用户确认环节。

质量验证清单（PDF §4.1 + §4.2）

生成 Skill 包后，必须逐项检查：

元数据完整性（必填 5 项 + 推荐 4 项）

• name：小写字母+连字符，全局唯一
• description：一句话描述含触发词
• category：从 10 大分类中选一个
• version：语义化版本号（如 1.0.0）
• author：合作方名称
• display_name / display_name_en：中英展示名（推荐）
• description_zh / description_en：中英详细介绍（推荐）

内容质量

• SKILL.md 正文 ≥ 200 字
• 中文友好：面向中文用户的描述和指令以中文为主
• 能力边界清晰：开头有"✅ 能做什么 / ❌ 不做什么"章节，且含越界拒绝模板
• 实战质量规则章节齐全：U4 前置校验 / U5 失败降级阈值表 / U6 数据真实性 / U7 完整交付 四节齐全（模板已内置，不得删减）；技能依赖受限工具/MCP/外部 API 时还需含 U3 工具能力契约表
• 工作流程拆分：复杂任务分 3-6 步，每步明确输入输出
• 至少 1 组 input → output 示例

安全要求

• 不含个人隐私、内部 URL、恶意代码、违规内容
• API 密钥不硬编码（通过环境变量或 MCP 配置）
• 涉及文件读写、网络请求时已显式声明
• 没有真实身份证、手机号、密钥等敏感信息

目录结构（红线·5 个必需文件缺一不可）

• SKILL.md 在根目录
• README.md 在根目录（技术说明文档，见 Phase 5.5）
• GUIDE.md 在根目录（终端用户使用指南，见 Phase 5.5）
• CASES.md 在根目录（至少 2-3 个实践案例，见 Phase 5.5）
• Prompt.md 在根目录（至少 5 条示例提示词，见 Phase 5.5）
• 如有参考资料，放在 references/
• 如有脚本，放在 scripts/
• 如有图标，放在 icons/（推荐 32×32 PNG，由图标设计专家在 Phase 2.5 完成，非本工具产出）
• 不包含 .git、.DS_Store、__pycache__ 等垃圾文件

加分项（内部参考）

• Skill 结构完整（SKILL.md + README.md + GUIDE.md + CASES.md + Prompt.md + references/）
• U1-U7 一键检查清单全部通过

异常处理

• 用户信息不完整：对缺失字段提供合理默认值建议，标注"[待专家确认]"
• 用户中途放弃某模块：该模块用简化版本填充，标注"[简化版，可后续扩展]"
• 不知道选哪个 category：默认使用 productivity（提效），后续可由主理人确认
• 工作流过于复杂：拆分为多个 Skill（每个 Skill 聚焦一个核心能力），由专家团主理人协调编排