# Skill Creator

> 专家团内部技能编写工具。按 WorkBuddy Skill 规范自动推导生成完整的 Skill 技能包（SKILL.md + README.md + GUIDE.md + CASES.md + Prompt.md + references/）。由专家团解决方案专家（帅帅/SY）调用，基于任务卡用户需求和已确认设计方向自动填充所有字段，将用户需求转化为可交付的技能产物。当主理人委托技能编写任务、或需要生成符合 U1-U7 质量原则的 Skill 时使用。⚠️ 仅由专家团内部调用，不直接面向终端用户。

- Skill: `infometa/skill-creator` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add infometa/skill-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/infometa/skill-creator/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Tencent SSV Internal
- Author: infometa (https://skillmd.com/u/infometa)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/infometa/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`** | 技术标识符，小写字母+连字符，全局唯一 | 由技能核心功能提炼（如"志愿者工时记录"→`volunteer-hour-tracker`），若疑似与已有技能重名，交主理人确认 |
| **`display_name`** | 中文展示名 | 用户需求摘要中的技能主题直接提炼 |
| **`display_name_en`** | 英文展示名 | `display_name` 的英文翻译 |
| **`description`** | 技能描述（AI 用来判断激活时机） | 由用户需求摘要 + 设计方向合成，含触发关键词（U1 要求，见下） |
| **`description_zh`** / **`description_en`** | 中英简短介绍 | `description` 的简写版本 |
| **`category`** | 10 大场景分类之一 | 按技能核心功能匹配最接近的分类；无法判断时默认 `productivity`，不阻塞流程 |
| **`version`** | 语义化版本号 | 初次交付固定 `1.0.0`（解决方案专家关键规则已规定） |
| **`author`** | 合作方名称 | 若任务卡已含用户机构名称则直接使用；若此时机构名称尚未采集（通常在 Phase 4 才采集），先填 `{待活动运营专家采集后补充}` 占位，不阻塞技能编写本身 |

⚠️ **仅当以下情况才需交主理人整理清单向用户确认**：`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：

```markdown
## 安全要求

- **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 正文时按需读取对应章节。

| 原则 | 一句话定义 | 对应 Phase 自查项 |
|---|---|---|
| **U1** 触发精准性 | description 含正向关键词 + 至少 2 个负向排除场景 | Phase 1：自问"哪些相邻场景容易被误触发" |
| **U2** 能力边界与越界拒绝 | 越界请求主动识别+礼貌拒绝，≥3 条具体边界+拒绝模板 | Phase 2：自行推导补全 |
| **U3** 工具能力契约 | 每个工具/MCP/API 的可用范围、失败降级、禁止替代方式均显式声明 | Phase 3：逐一自问可用范围/降级/禁止方式 |
| **U4** 执行前置校验 | 涉及外部资源的步骤必须"校验→告知→执行"，不得编造结果 | Phase 4：自问资源不可用时如何处置 |
| **U5** 失败降级机制 | 每类失败都有明确阈值+降级动作（工具失败1次、连续否定2次等） | Phase 4：覆盖工具失败+资源不可用+连续否定 |
| **U6** 数据真实性原则 | 不编造事实/数据/场景/合作方，生成型场景需「新增内容标注表」 | Phase 5：所有读取/提取/生成/润色步骤强制声明 |
| **U7** 完整交付保障 | 长文本主动分段、错误友好翻译、结构化输出质量自检 | Phase 4：自问输出格式与错误展示方式 |

> 兼容映射（旧 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 聚焦一个核心能力），由专家团主理人协调编排