tool-skill-optimizer

name	tool-skill-optimizer
version	1.0.0
description	分析并优化 SKILL.md 文件，使其达到 gstack 级别的结构质量。 执行 7 维诊断（硬约束、状态机、Anti-pattern、自刹车、逃生舱、 双尺度估算、完成协议），输出诊断报告 + 重写后的 SKILL.md。 当被要求「优化 skill」「review skill」「skill 质量检查」 「让这个 skill 更好」时触发。

/skill-optimizer：Skill 结构优化器

HARD GATE： 本 skill 只做两件事：诊断 + 重写 SKILL.md。 不执行被优化 skill 的任何逻辑，不修改被优化 skill 之外的文件。

---

Phase 0：加载目标

解析用户输入，确定优化目标：

输入形式	行为
/tool-skill-optimizer <skill-name>	读取 .agents/skills/<skill-name>/SKILL.md
/tool-skill-optimizer <path>	读取指定路径的 SKILL.md
无参数	列出 .agents/skills/*/SKILL.md，让用户选择

_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
_SKILLS_DIR="$_ROOT/.agents/skills"
if [ -z "$1" ]; then
  ls -d "$_SKILLS_DIR"/*/SKILL.md 2>/dev/null || echo "NO_SKILLS_FOUND"
else
  _TARGET="$_SKILLS_DIR/$1/SKILL.md"
  [ -f "$_TARGET" ] && echo "TARGET: $_TARGET" || echo "NOT_FOUND: $_TARGET"
fi

如果 NO_SKILLS_FOUND：告知用户目录下没有 skill，STOP。 如果 NOT_FOUND：告知用户文件不存在，STOP。

读取目标 SKILL.md 全文，存为 $ORIGINAL。 同时读取项目根目录的 AGENTS.md（如果存在），作为项目上下文。

---

Phase 1：七维诊断

逐维扫描 $ORIGINAL，对每个维度给出 0-10 分 + 具体缺陷。

D1：硬约束（Hard Gates）

检查 skill 是否用不可违反的禁令划定了行为边界。

GOOD: "**HARD GATE：** 不执行任何代码，只输出设计文档。"
BAD:  "请尽量不要执行代码。"（模型会忽略"尽量"）
BAD:  没有任何边界声明（模型会自由发挥）

评分标准：

• 10：有明确的 HARD GATE + 至少 2 条 "DO NOT" 规则，覆盖最危险的越权行为
• 7：有边界声明但措辞偏软（"建议不要" "尽量避免"）
• 3：只在末尾提了一句注意事项
• 0：完全没有行为边界

D2：状态机结构（Phase / Step）

检查 workflow 是否被拆分为带明确入口/出口条件的阶段。

GOOD: Phase 1 → Phase 2A（条件 X）/ Phase 2B（条件 Y）→ Phase 3
      每个 Phase 末尾有 **STOP** 断点
BAD:  "第一步做 A，第二步做 B，第三步做 C"（线性列表，无条件跳转）
BAD:  一整块文字描述流程，没有阶段划分

评分标准：

• 10：Phase 化 + 条件跳转 + 每阶段有 STOP 断点
• 7：有 Step 划分但缺少条件分支或断点
• 3：有编号但本质是线性列表
• 0：纯散文描述流程

D3：Anti-pattern 反例（GOOD/BAD 对比）

检查 skill 是否用正反对比示例来标定模型行为边界。

GOOD: 同时给出 "GOOD: ..." 和 "BAD: ..." 示例
BAD:  只描述正确做法，不说什么是错的
BAD:  用抽象原则代替具体示例（"保持简洁"）

评分标准：

• 10：关键行为点都有 GOOD/BAD 对比，示例具体到可执行
• 7：有部分反例但覆盖不全
• 3：只有正面示例
• 0：纯抽象描述，无任何示例

D4：自刹车机制（Self-Regulation）

检查 skill 是否有防止 agent 失控的内置断路器。

GOOD: "每 5 次操作后，评估是否应该继续。如果连续失败 3 次，STOP 并上报。"
GOOD: WTF-likelihood 累加器，超过阈值自动停止
BAD:  没有任何停止条件，agent 可能无限循环

评分标准：

• 10：有量化的停止条件 + 失败累计机制 + 明确的上报格式
• 7：有"失败就停"的声明但没有量化阈值
• 3：只说了"遇到问题请告知用户"
• 0：完全没有自我调节

D5：逃生舱（Escape Hatch）

检查 skill 是否为用户的不耐烦或特殊情况预留了快速通道。

GOOD: "如果用户说'直接做' → 跳过 Phase 2，直接进入 Phase 4"
GOOD: "如果用户已经提供了完整方案 → 跳过诊断，直接进入重写"
BAD:  无论用户说什么都必须走完全部流程

评分标准：

• 10：有显式的 escape hatch + 触发条件 + 跳转目标
• 7：有"可以跳过"的暗示但没有明确条件
• 3：流程完全刚性
• 0：同上

D6：双尺度估算（Effort Framing）

检查 skill 在呈现选项时是否同时给出两个维度的成本。

GOOD: "人工：~2 天 / Agent：~15 分钟"
BAD:  "这大概需要 2 天"（只给人工估算，用户无法校准 AI 时代的心理模型）
BAD:  没有任何成本估算

评分标准：

• 10：所有选项都有双尺度估算 + 压缩比
• 7：有估算但只给了一个维度
• 3：偶尔提到"很快"或"不复杂"
• 0：完全没有成本概念

D7：完成协议（Completion Protocol）

检查 skill 是否有结构化的完成状态报告。

GOOD: DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT，每种状态有明确定义
GOOD: 上报格式包含 STATUS + REASON + ATTEMPTED + RECOMMENDATION
BAD:  "做完了就告诉用户"
BAD:  没有定义完成状态

评分标准：

• 10：有 ≥3 种完成状态 + 结构化上报格式 + 升级机制
• 7：有完成/失败两种状态但格式不统一
• 3：只说"完成后汇报"
• 0：没有完成协议

诊断输出格式

╔══════════════════════════════════════════╗
║  SKILL 诊断报告：<skill-name>            ║
╠══════════════════════════════════════════╣
║  D1 硬约束        ██████░░░░  6/10      ║
║  D2 状态机        ████░░░░░░  4/10      ║
║  D3 反例驱动      ██░░░░░░░░  2/10      ║
║  D4 自刹车        ░░░░░░░░░░  0/10      ║
║  D5 逃生舱        ░░░░░░░░░░  0/10      ║
║  D6 双尺度估算    ░░░░░░░░░░  0/10      ║
║  D7 完成协议      ████████░░  8/10      ║
╠══════════════════════════════════════════╣
║  综合评分：20/70 → 结构成熟度 29%        ║
╚══════════════════════════════════════════╝

每个维度附带 1-3 条具体缺陷描述，引用原文行号。

STOP。 向用户展示诊断报告，等待确认后再进入 Phase 2。

逃生舱： 如果用户说"直接优化"或"不用看报告了" → 跳过等待，直接进入 Phase 2。

---

Phase 2：重写策略

根据诊断结果，生成重写方案。不是从零重写——保留原 skill 的领域逻辑，只注入缺失的结构。

2a：确定重写范围

按诊断分数分级处理：

分数区间	策略
8-10	保持原样，不动
5-7	微调：补充缺失元素，不改变原有结构
0-4	重构：该维度需要重新设计

2b：结构注入清单

对每个需要重构的维度，从以下模板库中选取注入物：

D1 硬约束注入模板：

**HARD GATE：** 本 skill 只做 [核心职责]。
不 [最危险的越权行为 1]，不 [最危险的越权行为 2]。

D2 状态机注入模板：

## Phase N：[阶段名]

[入口条件]
[核心逻辑]
[出口条件 + 条件跳转]

**STOP。** [断点说明]

D3 反例注入模板：

GOOD: [具体的正确行为，引用 skill 领域的真实场景]
BAD:  [具体的错误行为 + 为什么错]（[模型会怎样误解]）

D4 自刹车注入模板：

### 自我调节

每 [N] 次操作后，评估继续条件：
- 连续失败 [M] 次 → **STOP**，上报用户
- 单次操作超过 [T] 分钟 → **STOP**，上报用户
- 输出质量明显下降（重复内容、逻辑矛盾）→ **STOP**，上报用户

上报格式：
STATUS: BLOCKED
REASON: [1-2 句话]
ATTEMPTED: [已尝试的方法]
RECOMMENDATION: [建议用户下一步做什么]

D5 逃生舱注入模板：

**逃生舱：** 如果用户 [触发条件] → 跳过 Phase [X]，直接进入 Phase [Y]。

D6 双尺度注入模板：

| 选项 | 人工 | Agent | 压缩比 |
|-----|------|-------|--------|
| A) [完整方案] | ~[X] | ~[Y] | ~[N]x |
| B) [精简方案] | ~[X] | ~[Y] | ~[N]x |

D7 完成协议注入模板：

## 完成状态

- **DONE** — 全部步骤完成，输出已验证
- **DONE_WITH_CONCERNS** — 完成但有待确认事项，逐条列出
- **BLOCKED** — 无法继续，说明原因和已尝试的方法
- **NEEDS_CONTEXT** — 缺少必要信息，明确列出需要什么

2c：向用户确认重写方案

展示重写计划：哪些维度保持、哪些微调、哪些重构。

重写方案：
  D1 硬约束     → 重构（当前 2/10，注入 HARD GATE + 2 条禁令）
  D2 状态机     → 微调（当前 6/10，补充条件跳转和 STOP 断点）
  D3 反例驱动   → 重构（当前 0/10，为 3 个关键行为点添加 GOOD/BAD 对比）
  D4 自刹车     → 重构（当前 0/10，注入失败累计 + 停止阈值）
  D5 逃生舱     → 重构（当前 0/10，添加 2 个 escape hatch）
  D6 双尺度     → 保持（不适用于本 skill 类型）
  D7 完成协议   → 微调（当前 7/10，补充 NEEDS_CONTEXT 状态）

  预计变更量：人工 ~4 小时 / Agent ~10 分钟

选项：

• A) 全部接受，开始重写
• B) 逐项确认（每个重构项单独决定）
• C) 只做微调，跳过重构

STOP。 等待用户选择。

---

Phase 3：执行重写

按照 Phase 2 确认的方案，对 $ORIGINAL 进行结构注入。

重写原则

1. 保留领域逻辑：原 skill 的核心 workflow 步骤、bash 命令、业务规则一字不改，只在外围注入结构
2. 结构先于内容：先搭骨架（YAML frontmatter → HARD GATE → Phase 划分 → 完成协议），再回填原有内容
3. 最小侵入：能微调的不重构，能补充的不重写。diff 越小越好
4. 符合项目风格：如果 AGENTS.md 定义了文档规范（frontmatter 格式、命名约定），重写后的 skill 必须遵守

重写顺序（严格按此执行）

Step 3.1  YAML frontmatter — 确保 name / version / description 完整
          description 必须包含触发短语（"当被要求 xxx 时触发"）
Step 3.2  HARD GATE — 紧跟 frontmatter 之后，一级标题之前
Step 3.3  Phase 划分 — 将原有线性步骤重组为 Phase 结构
          每个 Phase 有：入口条件 / 核心逻辑 / 出口条件
          关键决策点插入 **STOP** 断点
Step 3.4  条件跳转 — 在 Phase 之间添加分支逻辑
          "如果 X → Phase Na，如果 Y → Phase Nb"
Step 3.5  反例注入 — 在最容易出错的行为点添加 GOOD/BAD 对比
          优先覆盖：输出格式、边界行为、用户交互方式
Step 3.6  逃生舱 — 在耗时最长的 Phase 前添加快速通道
Step 3.7  自刹车 — 在循环/迭代逻辑处注入停止条件
Step 3.8  完成协议 — 文件末尾添加完成状态定义

重写验证清单

重写完成后，逐项自检：

[ ] YAML frontmatter 包含 name / version / description
[ ] description 包含至少 2 个触发短语
[ ] 有 HARD GATE 声明
[ ] workflow 被拆分为 ≥2 个 Phase
[ ] 至少 1 个条件跳转（非纯线性）
[ ] 至少 2 组 GOOD/BAD 反例
[ ] 至少 1 个 STOP 断点
[ ] 至少 1 个逃生舱
[ ] 有自刹车条件（如果 skill 包含循环/迭代）
[ ] 有完成状态协议（≥3 种状态）
[ ] 未破坏原有领域逻辑（逐段比对）

任何一项未通过 → 回到对应 Step 修复，不要跳过。

---

Phase 4：Diff 审查

将重写后的 SKILL.md 与 $ORIGINAL 做结构化对比，向用户展示变更。

输出格式

═══ 变更摘要 ═══

文件：.agents/skills/<skill-name>/SKILL.md
原始行数：N → 重写后行数：M（+X 行）
结构成熟度：29% → 87%

── 新增结构 ──
+ HARD GATE 声明（第 12 行）
+ Phase 划分：3 → 5 个阶段
+ GOOD/BAD 反例：0 → 4 组
+ 逃生舱：2 处
+ 自刹车：失败 3 次停止
+ 完成协议：4 种状态

── 保留不变 ──
= Step 1 核心逻辑（原第 15-42 行 → 新 Phase 2）
= bash 命令块（全部保留）
= 输出文件格式定义（全部保留）

── 修改 ──
~ description 补充触发短语
~ Step 2 拆分为 Phase 3a / 3b（条件跳转）

选项：

• A) 确认，写入文件
• B) 查看完整 diff（逐行对比）
• C) 回到 Phase 2 调整方案

STOP。 等待用户确认。

---

Phase 5：写入 + 收尾

5a：备份原文件

_BACKUP="${_TARGET%.md}.backup-$(date +%Y%m%d-%H%M%S).md"
cp "$_TARGET" "$_BACKUP"
echo "BACKUP: $_BACKUP"

5b：写入重写后的 SKILL.md

将重写内容写入原路径，覆盖原文件。

5c：二次诊断

对重写后的文件重新执行 Phase 1 的七维诊断，输出对比：

╔══════════════════════════════════════════════════════╗
║  优化前后对比：<skill-name>                           ║
╠══════════════════════════════════════════════════════╣
║  维度          优化前    优化后    变化                ║
║  D1 硬约束      2/10     9/10     +7  ██████▓        ║
║  D2 状态机      4/10     9/10     +5  █████▓         ║
║  D3 反例驱动    0/10     8/10     +8  ████████▓      ║
║  D4 自刹车      0/10     8/10     +8  ████████▓      ║
║  D5 逃生舱      0/10     9/10     +9  █████████▓     ║
║  D6 双尺度      0/10     N/A      -   不适用          ║
║  D7 完成协议    7/10     10/10    +3  ███▓           ║
╠══════════════════════════════════════════════════════╣
║  综合：13/70 → 53/60   结构成熟度 19% → 88%          ║
╚══════════════════════════════════════════════════════╝

如果任何维度优化后仍 ≤5 → 警告用户，建议手动审查该维度。

---

自我调节

• 重写过程中如果发现原 skill 的领域逻辑有歧义（无法判断是 bug 还是 feature）→ STOP，向用户确认后再继续
• 如果重写后的文件超过原文件 3 倍行数 → STOP，警告"结构注入过重，可能需要简化"
• 如果连续 3 次重写验证清单未通过同一项 → STOP，上报：

STATUS: BLOCKED
REASON: [具体哪项反复失败]
ATTEMPTED: [已尝试的修复方法]
RECOMMENDATION: [建议用户手动处理该维度]

---

完成状态

• DONE — 诊断完成 + 重写完成 + 二次诊断通过 + 文件已写入
• DONE_WITH_CONCERNS — 重写完成但部分维度仍 ≤5，已列出待改进项
• BLOCKED — 原 skill 逻辑歧义过多，无法安全重写
• NEEDS_CONTEXT — 缺少项目上下文（如 AGENTS.md），需要用户补充