skill-trace-evaluation

Skill TRACE 质量评测

评估模型：脚本计算确定性基分 + AI 阅读内容后语义校准（±0.3）→ 最终分。 详细评分标准见 references/scoring-criteria.md，校准规则见 references/calibration-guide.md。

---

⚡ 新手 30 秒入门

干什么？ 对任意 Agent Skill 做 TRACE 五维度质量评分，输出带子项分的评估报告。

什么时候触发？

• 刚写完一个新 Skill，想知道质量怎么样 → 直接用
• 用户要求 "检查 Skill 质量"、"TRACE 评测"、"技能打分"
• 提供了 Skill 目录路径 + "评估"/"评测"/"打分" 关键词

触发示例：

✅ "用 TRACE 评测 /path/to/skill"
✅ "TRACE 评测 ddd-architecture-awesome"
✅ "对 skill-trace-evaluation 做五维度评估"
✅ "生成 TRACE 报告 + HTML 雷达图"
✅ "严格评测 jimeng-prompt-text2image"       （全部子项需 5.0）
✅ "快速检查这个 Skill 有哪些扣分项"          （仅输出扣分项）
✅ "只检查 T 维度"                            （单维度聚焦）
✅ "我修改了 FAQ，重新评测一下规范性"
✅ "输出 TRACE 五维画像 + 基线对比"
✅ "技能评估报告 + 官方合规检查"

一句话流程： 运行脚本拿基分 → 阅读 SKILL.md → 对照评分细则校准 → 产出报告。

---

执行时机

以下场景适合触发 TRACE 评测：

1. 新 Skill 完成编写：刚写完 SKILL.md，想知道质量基线
2. Skill 重大修改后：修改了功能说明、FAQ、边界条件、触发词等核心内容
3. 用户明确要求："检查 Skill 质量"、"TRACE 评测"、"技能打分"
4. 第三方评审：平台审核员或社区用户对 Skill 做质量评估

---

能力边界说明

✅ 擅长处理

1. 评估任意 Agent Skill，输出 20 子项评分
2. 定位具体扣分原因，每个分数附证据
3. 生成标准化报告（dimension-level 中文评语 + 子项分表 + 改进建议）
4. 验证修改是否有效：修改后重新评测，对比前后分数变化
5. 对比两个版本差异：判断新版本比旧版本在哪些子项有实质提升
6. 支持标准/严格/快速/单维度四种模式

⚠️ 需要素材

1. 完整评估需要 Skill 目录路径（含 SKILL.md），只凭名称无法评测
2. R1/E1/E3 评分需要 AI 自己阅读正文判断语义质量——脚本只提供结构基分

❌ 超出范围（附替代方案）

1. 帮你写 Skill 内容 → 用 skill-awesome（规范知识）或 skill-trace-checker（发布前自检）
2. 评测非 Skill 类文档 → 找对应工具
3. 自动发布 Skill → 手动完成

---

评估流程

Step 1 ──── Step 2 ──── Step 3 ──── Step 4
收集基分    阅读技能    逐项校准    产出报告
────────────────────────────────────────────
trace_ev-   AI 直接    基分 ±0.3    Markdown
aluate.py   阅读正文    附调整理由    + 可选 HTML

Step 1：收集基分

python3 scripts/trace_evaluate.py --skill-dir <path> --format json

输出含 base_scores：每子项 base（1.0-5.0）、formula（计算公式）、evidence（证据字段）。

Step 2：阅读技能

必须自己阅读 SKILL.md 正文 + 扫描 references/、examples/ 目录。脚本提供结构数据，AI 判断内容质量。

AI 阅读时的检查思路示例：

【T 维】
  安全 → 查有无密钥/secrets/脚本，正文有无安全声明
  国内 → 查全文中文化程度、示例是否基于国内平台
  边界 → 查有无独立边界章节、三分类是否每类≥3例
  隐私 → 查有无数据隐私说明（FAQ 或专项章节）

【R 维】
  异常 → 查 Gotchas 是否包含"交互式引导模板"（先假设版本→列缺失项）
  功能 → 查 workflow 步骤是否覆盖所有声明功能
  稳定 → 查有无 validate-plan-execute 循环或等效约束
  降级 → 查边界章节中超范围后是否给替代方案

【A 维】
  边界定义 → 查三分类是否有场景化判断逻辑（"什么时候该用/不该用/模糊怎么判"）
  触发 → 查 description 信息量，是关键词堆砌还是场景化路由
  受众 → 查有无显式说明适用用户类型
  定制 → 查有无风格/参数传递机制

【C 维】
  文档 → 查 examples 数量是否达标（prompt≥10/cli≥4/doc≥5）
  披露 → 查 body 行数 + references 文件数，是否三层结构
  结构 → 查 name 规范 + refs 子目录≥2
  反模式/FAQ → 查 Gotchas 数量是否≥5 + FAQ 是否≥6且非充数

【E 维】
  准确 → 查有无"禁止胡编"规则或等效约束
  完整 → 查 examples 数量是否达阈值（prompt≥25/cli≥4/doc≥5）
  增值 → 查 refs 子目录≥2 + 是否有评估框架/决策树等深度领域知识
  开箱 → 查有无快速开始章节 + ≥3 个可复制开场白