# Skill Improver — Skill 改进技能

对已存在的 skill 进行全方位改进，支持三种改进来源协同工作，形成"发现问题 → 沉淀经验 → 持续改进"的进化闭环。

## 触发场景

- 用户要求改进某个 skill（"帮我改进 XXX 这个 skill"）
- 用户要求自动优化（"自动优化这个 skill"、"让它变得更好"）
- 用户描述某个 skill 的不足并提出改进需求
- 用户提到 skill 有 BUG 需要修复
- 用户刚使用完某个 skill 后表示效果不好，希望改进
- 用户想让某个 skill 支持更多场景或功能
- 用户发现某个 skill 的触发条件不精准

## 三种改进来源

| 来源 | 触发方式 | 说明 |
|------|----------|------|
| **用户需求** | 用户指定具体改进方向 | 根据用户想要优化的内容进行针对性改进 |
| **运营沉淀** | 执行过程中自动记录 BUG 和临时修复 | 从历史问题中学习，实现自修复闭环 |
| **联网搜索** | 用户说"自动优化"或未指定方向 | 自动搜索外部最佳实践，分析后提出改进方案 |

三种来源可单独使用，也可组合使用。例如"自动优化并修复已知 BUG"同时触发联网搜索和运营沉淀修复。

---

## 工作流程

### 第一步：定位并加载目标 Skill

1. 根据用户指定的 skill 名称，按优先级在以下路径查找：
   - 用户级：`~/.workbuddy/skills/<skill-name>/SKILL.md`
   - 项目级：`.workbuddy/skills/<skill-name>/SKILL.md`
   - 内置级：WorkBuddy 安装目录下的 `builtin/skill-name/`
2. 读取完整的 `SKILL.md` 文件
3. 扫描 skill 目录下的所有子目录和文件
4. 如有 `references/` 下的文件，根据需要读取关键文件内容
5. 读取 `BUG_LOG.md`，筛选目标 skill 的未修复 BUG 记录
6. 如找不到目标 skill，提示用户提供正确的 skill 名称或路径

### 第二步：确定改进模式

根据用户指令和当前状态，选择并执行对应的改进模式。可按需组合多个模式。

---

### 模式 A：用户需求驱动

当用户指定了具体改进方向时执行。

**A1. 诊断分析**

从以下维度系统评估目标 skill：

| 维度 | 检查项 | 关注点 |
|------|--------|--------|
| 元数据 | name / description / metadata | 命名规范、触发条件完整性、关键词覆盖 |
| 指令质量 | 结构 / 清晰度 / 覆盖面 / 边界 / 示例 | 是否可执行、有无歧义、是否遗漏场景 |
| 资源组织 | 长度 / 引用 / 分层 / 冗余 | ≤500行、引用完整、无重复信息 |
| 用户体验 | 触发精准度 / 执行流畅度 / 输出质量 | 是否符合用户预期 |

详细优化技巧参见 `references/improvement-guide.md`。

**A2. 输出诊断报告**

修改前先输出结构化报告：
- 总体评价（一句话）
- 各维度评分（✅/⚠️ + 说明）
- 发现的问题（编号 + 严重程度：高/中/低）
- 改进建议（编号 + 预期效果）

**A3. 确认改进范围**

- 展示诊断报告后，询问用户希望改进哪些方面
- 如用户表示"全面改进"，按问题优先级逐项处理
- 如用户已指定方向，聚焦该方向结合诊断结果执行
- 对于内置 skill，提醒修改会写入用户级路径创建覆盖版本

**A4. 执行改进**

按照"第五步：执行改进"的通用规范执行。

---

### 模式 B：运营沉淀驱动

当 `BUG_LOG.md` 中存在目标 skill 的未修复记录，或用户提到 BUG 时触发。

**B1. 读取并分析 BUG 日志**

读取 `BUG_LOG.md`，筛选目标 skill 的 `[待修复]` 条目，按严重程度排序：
- **高**：导致 skill 无法正常工作或产出错误结果
- **中**：导致执行效果不佳或存在明显缺陷
- **低**：轻微问题，不影响核心功能但可改进

**B2. 逐一修复**

对每个 BUG 执行：
1. **定位**：根据"现象"描述，在 skill 内容中找到对应位置
2. **分析**：验证或补充"根因分析"
3. **修复**：实施修复方案，修改 SKILL.md 或相关文件
4. **更新日志**：在 BUG_LOG.md 中将状态更新为 `[已修复]`，记录修复日期

**B3. 添加预防性指令**

修复后，考虑在目标 skill 中添加防御性指令防止同类问题复发：
```
## 注意事项
- [具体预防措施]
```

**B4. 输出修复报告**

- 修复概要（BUG 数量、优先级分布）
- 每个 BUG 的修复方案和修改文件
- 残留问题（如有）
- 预防措施建议

---

### 模式 C：联网搜索驱动

当用户说"自动优化"、未指定方向，或需要外部灵感时执行。

**C1. 提取 Skill 特征**

从目标 skill 的 SKILL.md 中提取：
- 功能定位（description 中的核心功能描述）
- Skill 类型（工作流型 / 任务型 / 参考指南型 / 能力型）
- 所属领域和技术栈

**C2. 构造搜索查询**

根据 skill 特征构造 3-5 个搜索查询，覆盖不同优化维度：

| 维度 | 查询构造方式 |
|------|--------------|
| Prompt 质量 | `"[skill 功能] prompt engineering best practices"` |
| Agent 设计模式 | `"AI agent [skill 领域] workflow design patterns"` |
| 错误处理与健壮性 | `"prompt error handling edge cases [skill 功能]"` |
| 领域前沿实践 | `"[skill 领域] best practices [当前年份]"` |

使用 `web_search` 对每个查询执行搜索，收集 3-5 条最相关的结果。

**C3. 评估搜索结果**

对每条建议按以下标准评估：

| 评估项 | 评分 | 说明 |
|--------|------|------|
| 适用性 | 1-5 | 与当前 skill 的相关程度 |
| 可实施性 | 1-5 | 能否通过修改 SKILL.md 实现 |
| 风险等级 | 低/中/高 | 是否可能引入新问题 |
| 影响力 | 1-5 | 对 skill 效果的改善幅度 |

**分类规则**：
- 适用性 ≥ 4 且 可实施性 ≥ 4 且 风险低 → **直接采纳**
- 适用性 ≥ 3 且 可实施性 ≥ 3 → **需用户确认**
- 其他 → **过滤不采纳**

**C4. 展示改进方案**

向用户展示分类后的方案：

```
## 自动改进方案：[skill-name]

### 直接采纳的建议
1. **[标题]** — 来源概要 / 具体改动 / 预期效果

### 需要确认的建议
1. **[标题]** — 来源概要 / 不确定原因 / 选项(A采纳/B跳过/C部分采纳)

### 已过滤的建议
1. **[标题]** — 过滤原因
```

**C5. 交互确认后执行**

- "直接采纳"的建议直接执行
- "需要确认"的建议等待用户选择后执行
- 执行完毕后按"第六步：验证"检查

---

### 第三步：补充诊断（可选）

对于模式 B 和模式 C，在执行改进前可额外运行模式 A 的诊断分析，发现用户未提及的问题，一并列出供用户决定是否一并改进。

### 第四步：记录发现的问题

无论哪种模式，执行过程中发现目标 skill 的新问题时，将记录追加到 `BUG_LOG.md`：

**记录时机**：
- 执行过程中发现 skill 的指令缺陷（步骤矛盾、逻辑缺失、边界未处理）
- 执行了临时绕过方案（某个步骤不通，采用了非标准方式完成）
- 用户反馈效果不佳的部分

**记录规范**：
- 编号格式：`[BUG-YYYYMMDD-NN]`
- 必填：发现日期、目标 Skill、严重程度、现象
- 尽量填写：根因分析、修复方案
- 临时修复方案也需记录，即使未彻底解决

详细记录格式参见 `BUG_LOG.md` 头部的模板说明。

### 第五步：执行改进

无论哪种模式，修改 skill 时遵循以下规范：

#### 优先级

1. **高**：description 优化（影响触发）、指令逻辑缺陷（影响执行）
2. **中**：指令清晰度、示例补充、资源组织调整
3. **低**：格式美化、metadata 补充、非关键细节

#### 操作类型

| 操作 | 场景 | 方法 |
|------|------|------|
| 修改 frontmatter | 优化 description/name/metadata | replace_in_file 替换 YAML 字段 |
| 重写段落 | 指令不清晰、有缺陷 | replace_in_file 精准替换 |
| 补充内容 | 缺少步骤、示例、边界说明 | 在合适位置插入新段落 |
| 删除冗余 | 重复信息、过时内容 | 删除冗余段落 |
| 拆分长文件 | SKILL.md 超 500 行 | 内容移至 references/ |
| 新建文件 | 需要补充参考或脚本 | 在对应目录创建 |

#### 修改原则

- **最小改动**：仅修改需要改进的部分，保留已有且有效的指令
- **风格一致**：与 skill 原有的语气、格式、结构保持一致
- **增量安全**：每次修改后确保 skill 仍可用，不做破坏性重构
- **可回滚**：修改前在诊断/方案报告中记录原始内容的关键部分

### 第六步：验证

完成修改后逐项检查：

1. **YAML 有效性**：frontmatter 格式正确、字段合法
2. **name 一致性**：name 与目录名一致
3. **引用完整性**：文件引用路径正确、被引用文件存在
4. **逻辑连贯性**：通读 SKILL.md，确认无矛盾
5. **长度检查**：SKILL.md 在 500 行以内

输出改进结果摘要：

```
## 改进完成：[skill-name]

### 已执行的修改
1. [修改内容简述]

### 改进效果
- [预期改进说明]

### 新发现的问题（已记录到 BUG_LOG.md）
- [如有]

### 后续建议
- [如需要后续跟进的建议]
```

---

## 参考资源

- 改进技巧与最佳实践：[`references/improvement-guide.md`](references/improvement-guide.md)
- BUG 记录与修复日志：[`BUG_LOG.md`](BUG_LOG.md)

## 快速示例

### 示例 1：用户需求驱动

**用户**：帮我改进 company-guide 这个 skill，它的触发不太准确

**流程**：加载 skill → 模式 A 诊断 → 发现 description 关键词不够丰富 → 输出报告 → 用户确认 → 优化 description → 验证

### 示例 2：自动优化

**用户**：自动优化一下 finance-writer

**流程**：加载 skill → 模式 C 搜索最佳实践 → 分析结果分类 → 展示方案 → 用户确认 → 执行改进 → 验证

### 示例 3：BUG 自修复

**用户**：修复 invoice-ocr 的已知 BUG

**流程**：读取 BUG_LOG.md → 模式 B 找到 2 个待修复 BUG → 逐一修复 → 更新日志状态 → 输出修复报告

### 示例 4：组合模式

**用户**：自动优化 skill-optimizer 并修复已知问题

**流程**：同时执行模式 B（BUG 修复）+ 模式 C（联网搜索）→ 合并改进方案 → 统一执行 → 验证