# SkillsBench 评测方法论详解

## 1. SkillsBench 框架简介

SkillsBench 是首个专门评估 AI Agent Skills 效果的学术级基准测试框架,由加州大学伯克利分校等机构联合开发。

**核心论文:** [SkillsBench: Benchmarking How Well Agent Skills Work](https://arxiv.org/abs/2602.12670)

**关键特点:**
- 84 个专家策划的真实任务
- 覆盖多个专业领域(科学计算、工程、金融、法律等)
- 双维度评估:技能有效性(Skill Effectiveness) + 代理熟练度(Agent Proficiency)

---

## 2. 评测方法论核心原则

### 2.1 技能有效性 (Skill Effectiveness)

**定义:** 技能本身的质量、完整性和可用性

**评估维度:**
1. **指令清晰度**: 是否清楚表达了做什么和怎么做
2. **完整性**: 是否包含所有必要的步骤和资源
3. **可执行性**: Agent 是否能够理解并执行
4. **错误处理**: 是否提供了异常情况的处理指导

**量化方法:**
- 任务完成率 (Task Completion Rate)
- 正确性得分 (Correctness Score)
- 所需尝试次数 (Attempts Required)

### 2.2 代理熟练度 (Agent Proficiency)

**定义:** AI 代理理解和执行技能的能力

**评估维度:**
1. **理解能力**: 是否正确理解技能意图
2. **执行准确性**: 是否按照技能指引执行
3. **适应能力**: 遇到问题时是否能灵活调整
4. **效率**: 完成任务所需的时间和步骤

---

## 3. 触发准确性评测指南

### 3.1 测试用例设计

**正向测试** (应该触发):
- 使用典型用户查询
- 使用领域相关术语
- 使用任务相关动词

**反向测试** (不应触发):
- 使用相似但无关的查询
- 使用其他 Skills 的典型查询
- 使用模糊或歧义表达

### 3.2 Description 质量检查清单

- [ ] 清晰描述了 Skill 的核心功能
- [ ] 列举了主要使用场景 (用 "Use when" 或 "适用于" 引导)
- [ ] 包含了关键触发词汇
- [ ] 提供了足够的上下文信息
- [ ] 没有冗余或误导性信息
- [ ] 长度适中 (推荐 100-300 词)

**示例 - 优秀的 description:**
```yaml
description: |
  企业微信文档管理技能。提供文档和智能主页的创建、读取和编辑能力。
  支持通过 docid 或文档 URL 操作企业微信文档(doc_type=3)和智能表格(doc_type=10),
  以及创建智能主页和导出其内容。
  适用场景:(1) 以 Markdown 格式导出获取文档完整内容(异步轮询)
  (2) 新建文档或智能表格 (3) 用 Markdown 格式覆写文档内容
  (4) 将本地 Markdown 文件创建为智能主页 (5) 异步导出智能主页内容为 Markdown 文件。
  当用户需要查看文档内容、创建新文档、编辑文档正文、创建智能主页、
  或获取智能主页内容时触发此 Skill。
```

---

## 4. 执行完整性评测指南

### 4.1 核心要素检查

**必备元素:**
1. **清晰的工作流** - 分步骤说明如何完成任务
2. **具体的工具调用** - 明确需要使用哪些工具/命令
3. **参数说明** - 解释关键参数的含义和取值
4. **示例代码** - 提供可直接运行的代码片段
5. **错误处理** - 说明常见错误和解决方案

### 4.2 完整性评估矩阵

| 元素 | 权重 | 检查项 |
|------|------|--------|
| 工作流清晰度 | 30% | 步骤是否完整?是否有遗漏?逻辑是否清晰? |
| 工具/命令准确性 | 25% | 命令是否正确?参数是否准确? |
| 示例质量 | 20% | 示例是否可运行?是否覆盖主要场景? |
| 错误处理 | 15% | 是否提供错误处理指导? |
| 文档结构 | 10% | 结构是否合理?是否易于查找信息? |

### 4.3 常见缺陷

❌ **缺少关键步骤**
```markdown
# 错误示例
1. 调用 API 获取数据
3. 处理结果并输出
# (缺少步骤 2:解析返回数据)
```

✅ **完整的步骤**
```markdown
1. 调用 API 获取数据
2. 检查返回状态并解析 JSON
3. 处理结果并输出
```

❌ **模糊的工具调用**
```markdown
# 错误示例
使用相关工具读取文件内容
```

✅ **明确的工具调用**
```markdown
使用 `read` 工具读取文件:
​```bash
read /path/to/file.txt
​```
```

---

## 5. 文档质量评测指南

### 5.1 结构化评估

**层级结构:**
- [ ] 有清晰的章节标题
- [ ] 使用合理的标题层级 (H2, H3, H4)
- [ ] 重要信息放在前面

**可读性:**
- [ ] 段落长度适中 (3-5 行)
- [ ] 使用列表和表格组织信息
- [ ] 使用代码块展示命令/代码
- [ ] 使用加粗/斜体突出重点

**示例质量:**
- [ ] 提供真实可用的示例
- [ ] 示例覆盖主要使用场景
- [ ] 示例包含输入和输出
- [ ] 示例有适当的注释

### 5.2 OpenClaw Skill 规范合规性

**必须遵守:**
1. YAML frontmatter 格式正确
2. 只包含 `name` 和 `description` 字段
3. 使用 kebab-case 命名
4. 遵循渐进式披露原则
5. 不创建多余的辅助文档 (如 README.md)

**推荐实践:**
1. SKILL.md 保持在 500 行以内
2. 复杂内容拆分到 references/
3. 可执行脚本放入 scripts/
4. 模板文件放入 assets/

---

## 6. 资源组织评测指南

### 6.1 目录结构检查

**标准结构:**
```
skill-name/
├── SKILL.md              # 必需
├── scripts/              # 可选:可执行脚本
│   └── example.py
├── references/           # 可选:参考文档
│   ├── detailed-guide.md
│   └── api-reference.md
└── assets/               # 可选:模板/资源文件
    └── template.html
```

**检查清单:**
- [ ] 目录命名符合规范 (scripts/references/assets)
- [ ] 文件放在正确的目录中
- [ ] SKILL.md 中正确引用了资源文件
- [ ] 没有多余的文件 (README.md, LICENSE 等)

### 6.2 渐进式披露评估

**原则:** SKILL.md 应该简洁,详细内容放在 references/

**好的做法:**
```markdown
# SKILL.md
详细的 API 文档请参考 [references/api-docs.md](references/api-docs.md)
```

**不好的做法:**
```markdown
# SKILL.md (直接在主文件中放大量细节)
## API 文档
### API 1
详细说明...
### API 2
详细说明...
(导致 SKILL.md 过长)
```

---

## 7. 评分计算方法

### 7.1 维度权重

建议的权重分配:
- 触发准确性: 30%
- 执行完整性: 35%
- 文档质量: 25%
- 资源组织: 10%

### 7.2 综合得分计算

```python
综合得分 = (
    触发准确性得分 * 0.30 +
    执行完整性得分 * 0.35 +
    文档质量得分 * 0.25 +
    资源组织得分 * 0.10
)
```

### 7.3 等级划分

- **优秀** (90-100): 可作为范例的高质量 Skill
- **良好** (70-89): 可正常使用,有改进空间
- **一般** (50-69): 需要显著改进才能有效使用
- **较差** (低于50): 存在严重问题,需要重构

---

## 8. 实际任务测试方法

### 8.1 创建测试用例

**步骤:**
1. 从 Skill description 中提取主要使用场景
2. 为每个场景设计 2-3 个测试查询
3. 定义预期输出和成功标准
4. 执行测试并记录结果

**示例测试用例:**
```markdown
Skill: pdf-editor

测试用例 1:
- 输入: "帮我旋转这个 PDF 文件"
- 预期: 正确触发 pdf-editor skill
- 预期: 执行 scripts/rotate_pdf.py 或提供旋转步骤
- 预期: 生成旋转后的 PDF 文件

测试用例 2:
- 输入: "提取 PDF 中的文本内容"
- 预期: 正确触发 pdf-editor skill
- 预期: 使用合适的工具提取文本
- 预期: 输出提取的文本内容
```

### 8.2 成功标准

**完全成功:** 正确触发 + 完整执行 + 输出正确  
**部分成功:** 正确触发 + 执行有误 或 输出不完整  
**失败:** 未触发 或 触发错误 或 执行失败  

---

## 9. 改进建议生成指南

### 9.1 问题优先级判定

**P0 (严重) - 阻碍 Skill 基本功能:**
- description 严重不准确导致无法触发
- 核心工作流缺失关键步骤
- 示例代码无法运行

**P1 (重要) - 影响 Skill 使用体验:**
- description 不够清晰导致触发不稳定
- 缺少错误处理指导
- 文档结构混乱难以查找

**P2 (一般) - 优化改进:**
- 示例不够丰富
- 文档格式不够美观
- 可以进一步精简

### 9.2 建议的可操作性

**好的建议 (具体可操作):**
```markdown
建议: 在 description 中添加明确的触发场景
具体: 在 description 末尾添加:
"适用场景:(1) 旋转 PDF (2) 提取文本 (3) 合并多个 PDF"
```

**不好的建议 (模糊不具体):**
```markdown
建议: 改进 description
```

---

## 10. 参考资源

- [SkillsBench 官网](https://www.skillsbench.ai/)
- [SkillsBench 论文](https://arxiv.org/abs/2602.12670)
- [SkillsBench GitHub](https://github.com/benchflow-ai/skillsbench)
- [OpenClaw Skill 创建指南](https://docs.openclaw.ai/)