# Skill Design Benchmark

> 评估一个或一批 Agent Skills 的设计质量，按 8 个有来源、有证据的维度输出 0–100 分、S/A/B/C/D 等级和优先改进项。重点检查触发边界、完成闭环、决策适应、安全恢复、上下文效率、复杂度适配、一致性和真实行为；不奖励文件数量或流程堆砌。用于‘给 skill 打分’、‘扫描全部 skills’、‘benchmark skill 设计’、‘比较哪些 skills 值得优化’等场景；只评估，不修改被评 Skill。

- Skill: `wangjs-jacky/skill-design-benchmark` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add wangjs-jacky/skill-design-benchmark`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wangjs-jacky/skill-design-benchmark/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: wangjs-jacky (https://skillmd.com/u/wangjs-jacky)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wangjs-jacky/skill-design-benchmark

---


# Skill Design Benchmark

以最少上下文，对 Agent Skill 的设计质量做可追溯评分。评当前证据，不评作者意图，也不评领域知识多少。

## 不变量

- **默认只读**：检查文件、脚本、测试和现有运行记录；不修改被评 Skill。
- **每个分数必须附证据**：引用目标文件路径与行号、脚本输出、测试或运行记录。仅写在说明里的能力不等于已证明。
- **资源数量本身不加分**：存在 `references/`、`scripts/`、状态机或 SubAgent 都不是加分项。
- **不适用的复杂机制不扣分**：按任务本身需要的复杂度评估。简单 Skill 可以获得高分，复杂 Skill 也可能因过度设计失分。
- **100 分不得四舍五入**：满分必须包含运行证据，且所有维度均满足满分锚点。
- **静态最高 85 分**：前 7 个维度检查设计；最后 15 分只认真实行为验证，存在测试目录不等于已验证。
- 不为凑等级调整分数，不强制分布，也不拿两个参考项目当标准答案。

## 评测模式

| 模式 | 何时使用 | 证据范围 |
|---|---|---|
| `static` | 默认；单个或批量快速扫描 | 当前文件、资源，以及解析、链接、语法、`--help` 等无副作用检查；最高 85 分 |
| `verified` | 有现成记录，或允许安全前向测试 | `static` + 真实触发、边界/失败、产物和验收证据 |

无法安全运行时保持 `static`，明确证据缺口，不为追求高分制造副作用。

## 工作流

1. **确定范围**：接受一个 `SKILL.md`、一个 Skill 目录或仓库目录；记录当前 commit 与工作树状态，避免把快照结论说成永久事实。
2. **采集事实**：运行：

   ```bash
   python3 "${CLAUDE_SKILL_DIR}/scripts/collect_skill_facts.py" <目标> --format json
   ```

   若运行时不提供 `CLAUDE_SKILL_DIR`，从当前 `SKILL.md` 所在目录解析脚本路径。脚本只提供客观事实，不代替评分。
3. **建立画像**：记录产物（回答/文件/状态）、副作用（无/本地/外部）、路径（单路径/多分支/长流程）和依赖（无/本地/外部）。先判断需要多少复杂度，再评分。
4. **加载评分表**：完整读取 [`references/rubric.md`](references/rubric.md)，逐维度评分。不要预读其它被评 Skill 的所有 references；只读取会改变当前判断的文件。
5. **检查证据**：优先级为运行产物与断言 > 可执行脚本 > 当前规则文本 > README 或自我声明。发现矛盾时以更接近真实执行的证据为准。
6. **应用门槛与上限**：先处理 rubric 中的硬上限，再求和。保留原始整数分，不向上取整。
7. **输出报告**：批量任务先给总表，再给每个 Skill 的简版；只列最重要的 1–3 个改进项。

## 批量扫描纪律

- 先用事实采集脚本建立清单，再逐个读取主 `SKILL.md`。
- 只有该 Skill 的主文件明确路由到某个 reference，或当前维度无法判断时，才读取对应 reference。
- 不把整个仓库一次性塞进上下文；每评完一个 Skill 就形成短结论，再进入下一个。
- 使用同一 rubric 绝对评分，不按仓库内排名反推分数。

## 输出格式

```markdown
# <skill-name> — <总分>/100 · <等级>

画像：<产物> · <副作用> · <路径> · <依赖>
模式：static <x>/85 + behavior <y>/15

| 维度 | 得分 | 目标证据 | Benchmark 依据 |
|---|---:|---|---|
| D1 ... | x/12 | path:line / test / trace | G-...、W-... |

硬上限：无 | <规则与原因>
证据缺口：<没有则写“无关键缺口”>

优先改进：
1. P0 — <影响最大、可执行的一项>
2. P1 — <第二项，可省略>
3. P2 — <第三项，可省略>
```

等级固定为：`S 95–100`、`A 85–94`、`B 70–84`、`C 50–69`、`D 0–49`。分数表达当前证据下的设计成熟度，不代表业务知识价值。

批量总表只保留：Skill、分数、等级、模式、最大优点、最高优先级问题。详细报告按需展开，避免输出膨胀。

## References 路由

| 文件 | 何时读取 |
|---|---|
| [`references/rubric.md`](references/rubric.md) | 每次评分必读；唯一评分定义 |
| [`references/source-basis.md`](references/source-basis.md) | 用户追问准则来源、维护 benchmark 或核查来源 ID 时读取；普通批量扫描不必加载 |