Skill Improver — Skill 改进技能

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

触发场景

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

三种改进来源

| 来源 | 触发方式 | 说明 |

|------|----------|------|

| 用户需求 | 用户指定具体改进方向 | 根据用户想要优化的内容进行针对性改进 |

| 运营沉淀 | 执行过程中自动记录 BUG 和临时修复 | 从历史问题中学习，实现自修复闭环 |

| 联网搜索 | 用户说"自动优化"或未指定方向 | 自动搜索外部最佳实践，分析后提出改进方案 |

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

工作流程

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

1. 根据用户指定的 skill 名称，按优先级在以下路径查找：
• 用户级：~/.workbuddy/skills//SKILL.md
• 项目级：.workbuddy/skills//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
• BUG 记录与修复日志：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（联网搜索）→ 合并改进方案 → 统一执行 → 验证