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 启动 — 必须先问这两个问题：

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（必须）：

---
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： 按平台要求生成。常见格式：

{ "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 交付：

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：差异对比

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

## 修改对比

### 变更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域名、端点路径
业务常量	类型列表、编码、类别

必须输出参数清单：

| # | 参数 | 当前值 | 所在位置 |
|---|------|--------|---------|
| 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 覆盖了应触发的场景关键词