skill-evolver

Skill Evolver

分析技能执行轨迹，发现问题、找出改进机会，并修复技能文件。

轨迹格式

轨迹是具有以下结构的 JSON：

{
  "id": "uuid",
  "request": "user's original request",
  "skills_used": ["skill-name"],
  "success": true/false,
  "total_turns": 2,
  "total_input_tokens": 5000,
  "total_output_tokens": 200,
  "duration_ms": 7000,
  "steps": [
    {"role": "assistant", "content": "...", "tool_name": null},
    {"role": "tool", "tool_name": "...", "tool_input": {}, "tool_result": "..."}
  ],
  "llm_calls": [
    {"turn": 1, "stop_reason": "tool_use", "input_tokens": 2500, "output_tokens": 50}
  ]
}

工作流

此技能可接收两种类型的输入（至少需要一种）：

• 轨迹：来自真实技能运行的执行轨迹数据，用于以数据为依据发现问题
• 反馈：用户撰写的改进建议，用于提供明确的修改方向

如果同时提供两种输入，请结合分析结果：使用轨迹验证和发现问题，并根据反馈确定优先级和修复方向。

步骤 1：分析输入

如果提供了轨迹，请运行分析脚本：

scripts/analyze_traces.py <traces.json> [--skill <name>] [--format json|text]

输出包括：

• 成功率
• 平均轮数、时长、令牌数
• 常见问题和警告
• 建议

如果提供了反馈，请确定用户的改进目标，并将其对应到可执行的修改。

如果同时提供了两者，请交叉比对：反馈是否与轨迹发现的问题一致？根据反馈优先修复轨迹发现的问题。

步骤 2：提取问题详情

对于失败或存在问题的轨迹，请提取完整上下文：

scripts/extract_issue_context.py <traces.json> --failed
scripts/extract_issue_context.py <traces.json> --trace-id <id> --show-llm
scripts/extract_issue_context.py <traces.json> --high-turns

如果只提供了反馈（没有轨迹），请跳过此步骤。

步骤 3：确定根本原因

使用 references/issue-patterns.md 将问题对应到技能组件：

问题类型	可能的修复位置
execution_failure	scripts/、错误处理
high_turn_count	SKILL.md 清晰度、添加示例
tool_errors	scripts/、输入验证
high_token_usage	SKILL.md 冗长度、渐进式披露
repeated_tool_calls	SKILL.md 决策树

对于仅有反馈的输入，请将用户的建议直接对应到适当的技能组件。

步骤 4：应用修复

阅读目标技能，并根据分析结果应用修改：

1. 脚本错误：修复脚本、添加验证、改进错误消息
2. 效率问题：添加示例、决策树和更清晰的说明
3. 令牌问题：精简 SKILL.md，将内容移至 references/
4. 触发问题：更新 frontmatter 描述
5. 反馈指导的修改：应用用户的具体建议

范围限制——必须严格遵守：

• 仅修改目标技能的现有文件（SKILL.md、scripts/、references/）
• 不要创建新的参考文件、模板或指南
• 不要搜索网络获取特定领域的内容
• 不要生成 CHANGELOG、改进报告或其他额外交付物
• 演进后的技能文件本身就是唯一的交付物

快速参考

问题严重程度

• 高：失败、max_tokens、工具错误 → 立即修复
• 中：轮数过多、令牌数过高、重试 → 优化
• 低：耗时过长 → 考虑优化

关键指标阈值

指标	警告	操作
success_rate	<90%	检查失败情况
avg_turns	>4	简化工作流
avg_tokens	>30000	减少上下文
duration_ms	>60000	优化脚本

常见修复

成功率低：

• 在脚本中添加错误处理
• 添加输入验证
• 澄清含糊的说明

轮数过多：

• 添加决策树
• 提供更多示例
• 使用脚本执行多步骤操作

令牌使用量过高：

• 减少 SKILL.md 行数（少于 500 行）
• 将详细内容移至 references/
• 删除重复示例