| 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/页面相关的内容 |
模块知识文件格式：
# [模块名]
## 业务对象
| 对象 | 说明 | 关联 |
|------|------|------|
## 术语
| 术语 | 含义 |
|------|------|
## 与其他模块的关联
- [描述]
## 追问方向
涉及[xxx]时问：[...]
领域总览 _index.md 格式：
# [领域名] 领域知识总览
## 模块清单
| 模块 | 知识文件 | 涉及的业务对象 |
|------|---------|--------------|
## 通用术语
| 术语 | 含义 |
|------|------|
## 模块间关联
- [描述]
写入后更新 _index.md。
注意： 提取的是"有什么"，不是"怎么做"。具体业务规则在Phase 1中向用户追问获取。
沟通风格适配
注意根据用户的技术水平调整沟通方式：
- 面向实施/产品人员：避免直接使用JSON、assertion等术语，用业务语言解释
- 面向研发人员：可以使用技术术语，讨论接口细节
- 不确定时：简短解释术语含义，或直接问用户技术背景
Phase 1: 需求深挖
目标：把业务场景拆解到每个决策节点都有明确的数据来源和判断逻辑。
1.1 启动 — 必须先问这两个问题：
- 这个Skill要做什么？ — 一句话描述（如果Phase 0已问过，直接用Phase 0的回答）
- 给一个最典型的使用场景 — 端到端走一遍
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 的三层加载机制： 理解这个机制有助于决定内容放在哪一层：
- Metadata（name + description）— 始终在 Claude 的上下文中，~100字，决定是否触发
- SKILL.md body — 触发后加载，< 500 行，核心流程和指引
- Bundled resources（references/ scripts/ assets/）— 按需加载，无上限；scripts 可以直接执行无需加载到上下文
内容越往下层放，对上下文窗口的占用越少。大段参考内容放 references/ 并在 SKILL.md 中注明何时读取。超过 300 行的 reference 文件加目录。
4.3 编写Skill内容：
SKILL.md Frontmatter（必须）：
---
name: skill-name
description: 做什么+什么时候用
---
SKILL.md Body必须包含以下全部章节：
- 业务场景描述
- 接口调用脚本说明（见4.4）
- 核心流程 — 每步必须包含：做什么 + 用什么脚本命令调用接口 + 返回值处理 + 异常处理
- 子Skill调用关系（如有）— 双向写明
- 接口认证说明
SKILL.md限制： 不超500行。超出时将详细内容移到references/，SKILL.md中说明何时读取。
结构模式选择： 流程式（单据创建）/ 任务式（数据查询）/ 条件式（分支逻辑）
_meta.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中写明每个接口对应的脚本命令，示例：
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 交付：
- 将Skill目录写入平台的Skill存放位置
- 使用平台的注册机制注册新Skill（如配置文件、CLI命令等）
- 如果有
present_files 工具或用户需要分发，用 python3 -m scripts.package_skill <skill-folder> 打包为 .skill 文件（手动打包时先暂存到 /tmp/，再复制到输出目录——直接写可能权限不够）
- 将SKILL.md路径（或 .skill 文件路径）发送给用户
- 列出所有生成的文件清单
4.8 Description触发优化（推荐）：
建议在 Skill 功能完成且用户确认满意后再做 description 优化，不要在 Skill 还不稳定时就开始优化触发。
Skill的 description 字段是触发机制的核心。优化建议：
- description中同时写明"做什么"和"什么时候用"
- 适当"推"一点：列出应触发的典型场景关键词，即使用户没显式提到Skill名称
- 如需验证触发准确度，完整流程见
{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：差异对比
修改前必须展示差异对比，格式：
## 修改对比
### 变更1：[变更描述]
**修改前：**
> [原文内容]
**修改后：**
> [新内容]
**影响范围：** [受影响的其他步骤/接口/子Skill]
逐条列出所有变更点。
步骤4：确认并执行
用户确认后执行修改。修改完成后必须执行测试验证。
步骤5：版本追踪
修改完成后更新版本记录：
_meta.json 的 version 字段按语义化版本递增（功能新增 minor+1，bug修复 patch+1）- 在Skill目录下维护
history.json（格式见 {SKILL_DIR}/references/schemas.md），记录：版本号、修改日期、变更摘要、测试通过率
- 告知用户版本变更：旧版本 → 新版本 + 变更摘要
参数调整模式
最轻量的维护方式。只改业务参数，不碰核心逻辑。适用于客户现场部署适配。
步骤1：导入并识别可调参数
读取Skill完整内容，扫描并提取可调参数：
| 参数类型 | 示例 |
|---|
| 客户信息 | 客户名称、机构代码 |
| 字段映射 | 接口字段名与业务字段对应关系 |
| 阈值配置 | 金额上限、分级阈值、超时天数 |
| 接口地址 | API域名、端点路径 |
| 业务常量 | 类型列表、编码、类别 |
必须输出参数清单：
| # | 参数 | 当前值 | 所在位置 |
|---|------|--------|---------|
| 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 中的词——不列就不匹配。
快速检查清单：
