skill-forge-evolve

技能演进与改进

流程

步骤 1：诊断问题

询问用户或分析日志，以识别问题类别：

类别 A：触发问题

• 触发不足：技能在应该触发时没有触发
• 触发过度：技能在不应该触发时触发
• 触发错误：触发了错误的子技能

类别 B：执行问题

• 工作流不完整：技能在完成前就停止了
• 输出不正确：结果不符合预期
• 缺少错误处理：未能妥善处理故障
• 性能：速度太慢或使用的 token 太多

类别 C：架构问题

• 缺少能力：未覆盖新的用例
• 扩展性问题：技能太大，需要拆分
• 交叉引用问题：链接指向不存在的文件

类别 D：质量问题

• 结果不一致：相同输入产生不同输出
• 指令模糊：Claude 每次的解读都不同
• 缺少示例：没有具体的指导

步骤 2：按类别应用修复

修复：触发不足

1. 阅读当前描述
2. 找出缺少的触发短语
3. 添加领域关键词和释义
4. 如适用，添加文件类型说明
5. 使用 5 条现在应该触发的查询进行测试

常见原因：

• 描述过于笼统
• 缺少常见的释义
• 使用了技术术语，但没有通俗说法

修复模板：

# Before (under-triggers)
description: Analyzes code quality

# After (specific triggers)
description: >
  Static code analysis and quality assessment. Checks code style,
  complexity, security vulnerabilities, and test coverage. Use when
  user says "code review", "code quality", "lint", "static analysis",
  "code smell", "code audit", or "check my code".

修复：触发过度

1. 阅读当前描述
2. 找出不相关查询触发的原因
3. 添加否定触发条件（“不要用于……”）
4. 让描述更具体
5. 使用 5 条不应该触发的查询进行测试

修复模板：

# Before (over-triggers)
description: Processes documents for review

# After (specific + negative triggers)
description: >
  Processes PDF legal documents for contract clause extraction and
  compliance review. Use for legal contracts, NDAs, terms of service.
  Do NOT use for general document editing, formatting, or non-legal PDFs.

修复：执行问题

1. 找出工作流中失败的步骤
2. 在各步骤之间添加明确的验证关卡
3. 添加错误处理，并提供清晰的恢复指引
4. 添加“如果 X 失败，则执行 Y”的回退路径
5. 考虑为易出错的操作添加脚本

修复：质量问题

1. 用具体指令替换模糊指令
2. 添加预期输入/输出的具体示例
3. 明确添加“这样做，而不是那样做”的对比
4. 在最终输出前添加质量检查步骤
5. 考虑添加验证脚本

步骤 3：迭代工作区协议

使用结构化工作区跟踪各轮迭代中的改进：

eval-workspace/
  iteration-1/          # First version
    eval-0/with_skill/  # Eval results
    eval-0/baseline/
    benchmark.json      # Aggregated metrics
    benchmark.md        # Human-readable report
    feedback.json       # User feedback
  iteration-2/          # After first improvement
    eval-0/with_skill/
    eval-0/baseline/
    benchmark.json
    benchmark.md
    feedback.json

迭代循环：

1. 将修复应用到技能
2. 运行 /skill-forge eval <path>，将结果保存到 iteration-<N+1>/
3. 使用 --previous iteration-<N>/ 运行 /skill-forge benchmark <path>
4. 检查基准测试对比结果，查看是否出现退化
5. 将用户反馈收集到 feedback.json
6. 阅读反馈并继续迭代（返回步骤 2）

在以下情况下停止迭代：

• 用户表示满意
• 所有反馈均为空（看起来一切正常）
• 基准测试显示迭代之间没有明显进展
• 通过率达到既定阈值

步骤 3b：自退火循环

适用于无需完整评估流程的快速修复：

1. Apply the fix
2. Test with the original failing case
3. Test with 3 other cases (regression check)
4. If fix works:
   -> Update the directive/SKILL.md
   -> Document the learning in references or SKILL.md
5. If fix fails:
   -> Diagnose why
   -> Try alternative approach
   -> Repeat

步骤 3c：描述优化循环

对于触发问题（类别 A），使用自动优化循环：

1. 生成触发评估集：python scripts/generate_eval_set.py <path>
2. 与用户一起检查并完善评估集
3. 运行优化：python scripts/optimize_description.py <path> --eval-set evals.json
4. 检查训练集/测试集拆分得分和改进建议
5. 应用建议的描述修改
6. 重新运行优化，以衡量改进效果
7. 选择测试得分最高的描述（而非训练得分，以避免过拟合）
8. 最多迭代 5 次，或直到测试得分趋于稳定

第 4 步：架构演进

当某个技能超出其层级时：

Tier 1 -> Tier 2（需要脚本）：

1. 找出脆弱或确定性的操作
2. 在 scripts/ 中创建脚本
3. 更新 SKILL.md 以引用该脚本
4. 独立测试脚本

Tier 2 -> Tier 3（需要子技能）：

1. 找出可以拆分的不同工作流
2. 将每个工作流提取到各自的 skills/{parent}-{child}/SKILL.md
3. 更新主 SKILL.md，添加路由表
4. 将共享知识移至 references/
5. 更新 install.sh

Tier 3 -> Tier 4（需要 Agent）：

1. 找出可以并行运行的工作流
2. 在 agents/ 中创建 Agent 定义
3. 更新 audit/full-analysis 子技能，使其委派任务给 Agent
4. 测试并行执行

第 5 步：版本管理

演进后：

1. 更新 frontmatter 中的 metadata.version（如果存在）
2. 将经验补充到 SKILL.md 或参考文件中
3. 更新所有受影响的交叉引用
4. 重新运行验证：python scripts/validate_skill.py <path>
5. 端到端测试完整工作流

常见的演进模式

模式：添加行业检测

当技能需要根据用户类型调整行为时：

## Industry Detection
Detect user type from context:
- **Type A**: [signals] -> [behavior]
- **Type B**: [signals] -> [behavior]

模式：添加质量关卡

当输出质量不稳定时：

## Quality Gates
Before delivering output:
- [ ] [Check 1]
- [ ] [Check 2]
- [ ] [Check 3]

模式：添加评分

当用户需要可衡量的输出时：

## Scoring (0-100)
| Category | Weight |
|----------|--------|
| Category A | 30% |
| Category B | 30% |
| Category C | 20% |
| Category D | 20% |