Skill Evaluator
> 基于 SkillsBench 论文方法论 + skill-audit 工程实践
> 核心理念：Skill 只有验证过，才是资产。把每次评测变成证据。
设计哲学
SkillsBench 审计了 47,150 个 Skills，发现：
- 平均分仅 6.2/12
- AI 自动生成的 Skill 平均拉低任务成功率 1.3%
- 只有高质量 Skill (≥9分) 才能提升 Agent 表现，平均 +16.2%
- Skill 质量远比数量重要
本评测工具的目标：
1. 量化 — 每个 Skill 都有明确分数，不再凭感觉
2. 分级 — 三层分级与 SkillsBench 论文对齐，知道自己在什么位置
3. 可执行 — 每个扣分项都有具体修复建议，不是泛泛而谈
4. 可对比 — 支持批量评测，排行榜一目了然
评测模式
模式 1：单 Skill 评测
用户指定或当前对话中涉及某个 Skill 时触发。流程：
- 定位 Skill — 确认 Skill 路径
- 读取 SKILL.md — 完整读取目标文件
- 逐维度评测 — 按
references/rubric.md中 12 维度逐项打分 - 生成报告 — 输出格式化评测报告 (见下方模板)
- 改进建议 — 每个失分维度给出一条可执行的修复建议
模式 2：批量全库评测
用户说「所有skill打分」「skill排行榜」时触发。流程：
- 扫描目录 — 读取
~/.workbuddy/skills/下所有 SKILL.md - 逐个评测 — 对每个 Skill 执行模式 1 的评分流程
- 输出排行榜 — 按分数降序排列
- 生成热力图 — 标注全库的强项和薄弱维度
- 系统性问题 — 跨 Skill 重复出现的缺陷模式总结
评分流程（执行指南）
Step 1: 读取 Skill 文件
使用 Read 工具完整读取目标 SKILL.md。如果 Skill 有 references/ 子目录，一并扫描文件结构。
Step 2: 逐维度评分
严格按 references/rubric.md 中定义的 12 个维度逐一评定，每个维度给 0 或 1 分。
评分时必须引用原文证据：每个维度的分数后标注判断依据（原文中的具体行或段落）。
Step 3: 计算总分与分级
| 总分 | 等级 | 标签 | SkillsBench 对齐 |
|---|---|---|---|
| 0-8 | 🔴 基石层 (Foundation) | 需要大幅改进 | 对应 ~75% 的 Skills，平均分 6.2 |
| 9-10 | 🟡 专业层 (Professional) | 扎实可用 | 对应 ~25% 的 Skills，提升 16.2% 成功率 |
| 11-12 | 🟢 精品层 (Premium) | 生产级范例 | 对应 ~2.5% 的 Skills，工业级落地 |
Step 4: 输出评测报告
报告格式如下：
╔══════════════════════════════════════════╗
║ SkillsBench Skill 质量评测报告 ║
╠══════════════════════════════════════════╣
║ Skill: <name> ║
║ 版本: <version> ║
║ 行数: <line_count> ║
╠══════════════════════════════════════════╣
║ 总分: X/12 | 等级: 🔴/🟡/🟢 X层 ║
║ SkillsBench 百分位: 超越 ~XX% 的技能 ║
╠══════════════════════════════════════════╣
║ # 维度 (12项) 得分 ║
║ 1 Frontmatter 元数据 ✅/❌ ║
║ 2 触发条件明确性 ✅/❌ ║
║ 3 角色/人设设定 ✅/❌ ║
║ 4 指令结构清晰度 ✅/❌ ║
║ 5 自由度分级 ✅/❌ ║
║ 6 输出格式规范 ✅/❌ ║
║ 7 示例覆盖度 ✅/❌ ║
║ 8 陷阱/已知坑点 ✅/❌ ║
║ 9 约束条件明确 ✅/❌ ║
║ 10 工具控制 ✅/❌ ║
║ 11 验证机制 ✅/❌ ║
║ 12 简洁性 ✅/❌ ║
╠══════════════════════════════════════════╣
║ 🔧 改进建议 (按影响优先级排序) ║
║ 1. [维度X] 具体修复方案... ║
║ 2. [维度Y] 具体修复方案... ║
║ ... ║
╚══════════════════════════════════════════╝
Step 5: 批量模式额外输出
批量评测完成后，追加：
排行榜：
🏆 Skill 质量排行榜 (SkillsBench 12分制)
────────────────────────────────────────
1. 🟢 skill-name-1 11/12 精品层
2. 🟡 skill-name-2 10/12 专业层
3. 🟡 skill-name-3 9/12 专业层
...
热力图 (标注全库薄弱维度)：
📊 全库维度通过率热力图
────────────────────────
Frontmatter 元数据 ████████░░ 80%
触发条件明确性 ██████░░░░ 60%
角色/人设设定 ██░░░░░░░░ 20% ← 最薄弱
...
系统性问题 (≥30% Skill 共有的缺陷)：
⚠️ 系统性缺陷
────────────────────────
1. 68% 的 Skill 缺少「陷阱/已知坑点」章节
2. 55% 的 Skill description 未说明触发条件
3. 43% 的 Skill 没有输出格式示例
改进建议生成规则
对每个失分维度，按以下格式生成建议：
[维度名称] → 问题：<具体缺失了什么>
修复方案：
```markdown
<可直接复制粘贴的修复代码>
```
参考范例：<指向评分高的 Skill 中的对应章节>
排序规则：按影响程度排序。以下维度失分影响更大，优先排列：
- 维度 2 (触发条件)：直接影响 Skill 是否能被正确调用
- 维度 4 (指令结构)：直接影响执行成功率
- 维度 8 (陷阱)：直接影响错误率
- 维度 10 (工具控制)：直接影响安全性
重要原则
- 客观证据 — 每个维度的评分必须引用原文具体行/段落作为证据
- 不猜测意图 — 只看写了什么，不看"可能想表达什么"
- 可执行建议 — 每个改进建议必须是可直接使用的代码片段
- SkillsBench 对齐 — 报告中明确标注百分位和层级对应关系
- 尊重差异 — 不同 Skill 有不同定位 (工具型/工作流型/知识型)，评分时考虑定位差异
辅助工具 (scripts/)
batch-scan.py — 批量扫描
快速摸底 Skill 库基本状况，无需 LLM 介入：
# 扫描全部 Skill，输出 CSV 报告
python scripts/batch-scan.py ~/.workbuddy/skills/
# 输出 JSON 格式
python scripts/batch-scan.py ~/.workbuddy/skills/ --json
# 质量门禁：平均分低于 7 则 exit 1（适合 CI）
python scripts/batch-scan.py ~/.workbuddy/skills/ --gate 7
输出字段：name, lines, h2_count, frontmatter, allowed_tools, triggers, gotchas, constraints, verification, examples, quick_score(快速估分 0-12)
report-card.py — 报告生成
从评测结果 JSON 生成格式化 Markdown 报告：
# 单 Skill 评测报告
python scripts/report-card.py result.json -o report.md
# 批量排行榜
python scripts/report-card.py results.json --batch -o leaderboard.md
报告模板 (assets/templates/)
评测时可直接套用的 Markdown 模板（含 {{占位符}}）：
| 模板 | 用途 |
|---|---|
assets/templates/report-template.md |
单 Skill 评测报告模板 |
assets/templates/batch-summary-template.md |
批量排行榜 + 热力图 + 系统性缺陷模板 |
使用方式：读取模板 → 替换 {{占位符}} 为实际评分数据 → 输出最终报告。
文件结构
skill-evaluator/
├── SKILL.md # 主文件
├── scripts/
│ ├── batch-scan.py # 批量扫描工具
│ └── report-card.py # 报告生成工具
├── references/
│ ├── rubric.md # 12维度评分标准
│ └── scoring-guide.md # 评分指南与对齐说明
└── assets/
└── templates/
├── report-template.md # 单Skill报告模板
└── batch-summary-template.md # 批量排行榜模板
