Skill Improver — Skill 改进技能

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

触发场景

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

三种改进来源

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

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

工作流程

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

根据用户指定的 skill 名称，按优先级在以下路径查找：
- 用户级：~/.workbuddy/skills/<skill-name>/SKILL.md
- 项目级：.workbuddy/skills/<skill-name>/SKILL.md
- 内置级：WorkBuddy 安装目录下的 builtin/skill-name/
读取完整的 SKILL.md 文件
扫描 skill 目录下的所有子目录和文件
如有 references/ 下的文件，根据需要读取关键文件内容
读取 BUG_LOG.md，筛选目标 skill 的未修复 BUG 记录
如找不到目标 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 执行：

定位：根据"现象"描述，在 skill 内容中找到对应位置
分析：验证或补充"根因分析"
修复：实施修复方案，修改 SKILL.md 或相关文件
更新日志：在 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 时遵循以下规范：

优先级

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

操作类型

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

修改原则

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

第六步：验证

完成修改后逐项检查：

YAML 有效性：frontmatter 格式正确、字段合法
name 一致性：name 与目录名一致
引用完整性：文件引用路径正确、被引用文件存在
逻辑连贯性：通读 SKILL.md，确认无矛盾
长度检查：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（联网搜索）→ 合并改进方案 → 统一执行 → 验证