Skill creator

Skill Creator — 新 Skill 创建引导

本文件是创建新 Skill 的操作规程。每次新建 Skill 时必须完整执行以下 6 个步骤，禁止跳过任何步骤。

---

⚠️ Part 0 — Skill Creator 自身反幻觉规则（最高优先级）

必须读取，禁止凭记忆

1. 每次创建前必须读取 SKILL-template.md，不得用记忆中的模板内容替代 — 模板可能已更新
2. 每次创建前必须读取 html-skeleton.html，不得凭印象生成 HTML 内容
3. 若项目根存在 launcher.html，必须读取再追加注册条目 — 禁止凭猜测推断 SKILLS 数组末尾位置。若不存在 launcher.html（纯 plugin 场景），跳过 Step 5 是合规的

禁止超出用户回答范围

4. 只根据 Q1–Q8 的答案生成内容 — 不猜测用户意图，不主动扩展功能，不添加用户未要求的字段
5. 问卷完成前不生成任何文件 — 必须先完成 Step 1 并获得确认，再进入 Step 2

模板占位符处理

6. 所有 {{SKILL_ID}}、{{SKILL_NAME}}、{{SKILL_DESCRIPTION}} 占位符必须全部替换 — 完成后自检，不得有残留占位符
7. SKILL-template.md 的 Part 0 示例为通用占位格式 — 创建 Skill 后，须在 Step 6 提醒用户将 [参数名]=[值] 占位示例替换为本 Skill 领域的实际示例

文件操作安全

8. 写入前核查路径 — skills/{{SKILL_ID}}/ 路径必须与 Q1 完全一致，不得混用其他 Skill 的路径
9. launcher.html 追加后验证语法 — 追加条目后检查数组 JSON 语法（逗号、闭合括号），不得破坏已有数据
10. 写入前检查 SKILL_ID 唯一性 — 在 Step 1 收到 Q1 后，用 Glob 工具确认 skills/[Q1值]/ 目录不存在；若已存在，必须停止并要求用户更换 ID，禁止覆盖已有 Skill

步骤完整性

11. 禁止跳过 Step 4-B（evals 目录创建） — 无论 Q3/Q4/Q5 如何，evals 目录必须始终创建
12. Step 5（launcher 注册）条件化 — 若项目根有 launcher.html，不得跳过 Step 5；若无 launcher（纯 plugin 或极简项目），跳过是合规的，需在 Step 6 摘要中说明"未检测到 launcher，已跳过卡片注册"

---

Step 1 — 快速问卷

⚡ 前置环境探测（先于所有提问，静默执行）：

用 Glob 探测项目根目录结构，记录两个事实以供后续步骤使用：

• HAS_LAUNCHER = Glob launcher.html 命中与否（影响 Step 5 是否执行）
• HAS_CLIENTS = Glob clients/*/client-profile.md 命中与否（影响 Q5 是否询问）

若两者皆无，本 Skill 运行在"极简/ plugin"模式下，Step 5 整节跳过，Q5 自动为 N。

⚡ 前置验证（先于 Q1-Q8，单独提问）：

在发出 Q1-Q8 问卷之前，先向用户提一个问题：

"这个 Skill 解决什么具体问题？预计每月会使用几次？"

判断规则：

• 若描述模糊（如"备用"、"以后可能用"）或预计月使用 < 1 次 → 主动提示："这个 Skill 使用频次较低，是否确认需要创建？"，等待用户明确确认后再继续
• 若描述清晰且有合理频次 → 直接进入 Q1-Q8 问卷，无需用户再次确认

自适应问卷（两阶段）：

Phase 1 — 必问（所有 skill 都需要）

一次性发出 Q1-Q5 + Q8（共 6 个问题，一条消息）：

我需要了解以下信息来创建这个 Skill：

Q1. Skill 英文 ID（小写+连字符，如 pump-reliability、valve-inspection）
Q2. 功能描述（一句话，20字以内）
Q3. 类型：
    [A] 纯对话分析（无需 HTML 界面，Claude 直接输出结果）
    [B] 含 HTML 界面（需要前端操作界面）
    [C] 两者都要（SKILL.md 引导 + HTML 界面）
Q4. 是否需要 KB 知识库文件？（Y = 需要，N = 不需要）
Q5. 是否接入客户上下文（读取 clients/[client]/client-profile.md）？（Y / N）
    [若 HAS_CLIENTS=false，此项替换为："Q5. （本项目未检测到 clients/ 目录，已自动跳过，按 N 处理）"，不再等待用户作答]
Q8. 触发关键词（3-5 个，用 · 分隔，如「API-571 · 退化机理 · 检验计划」）

请按上述顺序回答即可。

收到用户回答后，先执行 Q1 三项检查（格式规范化 → 唯一性 → 功能重叠，细节见下方），再决定是否进入 Phase 2。

⚠️ Q1 格式规范化检查（优先执行；规范化后的值传入后续所有步骤，包括唯一性检查、目录创建、launcher 注册）：

1. 校验 Q1 是否匹配 ^[a-z0-9][a-z0-9-]*$
2. 若匹配 → 使用原值，跳到唯一性检查
3. 若不匹配，先判断能否规范化：
   • 含非 ASCII 字符（中文、日文等）→ 拒绝："ID 必须用英文，请重新输入 Q1"，等待新值
   • 规范化后为空或仅剩 1 字符 → 拒绝："ID 至少需 2 个有意义字符，请重新输入 Q1"
   • 规范化后仍含非法字符（符号、标点）→ 拒绝，说明原因
4. 可规范化时，依次应用以下规则：
   • 转小写
   • 空格、下划线 → 连字符
   • 去除版本后缀（正则 [-_ ]?v\d+(\.\d+)*$，如 -v0.1、_v1）
   • 去除点号
   • 合并连续连字符，去首尾连字符
5. 明示并等待用户确认："Q1 [原值] 不符合命名规范（需小写+连字符+数字）。建议改为 [规范化值]。使用此规范化 ID 吗？（Y = 用这个，N = 我重新输入 Q1）"
   • Y → 后续所有步骤使用 [规范化值]，在 Step 6 摘要中注明"原始输入 [原值] 已规范化为 [规范化值]"
   • N → 等待用户重新输入 Q1，重新走本检查

⚠️ Q1 唯一性检查：用 Glob 工具查询 skills/[Q1规范化值]/ 是否已存在。

• 若已存在 → 停止，告知用户 "Skill ID 已被占用，请重新选择"，等待用户提供新的 Q1 后重新检查
• 若不存在 → 继续下一步

⚠️ Q1 功能重叠检查：用 Glob 列出 skills/ 下所有现有子目录名称，与 Q2（功能描述）做语义比对：

• 若发现高度相似的现有 Skill（如用户要创建"设备退化简版"而 equipment-degradation-proforma 已存在）→ 提示用户："已有 [相似 Skill ID] 可能覆盖类似功能，确认仍需新建？"，等待用户明确确认后继续
• 若无明显重叠 → 直接继续

Q1 三项检查全部通过后，决定是否发 Phase 2：

Phase 2 — 条件问（仅当需要 launcher 卡片视觉定制时）

进入条件：Q3 ≠ A 且 HAS_LAUNCHER=true

• 条件成立 → 发送 Phase 2 问卷：

  Phase 1 收到，还需补 2 个视觉问题（launcher 卡片用）：
  
  Q6. Skill 卡片分类（在 launcher.html 中显示）：
      [1] 静设备  [2] 转动设备  [3] 工艺安全  [4] 热工  [5] 物流  [6] 通用
  Q7. 卡片图标 Emoji（从以下选一个，或自定义）：
      🔬 🔧 ⚙️ 🛢️ 🌡️ 📊 🔩 📋 ⚠️
  

• 条件不成立（Q3=A 或无 launcher）→ 跳过 Phase 2，自动应用默认值：Q6=[6]通用、Q7=⚙️。在 Step 6 摘要说明"Q6/Q7 已默认为 通用 / ⚙️，如需定制请在 launcher.html 中手动修改"。

---

Phase 2 完成（或跳过）后，复述确认一次："我将创建：ID=[Q1规范化值]（若经规范化，补注：规范化自你输入的 [原值]），类型=[Q3]，分类=[Q6]（默认/你选），继续？"，用户确认后进入 Step 2。

---

Step 2 — 读取模板并生成 SKILL.md

1. 读取 skills/skill-creator/templates/SKILL-template.md
2. 将占位符替换为用户的回答：
   • {{SKILL_ID}} → Q1 的值
   • {{SKILL_NAME}} → Q2 的值（中文或英文均可）
   • {{SKILL_DESCRIPTION}} → Q2 的值
3. 根据 Q4 和 Q5 决定保留/删除可选章节（先执行此步，再执行 item 4）：
   • Q4 = N → 删除 Part III（知识库架构）整节，同时删除 Part V Step 0 中的「0-A. 知识库预读」子节
   • Q5 = N → 删除 Part II（客户上下文接入）整节，同时删除 Part V Step 0 中的「0-B. 客户上下文注入」子节
   • Q4 = N 且 Q5 = N（双双删除）→ Step 0「预加载」整节也一并删除（含标题行和前言文字，保留「Step 1 — 数据收集与核实」）
4. 删除所有剩余 HTML 注释行（<!-- ... --> 格式）：这些是模板条件标记，不应出现在最终 SKILL.md 中
5. 写入文件：skills/{{SKILL_ID}}/SKILL.md

---

Step 3 — 生成 HTML 界面（仅当 Q3 = B 或 C）

1. 用 Bash 创建 templates/ 子目录（必须先建目录，再写文件）：

   mkdir -p "skills/{{SKILL_ID}}/templates"
   

2. 读取 skills/skill-creator/templates/html-skeleton.html
3. 将以下占位符全部替换（文件中多处出现，需全部替换）：
   • {{SKILL_ID}} → Q1 的值
   • {{SKILL_NAME}} → Q2 的值
4. 写入文件：skills/{{SKILL_ID}}/templates/{{SKILL_ID}}.html
5. 可选：若新 Skill 需要把结果交给下游 Skill 处理（如诊断 → 工单），参考 skills/skill-creator/references/cross-skill-messaging-pattern.md 实现 localStorage 握手，并在 CLAUDE.md 的握手协议表追加一行

---

Step 4 — 创建目录结构

4-A. 业务目录（仅 Q4 = Y 时执行）

Q4 = N → 跳过 4-A，直接进入 4-B。

Q4 = Y 时，用 Bash 创建知识库目录并写入索引占位：

mkdir -p "skills/{{SKILL_ID}}/kb"
mkdir -p "skills/{{SKILL_ID}}/references"

kb/INDEX.md 占位内容：

# {{SKILL_NAME}} 知识库索引

> 此文件是知识库的入口，每次分析前必须首先读取。

## 文件清单

| 文件 | 内容 | 优先级 |
|------|------|-------|
| （待填充） | （待填充） | 高 |

## 设备/场景决策树

（待填充：描述何时读取哪个 KB 文件）

4-B. Evals 目录（始终创建，无论 Q3/Q4/Q5）

mkdir -p "skills/{{SKILL_ID}}/evals"

然后从模板复制三个 stub 文件，将占位符替换为实际 Skill 信息：

复制并替换：

• skills/skill-creator/templates/evals-template/evals.json → skills/{{SKILL_ID}}/evals/evals.json
  • 替换 {{SKILL_ID}}、{{SKILL_NAME}}
• skills/skill-creator/templates/evals-template/eval_log.md → skills/{{SKILL_ID}}/evals/eval_log.md
  • 替换 {{SKILL_NAME}}、{{SKILL_ID}}，填写创建日期
• skills/skill-creator/templates/evals-template/OPTIMIZER.md → skills/{{SKILL_ID}}/evals/OPTIMIZER.md
  • 替换 {{SKILL_ID}}、{{SKILL_NAME}}

---

Step 5 — 注册到 launcher.html（条件执行）

前置判断：

• HAS_LAUNCHER=false（Step 1 已探测） → 整节跳过，直接进入 Step 6。在 Step 6 摘要中加一行："⚠️ 未检测到 launcher.html，已跳过卡片注册。如后续添加 launcher，请参考 references/launcher-card-schema.md 补注册。"
• HAS_LAUNCHER=true → 按以下步骤执行

1. 读取 launcher.html，找到 const SKILLS = [ 数组
2. 在数组末尾最后一个 } 之后，追加新条目（使用 Q6~Q8 的答案）：

  { id:'{{SKILL_ID}}',
    name:'{{SKILL_NAME}}',
    icon:'{{Q7_EMOJI}}',
    badge:'{{Q6_BADGE_CLASS}}',
    badgeText:'{{Q6_BADGE_TEXT}}',
    trigger:'{{Q8_KEYWORDS}}',
    path:'skills/{{SKILL_ID}}/templates/{{SKILL_ID}}.html' },

Q6 → badge 类名和 badgeText 映射：

Q6 回答	badge	badgeText
[1] 静设备	badge-static	静设备
[2] 转动设备	badge-rotating	转动设备
[3] 工艺安全	badge-process	工艺安全
[4] 热工	badge-thermal	热工
[5] 物流	badge-logistics	物流
[6] 通用	badge-general	通用

注意：

• 若 Q3 = A（纯对话），path 字段填 ''（空字符串）。launcher 卡片会显示，但点击时不跳转 HTML 界面，用户需通过 Claude Code 对话调用此 Skill。在 Step 6 输出摘要时，须提醒用户该 Skill 为纯对话模式，从 launcher 点击无效果。
• 确保追加位置在数组内、最后一个 } 的逗号后，且在闭合 ] 之前
• 追加后验证：JSON 语法正确（无多余逗号，无缺少逗号）

---

Step 6 — 输出摘要 + 验收清单

创建完成后，向用户输出以下摘要（Markdown 格式），并执行自检：

## ✅ Skill 创建完成：{{SKILL_ID}}

**已创建文件：**
- `skills/{{SKILL_ID}}/SKILL.md` — 操作规程（需补充业务规则）
- `skills/{{SKILL_ID}}/templates/{{SKILL_ID}}.html` — HTML 界面骨架（如适用）
- `skills/{{SKILL_ID}}/kb/INDEX.md` — 知识库索引（如适用）
- `skills/{{SKILL_ID}}/evals/evals.json` — 评估测试用例（需补充实际 test case）
- `skills/{{SKILL_ID}}/evals/eval_log.md` — 优化日志（已初始化）
- `skills/{{SKILL_ID}}/evals/OPTIMIZER.md` — 自动优化循环指南

**launcher.html 已更新：** 新 Skill 卡片已注册（badge=[分类]，icon=[emoji]）

6-A. 验收清单（自检后汇报）

在摘要之后，逐项检查并输出（每项必须明确 ✅ 或 ⚠️）：

验收检查：
✅/⚠️ SKILL.md — 7个Part均已生成，无 {{占位符}} 残留
✅/⚠️ SKILL.md Part 0 — 存在反幻觉规则，且规则1/4的示例表中已提示用户替换为领域专属示例
✅/⚠️ HTML — 所有 {{SKILL_ID}} 和 {{SKILL_NAME}} 占位符已替换（如适用）
✅/⚠️ HTML systemPrompt — 含 【TODO】 标记，提示开发者替换为实际 SKILL.md Part 0 内容
✅/⚠️ launcher.html — 新条目 JSON 语法正确（无多余/缺失逗号）
✅/⚠️ evals/evals.json — 已创建，_meta.skill 字段正确
✅/⚠️ localStorage key = "[新Skill的ID]_records"（与现有Skill不冲突）
✅/⚠️ skill_lint — 执行退出码为 0（命令见下方）

⚠️ 以下项目禁止凭印象直接标 ✅，必须使用工具执行验证：

• 第 1、3 项（占位符残留）：用 Grep 工具在 skills/[SKILL_ID]/ 目录下搜索 {{，零结果才能标 ✅

• 第 7 项（localStorage key）：Step 1 已确认 SKILL_ID 唯一，故 [SKILL_ID]_records 无冲突，标 ✅ 时在括号内注明"Step 1 Glob 已确认 ID 唯一"

• 第 8 项（skill_lint）：用 Bash 实际执行 lint，退出码为 0 才能标 ✅。若有 ERROR/WARN，逐条报告并修复；修复后重新跑直至通过。按以下顺序尝试：

  # 优先：plugin 模式（$CLAUDE_PLUGIN_ROOT 由 Claude Code 自动注入）
  python "$CLAUDE_PLUGIN_ROOT/bin/skill_lint.py" --strict --root "$CLAUDE_PROJECT_DIR"
  
  # Fallback：仓库本地模式（仅当 plugin 模式失败/变量未设置）
  python scripts/skill_lint.py --strict
  

若任一项为 ⚠️，立即说明原因并修复。

6-B. 下一步建议

下一步建议：

1. 打开 SKILL.md，填写 Part I（适用场景）、Part V（具体分析逻辑）、Part VI（输出字段）
2. ⚠️ 必做 — 替换 Part 0 示例：将 Part 0-A 规则1 和规则4 中的 [参数名]=[值] 占位示例，替换为本 Skill 领域的 2-3 个真实参数示例（参考 DMA SKILL.md 中的腐蚀参数示例格式）
3. ⚠️ 必做 — 替换 HTML system prompt：打开 templates/{{SKILL_ID}}.html，将 runAnalysis() 中的 systemPrompt 替换为 SKILL.md Part 0 的完整内容（文件中有 【TODO】 标记提示）
4. 填充 evals/evals.json 中的实际 test case（至少 3 个，含正常路径、边界拒绝、缺数据场景）
5. 如有知识库文件，放入 kb/ 并更新 kb/INDEX.md
6. 打开 launcher.html 验证新 Skill 卡片显示正常
7. Skill 完善后，使用 evals/OPTIMIZER.md 中的提示词启动自动优化循环