Biz Skill Creator

---
name: biz-skill-creator
description: 创建、修改和优化Skill的首选工具。当用户想要新建Skill、改进已有Skill、调整Skill参数、测试Skill效果、优化Skill触发准确度时使用。支持从简单prompt Skill到复杂业务Skill的全场景覆盖——简单Skill自动精简流程，复杂Skill提供结构化深挖（领域知识积累、三维度需求分析、接口封装、Mock测试、迭代改进）。即使用户没有明确说"创建Skill"，只要意图是将某个工作流、业务逻辑或重复操作封装为可复用的AI能力，都应使用此工具。
---

# Biz Skill Creator

业务Skill的全生命周期管理：创建、修改、参数调整、测试验证。支持任意业务领域，首次接触新领域时自动从设计文档提取并积累领域知识。

## 模式选择

根据用户意图判断进入哪个模式：

| 用户意图 | 模式 |
|---------|------|
| "我要做一个新的Skill" / 从零开始 | **创建模式** |
| "帮我改一下这个Skill" / 修改已有 | **修改模式** |
| "换个客户部署" / 只改参数 | **参数调整模式** |
| "先把这个领域的知识导进来" / 只导知识不做Skill | **知识导入模式** |

判断不了就直接问："你是要新建Skill、修改已有Skill、调整参数、还是先导入领域知识？"

**灵活度指引：** 下面的流程是完整版，但不是每个场景都需要走完每一步。流程服务于用户，不是用户服务于流程。根据实际情况灵活调整：

- 用户已经带着完整方案来了 → Phase 1 仍然逐步检查三维度（数据来源/判断逻辑/异常处理），但用户已明确的维度标 ✅ 跳过展开，只追问未覆盖的
- 用户说"不用测试，先用起来" → 尊重用户的判断，交付后提醒后续可以补测
- Skill 的输出是主观的（写作风格、设计审美） → 不强求断言式评分，人工审核更合适
- 纯 prompt 逻辑、无接口调用 → Phase 3 和 scripts/ 可以跳过
- 简单参数调整 → 不需要完整测试流程

如果某个标记"必须"的步骤在当前场景下明显多余，跳过它是合理的。下面各阶段会标注何时可以省略。

---

## 创建模式

### Phase 0: 领域知识准备

在需求追问之前，先确保拥有足够的领域知识。*（纯工具类 Skill——不涉及专业业务术语和领域概念——可跳过本阶段。）*

**0.1 初步了解场景：**

先问用户一句话描述要做什么，判断涉及哪个业务领域、哪些业务模块。

**0.1b 从对话上下文捕获意图：**

当前对话中可能已包含用户想要封装为Skill的工作流（如用户说"把刚才的流程做成Skill"）。如果是，先从对话历史中提取：
- 使用了哪些工具和脚本
- 执行步骤的顺序
- 用户做过的修正
- 观察到的输入/输出格式

提取后让用户确认并补充遗漏，再进入后续Phase。如果不是从对话捕获，正常继续。

**0.2 检查领域知识是否已有：**

领域知识存放在 `{SKILL_DIR}/references/domains/` 下，按领域分目录：

```
{SKILL_DIR}/references/domains/
├── <领域名>/
│   ├── _index.md        # 该领域总览（模块清单、通用术语、模块间关联）
│   ├── <模块1>.md       # 模块知识文件
│   ├── <模块2>.md
│   └── ...
└── <其他领域>/
    └── ...
```

检查用户场景涉及的领域目录和模块文件是否存在。

**0.3 根据检查结果决定下一步：**

- **领域目录和模块文件已存在** → 读取 `_index.md` 和对应模块文件，直接进入Phase 1
- **领域目录不存在或模块文件缺失** → 向用户要该领域/模块的设计文档（产品文档、需求文档、数据库设计文档等均可），然后执行0.4

**0.4 从设计文档提取领域知识（如需）：**

从用户提供的文档中提取以下信息，写入对应的知识文件：

| 提取什么 | 不提取什么 |
|---------|-----------|
| 该模块有哪些业务对象/概念（名称+一句话解释） | 具体业务规则（流程怎么走、字段怎么算） |
| 业务对象之间的关联关系 | 具体的流程步骤 |
| 该模块涉及的专业术语 | 具体的字段定义和取值范围 |
| 与其他模块的关联点 | 具体的接口定义 |
| 该模块场景下应该追问的方向 | UI/页面相关的内容 |

**模块知识文件格式：**
```markdown
# [模块名]

## 业务对象
| 对象 | 说明 | 关联 |
|------|------|------|

## 术语
| 术语 | 含义 |
|------|------|

## 与其他模块的关联
- [描述]

## 追问方向
涉及[xxx]时问：[...]
```

**领域总览 `_index.md` 格式：**
```markdown
# [领域名] 领域知识总览

## 模块清单
| 模块 | 知识文件 | 涉及的业务对象 |
|------|---------|--------------|

## 通用术语
| 术语 | 含义 |
|------|------|

## 模块间关联
- [描述]
```

写入后更新 `_index.md`。

**注意：** 提取的是"有什么"，不是"怎么做"。具体业务规则在Phase 1中向用户追问获取。

---

### 沟通风格适配

注意根据用户的技术水平调整沟通方式：
- 面向实施/产品人员：避免直接使用JSON、assertion等术语，用业务语言解释
- 面向研发人员：可以使用技术术语，讨论接口细节
- 不确定时：简短解释术语含义，或直接问用户技术背景

### Phase 1: 需求深挖

目标：把业务场景拆解到每个决策节点都有明确的数据来源和判断逻辑。

**1.1 启动 — 必须先问这两个问题：**
1. **这个Skill要做什么？** — 一句话描述（如果Phase 0已问过，直接用Phase 0的回答）
2. **给一个最典型的使用场景** — 端到端走一遍

Phase 0中已加载的领域知识用于辅助追问——知道该问什么、听懂用户在说什么。如果有可用的 MCP 工具（如文档搜索、知识库查询），主动用来调研相关背景，减少用户的解释负担。

**1.2 递归追问 — 必须按三维度结构化追问：**

对用户描述的场景拆出每个步骤，每个步骤必须明确回答以下三个问题后才算完成。*（用户带着完整方案来的，仍需对照三维度逐项确认覆盖——已明确的标 ✅ 不展开，未覆盖的仍需追问。）* 每轮追问时，先列出当前已识别的步骤，标注哪些维度已明确、哪些待追问，然后只问待追问的：

| 维度 | 追问 | 完成标准 |
|------|------|----------|
| **数据来源** | 这个数据从哪来？ | 已明确为：用户输入 / 接口查询 / 子Skill输出 / 固定配置 |
| **判断逻辑** | 怎么决定走哪条路？ | 已明确为：固定规则 / 用户选择 / AI推理（推理依据已明确） |
| **异常处理** | 拿不到/有歧义怎么办？ | 已明确为：默认值 / 报错提示 / 降级方案 |

**追问格式：** 见 `{SKILL_DIR}/references/templates.md` "Phase 1 追问格式模板"。

**不替用户做假设。** 用户说"根据历史数据推荐"→ 必须追问：接口？逻辑？无数据时怎么办？

**1.3 识别子Skill** — 同时满足逻辑独立+足够复杂+可复用时，标记为子Skill。对子Skill也必须执行同样的三维度追问。

**1.4 终止检查 — 在结束Phase 1前，必须输出完整的节点检查表。** 格式见 `{SKILL_DIR}/references/templates.md` "Phase 1 终止检查格式模板"。

### Phase 2: 需求方案输出

按 `{SKILL_DIR}/references/templates.md` "Phase 2 需求方案模板" 格式输出，不可省略任何章节。

**必须等用户明确确认后才进入Phase 3。**

### Phase 3: 接口收集

*（Skill 无外部接口调用——纯 prompt 逻辑——时跳过本阶段。）*

逐个收集。每个接口必须收集以下全部信息：
- 调用方式（HTTP GET/POST / MCP工具 / 本地函数）
- URL/路径
- 请求参数（必填/选填，类型）
- 返回数据（JSON示例）
- 认证方式
- 错误情况

接口未开发时：标记 `[待开发]`，让用户描述预期输入输出，Skill中用TODO标记。

### Phase 4: Skill生成

**以下步骤必须按顺序全部执行，不可跳过任何一步。**

**核心约束：生成的Skill内容不可超出Phase 1-3收集到的范围。** Skill 的内容不应让用户在描述其功能时感到意外——不可包含恶意代码、数据外传、或超出用户意图的隐藏行为。不可配合用户创建误导性 Skill 或用于未授权访问、数据外传的 Skill。角色扮演类 Skill（如"扮演某角色进行对话"）是可以的。

具体来说：
- Phase 1中用户说"AI自行判断"的逻辑，在生成的Skill中写为"AI根据上下文判断"，**不可自行编造具体规则或阈值**
- Phase 1中未追问到的决策节点，不可在Phase 4中自行补充逻辑
- Phase 3中未收集到的接口参数/返回值字段，不可在Skill中自行添加
- 如果Phase 4编写时发现需要补充业务逻辑或参数，**必须回到Phase 1向用户确认**，不可自行填充

**4.1 读取设计模式参考（必须）：**

在编写任何Skill内容之前，必须先读取以下三个文件：
```
读取 {SKILL_DIR}/references/workflows.md
读取 {SKILL_DIR}/references/output-patterns.md
读取 {SKILL_DIR}/references/progressive-disclosure-patterns.md
```

**4.2 初始化Skill目录（必须）：**

使用当前平台提供的Skill初始化工具创建目录结构。如果平台没有初始化工具，手动创建以下目录结构：

```
skill-name/
├── SKILL.md          # 必须
├── _meta.json        # 按平台要求，有些平台不需要
├── scripts/          # 接口调用脚本
└── references/       # 业务参考文档
```

对每个Skill（主Skill和所有子Skill）分别初始化。

**Skill 的三层加载机制：** 理解这个机制有助于决定内容放在哪一层：
1. **Metadata**（name + description）— 始终在 Claude 的上下文中，~100字，决定是否触发
2. **SKILL.md body** — 触发后加载，< 500 行，核心流程和指引
3. **Bundled resources**（references/ scripts/ assets/）— 按需加载，无上限；scripts 可以直接执行无需加载到上下文

内容越往下层放，对上下文窗口的占用越少。大段参考内容放 references/ 并在 SKILL.md 中注明何时读取。超过 300 行的 reference 文件加目录。

**4.3 编写Skill内容：**

**SKILL.md Frontmatter（必须）：**
```yaml
---
name: skill-name          # hyphen-case, max 64字符
description: 做什么+什么时候用  # max 1024字符, 不含尖括号, 这是触发机制
---
```

**SKILL.md Body必须包含以下全部章节：**
1. 业务场景描述
2. 接口调用脚本说明（见4.4）
3. 核心流程 — 每步必须包含：做什么 + 用什么脚本命令调用接口 + 返回值处理 + 异常处理
4. 子Skill调用关系（如有）— 双向写明
5. 接口认证说明

**SKILL.md限制：** 不超500行。超出时将详细内容移到references/，SKILL.md中说明何时读取。

**结构模式选择：** 流程式（单据创建）/ 任务式（数据查询）/ 条件式（分支逻辑）

**_meta.json：** 按平台要求生成。常见格式：
```json
{ "ownerId": "local", "slug": "skill-name", "version": "1.0.0", "publishedAt": "[当前ISO时间]" }
```

**references/：** 接口完整定义（JSON示例）、字段映射、业务规则等放此处。

**写作哲学：** 向模型解释"为什么"而不是堆砌 MUST/NEVER——模型有很好的理解力和 theory of mind，说清原因比强制指令更有效、更能泛化到未预见的场景。指令用祈使句（"读取接口返回值"而非"你应该读取接口返回值"）。写 Skill 时要有通用性意识：用户会在各种不同的 prompt 下使用它，不要把指令写得只适用于你测试过的那几个例子。建议先写一版草稿，然后以全新视角重读，问自己"如果我是第一次看到这个 Skill，能理解每条指令的意图吗？"——不能的就改。

**4.4 生成接口调用脚本（必须）：**

有接口调用的 Skill，所有接口必须封装为 `scripts/` 下的 Python 脚本，不可只在 SKILL.md 中写 curl 示例。*（无接口的纯 prompt Skill 不需要 scripts/。）*

脚本要求：
- 统一处理认证（Header注入）
- 统一处理错误（HTTP错误/业务错误输出到stderr）
- JSON格式化输出到stdout
- 支持命令行参数调用

生成后在SKILL.md中写明每个接口对应的脚本命令，示例：
```bash
python3 {SKILL_DIR}/scripts/xxx.py --param1 value1
```

**Mock模式：** 所有接口脚本必须支持 `--mock` 参数，返回与真实接口格式一致的示例数据。详见 `{SKILL_DIR}/references/testing-basics.md` 第2节。

**4.5 验证（必须）：**

使用当前平台提供的Skill验证工具检查生成的Skill。如果平台没有验证工具，手动检查以下项：
- SKILL.md存在且有合法的YAML frontmatter
- name字段为hyphen-case，max 64字符
- description字段不含尖括号，max 1024字符
- scripts/下的脚本语法正确（`python3 -c "import py_compile; py_compile.compile('script.py')"`)

验证失败则修复后重新验证，直到通过。

**4.6 测试验证（必须）** — 见下方"测试验证"章节。

**4.7 交付：**
1. 将Skill目录写入平台的Skill存放位置
2. 使用平台的注册机制注册新Skill（如配置文件、CLI命令等）
3. 如果有 `present_files` 工具或用户需要分发，用 `python3 -m scripts.package_skill <skill-folder>` 打包为 `.skill` 文件（手动打包时先暂存到 /tmp/，再复制到输出目录——直接写可能权限不够）
4. 将SKILL.md路径（或 .skill 文件路径）发送给用户
5. 列出所有生成的文件清单

**4.8 Description触发优化（推荐）：**

建议在 Skill 功能完成且用户确认满意后再做 description 优化，不要在 Skill 还不稳定时就开始优化触发。

Skill的 `description` 字段是触发机制的核心。优化建议：

1. description中同时写明"做什么"和"什么时候用"
2. 适当"推"一点：列出应触发的典型场景关键词，即使用户没显式提到Skill名称
3. 如需验证触发准确度，完整流程见 `{SKILL_DIR}/references/testing-tools.md` 第 1.8 节（有subagent）或第 2 节（无subagent）。简要步骤：
   - 编写 trigger_eval.json（格式见 `{SKILL_DIR}/references/schemas.md`），包含 ~20 条查询
   - 用 `{SKILL_DIR}/assets/eval_review.html` 让用户审核查询集（替换占位符后打开）
   - 有 `claude -p` 时用 `scripts/run_loop.py` 自动优化；无则手动逐条判断并调整

优化前后对比示例：
- 差："采购管理Skill"
- 好："创建和管理采购申请单。当用户提到采购申请、请购单、供应商询价、比价、采购审批时使用，即使没有直接说'采购Skill'"

---

## 修改模式

### 步骤0：领域知识检查

判断修改涉及的业务模块，检查对应的领域知识文件是否已有。不足时向用户要设计文档补充（流程同创建模式Phase 0）。

### 步骤1：导入Skill

请用户提供Skill路径或名称，读取完整内容（SKILL.md + scripts/ + references/）。

**平台注意事项：** 已安装的 Skill 路径可能是只读的。如果是，先 `cp -r <skill-path> /tmp/<skill-name>/`，在副本上编辑，完成后打包或复制回去。保留原始的目录名和 frontmatter name 字段不变（不要加 `-v2` 后缀）。

读完后简要复述业务场景和核心流程，确认理解一致。

### 步骤2：理解修改意图

用户用自然语言描述修改意图，例如：
- "把工具A换成工具B"
- "输出格式加一个字段"
- "这个场景还需要覆盖退回重提的情况"

对修改意图追问确认：改哪个步骤？新逻辑的数据来源和判断规则？是否影响其他步骤？需要新接口吗？

如需新接口，走接口收集流程（复用创建模式Phase 3）。

### 步骤3：差异对比

修改前必须展示差异对比，格式：

```markdown
## 修改对比

### 变更1：[变更描述]
**修改前：**
> [原文内容]

**修改后：**
> [新内容]

**影响范围：** [受影响的其他步骤/接口/子Skill]
```

逐条列出所有变更点。

### 步骤4：确认并执行

用户确认后执行修改。修改完成后必须执行测试验证。

### 步骤5：版本追踪

修改完成后更新版本记录：
1. `_meta.json` 的 version 字段按语义化版本递增（功能新增 minor+1，bug修复 patch+1）
2. 在Skill目录下维护 `history.json`（格式见 `{SKILL_DIR}/references/schemas.md`），记录：版本号、修改日期、变更摘要、测试通过率
3. 告知用户版本变更：旧版本 → 新版本 + 变更摘要

---

## 参数调整模式

最轻量的维护方式。只改业务参数，不碰核心逻辑。适用于客户现场部署适配。

### 步骤1：导入并识别可调参数

读取Skill完整内容，扫描并提取可调参数：

| 参数类型 | 示例 |
|---------|------|
| 客户信息 | 客户名称、机构代码 |
| 字段映射 | 接口字段名与业务字段对应关系 |
| 阈值配置 | 金额上限、分级阈值、超时天数 |
| 接口地址 | API域名、端点路径 |
| 业务常量 | 类型列表、编码、类别 |

必须输出参数清单：

```markdown
| # | 参数 | 当前值 | 所在位置 |
|---|------|--------|---------|
| 1 | 客户名称 | XX公司 | SKILL.md 第23行 |
| 2 | API地址 | http://xxx/api | scripts/query.py 第5行 |
```

### 步骤2：调整参数

用户指定参数和新值，逐个替换，展示变更确认。

**边界识别：** 如果调整实际涉及核心逻辑变更，必须提醒用户切换到修改模式。

---

## 知识导入模式

只导入领域知识，不创建Skill。适用于提前积累领域知识，后续创建Skill时直接复用。

### 步骤1：了解领域和模块
问用户要导入哪个业务领域的知识，涉及哪些模块。

### 步骤2：收集设计文档
向用户要该领域/模块的设计文档（产品文档、需求文档、数据库设计文档等均可）。

### 步骤3：提取并写入
按创建模式 Phase 0.4 的提取规则和文件格式，将知识写入 `{SKILL_DIR}/references/domains/` 对应目录。

### 步骤4：确认
输出已导入的模块清单和知识摘要，告知用户后续创建Skill时可直接使用。

---

## 测试验证

Skill 生成或修改后强烈建议执行。对于业务流程类 Skill（有接口调用、有判断逻辑），测试是发现问题最低成本的方式；对于简单的文案模板或纯 prompt Skill，用户觉得可以先跳过时尊重其判断，交付后提醒可以后续补测。

完整测试方法论见 `{SKILL_DIR}/references/testing-basics.md`，包括：
- 测试用例生成（正常/边界/异常三类）
- Mock测试流程（脚本 `--mock` 模式）
- 断言式评分（expectations格式见 `{SKILL_DIR}/references/schemas.md`）
- 脚本复用检查（多个测试中重复出现的辅助脚本应提取到 `scripts/`）
- 迭代修复闭环

**最小执行要求：** 至少3个测试用例（正常1 + 边界1 + 异常1），逐步模拟执行，输出通过/未通过结果。未通过则修复后回归测试，直到全部通过。

---

## 需求追问参考清单

业务场景匹配时参考，提醒别遗漏关键点。

**单据创建类：** 类型判断？必填字段？金额计算？附件？审批流程？草稿/暂存？模板/复制？

**数据查询类：** 查询条件？分页排序？导出？权限过滤？

**推荐/智能填充类：** 推荐依据？数据源？展示形式？用户覆盖？无结果降级？

**审批/流程类：** 节点？审批人确定？退回/加签/转审？催办？

**数据处理/ETL类：** 输入格式？清洗规则？输出目标？批量？重试？

---

## 参考文件索引

`agents/` 目录包含 subagent 指令，需要 spawn 对应 subagent 时读取：
- `agents/grader.md` — 评分：对照断言评估输出
- `agents/comparator.md` — 盲评 A/B 对比两个输出
- `agents/analyzer.md` — 溯因分析 winner 胜出原因 + benchmark 模式分析

`references/` 目录包含参考文档：
- `references/schemas.md` — evals.json / grading.json / benchmark.json / comparison.json / analysis.json 等 JSON 格式规范
- `references/testing-basics.md` — 基础测试方法（用例、mock、断言、结果对比）
- `references/testing-tools.md` — 环境适配测试（subagent 工具链、benchmark、description 优化）
- `references/testing-iteration.md` — 系统性迭代改进方法论
- `references/templates.md` — Phase 1/2 的格式模板
- `references/workflows.md` / `output-patterns.md` / `progressive-disclosure-patterns.md` — Skill 设计模式参考

`scripts/` 目录包含工具脚本（详见 `references/testing-tools.md` 第 3 节速查表）。
`eval-viewer/` 目录包含测试结果可视化工具。
`assets/` 目录包含 HTML 模板。

---

## 核心原则

**忠于用户的输入。** 整个流程的本质是把用户脑中的业务知识转化为可执行的 Skill。这意味着：你收集到什么就用什么，没收集到的不要补。接口地址、请求参数、认证方式只有用户知道——猜出来的上线必出错。判断规则是领域知识——编造的规则在用户环境中不成立。"AI自行判断"只有用户明确说了才能标记，否则等于把未确认的逻辑默认交给模型发挥。待开发的接口用 TODO 标记而非 mock 数据，因为 mock 会掩盖"接口还没到位"这个事实。

**让 Skill 可维护。** 写完的 Skill 不是一次性的——它会被修改、被测试、被换客户部署。每个决定都应该为下一次维护降低成本。接口调用封装到 `scripts/` 里，是为了统一管理认证和错误处理，也为了 `--mock` 模式能跑测试。主 Skill 和子 Skill 双向写调用关系，是因为维护时只看一方会漏掉依赖。测试中发现的重复辅助逻辑提取为脚本，避免每次调用从零写。每次修改更新 version 和 history.json，因为这是回溯"哪次改动引入了问题"的唯一线索。领域知识写入文件，下次同领域直接复用。

**流程步骤为什么存在。** 每步走完——是因为跳步遗漏的业务细节在后期的返工成本远高于前期多问一轮。修改前差异对比——是因为改错位置或误解意图后回退成本很高。参数调整识别越界——是因为看似改参数实际涉及流程变更的情况很常见。测试闭环——是因为不测试就交付的 Skill 在真实场景大概率出问题，而修复时已经没有创建时的上下文了。写 Skill 时解释 why 而非堆 MUST，因为模型理解意图后能泛化到未预见的场景。Description 要主动覆盖应触发的场景关键词，因为触发依赖 description 中的词——不列就不匹配。

**快速检查清单：**
- [ ] 接口都由用户提供，未自行假设
- [ ] 判断逻辑都有用户确认，未编造规则
- [ ] 接口调用封装在 scripts/，支持 --mock
- [ ] 主/子 Skill 双向写了调用关系
- [ ] 待开发接口标 TODO，不用 mock 冒充
- [ ] 修改前展示了差异对比
- [ ] 测试用例覆盖正常/边界/异常
- [ ] version 和 history.json 已更新
- [ ] Description 覆盖了应触发的场景关键词