Skill 上架体检官 · Eval Gate
Overview
把「这个 Skill 到底能不能发布」变成一条可复现的证据链。检测器不调用模型、不联网、不读系统时间，同一目录永远得到同一分数，因此结果可以直接放进 CI 当门禁，也可以贴成 README 徽章。
判定永远附带证据与修复建议；不给黑盒分数，不因为想让分数好看而放宽规则。
何时使用 / 何时不使用
在下列情况启动本技能：
- 准备把 Skill 发布到 SkillHub 或任意 Agent 技能市场，提交审核前自查。
- 改了 SKILL.md 的 description，想知道触发边界是否变宽或变窄。
- 需要给自己的 Skill 生成一份 evals 测试集骨架（正例 + 负例 + 回归用例）。
- 需要在 README 或详情页展示一个可复现的质量徽章。
- 需要比较改版前后是否发生退化，并把失败固化成长期回归用例。
在下列情况保持沉默，不要加载本技能：
- 用户要评测的是 Agent 的真实运行效果、成功率或模型表现——那需要隔离 Runner 与多次重复试验，本技能只做静态可评测性检查。
- 用户要核查正文里的事实、引用或数字真伪。
- 用户要改写、润色或翻译 SKILL.md 内容。
- 目标不是 SKILL.md 体系（例如纯 MCP Server、普通 Python 包、
.cursorrules）。
快速上手
在技能根目录执行（仅 Python 3.9+ 标准库，无需 pip install）：
# 1. 评分卡
python scripts/eval_gate.py /path/to/my-skill
# 2. 生成徽章与机器可读结果
python scripts/eval_gate.py /path/to/my-skill --badge ./badge.svg --json > report.json
# 3. 建立基线，改版后做回归对比（有退化即退出码 3）
python scripts/eval_gate.py /path/to/my-skill --write-baseline baseline.json --quiet
python scripts/eval_gate.py /path/to/my-skill --baseline baseline.json
# 4. CI 门禁：低于 80 分直接失败
python scripts/eval_gate.py /path/to/my-skill --min-score 80 --quiet
# 5. 给新技能生成 3 正例 + 3 负例 + 1 回归用例的骨架
python scripts/eval_gate.py /path/to/my-skill --init-evals
Windows 下把 python 换成 py -3 或实际解释器路径即可；路径含空格时用双引号包裹。
工作流
- 确认目标：定位被测技能根目录，确认存在
SKILL.md。用户给的是单个文件时，取其父目录。 - 运行评分：执行
scripts/eval_gate.py <目标目录>，读取评分卡。不要凭肉眼估计分数。 - 按证据修复：只处理 FAIL / WARN 项，逐条按
→后的建议改；改完重跑，对比分数。禁止通过修改检测器规则、删除失败项或降低--min-score来让门禁通过。 - 补齐 Eval：缺少测试集时执行
--init-evals，把占位 prompt 换成真实用户说法，为每条补上可被程序检查的expected_checks。 - 固化为门禁：
--write-baseline保存基线；此后每次改版都带--baseline运行。任何 PASS→FAIL 或总分下降都判为 REGRESSION，先修再合并。 - 输出徽章：得分达到预期后
--badge生成 SVG，供 README 或详情页引用。
评分维度
八维共 28 个检查项，基准权重 103，总分按权重归一化到 0–100（新增维度不破坏满分契约）。等级 A≥90 / B≥80 / C≥70 / D≥60 / E<60。安全红线中的「危险执行」属于硬阻断，命中即判 F 且退出码 2，不因总分高而豁免；X5「硬编码绝对路径」只扣分、不硬阻断。
| 维度 | 分值 | 核心问题 |
|---|---|---|
| 结构合规 | 18 | frontmatter 与发布字段齐备吗 |
| 触发描述 | 20 | 该出手时出得来、不该出手时保持沉默吗 |
| 边界与负例 | 16 | 有可回归的测试集吗 |
| 脚本可执行 | 12 | 打包脚本能跑、依赖说清了吗 |
| 资源引用 | 10 | 引用的文件真实存在吗、正文是否过载 |
| 安全红线 | 17 | 会被平台安全审核拒绝吗、脚本是否绑死某台机器 |
| 文档可用 | 6 | 买家装之前看得懂吗 |
| 可评测性 | 4 | 有没有不改变行为的空转指令 |
完整判定规则、权重来源与每条修复方法见 references/rubric.md；安全规则表见 assets/security_rules.json。
输出契约
- 默认：人类可读评分卡，按维度分组，每条含
PASS/WARN/FAIL、得分、证据、修复建议。 --json：完整机器可读结果，含score、grade、blocked、block_reasons、每项checks与exit_hint。--badge：SVG 徽章文件，内容为分数与等级。- 退出码：
0通过、1未达门禁或目标无效、2安全硬阻断、3检测到回归。
失败处理与硬边界
- 目标目录没有
SKILL.md：直接报错退出码 1，不猜测、不自动创建。 - 规则表
assets/security_rules.json缺失：明确报出缺失路径，不静默降级为「无规则」。 - 被测技能含危险执行模式：返回退出码 2，并在报告中列出文件与原因；不自行删除、不改写用户文件。
- 回归检测到退化：返回退出码 3，列出具体检查项；不允许通过覆盖基线文件来消除告警。
- 本技能只读被测目录，从不写入被测目录；唯一例外是用户显式传入
--init-evals时创建evals/evals.json，且目标已存在时不会覆盖。
已知限制（如实声明）
- 静态检查无法证明 Skill 在真实 Agent 中「有效」。要证明增量价值，仍需隔离 Runner、每例 3–5 次重复、跨 Harness 测试与 Skill ON/OFF 消融，本技能不提供这些能力。
- frontmatter 解析只覆盖 SKILL.md 常用的 YAML 子集（标量、块标量），不支持嵌套对象、锚点与复杂类型。
- 安全规则是正则启发式，不等于完整漏洞扫描；平台仍有独立的三线安全准入。
- X5 只扫描代码文件，不判定 Markdown 中的路径示例，也不验证脚本在他人机器上是否真的能跑通；它报的是「可被静态观察到的机器绑定」，不是可移植性证明。
expected_checks是否真的可判定，由用例作者负责；本技能只检查字段存在。- 分数是「发布就绪度」，不是「能力质量」。一个 95 分的 Skill 仍可能解决了一个没人需要的问题。
资源索引
scripts/eval_gate.py：检测器全部逻辑，可直接执行，也可被 CI 引用。references/rubric.md：完整评分规则与修复手册，按需加载。assets/security_rules.json：安全规则表（数据），可扩展。assets/sample-report.md：一份真实运行的示例评分卡，用于详情页与传播。evals/evals.json：本技能自带的 11 条 Eval 用例（含regression-003硬编码路径真实失败），作为测试集格式示范。README.md：面向安装者的快速上手与示例。
