skill-optimizer

name	skill-optimizer
description	Use when the user says "优化 skill", "skill 优化", or reports that a skill isn't working well — also use when a conversation reveals patterns where a skill was missed, misfired, or required manual correction

Skill Optimizer

概述

元技能。分析对话上下文，识别已有 skill 的改进空间，按置信度分级展示，经长期复利滤网过滤，待用户确认后逐条执行修改。

触发：

用户说	行为
"优化 skill" / "skill 优化" / "优化一下 skill"	全局扫描，自动识别相关 skill
"XX skill 有问题" / "XX skill 不太好用"	指定目标，仅分析该 skill
"/skill-optimizer" / "/optimize-skill"	同上

设计原则：

• 最小改动，最大收益 — 每条改动可追溯到一个具体的对话问题
• 长期复利优先 — 改规则不补补丁，每个修改过三问滤网
• 置信度驱动 — 不确定的不动，中等确定的不验证不动
• 优雅降级 — 依赖不可用时自动切换路径，不报错中断

核心工作流

用户触发
    │
    ▼
┌────────────────────────┐
│ 阶段 1: 上下文采集      │
│ · 读当前对话            │
│ · 条件查询历史记忆      │
│ · 列出相关 skill        │
│   扫描范围:             │
│   ~/.claude/skills/ +   │
│   .claude/skills/       │
│ · 判断模式（轻量/标准）  │
│ · 无相关 skill → 返回   │
└───────────┬────────────┘
            ▼
┌────────────────────────┐
│ 阶段 1.5: 条件调复盘    │
│ · 有异常信号？          │
│   报错/行为异常/手动纠正 │
│   ├─ 有 → 调 debug-     │
│   │       architect     │
│   │  ├─ 成功 → 路径 A   │
│   │  ├─ 不存在 → 路径 B │
│   │  ├─ 超时 → 路径 B   │
│   │  └─ 空结果 → 路径 B │
│   └─ 无 → 路径 B        │
└───────────┬────────────┘
            ▼
┌────────────────────────┐
│ 阶段 2: 三维并行审查    │
│ Agent A: 触发准确度     │
│ · 该触发时没触发？      │
│ · 不该触发时误触发？    │
│ · description 精准？   │
│ Agent B: 内容质量       │
│ · 遗漏/冗余/矛盾？      │
│ · 流程步骤最优？        │
│ · 示例仍有效？         │
│ Agent C: 工作流效率     │
│ · 来回过多？            │
│ · 检查点合理？          │
│ · token 可控？          │
└───────────┬────────────┘
            ▼
┌────────────────────────┐
│ 阶段 3: 合成+置信度     │
│ · 去重                  │
│ · 置信度分级 [高][中]   │
│ · 对抗验证（[中] 档）   │
│ · 长期复利滤网          │
└───────────┬────────────┘
            ▼
┌────────────────────────┐
│ 阶段 4: 用户决策        │
│ · 展示报告（按skill分组）│
│   [✅改] [❌不改]       │
│   [🔧换个方式]          │
└───────────┬────────────┘
            ▼
┌────────────────────────┐
│ 阶段 5: 执行修改        │
│ · 逐条应用 + 自检       │
│   - YAML frontmatter   │
│   - Markdown 结构      │
│   - 触发词交叉检查      │
│ · 失败→回滚，标注警告    │
└───────────┬────────────┘
            ▼
┌────────────────────────┐
│ 阶段 6: 收尾            │
│ · 更新 memory           │
│ · 建议 commit           │
│ · 建议后续动作          │
└────────────────────────┘

三种模式

模式选择（阶段 1 末尾）

输入: 相关 skill 数 N, 对话轮数 R, 用户是否显式指定目标

if 用户显式指定了目标 skill:
    → 标准模式（仅分析指定 skill）
elif N == 0:
    → 直接返回："对话中没有发现相关 skill，无需优化"
elif N ≤ 2 且 R < 10:
    → 轻量模式
else:
    → 标准模式

轻量模式

单 agent 合并审查（三维度一锅出），跳过对抗验证。标注"轻量模式，置信度仅供参考"。

标准模式

3 agent 并行审查 + 对抗验证（[中] 档）+ 长期复利滤网（所有发现）。

置信度体系

公式： 来源信号（可叠加） × 证据强度（0.4/0.7/1.0） → 原始分 + 影响范围修正（0%/-5%/-10%） → 置信度%，cap 95%。

档位	阈值	行为
[高]	≥80%	强烈推荐修改 → 进长期复利滤网
[中]	50-79%	建议修改 → 先进对抗验证
[低]	<50%	忽略，不出现在报告中

关键信号：

• 用户手动纠正 skill 行为 → +40
• debug-architect 🟢 输出 → +40
• skill 未被触发但本该触发 → +30
• skill 被触发但表现异常 → +25

对抗验证： 仅对 [中] 档执行。由独立 agent 从反面论证，确认是 skill 问题而非上下文特殊后，才升至 [高]。

详见 references/confidence-scoring.md。

长期复利滤网

每个待修改项过三问：

1. 系统性 vs 偶发？ — 仅当前对话出现、历史无迹 → 降档
2. 三个月后庆幸还是后悔？ — 后悔 → 放弃
3. 规则还是补丁？ — 补丁 → 放弃（除非你声明临时）

五条红线（禁止）：

• 为单一对话添加触发词
• 为罕见边缘路径加步骤
• 删除"看起来没用"的步骤（先查 git log）
• 把通用流程改成今天对话的形状
• 未经对抗验证的 [中] 档修改

详见 references/long-term-filter.md。

报告格式

摘要

╔══════════════════════════════════════╗
║  🔍 Skill 优化报告                   ║
╠══════════════════════════════════════╣
║  分析范围：[N] 个 skill              ║
║  模式：[标准/轻量]                   ║
║  信号源：[复盘驱动/对话推断]          ║
╠══════════════════════════════════════╣
║  [高] ≥80%：[N] 项                   ║
║  [中] 50-79%：[N] 项                 ║
║  [低] <50%：[N] 项（已忽略）          ║
╠══════════════════════════════════════╣
║  长期复利滤网：                      ║
║  ✅ 通过：[N]                       ║
║  ❌ 拦截：[N]（+原因）               ║
╚══════════════════════════════════════╝

逐项详情

每项展示：

## skill-name

### [高] 推荐修改

#### 1. [问题标题] — 置信度 92%
**发现来源：** [信号描述]
**问题：** [一句话]
**当前内容：** > [原文]
**建议改为：** > [修改后]
**长期复利：** ✅ 通过 — [理由]

### [中] 建议修改（需判断）

#### 3. [问题标题] — 置信度 65%（已对抗验证）
**发现来源：** [信号描述]
**对抗验证结论：** [结论]
**建议：** [修改方案]
**长期复利：** ⚠️ 不确定 — [原因]

### ❌ 已拦截

#### 4. [问题标题] — 原始置信度 75%
**拦截原因：** [违反哪条红线]

用户操作

不逐条让用户选。 报告结尾必须将全部待修改项合成 2-4 个预组合行动选项，每个选项一句话说清涵盖哪些修改 + 理由。必须有一个选项标记（推荐）。

选项设计原则：

• 每个选项是互斥的完整行动方案——用户选一个就执行全套
• 选项之间差异化（激进 vs 保守、全改 vs 只改高置信）
• （推荐）默认落在"全部 [高] + 用户可追加 [中]"——最高 ROI 且最低风险

格式：

📋 行动选项

A. [选项名] — [涵盖哪几条修改] — [一句话理由]
B. [选项名] — [涵盖哪几条修改] — [一句话理由] （推荐）
C. [选项名] — [涵盖哪几条修改] — [一句话理由]

回复 A/B/C，或说具体怎么调。

常见选项模板：

模板	内容
A. 只改高置信	全部 [高] 项。理由：改动最小、风险最低、收益明确
B. 全部改（推荐）	全部 [高] + 全部 [中]。理由：[根据具体情况写]
C. 只改某一个	仅改某一项。理由：[用户表达过特定关注]
D. 都不改	跳过本次所有修改。理由：改动不够紧迫或需要更多证据

约束：

• 选项不超过 4 个（超过 → 合并相似项）
• 每个选项一行，不需要展开细节（细节上文已有）
• 如果只有 1 项发现 → 跳过选项，直接问"改还是不改"

边缘场景

对话边界

场景	处理
空对话 / 刚启动	直接返回："对话中还没有使用任何 skill，无需优化"
对话很短（<5轮）但涉及 skill	自动走轻量模式
超长对话（>50轮）	摘要压缩，标注"基于摘要，置信度可能偏低"

特殊对象

场景	处理
目标是 skill-optimizer 自身	允许内容审查，禁止修改自身工作流
目标 skill 有依赖关系	修改后检查依赖 skill 是否需同步，有则追加 [中] 建议
目标是插件 skill（无本地文件）	只出报告不修改，提示提交反馈给插件作者
目标已被禁用（.disabled）	跳过，标注"已禁用"

修改安全

风险	防护
YAML frontmatter 损坏	修改后校验 name/description 字段存在、格式正确
Markdown 结构断裂	关键章节标题完整性检查，章节数增减 ≤ 20%
并发冲突（另一个会话同时改）	git diff 检测未预期变更 → 暂停，提示
触发词交叉冲突	新触发词与已有 skill 重叠 → 标注警告

冲突仲裁

当多个 Agent 对同一问题得出矛盾结论时：

1. 两者进对抗验证，各自辩护
2. 仲裁标准：哪个选择的长期副作用更小？
3. 无法裁决 → 两条都展示（[中]），让用户决定

降级与熔断

条件	行为
任一 Agent 超时 >120s	该维度标记"⏱️ 未完成"，其余照常
2+ Agent 超时	降级为轻量模式重试
修改后自检连续 2 次失败	该条放弃，标注"⚠️ 需手动处理"
Token 消耗超估计值 1.5 倍	暂停新 Agent，输出已有结果

与 debug-architect 的协作

调用关系

skill-optimizer -(调用)→ debug-architect
                          ├─ 扫描错误 + 追踪根因
                          ├─ 四象限分级
                          └─ 生成 "Skill 修改建议"

skill-optimizer ←(接收)── 硬证据信号
                          ├─ 应用长期复利滤网
                          └─ 执行修改

降级策略

debug-architect 调用：
  ├─ Skill 不存在 → 静默降级为路径 B（对话推断）
  ├─ 超时（>120s）→ 降级为路径 B
  ├─ 返回空结果 → 降级为路径 B
  └─ 已在当前会话运行过 → 直接用已有结果

置信度映射

debug-architect      →  skill-optimizer 信号加分
🟢 确定·高价值        →  +40（等同于用户手动纠正）
🟡 确定·低价值        →  +25
🔵 推测·高价值        →  +20
⚪ 存疑/一次性        →  +5

反模式

借口	现实
"这次很明显，加个触发词就行"	单次对话 ≠ 模式，触发词只增不减
"步骤 3 从来没人用，删了吧"	先 git log 看它为什么存在
"这个场景很特殊，加个 if 分支"	补丁累积 → 通用流程变成条件树
"65% 置信度，差不多可以改了"	35% 概率改错 > 不改的代价

如果发现自己在想上面任何一句 → 停下来，回到滤网重新判断。