Development
skill-trace-evaluation
对任意 Agent Skill 做 TRACE 五维度评测（T/R/A/C/E），输出 Markdown/HTML 报告与雷达图；当用户要求“TRACE 评测/打分/生成 TRACE 报告/五维度评估”或需要改进建议时使用。
对任意 Agent Skill 做 TRACE 五维度评测（T/R/A/C/E），输出 Markdown/HTML 报告与雷达图；当用户要求“TRACE 评测/打分/生成 TRACE 报告/五维度评估”或需要改进建议时使用。
评估模型：脚本计算确定性基分 + AI 阅读内容后语义校准（±0.3）→ 最终分。 详细评分标准见 references/scoring-criteria.md，校准规则见 references/calibration-guide.md。
干什么？ 对任意 Agent Skill 做 TRACE 五维度质量评分，输出带子项分的评估报告。
什么时候触发？
触发示例：
✅ "用 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 评测：
skill-awesome（规范知识）或 skill-trace-checker（发布前自检）Step 1 ──── Step 2 ──── Step 3 ──── Step 4
收集基分 阅读技能 逐项校准 产出报告
────────────────────────────────────────────
trace_ev- AI 直接 基分 ±0.3 Markdown
aluate.py 阅读正文 附调整理由 + 可选 HTML
python3 scripts/trace_evaluate.py --skill-dir <path> --format json
输出含 base_scores：每子项 base（1.0-5.0）、formula（计算公式）、evidence（证据字段）。
必须自己阅读 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 个可复制开场白
查 base → 读 references/scoring-criteria.md 中该子项的满分标准 + 扣分原因 → 判断正文内容匹配哪一档 → 按 references/calibration-guide.md 调整（±0.3）→ 附一句调整理由。
评分完成后必须输出报告，不允许只口头报告分数而不写入文件。
报告使用统一模板，模板文件中有 {...} 占位符，替换为实际评估结果后写入目标文件。
| 格式 | 模板文件 | 说明 |
|------|----------|------|
| Markdown | examples/trace-report.generated.md | 纯文本，控制台可读，适合存档和 diff |
| HTML | examples/trace-report.generated.html | 可视化雷达图 + Tailwind 卡片，适合浏览器展示和分享 |
评分完成后，必须用 AskUserQuestion 工具询问用户选择输出格式：
问题：评估完成，请选择报告输出格式
选项：
- "Markdown 报告" — 使用 examples/trace-report.generated.md 模板，输出纯文本报告
- "HTML 报告" — 使用 examples/trace-report.generated.html 模板，输出含 SVG 雷达图的交互式报告
- "两者都要" — 同时输出 Markdown + HTML
用户选择后：
trace-report.generated.md 模板填入数据 → 写入 {skill-dir}/trace-report.mdtrace-report.generated.html 模板填入数据 → 写入 {skill-dir}/evaluation-report.html写入完成后，必须向用户报告文件路径。
TRACE 评测不只是打一个分数，最终目标是帮助 Skill 达到更高质量。评测报告产出后：
评分在 4.8 及以上时可视为达到实用标准，不必无限追求字面上的 5.0。
评分细则全文在 references/scoring-criteria.md，校准规则全文在 references/calibration-guide.md。以下为 20 子项的基分公式 + 满分标准摘要。
| ID | 名称 | 基分公式 | 满分标准摘要 |
|----|------|---------|------------|
| T1 | 安全性扫描 | 4.5 + no_scripts(+0.3) + secdecl(+0.2) - secrets(-1.0) | 无密钥+无scripts+有安全声明 |
| T2 | 国内适配性 | has_chinese ? 5.0 : 2.0 | 全中文，示例基于国内平台 |
| T3 | 边界透明度 | boundary ? 4.5+0.3(when_to_use) : 3.0 | 三分类（✅/⚠/❌），每类≥3例 |
| T4 | 数据隐私规范 | 4.5 + secdecl(+0.5) - scripts(-0.2) | 声明"不收集/不处理数据" |
T 维扣分常见原因： 示例全是英文场景；没有隐私使用说明；边界描述模糊（只说"有些场景不支持"）。
| ID | 名称 | 基分公式 | 满分标准摘要 |
|----|------|---------|------------|
| R1 | 异常处理 | gotchas ? 4.0+0.5(val) : 3.0 | Gotchas + 交互式引导模板 |
| R2 | 功能完善性 | WF ? 4.5+0.3(steps≥5或exs≥10) : 3.5~4.0 | Workflow+场景覆盖无死角 |
| R3 | 运行稳定性 | 4.0 + gotchas/rules(+0.3) + val(+0.2) | 约束规则+校验清单 |
| R4 | 降级兜底 | boundary ? 4.5 : 3.5 | 超出范围给替代工具引导 |
R 维扣分常见原因： 用户输入不完整时 AI 直接停下问，没有先给假设版本；超范围请求直接拒绝，没有替代方案引导。
| ID | 名称 | 基分公式 | 满分标准摘要 |
|----|------|---------|------------|
| A1 | 能力边界定义 | boundary+when_to_use ? 4.5 : 4.0 | 场景化判断逻辑 |
| A2 | 触发方式 | desc≥100 ? 5.0 : 3.5~4.5 | 场景化路由，非关键词堆砌 |
| A3 | 受众广度 | 4.0 + chinese(+0.3) | 显式说明适用用户类型 |
| A4 | 定制化支持 | type=cli或exs≥10 ? 4.5 : 4.0 | 风格卡片/场景参数/配置机制 |
A 维扣分常见原因： 触发方式只有关键词列表，没有"什么情况用哪个功能"的判断逻辑；没有说明不同类型用户如何使用。
| ID | 名称 | 基分公式 | 满分标准摘要 |
|----|------|---------|------------|
| C1 | 文档质量 | exs≥阈值(cli=4/prompt=10) ? 5.0 : 3.5~4.5 | 示例可直接复制、格式规范 |
| C2 | 渐进式披露 | refs≥8+body<200 ? 5.0 : 3.0~4.5+th(+0.2) | 三层结构30秒上手 |
| C3 | 结构清晰 | 4.5 + name(+0.2) + refsd≥2(+0.3) | refs子目录≥2 |
| C4 | 反模式与FAQ | gotchas ? 4.5+0.3(gc≥5) : 3.5 | Gotchas≥5 + FAQ≥6非充数 |
C 维扣分常见原因： 没有 references/ 深度文档；FAQ 只有 3~4 题覆盖面不够；无反模式案例，用户不知道什么做法会导致差输出。
| ID | 名称 | 基分公式 | 满分标准摘要 |
|----|------|---------|------------|
| E1 | 输出准确性 | WF ? 4.5+0.3(val) : 4.0 | 场景区分明确、禁止胡编规则 |
| E2 | 内容完整度 | exs≥阈值(prompt=25/cli=4/doc=5) ? 5.0 : 3.0~4.5 | 场景全覆盖、E2E示例 |
| E3 | 创造力与增值 | refsd≥2 ? 4.5+0.2(refs≥10) : 4.0 | 评估框架/决策树/领域知识体系 |
| E4 | 开箱即用度 | 4.0 + WF(+0.3) + val(+0.3) + gotchas(+0.2) + cli(+0.2) | 快速开始章节+可复制开场白 |
E 维扣分常见原因： 没有新手入门引导，用户不知道从哪里开始；输出示例不够真实（用通用模板而非真实场景）；缺乏增值特性，只是机械执行指令。
在触发时可传入以下参数定制评测行为：
| 模式 | 触发关键词 | 行为 |
|------|-----------|------|
| 标准模式 | "TRACE 评测"（默认） | 全量 20 子项评测，输出完整报告 |
| 严格模式 | "严格评测" | 所有子项必须达到 5.0，中间分视为不合格 |
| 快速模式 | "快速检查" / "只看扣分项" | 仅输出 < 4.5 的扣分项，跳过满分说明 |
| 专项模式 | "只检查 [维度]" | 聚焦单个维度，其他维度跳过 |
| 对比模式 | "对比修改前后" | 提供两版路径 → 输出差异对比表 |
| HTML 报告 | "生成雷达图" / "可视化" | 除 Markdown 外，额外生成含 radar 图的 HTML |
| # | 规则 | 说明 |
|---|------|------|
| 1 | 仅在有语义信号时调整 | 正文有满分模式→上调，有扣分模式→下调。都不匹配→不调 |
| 2 | 调幅 ±0.3 | 单子项 max ±0.3。4.5 不能跳到 5.0（只能到 4.8） |
| 3 | 附调整理由 | 一句中文，引用具体内容 |
| 4 | 去重降档 | ref_names 有 ≥3 同版本前缀 → C2/E2 降一档（max 4.5） |
| 5 | 完美阈值缓冲 | 同维 4 子项全可到 5.0 → 查隐性瑕疵 → 有则 max 4.8 |
| 6 | 类型感知 | CLI型 C2=150行 E2=4exs。脚本已内置 |
五维均分 = Overall。
| Rating | Score | |--------|-------| | Excellent (优秀) | ≥ 4.5 | | Good (良好) | 3.5 – 4.4 | | Needs improvement (需改进) | < 3.5 |
# TRACE Evaluation Report
Target: `<path>`
## Overall Assessment
**Overall Score: X.X / 5**
**Overall Rating: Excellent (优秀) / Good (良好) / Needs improvement (需改进)**
One-sentence conclusion: ...（自然中文，具体不空洞）
## TRACE Dimension Explanation
SkillHub TRACE 评测体系从**可信任度、可靠性、适用性、规范性、有效性**五个维度全面评估。
[了解详情](https://skillhub.cn/tutorials#trace-evaluation)
评测基于 AI 自动化检测，结果供参考。
## Evaluation Details
### T · Trust — X.X / 5
（1-2 句中文）
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 安全性扫描 | X.X | 一句话证据 |
| 国内适配性 | X.X | ... |
| 边界透明度 | X.X | ... |
| 数据隐私规范 | X.X | ... |
### R · Reliability — X.X / 5
（中文评语）
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 异常处理 | X.X | ... |
| 功能完善性 | X.X | ... |
| 运行稳定性 | X.X | ... |
| 降级兜底 | X.X | ... |
### A · Adaptability — X.X / 5
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 能力边界定义 | X.X | ... |
| 触发方式 | X.X | ... |
| 受众广度 | X.X | ... |
| 定制化支持 | X.X | ... |
### C · Convention — X.X / 5
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 文档质量 | X.X | ... |
| 渐进式披露 | X.X | ... |
| 结构清晰 | X.X | ... |
| 反模式与FAQ | X.X | ... |
### E · Effectiveness — X.X / 5
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 输出准确性 | X.X | ... |
| 内容完整度 | X.X | ... |
| 创造力与增值 | X.X | ... |
| 开箱即用度 | X.X | ... |
## Improvement Suggestions (prioritized)
1. ...（具体、可行动）
2. ...
3. ...
各维度建议措辞：
| 维度 | 正面措辞示例 | 负面措辞示例 | |------|------------|------------| | T | 未发现敏感信息硬编码；安全声明完整 | 发现疑似凭据模式需移除；缺少数据边界说明 | | R | 异常输入有自检与提示；失败路径处理清晰 | 对异常输入缺少自检提示；缺少降级兜底策略 | | A | 明确了不适用边界因此不易误用；有 near-miss 防范 | 描述过泛导致误触发；与相邻技能能力边界冲突 | | C | 结构遵循快速上手→流程→示例且细节下沉 references/ | 内容堆在 SKILL.md 缺索引/目录；示例不可复制 | | E | 示例覆盖主流场景拿来就能用；能显著减少返工 | 高级场景指导不足；只能完成浅层输出 |
| 用户类型 | 使用方式 | |---------|---------| | Skill 评测者 | 对社区或平台上的 Skill 做第三方质量评估，输出标准化报告 | | 平台审核员 | 使用本标准作为统一评审框架，确保审核口径一致 | | Skill 作者自查 | 发布前自检，定位短板并针对性修改 | | 社区用户 | 选 Skill 前快速了解质量，或对比多个同类型 Skill |
Q1：脚本基分和 AI 校准分不一致，以哪个为准？ 最终报告中的分数 = 基分 ± AI 语义校准。校准只允许 ±0.3，所以两者不会差太远。如果差幅超过 0.3，说明该子项的满分标准描述模糊，建议对照 scoring-criteria.md 中该子项的"4.5 vs 5.0 比对"案例找到客观标准。
Q2：我只改了 Skill 的几行文字，需要重新做 TRACE 吗？ 修改了功能说明、FAQ、边界条件、触发词等影响使用体验的内容 → 需要重新评测。只修正了错别字或格式 → 不需要。
Q3：TRACE 评测结果是 AI 自动打的还是人工打的？ 脚本计算确定性基分（结构检测），AI 阅读正文后做语义校准（±0.3），最终由 AI 综合输出。具有一致性但不保证与 SkillHub 官方评测结果完全一致——官方还涉及用户行为数据维度。
Q4：某个子项反复评测还是不给满分，怎么办？ 对照 references/scoring-criteria.md 中该子项的"满分标准"和"4.5 vs 5.0 对比"案例。对比案例展示了刚好 5.0 的具体格式要求，找到差距后针对性修改文件。
Q5：references/ 下的文件不存在，该子项怎么评分？ 不存在 = 该标准未满足 = 脚本基分最多给 4.0。必须创建对应文件并填充实质内容，AI 校准后才可能达到 5.0。
Q6：我可以只检查某一个维度吗？ 可以。触发时明确说明"只检查 E·有效性"或"只看 C 维度"，评测会聚焦该维度打分并给出改进建议。深度 FAQ（第 7-15 题）见 references/trace-faq-deep.md。
| 行为 | 原因 |
|------|------|
| 无论据就调基分（纯为凑数） | 校准必须有语义信号支撑 |
| 无 evidence 就说"表现良好" | 每分必须有可引用证据 |
| CLI 和 Prompt 型用同一标准 | 必须应用类型感知 |
| FAQ 充数判满分 | 读内容判断实质价值 |
| 忽视去重信号 | ref_names 前缀 ≥3 必须降档 |
以下内容来自腾讯科技、SkillHub 与腾讯玄武实验室于 2026 年 5 月 21 日联合发布的 TRACE 严选框架官方公告。
距离 Anthropic 推出 Agent Skills 不过半年，国内 Skill 社区 SkillHub 上的 Skill 数量已进入 7 万量级。5 月 21 日，腾讯科技、SkillHub 与腾讯玄武实验室联合发布 TRACE —— 国内首个面向 Skill 真实使用场景的严选评测体系。
T（Trust，安全可信） — 红线维度。R（Reliability，运行可靠） — 稳定性、可复现性和交付可靠性。A（Adaptability，场景适用） — Agent 能否自然识别并加载目标 Skill。C（Convention，结构规范） — 不是判断写得是否漂亮，而是具备被理解运行评测复用和维护的基础。E（Effectiveness，效果增益） — 结果必须明显优于 no-skill 参照组，且改善值得付出代价。
TRACE 是质量观测坐标系，采用"热度信号 + 时间切片 + 系统评测 + 编辑精选"的严选机制，不追求全量评分排名。
English: trace-evaluation, trace-scoring, trace-report, skill-quality, five-dimension-evaluation
中文： TRACE 评测, TRACE 评分, TRACE 报告, 五维度评估, T/R/A/C/E 评估, 技能质量评测, Trace 严选, 严格评测, 快速检查