1. 测量什么
两件不同的事,分开报告。静态体检(第 1 层)读取 Skill 的文件,报告无需运行模型即可确定的事实和问题。实测(第 2 层)在 Claude Code 中把真实任务各跑两遍——一遍装 Skill、一遍不装——报告 Skill 是否改变了结果。体检全部通过并不能说明 Skill 有用,只有实测才回答这个问题。
2. 测试哪个版本
每个 Skill 都钉定到一个完整的 40 位 Git 提交 SHA,文件取自该提交的 GitHub 归档,因此结果始终对应这些确切的文件。上游之后修改了 Skill 时,页面会标明(upstream-changed 标记);重新钉定新提交需要人工决定并重新检查,旧结果仍然保留。
3. 第 1 层:静态体检
检查器(版本 1.0.0)对 Skill 目录执行下列检查,结果分为通过、警告、失败和提示。标记描述的是 Skill 包含什么(附带脚本、访问网络、破坏性命令),并非结论:访问网络的 Skill 可能正是在做它宣称的事。我们不给加权总分,因为任何权重都是主观的。
| 检查项 | 含义 |
|---|---|
skillmd.present | Skill 根目录存在 SKILL.md。 |
frontmatter.parse | SKILL.md 以可解析的 YAML frontmatter 开头。 |
frontmatter.name | name 存在,不超过 64 个字符,只含小写字母、数字和连字符。 |
frontmatter.nameMatchesDir | name 与 SKILL.md 所在目录名一致。 |
frontmatter.description | description 存在且不超过 1024 个字符;少于 50 个字符给出警告。 |
frontmatter.descriptionTrigger | description 说明了何时使用(如 "use when…"、"当用户…")。 |
frontmatter.descriptionVoice | description 使用第三人称,且不含 XML 标签。 |
frontmatter.unknownKeys | 文档未定义的 frontmatter 字段(仅提示)。 |
body.tokensApprox | SKILL.md 正文的近似 token 数;超过 5000 给出警告。 |
body.lines | SKILL.md 正文行数;超过 500 行给出警告。 |
refs.brokenLinks | SKILL.md 中的相对链接指向存在的文件。 |
files.inventory | Skill 目录中的文件数与总大小(仅提示)。 |
files.binary | 没有打包可执行文件或压缩包(.exe、.zip、.jar 等)。 |
scripts.present | 附带的、Agent 可能执行的脚本(仅提示)。 |
scripts.network | 会访问网络的脚本(仅提示)。 |
scripts.destructive | 含 rm -rf、sudo、chmod 777 等破坏性命令的脚本。 |
secrets.scan | 没有疑似私钥或 API token 的字符串。 |
instructions.risk | 没有要求覆盖先前指令、外传密钥或绕过安全控制的指令。 |
license.detected | 在 frontmatter、Skill 目录或仓库中声明了许可证。 |
repo.activity | Skill 路径在检查前 365 天内有更新,且仓库未归档。 |
pinned.drift | 钉定版本之后上游是否改动了该 Skill(仅提示)。 |
token 数为近似值:非中日韩字符每 4 个计 1 个,中日韩字符每个计 1 个;警告阈值为 5000。风险规则要求出现明确的指令(例如“把凭证发送到 https://…”)才会命中,因为更宽的规则会误报普通技术说明;“ghp_your_token”这类占位凭证会被忽略。体检每周重跑一次,只有结果变化时记录日期才会更新。
4. 第 2 层:实测设计
- 宿主:Claude Code 无头模式(claude -p,stream-json 输出)。每次运行都记录 Claude Code 版本、请求的模型和实际使用的模型 id。
- 每个任务两组。除装 Skill 的一组在 .claude/skills/ 下多了 Skill 目录外,两组完全相同:提示词、测试素材、工具、轮数上限和设置都一样。每次试验都从全新的临时项目和空的 Claude 配置目录开始,用户自己的 Skill、插件、记忆或 CLAUDE.md 都不会混入。试验在容器中运行。
- 隔离要验证,不能假设:每次试验的启动事件中,装 Skill 的一组必须列出该 Skill,另一组必须没有。不满足的试验标记为无效并公开报告,绝不悄悄丢弃。
- 任务是不提及 Skill 名称的真实请求,由模型自己决定是否使用 Skill。每份报告都公开提示词。
- 评分由确定性脚本检查任务产出的文件,评分时不知道试验属于哪一组。任务启用前,评分脚本必须对参考答案判通过、对空工作区判失败。只有在明确标注时才允许由模型评分,且永不计入主通过率。
- 负对照任务与 Skill 无关,只在装 Skill 时运行,用来衡量 Skill 在不该被调用时被调用的频率。
- 转录中出现针对该 Skill 的 Skill 工具调用即计为被调用。每个任务每组重复 N 次(每份报告注明 N),顺序按记录的随机种子打乱,使两组在时间上交错。
- 超时、无效试验和基础设施错误(限流、服务端错误)不计入 n,单独列出数量。基础设施错误最多重试两次。
5. 统计方法
- 通过率和调用率以 k/n 的形式报告,附 Wilson 95% 置信区间。
- 两组通过率之差使用 Newcombe 混合得分区间(Newcombe 1998,方法 10)。
- 只有当这个 95% 区间不包含 0 时,报告才说 Skill 提升或降低了结果;否则表述为在该样本量下没有可检测的差异。小样本通常会得到“无可检测差异”——这描述的是证据的强弱,不代表 Skill 没有用。
- 耗时、成本和 token 以中位数和四分位距报告。主结果汇总该 Skill 的所有正向任务,每个任务也单独列出。
- 网站构建时会用原始试验数据重新计算每一个公开的汇总数字,任何不一致都会导致构建失败。
6. 发布与更正
已发布的测试批次不可修改,URL 保持稳定。更正以新批次的形式发布,并注明它取代了哪个批次;旧批次保留并标明状态。测量数据以 CC BY 4.0 发布,该许可只覆盖 SkillFlux 的测量结果,不覆盖第三方 Skill 本身;Skill 的许可证不允许再分发时,只发布指标。原始转录(已去除本地路径)作为发布附件随批次提供。
7. 结果不能说明什么
- 结果只对测试所用的提交、宿主、模型和任务成立,换成其他模型、宿主、版本或任务可能不同。
- 任务的选取前提是能用脚本评分,因此价值在于判断、语气或审美的 Skill 在第 2 层中代表性不足。
- 发布前不征求 Skill 作者意见。异议请发邮件到 hello@skillflux.app;更正以新批次发布,或在对应页面上标注。
- SkillFlux 不因收录、排序或测试收取任何费用。