Skill Polisher - 技能打磨系统

让技能越用越好用的进化引擎。

运行模式（重要）

🔒 只读分析：skill-polisher 只读取技能文件进行分析，生成改进建议，不会修改任何技能文件。

功能范围

• - ✅ 收集用户反馈
• ✅ 分析反馈数据，识别问题模式
• ✅ 生成健康报告
• ✅ 输出改进建议
• ❌ 不修改 SKILL.md
• ❌ 不修改脚本代码
• ❌ 不修改文件权限

改进建议输出位置

所有改进建议输出到 ~/.openclaw/workspace/.skill-polisher/polish-history/，用户自行决定是否采纳。

---

核心流程

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 技能执行 │ → │ 评分收集 │ → │ 数据沉淀 │ → │ 输出建议 │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
只读 只读 只读 只读

🔒 全流程只读，不修改任何技能文件。

快速开始

1. 技能执行后自动收集反馈

每次技能执行完毕，自动询问用户：

任务完成度评分 (0-10)：7
主观评价：输出格式不太对，需要调整
遇到的问题：表格渲染有问题

2. 查看技能健康报告

bash

查看所有技能健康度

python3 scripts/health-report.py

查看单个技能详情

python3 scripts/health-report.py learning-analyzer

生成改进建议

python3 scripts/polish-suggest.py

3. 生成改进建议

bash

对指定技能生成改进建议

python3 scripts/polish-suggest.py --skill learning-analyzer

或：根据健康报告自动选择最需要改进的技能

python3 scripts/polish-suggest.py --auto

建议输出到 ~/.openclaw/workspace/.skill-polisher/polish-history//-suggest.md

数据存储

~/.openclaw/workspace/.skill-polisher/
├── feedback/ # 用户反馈记录
│ ├── learning-analyzer/
│ │ ├── 2026-03-14-001.json
│ │ └── 2026-03-15-002.json
│ └── code-reviewer/
│ └── ...
├── expectations/ # 技能成功标准（每个技能一个）
│ ├── learning-analyzer.json
│ └── code-reviewer.json
├── metrics/ # 聚合指标
│ ├── skill-health.json
│ └── trends.json
├── polish-history/ # 打磨历史
│ └── learning-analyzer/
│ ├── 2026-03-10-polish.md
│ └── 2026-03-15-polish.md
└── knowledge-base/
├── best-practices.md
├── pitfalls.md
└── quality-standards.md

评分维度

简化评分，只有一个维度：

维度	说明	范围
综合评分	整体满意度	0-10

健康度计算

Skill Health Score =
近期平均分 × 10 × 40% +
使用频率 × 10 × 20% +
成功率 × 30% +
反馈丰富度 × 10 × 10%

等级划分：

• - 🟢 优秀 (80-100)：保持现状，可作为标杆
• 🟡 良好 (60-79)：小有瑕疵，可轻度优化
• 🟠 需关注 (40-59)：有明显问题，建议打磨
• 🔴 需重构 (<40)：问题严重，需要大幅改进

打磨触发条件

自动触发：

• - 健康度连续 7 天低于 60
• 单次评分低于 4 分
• 累计收到 3 条同类负面反馈

手动触发：

• - 用户主动要求打磨某个技能
• 定期复盘时批量检查

打磨流程（只读分析）

1. 1. 读取技能当前状态 (SKILL.md + scripts/)
2. 分析反馈数据，识别问题模式
3. 对比 best-practices.md 检查差距
4. 生成改进建议
5. 输出建议到 polish-history/
6. 显示建议给用户

用户自行决定是否采纳建议，手动修改技能文件。

---

知识沉淀

最佳实践 (best-practices.md)

markdown

文档编写

SKILL.md 结构

• - 必须有 YAML frontmatter (name + description)
• description 要说明什么时候用这个技能
• Quick Start 放在最前面
• 复杂流程用 mermaid 图

命名规范

• - 技能名：小写 + 连字符，如 code-reviewer
• 脚本名：动词开头，如 review.py, analyze.sh

脚本设计

错误处理

• - 所有脚本必须有 set -e 或等价处理
• 错误信息要包含上下文（哪个文件、哪一步）

输出格式

• - 进度信息输出到 stderr
• 结果输出到 stdout（便于管道）
• 支持 --json 输出模式（可选但推荐）

踩坑记录 (pitfalls.md)

markdown

2026-03-14 | 技能名过长导致加载失败

问题：skill 名称超过 64 字符，OpenClaw 无法识别
解决：限制名称长度，使用缩写
预防：创建时检查名称长度

2026-03-10 | 脚本依赖未声明

问题：脚本依赖外部工具，但 SKILL.md 没说明
解决：在 Quick Start 中添加依赖安装步骤
预防：创建检查清单，强制检查依赖声明

质量标准 (quality-standards.md)

markdown

SKILL.md 必备检查项

• - [ ] YAML frontmatter 完整
• [ ] description 包含使用场景
• [ ] 有 Quick Start 章节
• [ ] 所有脚本路径正确
• [ ] 示例代码可运行

脚本必备检查项

• - [ ] 有执行权限
• [ ] 有 shebang
• [ ] 错误处理完善
• [ ] 帮助信息 (-h/--help)
• [ ] 参数校验

进阶标准

• - [ ] 有单元测试
• [ ] 支持 CI 集成
• [ ] 有版本变更记录

集成到技能执行流程

skill-polisher 作为技能被 Agent 加载后，Agent 根据任务完成情况自主判断是否触发反馈收集。

🔒 全流程只读：反馈收集、健康报告、改进建议都不会修改任何技能文件。

触发时机

Agent 在完成技能任务后，自主判断是否需要收集反馈：

1. 1. 任务完成且用户确认满意 → 询问评分
2. 用户主动反馈问题 → 记录问题
3. 复杂/重要任务 → 必须收集反馈

询问模板

任务已完成。

📊 请对本次执行评分 (0-10): _
📝 遇到的问题或建议 (可选): _

Agent 调用方式

Agent 询问用户后，调用以下命令记录反馈：

bash

交互式收集（询问用户）

python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/collect-feedback.py \
--skill

或命令行直接记录（已知评分时）

python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/collect-feedback.py \ --skill --score 8 --comment 运行很快

注意：以上由 Agent 自主执行，不涉及修改任何技能脚本。

Agent 使用规范

技能生命周期管理

1. 管理追踪列表

只有用户明确要求打磨的技能，才会加入追踪列表：

bash

查看追踪列表

python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/tracking.py

添加技能到追踪列表（开始打磨）

python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/tracking.py --add

从追踪列表移除（停止打磨，历史数据保留）

python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/tracking.py --remove

查看追踪状态

python3 ~/.openclaw/workspace/skills/s