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. 采集事实：运行：

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

   若运行时不提供 CLAUDE_SKILL_DIR，从当前 SKILL.md 所在目录解析脚本路径。脚本只提供客观事实，不代替评分。

3. 建立画像：记录产物（回答/文件/状态）、副作用（无/本地/外部）、路径（单路径/多分支/长流程）和依赖（无/本地/外部）。先判断需要多少复杂度，再评分。

4. 加载评分表：完整读取 references/rubric.md，逐维度评分。不要预读其它被评 Skill 的所有 references；只读取会改变当前判断的文件。

5. 检查证据：优先级为运行产物与断言 > 可执行脚本 > 当前规则文本 > README 或自我声明。发现矛盾时以更接近真实执行的证据为准。

6. 应用门槛与上限：先处理 rubric 中的硬上限，再求和。保留原始整数分，不向上取整。

7. 输出报告：批量任务先给总表，再给每个 Skill 的简版；只列最重要的 1–3 个改进项。

批量扫描纪律

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

输出格式

# <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/source-basis.md	用户追问准则来源、维护 benchmark 或核查来源 ID 时读取；普通批量扫描不必加载