Skill Polisher - 技能打磨系统
让技能越用越好用的进化引擎。
运行模式（重要）
🔒 只读分析：skill-polisher 只读取技能文件进行分析，生成改进建议，不会修改任何技能文件。
功能范围
- ✅ 收集用户反馈
- ✅ 分析反馈数据，识别问题模式
- ✅ 生成健康报告
- ✅ 输出改进建议
- ❌ 不修改 SKILL.md
- ❌ 不修改脚本代码
- ❌ 不修改文件权限
改进建议输出位置
所有改进建议输出到 ~/.openclaw/workspace/.skill-polisher/polish-history/，用户自行决定是否采纳。
核心流程
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 技能执行 │ → │ 评分收集 │ → │ 数据沉淀 │ → │ 输出建议 │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
只读 只读 只读 只读
🔒 全流程只读，不修改任何技能文件。
快速开始
1. 技能执行后自动收集反馈
每次技能执行完毕，自动询问用户：
任务完成度评分 (0-10)：7
主观评价：输出格式不太对，需要调整
遇到的问题：表格渲染有问题
2. 查看技能健康报告
# 查看所有技能健康度
python3 scripts/health-report.py
# 查看单个技能详情
python3 scripts/health-report.py learning-analyzer
# 生成改进建议
python3 scripts/polish-suggest.py
3. 生成改进建议
# 对指定技能生成改进建议
python3 scripts/polish-suggest.py --skill learning-analyzer
# 或：根据健康报告自动选择最需要改进的技能
python3 scripts/polish-suggest.py --auto
建议输出到 ~/.openclaw/workspace/.skill-polisher/polish-history/<skill>/<date>-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. 读取技能当前状态 (SKILL.md + scripts/)
2. 分析反馈数据，识别问题模式
3. 对比 best-practices.md 检查差距
4. 生成改进建议
5. 输出建议到 polish-history/
6. 显示建议给用户
用户自行决定是否采纳建议，手动修改技能文件。
知识沉淀
最佳实践 (best-practices.md)
## 文档编写
### SKILL.md 结构
- 必须有 YAML frontmatter (name + description)
- description 要说明"什么时候用这个技能"
- Quick Start 放在最前面
- 复杂流程用 mermaid 图
### 命名规范
- 技能名：小写 + 连字符，如 `code-reviewer`
- 脚本名：动词开头，如 `review.py`, `analyze.sh`
## 脚本设计
### 错误处理
- 所有脚本必须有 `set -e` 或等价处理
- 错误信息要包含上下文（哪个文件、哪一步）
### 输出格式
- 进度信息输出到 stderr
- 结果输出到 stdout（便于管道）
- 支持 `--json` 输出模式（可选但推荐）
踩坑记录 (pitfalls.md)
## 2026-03-14 | 技能名过长导致加载失败
**问题**：skill 名称超过 64 字符，OpenClaw 无法识别
**解决**：限制名称长度，使用缩写
**预防**：创建时检查名称长度
## 2026-03-10 | 脚本依赖未声明
**问题**：脚本依赖外部工具，但 SKILL.md 没说明
**解决**：在 Quick Start 中添加依赖安装步骤
**预防**：创建检查清单，强制检查依赖声明
质量标准 (quality-standards.md)
## SKILL.md 必备检查项
- [ ] YAML frontmatter 完整
- [ ] description 包含使用场景
- [ ] 有 Quick Start 章节
- [ ] 所有脚本路径正确
- [ ] 示例代码可运行
## 脚本必备检查项
- [ ] 有执行权限
- [ ] 有 shebang
- [ ] 错误处理完善
- [ ] 帮助信息 (-h/--help)
- [ ] 参数校验
## 进阶标准
- [ ] 有单元测试
- [ ] 支持 CI 集成
- [ ] 有版本变更记录
集成到技能执行流程
skill-polisher 作为技能被 Agent 加载后，Agent 根据任务完成情况自主判断是否触发反馈收集。
🔒 全流程只读：反馈收集、健康报告、改进建议都不会修改任何技能文件。
触发时机
Agent 在完成技能任务后，自主判断是否需要收集反馈：
- 任务完成且用户确认满意 → 询问评分
- 用户主动反馈问题 → 记录问题
- 复杂/重要任务 → 必须收集反馈
询问模板
任务已完成。
📊 请对本次执行评分 (0-10): ___
📝 遇到的问题或建议 (可选): ___
Agent 调用方式
Agent 询问用户后，调用以下命令记录反馈：
# 交互式收集（询问用户）
python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/collect-feedback.py \
--skill <skill-name>
# 或命令行直接记录（已知评分时）
python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/collect-feedback.py \
--skill <skill-name> --score 8 --comment "运行很快"
注意：以上由 Agent 自主执行，不涉及修改任何技能脚本。
Agent 使用规范
技能生命周期管理
1. 管理追踪列表
只有用户明确要求打磨的技能，才会加入追踪列表：
# 查看追踪列表
python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/tracking.py
# 添加技能到追踪列表（开始打磨）
python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/tracking.py --add <skill-name>
# 从追踪列表移除（停止打磨，历史数据保留）
python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/tracking.py --remove <skill-name>
# 查看追踪状态
python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/tracking.py --status
2. 为新技能设置成功标准（可选）
# 交互式设置成功标准
python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/set-expectation.py --skill <name> --edit
成功标准包含：
- 核心功能：这个技能是做什么的（一句话）
- 成功标准：用户怎么判断任务完成了？（ checklist ）
- 常见失败：什么情况下算没完成？
- 预期输出：应该产生什么结果？
3. 检查规范合规性（可选）
# 检查技能是否符合 https://agentskills.io/specification
python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/check-spec.py --skill <name>
4. 执行技能后：收集反馈（仅追踪列表中的技能）
询问模板：
任务已完成。
📊 请对本次执行评分 (0-10): ___
📝 遇到的问题或建议 (可选): ___
记录反馈：
# 交互式收集
python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/collect-feedback.py --skill <name>
# 命令行直接记录
python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/collect-feedback.py \
--skill <name> --score 8 --comment "运行很快"
⚠️ 注意：只有追踪列表中的技能才能收集反馈。如果技能不在列表中，会提示：
⚠️ <skill-name> 不在追踪列表中
使用 tracking.py --add <skill-name> 添加到追踪列表
5. 定期复盘：查看健康报告（仅追踪列表中的技能）
# 查看所有追踪中技能的健康报告
python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/health-report.py
# 查看单个技能
python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/health-report.py <name>
6. 持续改进
# 生成改进建议
python3 ~/.openclaw/workspace/skills/skill-polisher/scripts/polish-suggest.py --skill <name>
# 查看建议
cat ~/.openclaw/workspace/.skill-polisher/polish-history/<name>/<date>-suggest.md
🔒 只读：建议输出到文件，用户自行决定是否采纳。
成功标准示例
learning-analyzer
{
"purpose": "自动分析学习历程数据，生成知识点掌握度报告",
"success_criteria": [
"正确识别所有输入文件格式",
"输出包含知识点掌握度统计",
"生成可视化图表或清晰的数据表格",
"报告格式整洁、易于阅读"
],
"failure_modes": [
"文件解析失败或格式错误",
"输出数据不完整或明显错误",
"缺少关键统计指标",
"报告格式混乱难以阅读"
],
"expected_output": "Markdown 格式的分析报告，包含数据表格"
}
code-reviewer
{
"purpose": "系统化审查代码，发现潜在问题和改进点",
"success_criteria": [
"覆盖所有关键检查项（安全、性能、可维护性）",
"发现的问题有具体位置和修复建议",
"生成结构化的审查报告",
"评分合理，有改进优先级"
],
"failure_modes": [
"遗漏明显的问题",
"误报过多（false positive）",
"报告格式混乱",
"没有可执行的改进建议"
]
}
隐私与数据安全
核心原则
用户数据与技能代码绝对分离
所有用户个人数据存储在 workspace 下的独立目录：
~/.openclaw/workspace/.skill-polisher/ ← 用户数据（隐私，不同步到 clawhub）
├── feedback/ # 用户评分记录
├── expectations/ # 技能成功标准
├── metrics/ # 聚合统计
└── polish-history/ # 打磨历史
技能代码存储在：
~/.openclaw/workspace/skills/skill-polisher/ ← 技能代码（可同步到 clawhub）
├── SKILL.md
├── scripts/
└── references/
为什么重要
- 隐私保护：用户反馈、项目信息不会泄露到公共仓库
- 技能可共享：技能目录可以安全地发布到 clawhub
- 多用户安全：不同用户的数据互不干扰
设计原则（所有技能必须遵守）
- ✅ 用户数据 →
~/.openclaw/workspace/.skill-name/ - ✅ 技能代码 →
~/.openclaw/workspace/skills/skill-name/ - ❌ 绝不在技能目录内存储用户隐私数据
- ❌ 绝不在技能目录内存储项目特定信息
参考文档
- references/QUALITY-STANDARDS.md - 技能质量检查清单
- references/BEST-PRACTICES.md - 最佳实践
- references/PITFALLS.md - 踩坑记录
- references/QUALITY-CHECKLIST.md - 技能质量检查清单
- references/DATA-SCHEMA.md - 数据格式规范
TODO
- 创建数据存储目录结构
- 实现 collect-feedback.py 评分收集
- 实现 health-report.py 健康报告
- 实现 polish-suggest.py 改进建议（只读）
- 填充 best-practices.md 初始内容
- 填充 pitfalls.md 初始内容（基于已有技能经验）
- 创建 QUALITY-CHECKLIST.md