如何构建 AgentSkill 质量评估体系？Skill Arena Leaderboard 五维评分实践

一、为什么需要 Skill 质量评估？

随着 Agent 生态的快速发展，AgentSkill（智能体技能）的数量正在爆发式增长。一个技能写得好不好，直接决定了 Agent 能不能被正确触发、能不能稳定执行、能不能被其他开发者复用。

但现实是：很多 Skill 的 SKILL.md 写得含糊不清，触发词缺失，没有边界声明，更没有可验收的测试。开发者提交了一个 Skill，却没人能快速判断"这个技能靠不靠谱"。

这就是我构建 Skill Arena Leaderboard 的初衷——用一套可量化、可复现的评分体系，给每个 AgentSkill 打一个"质量分"，生成排行榜，让好技能浮出水面，让有问题的技能暴露短板。

二、五维评分框架

我没有用一个笼统的"好/中/差"来评判，而是拆成五个维度，每个维度 20 分，满分 100 分。这样既能给出总分排名，又能定位到具体哪个维度是短板。

维度一：文档质量（20 分）

这是最基础的维度。一个好的 Skill 首先得让人看懂它是干什么的。检查项包括：description 是否足够详细（超过 50 字符得 4 分，超过 150 字符再得 2 分）、是否包含触发关键词、body 内容是否充实、是否有代码示例、是否有清晰的标题结构。

为什么要卡 description 长度？因为 description 是 Agent 做技能匹配时最先读到的字段。如果一句话都写不清楚，Agent 的路由机制就很难准确命中这个技能。

维度二：触发精度（20 分）

触发精度决定了"用户说了一句话，Agent 会不会选对这个技能"。检查项包括：是否有显式的 Trigger 声明（5 分）、是否中英文双语覆盖（5 分）、是否包含 3 个以上动作动词如 create/query/delete/deploy（5 分）、是否有场景示例（3 分）、是否有 2 个以上 tags（2 分）。

这里有个实践心得：很多 Skill 只写了英文触发词，但中文用户说"帮我查一下 ECS"，如果 description 里没有"查询""弹性云服务器"这样的中文词，就匹配不上。所以中英文双语覆盖我给了 5 分的高权重。

维度三：结构规范（20 分）

一个规范的 Skill 目录应该有 scripts/（可执行脚本）、references/（参考文档）、assets/（静态资源）三个子目录。同时不应该有 README.md、CHANGELOG.md 等冗余文件——因为 SKILL.md 就是 Skill 的唯一入口文件。

检查项：scripts/ 目录存在且非空（7 分）、references/ 目录存在（3 分）、assets/ 目录存在（2 分）、无冗余文件（4 分）、SKILL.md 大小合理（2 分）、frontmatter 有效（2 分）。

维度四：健壮性（20 分）

健壮性是区分"玩具级 Skill"和"生产级 Skill"的关键。检查项包括：是否有拒绝/边界声明（5 分，如"refuse""拒绝""不支持""read-only"）、是否提及错误处理（4 分）、是否有确认警告（4 分，如"confirm""确认""destructive"）、是否声明了边界和限制（3 分）、是否有前置条件检查（2 分）、是否有安全考虑（2 分）。

举个例子：一个删除资源的 Skill，如果没有任何"确认"或"不可逆"的声明，那它就是危险的。这 4 分的确认警告检查项，就是在倒逼开发者把风险写明。

维度五：可验收性（20 分）

可验收性回答的是"我怎么知道这个 Skill 真能用"。检查项包括：是否有测试文件（6 分）、内容中是否提及测试（3 分）、是否有示例输入输出（4 分）、是否有可执行脚本（4 分）、是否声明了运行环境（3 分）、是否有命令示例（3 分）。

测试文件我给了最高的 6 分，因为这是最硬的验收标准。有测试的 Skill，意味着开发者自己验证过；没测试的，就只是"我觉得它能跑"。

三、评分引擎实现

评分引擎用 Python 实现，核心流程是三步：扫描、评分、输出。

第一步扫描：遍历指定目录下的所有 Skill 子目录，读取每个 SKILL.md 文件，解析 YAML frontmatter（提取 name、description、tags 等元数据）和 body 内容。

第二步评分：对每个 Skill 依次跑五个维度的检查函数。每个检查函数返回一个得分和诊断信息。比如检查"description 长度是否超过 50 字符"，如果通过就返回 4 分，不通过就返回 0 分并附上诊断"description 过短，建议补充详细说明"。

第三步输出：支持三种格式——HTML 交互页面、Markdown 表格、JSON API。HTML 页面有排名徽章、评分进度条、Tag 筛选器、可展开详情和改进建议。Markdown 格式方便嵌入 README 或 Issue。JSON API 方便其他系统集成。

四、评分分层与改进诊断

总分出来后，我会做一个分层：

• S 级（85-100 分，绿色）：生产就绪，文档完善，可直接推荐使用。
• A 级（70-84 分，黄色）：质量不错，有小缺口，稍加完善即可。
• B 级（50-69 分，橙色）：功能可用但需要改进，建议补充短板维度。
• C 级（0-49 分，红色）：存在显著问题，需要返工。

更重要的是改进诊断：对于得分低于 60% 的维度，引擎会自动生成针对性的改进建议。比如"触发精度"得分偏低，建议是"补充中文触发关键词，添加 3 个以上动作动词，增加场景示例"。这让开发者不仅知道分数，还知道怎么改。

五、实际使用与效果

启动 Web 服务器后，就能看到交互式排行榜。页面顶部是总分排名，每个技能卡片显示名称、总分、五个维度的迷你评分条和 S/A/B/C 徽章。点击卡片可以展开详情，看到每个维度的得分明细和诊断建议。顶部有 Tag 筛选器，可以按标签过滤技能类别。

命令行模式下，直接运行评分引擎，传入 Skill 目录路径，就能输出 Markdown 格式的排行榜表格，方便嵌入文档或 Issue。

六、实践心得

心得一：评分标准要公开透明。 我把所有评分规则写在 references/scoring-rules.md 里，每一分怎么拿、为什么扣，都列得清清楚楚。这样开发者不是面对一个"黑盒打分器"，而是能对照规则逐项自查。

心得二：维度权重要反映实际痛点。 我给"触发精度"里的中英文双语覆盖 5 分，是因为我实际遇到过中文用户触发不了只写英文触发词的 Skill。权重不是拍脑袋定的，是从踩坑经验里来的。

心得三：诊断比评分更有价值。 开发者看到"72 分"可能不知道该改什么，但看到"触发精度 12/20：缺少中文触发词、动作动词不足 3 个"，就知道具体该补什么。评分是诊断的入口，诊断才是改进的抓手。

七、后续计划

当前版本是静态评分，下一步计划加入：动态测试执行（实际运行 Skill 的测试脚本验证通过率）、历史趋势追踪（同一 Skill 多次评分的变化曲线）、社区投票加权（让使用者也能参与质量评价）。如果你也在开发 AgentSkill，欢迎用这个工具跑一下自己的技能，看看能打多少分。