Skill 评估框架与评分细则¶
版本：v2.0 | 维护人：SkillForge 组 | 面向对象：Skill 作者、审阅人、评估工具使用者
本文档描述 Skill 质量评估的维度划分、子项定义与等级判定标准，供人工审阅与自动化评分（skill-eval）共同参照。
〇、写在前面：评分框架的设计原则¶
Skill 质量评估的目的不是给作者打分，而是帮 Skill 作者定位薄弱环节——哪里写得不够清楚、哪里遗漏了必要信息、哪里存在安全隐患。评分是手段，改进是目的。
本框架有四条核心设计原则：
- ABCD 四等制——每个子项只判 A/B/C/D 四级，避免"打 82 分还是 83 分"的无谓纠结。等级对应固定系数：A=100%，B=60%，C=30%，D=0%。
- 维度正交（MECE）——8 个维度两两语义不重叠，一个问题只在一个维度里评。这样才能定位到具体薄弱点，而不是"综合评价一般"。
- 子项独立——每个维度内的子项也彼此独立，评分时只看该子项声明的关注点，不牵扯其他子项的内容。
- 缺失即 D——没有写就是 0 分，不给"可能作者忘了写但心里知道"的辩解空间。
打分公式：
$$ \text{子项得分} = 100 \times \text{维度权重} \times \text{子项权重} \times \text{等级系数} $$
$$ \text{总分} = \sum \text{子项得分} $$
满分 100。若任一维度得分率 < 30%，标注为短板维度，优先修复。
一、评分维度总览¶
Skill 的质量拆成 8 个正交维度，权重分配如下：
| 编号 | 维度 | 权重 | 一句话概括 |
|---|---|---|---|
| 1 | 可发现性 | 15% | Agent 能否在正确时机找到并加载这个 Skill？ |
| 2 | 清晰度 | 15% | 已经写下的指令是否无歧义、结构化？ |
| 3 | 完备性 | 20% | 必要信息是否全部覆盖？ |
| 4 | 一致性 | 10% | 已有信息之间是否自洽无矛盾？ |
| 5 | 安全性 | 15% | 风险和破坏性操作是否受控？ |
| 6 | 经济性 | 5% | Token 消耗是否合理、无冗余？ |
| 7 | 可移植性 | 10% | 换个环境还能用吗？ |
| 8 | 可维护性 | 10% | 将来容易修改和扩展吗？ |
下面逐个维度展开。
二、可发现性（15%）¶
核心问题：Agent 在正确时机能不能找到这个 Skill？
Agent 加载 Skill 前会扫描 frontmatter 的 name 和 description，据此判断"要不要用这个 Skill"。如果这两个字段写得不好，再优秀的 Skill 也进不了 Agent 的候选池——写了等于没写。
2.1 命名质量（30%）¶
只看 frontmatter 的 name 字段本身，不结合 description 判断。
| 等级 | 判定标准 | 示例 |
|---|---|---|
| A | 动作导向 + 具体对象，一见即知功能 | github-pr-workflow、vasp-relax |
| B | 可接受但不够具体 | github、vasp |
| C | 有命名但含义不明，需猜测才能理解功能 | wrangler、toolkit |
| D | 无 name 字段，或无意义命名 |
helper、utils、misc |
2.2 描述准确性（40%）¶
看 frontmatter 的 description 字段以及正文中的 Overview / When to Use 章节。只评这两块内容本身的质量，不评 name 也不评负向边界。
description 的黄金公式：Use when \<触发场景>. \<能力/覆盖范围>.
| 等级 | 判定标准 |
|---|---|
| A | 精确说明"做什么 + 何时用"，含关键触发词，第三方一看即懂 |
| B | 说明了做什么和何时用，但关键词不够精确或表述笼统 |
| C | 粗略说明做什么，但没写何时用，缺乏关键词 |
| D | 无 description，或极度模糊到无法判断做什么 |
2.3 负向边界声明（30%）¶
只看 Skill 中"不适用范围"的显式声明，通常出现在 When to Use 的 Don't use for: 小节。
| 等级 | 判定标准 |
|---|---|
| A | 明确列举不处理的场景，且与相似 Skill 有可辨识的区分标准 |
| B | 明确列举不处理的场景类型 |
| C | 有边界说明但模糊，无法据此排除具体场景 |
| D | 无任何"不处理什么"的说明 |
为什么负向边界重要
没有负向边界，Agent 会在错误的场景下也加载这个 Skill，然后按里面的步骤去做——结果可能比不加载还糟。写清楚"不该用"和"该用"同等重要。
三、清晰度（15%）¶
核心问题：已经写下的指令，读得懂、能执行吗？
清晰度评估的是已写内容的质量，不是内容多寡。哪怕只写了三句话，只要每句都无歧义、可执行，清晰度就是 A。
3.1 指令语义精确性（50%）¶
评估每一条操作指令、每一个条件分支的用词和语法精度。核心检查项：主语是否明确？动词是否具体？条件能否做 Y/N 判断？
| 等级 | 判定标准 |
|---|---|
| A | 所有指令（含条件分支）有明确主语 + 动词 + 宾语，条件均可做 Y/N 判断 |
| B | 大部分指令可执行，个别用词模糊或条件需推测 |
| C | 部分指令可执行，但多处用词模糊或条件需推测 |
| D | 大量模糊动词（consider / ensure / appropriate），缺主语或宾语，条件分支无法做确定性判断 |
常见的模糊动词
考虑、适当、确保、必要时、根据情况——这些词一出现，Agent 就得靠猜。清晰度的敌人就是这类"看起来说了什么，其实什么都没说"的表述。
3.2 结构化格式（50%）¶
评估文档的视觉层次——标题层级、编号步骤、代码块、分隔符、表格。这是"排版"层面，不评单条指令的语义（那是 3.1）。
| 等级 | 判定标准 |
|---|---|
| A | 充分利用标题层级、编号步骤、代码块、分隔符，视觉层次清晰 |
| B | 有合理的标题层级和编号步骤，代码块使用正确 |
| C | 有基本标题或编号，但层次不清或缺少代码块标记 |
| D | 纯文本段落堆砌，无标题 / 编号 / 分隔 |
四、完备性（20%）¶
核心问题：必要信息是不是全都覆盖了？
这是权重最高的维度。清晰度评估"写了的部分好不好"，完备性评估"该写的都写了没有"。
4.1 主流程覆盖（25%）¶
评估正常执行路径（happy path）的步骤完整性。异常路径归 4.3。
| 等级 | 判定标准 |
|---|---|
| A | 核心流程完整、顺序准确、无遗漏 |
| B | 基本完整，有轻微遗漏但不阻断主流程 |
| C | 有基本步骤但存在明显遗漏，部分环节需猜测 |
| D | 关键步骤缺失，按现有内容无法完成核心任务 |
4.2 外部依赖声明（20%）¶
评估运行前需要准备什么——工具、权限、环境依赖。通常在 Prerequisites / Requirements / Setup 章节。
| 等级 | 判定标准 |
|---|---|
| A | 所有工具 / 权限 / 环境依赖完整列出，且说明获取方式 |
| B | 列出了主要依赖，获取方式基本说明 |
| C | 列出部分依赖，但获取方式缺失或不完整 |
| D | 未列出任何依赖 |
和输入输出契约的区别
外部依赖 = 运行前要准备什么（VASP 是否装了、GPU 是否可用）；输入输出契约 = 运行时数据长什么样（config.yaml 有哪些字段）。前者归 4.2，后者归 4.4。
4.3 异常处理指导（20%）¶
评估对失败 / 边界场景的文字处理策略。注意：这一项评的是"文字层面的策略描述"，不是"有没有具体的示例演示"（后者归 4.5）。
| 等级 | 判定标准 |
|---|---|
| A | 系统覆盖输入缺失、格式错误、依赖不可用等典型异常，每种有明确处理分支 |
| B | 覆盖了部分常见错误，有初步处理指导 |
| C | 提及少数常见错误，但处理方式笼统 |
| D | 完全未提及任何失败 / 边界情况的处理方式 |
4.4 输入输出契约（15%）¶
评估输入输出的数据结构定义——字段、类型、默认值、约束、校验规则。
| 等级 | 判定标准 |
|---|---|
| A | 完整的输入 / 输出规格（类型、默认值、约束、校验规则） |
| B | 有主要字段定义，但缺少部分约束或默认值 |
| C | 有大致描述但缺字段约束或类型 |
| D | 未定义输入输出的任何规格 |
4.5 示例完备度（20%）¶
评估具体示例的数量和场景覆盖。
| 等级 | 判定标准 |
|---|---|
| A | 正例 + 反例 + 边界用例均覆盖，参数完整，与描述一致 |
| B | 有正向示例，但反例或边界用例不全 |
| C | 仅有一个正向示例，缺反例或边界用例 |
| D | 无任何示例 |
五、一致性（10%）¶
核心问题：已有信息之间自洽吗？
一致性由两个互补的检查组成——一个负面（找矛盾），一个正面（看术语统一）。
5.1 指令无矛盾（60%）——负面检查¶
在指令之间找逻辑冲突。同一场景下有没有出现互相打架的两条规则？
| 等级 | 判定标准 |
|---|---|
| A | 全部指令逻辑自洽；若有潜在冲突场景，已给出明确优先级排序 |
| B | 整体自洽，个别边缘指令略有矛盾 |
| C | 存在边缘指令矛盾，无消解机制 |
| D | 同一场景存在多处直接冲突的指令，且无消解机制 |
5.2 术语一致性（40%）——正面检查¶
在全文用词中看统一性。同一概念是不是自始至终用同一个术语？
| 等级 | 判定标准 |
|---|---|
| A | 全文术语严格统一，有术语表或别名说明 |
| B | 术语基本一致，偶尔混用不影响理解 |
| C | 偶尔混用，部分造成理解困难 |
| D | 同一概念多处使用不同名称，造成混淆 |
术语混用的典型例子
同一份文档里，一会儿叫"K 点"，一会儿叫"K-points"，一会儿叫"网格密度"——读者要在脑子里做映射，Agent 更是容易搞混。要么统一，要么在开头列一份术语对照表。
六、安全性（15%）¶
核心问题：风险和破坏性操作是否受控？
四个子项对应四个不同的方向：INBOUND（谁能进来）、EXECUTION（怎么安全地做）、CREDENTIALS IN（凭据怎么进来）、DATA OUT（数据怎么出去）。
6.1 意图拒绝边界（25%）—— INBOUND¶
评估对恶意 / 有害请求的拒绝规则。Skill 是不是说清楚了"什么请求我不做"？
Note
Skill 因功能需要而声明 API Key / 网络访问需求，不扣分。
| 等级 | 判定标准 |
|---|---|
| A | 明确列举需拒绝的意图场景，给出拒绝模板 |
| B | 有明确的拒绝规则，但场景列举不够全面 |
| C | 有简单安全声明但边界模糊 |
| D | Skill 可触达有害操作但无任何拒绝规则 |
6.2 破坏性操作约束（25%）—— EXECUTION¶
评估对合法但不可逆操作（删除、推送、发送、覆写）的保护——确认步骤、回滚方案、干跑模式。
| 等级 | 判定标准 |
|---|---|
| A | 不可逆操作有明确确认步骤或回滚方案 |
| B | 有确认步骤，但部分操作缺少保护 |
| C | 有提醒但无强制保护机制 |
| D | 涉及不可逆操作无任何确认 / 保护 |
6.3 凭据安全管理（25%）—— CREDENTIALS IN¶
评估凭据（API Key、Token、密码）的传入和存储方式。
| 等级 | 判定标准 |
|---|---|
| A | 凭据通过环境变量 / 配置注入，明确不记录到日志 |
| B | 凭据通过环境变量注入，但日志处理不明确 |
| C | 凭据作为参数但未说明安全存储方式 |
| D | 在文档 / 脚本中硬编码凭据或敏感信息 |
6.4 输出脱敏规则（25%）—— DATA OUT¶
评估输出中的敏感信息过滤——脱敏、匿名化、字段裁剪。
| 等级 | 判定标准 |
|---|---|
| A | 明确要求脱敏 / 匿名化，定义过滤规则 |
| B | 有基本脱敏要求，但规则不够具体 |
| C | 有提醒但无具体过滤策略 |
| D | 输出可能含敏感内容但无任何过滤规则 |
七、经济性（5%）¶
核心问题：Token 消耗合理吗？有没有冗余？
Skill 加载时全文注入 context。太长会挤占对话历史和工具输出的空间，太啰嗦会降低 Agent 注意力密度。经济性从三个角度评。
7.1 绝对长度（35%）——多大¶
纯量度判断，看行数和 token 数。
| 等级 | 判定标准 |
|---|---|
| A | ≤ 500 行 且 ≤ 5000 token |
| B | 略超标但有组织，可接受 |
| C | 明显超标（300-500 行）但有一定组织 |
| D | > 500 行 或 token 严重超标 |
7.2 信息密度（35%）——值不值¶
质量判断，看每段内容的必要性。核心自问："删掉这段会出错吗？" 答案"会"就是必要，答案"不会"就是冗余。
| 等级 | 判定标准 |
|---|---|
| A | 每段都有不可替代的信息量 |
| B | 有少量解释性冗余，整体密度可接受 |
| C | 有较多解释性冗余，信息密度偏低 |
| D | 大量填充 / 通用知识，Agent 不看也不影响执行 |
Note
绝对长度和信息密度是独立评分——短文件也可能全是废话（低密度），长文件也可能每句都必要（高密度）。
7.3 渐进披露（30%）——放哪里¶
评估主文件与 references/ 的内容分布策略。
| 等级 | 判定标准 |
|---|---|
| A | 详细内容正确使用 references/，"何时读哪个文件"有明确说明 |
| B | 有合理的拆分，引用关系基本清楚 |
| C | 有部分拆分但引用关系不清 |
| D | 所有内容堆在主文件，未做拆分 |
八、可移植性（10%）¶
核心问题：换个环境还能用吗？
8.1 值外部化（50%）——技术层面¶
评估所有可变值（路径、URL、阈值、模板）是否提取为配置或变量。
| 等级 | 判定标准 |
|---|---|
| A | 全部可变值通过配置区块 / 环境变量 / 占位符注入，集中管理 |
| B | 多数可变值已外部化，个别遗漏 |
| C | 部分值提取为配置或占位符，关键值仍部分硬编码 |
| D | 关键值硬编码在正文（含绝对路径、固定 URL、魔法数字） |
8.2 跨平台兼容（50%）——架构层面¶
评估是否能在多个平台上运行，或明确标注支持范围。
| 等级 | 判定标准 |
|---|---|
| A | 跨平台可用，或明确标注"支持 X，不支持 Y"及原因 |
| B | 有平台假设但提供了部分兼容说明 |
| C | 有平台假设但无兼容说明 |
| D | 假设特定 OS / 工具链且无替代方案或说明 |
九、可维护性（10%）¶
核心问题：将来容易修改和扩展吗？
三个子项分别对应骨架（结构拆分）、血肉（文字注释）、时间线（版本追踪）。
9.1 模块化结构（40%）——骨架¶
评估功能是否拆分为独立可修改的单元。
| 等级 | 判定标准 |
|---|---|
| A | 独立功能拆分为子模块 / 子提示，单一职责，修改局部化 |
| B | 有合理的分段，部分逻辑可独立修改 |
| C | 有分段但关键逻辑耦合，改一处需动多处 |
| D | 所有内容堆在一起，无分段 |
9.2 注释与文档（35%）——血肉¶
评估是否解释了设计意图和决策理由——"为什么这么做"，不是"做了什么"。
| 等级 | 判定标准 |
|---|---|
| A | 解释"为什么这么做" + 设计权衡，有完整的使用 / 修改指南 |
| B | 有部分"为什么这么做"的解释，但不完整 |
| C | 有注释但只说"做了什么"，缺设计意图 |
| D | 无注释或注释与内容无关 |
9.3 版本与变更追踪（25%）——时间线¶
评估是否有版本号和变更记录。
| 等级 | 判定标准 |
|---|---|
| A | 语义化版本 + CHANGELOG 或更新说明 |
| B | 有版本号和简单的变更记录 |
| C | 有版本号但无变更记录 |
| D | 无版本信息 |
十、如何使用本框架¶
作为 Skill 作者¶
写完初稿后，对照 8 个维度自查一遍：
- 先查完备性（20%）和可发现性（15%）——这两块权重最高，也是低分重灾区。
- 再查安全性和清晰度——涉及不可逆操作时安全性尤其关键。
- 一致性、经济性、可移植性、可维护性最后过——这几项往往靠一次全文重读就能改到 B 以上。
作为审阅人¶
不用逐项打分，先扫一遍找明显的 D：
- 有没有
Don't use for:段落？没有就是 2.3 D。 - 有没有 pitfalls / Verification Checklist？没有就是 4.3 / 4.5 D。
- 有没有硬编码路径 / URL？有就是 8.1 D。
找完 D，再考虑剩下的是 A 还是 B。
作为自动化工具（skill-eval）¶
评分逻辑：LLM 只负责判 A/B/C/D，权重计算在代码里完成。评估结果给出每个子项的等级 + 总分 + 短板维度列表，作者按短板维度优先修复。
附录：完整权重表¶
| 维度 | 维度权重 | 子项 | 子项权重 | 满分权重 |
|---|---|---|---|---|
| 1 可发现性 | 15% | 命名质量 | 30% | 4.5 |
| 描述准确性 | 40% | 6.0 | ||
| 负向边界声明 | 30% | 4.5 | ||
| 2 清晰度 | 15% | 指令语义精确性 | 50% | 7.5 |
| 结构化格式 | 50% | 7.5 | ||
| 3 完备性 | 20% | 主流程覆盖 | 25% | 5.0 |
| 外部依赖声明 | 20% | 4.0 | ||
| 异常处理指导 | 20% | 4.0 | ||
| 输入输出契约 | 15% | 3.0 | ||
| 示例完备度 | 20% | 4.0 | ||
| 4 一致性 | 10% | 指令无矛盾 | 60% | 6.0 |
| 术语一致性 | 40% | 4.0 | ||
| 5 安全性 | 15% | 意图拒绝边界 | 25% | 3.75 |
| 破坏性操作约束 | 25% | 3.75 | ||
| 凭据安全管理 | 25% | 3.75 | ||
| 输出脱敏规则 | 25% | 3.75 | ||
| 6 经济性 | 5% | 绝对长度 | 35% | 1.75 |
| 信息密度 | 35% | 1.75 | ||
| 渐进披露 | 30% | 1.5 | ||
| 7 可移植性 | 10% | 值外部化 | 50% | 5.0 |
| 跨平台兼容 | 50% | 5.0 | ||
| 8 可维护性 | 10% | 模块化结构 | 40% | 4.0 |
| 注释与文档 | 35% | 3.5 | ||
| 版本与变更追踪 | 25% | 2.5 | ||
| 合计 | 100% | 100 |
反馈与贡献¶
- 本评分细则是活文档，随团队实践持续迭代。
- 如果你在使用中发现维度边界不清、子项含义歧义、或某些场景无法归类，请反馈给 SkillForge 组。
- 自动化评估工具（skill-eval）的实现与本文档保持同步。