Skill Trace Evaluation
- 8 installs
- 2 repo stars
- Updated July 29, 2026
- full-statck-skills/utility-skills
Score any Agent Skill on the TRACE five dimensions and output a Markdown/HTML report with a radar chart and improvement suggestions.
About
Produces a TRACE five-dimension quality score for a skill by combining script-computed base scores with AI semantic calibration. A developer uses it to grade a skill and get a report with improvement advice.
- Combines deterministic base scoring with AI calibration
- Outputs Markdown/HTML report and radar chart
Skill Trace Evaluation by the numbers
- 8 all-time installs (skills.sh)
- Ranked #545 of 782 Skill Development skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/full-statck-skills/utility-skills --skill skill-trace-evaluationAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 8 |
|---|---|
| repo stars | ★ 2 |
| Last updated | July 29, 2026 |
| Repository | full-statck-skills/utility-skills ↗ |
What it does
Score any Agent Skill on the TRACE five dimensions and output a Markdown/HTML report with a radar chart and improvement suggestions.
Files
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 阅读正文 附调整理由 + 可选 HTMLStep 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 个可复制开场白Step 3：逐项校准
查 base → 读 references/scoring-criteria.md 中该子项的满分标准 + 扣分原因 → 判断正文内容匹配哪一档 → 按 references/calibration-guide.md 调整（±0.3）→ 附一句调整理由。
Step 4：产出报告 ⚠️ 必须执行
评分完成后必须输出报告，不允许只口头报告分数而不写入文件。
报告使用统一模板，模板文件中有 {...} 占位符，替换为实际评估结果后写入目标文件。
报告模板
| 格式 | 模板文件 | 说明 |
|---|---|---|
| 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用户选择后：
- 选 "Markdown" → 基于
trace-report.generated.md模板填入数据 → 写入{skill-dir}/trace-report.md - 选 "HTML" → 基于
trace-report.generated.html模板填入数据 → 写入{skill-dir}/evaluation-report.html - 选 "两者都要" → 同时生成上述两个文件
写入完成后，必须向用户报告文件路径。
Markdown 报告结构
1. 综合评分表（5 维 + 综合） 2. 一句结语 3. 五维详析（每维 4 子项：得分 + 证据 + 建议） 4. no-skill 基线对比表 5. 官方规范合规表（10 项 agentskills.io 检查） 6. 优化建议（优先级排序 P1/P2/P3） 7. Skill 基础画像
HTML 报告包含
- SVG 雷达图（T/R/A/C/E 五轴）
- 五维评分卡片 + 进度条
- 20 子项详表（每子项：得分 + 证据 + 建议）
- 基线对比 + 官方合规 + 优化建议 + Skill 画像
- 支持 Print 和移动端响应式
评测后的改进指引
TRACE 评测不只是打一个分数，最终目标是帮助 Skill 达到更高质量。评测报告产出后：
1. 定位扣分项：查看报告中 < 5.0 的子项，对照 scoring-criteria.md 中该子项的"满分标准"和"修改对比"示例 2. 修改对应文件：每个扣分点都必须对应 SKILL.md 或 references/ 文件的实质改动（禁止只改报告措辞不修改文件） 3. 重新评测验证：修改后再次运行评测，确认分数有实质提升 4. 参考案例：不知道怎么改时，查看 trace-anti-patterns.md 中同类问题的正确修复方式
评分在 4.8 及以上时可视为达到实用标准，不必无限追求字面上的 5.0。
---
评分标准速查
评分细则全文在 references/scoring-criteria.md，校准规则全文在 references/calibration-guide.md。以下为 20 子项的基分公式 + 满分标准摘要。
T · Trust（可信任度）
| 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 维扣分常见原因： 示例全是英文场景；没有隐私使用说明；边界描述模糊（只说"有些场景不支持"）。
R · Reliability（可靠性）
| 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 直接停下问，没有先给假设版本；超范围请求直接拒绝，没有替代方案引导。
A · Adaptability（适用性）
| 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 维扣分常见原因： 触发方式只有关键词列表，没有"什么情况用哪个功能"的判断逻辑；没有说明不同类型用户如何使用。
C · Convention（规范性）
| 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 题覆盖面不够；无反模式案例，用户不知道什么做法会导致差输出。
E · Effectiveness（有效性）
| 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. ...评语规范
- dimension-level：1-2 句自然中文，抓住核心。✅ "纯文档型零风险，全中文专为即梦打造。边界清晰但未声明数据隐私" ❌ "整体表现良好"
- sub-item：一句话引用证据。✅ "Gotchas 13 条+checklist，但缺交互式引导模板" ❌ "安全方面没问题"
各维度建议措辞：
| 维度 | 正面措辞示例 | 负面措辞示例 |
|---|---|---|
| T | 未发现敏感信息硬编码；安全声明完整 | 发现疑似凭据模式需移除；缺少数据边界说明 |
| R | 异常输入有自检与提示；失败路径处理清晰 | 对异常输入缺少自检提示；缺少降级兜底策略 |
| A | 明确了不适用边界因此不易误用；有 near-miss 防范 | 描述过泛导致误触发；与相邻技能能力边界冲突 |
| C | 结构遵循快速上手→流程→示例且细节下沉 references/ | 内容堆在 SKILL.md 缺索引/目录；示例不可复制 |
| E | 示例覆盖主流场景拿来就能用；能显著减少返工 | 高级场景指导不足；只能完成浅层输出 |
---
受众说明
| 用户类型 | 使用方式 |
|---|---|
| Skill 评测者 | 对社区或平台上的 Skill 做第三方质量评估，输出标准化报告 |
| 平台审核员 | 使用本标准作为统一评审框架，确保审核口径一致 |
| Skill 作者自查 | 发布前自检，定位短板并针对性修改 |
| 社区用户 | 选 Skill 前快速了解质量，或对比多个同类型 Skill |
---
常见问题 FAQ
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 必须降档 |
---
TRACE 评测体系（原文）
以下内容来自腾讯科技、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 是质量观测坐标系，采用"热度信号 + 时间切片 + 系统评测 + 编辑精选"的严选机制，不追求全量评分排名。
---
References
- SkillHub TRACE Evaluation System
- references/scoring-criteria.md — 20 子项满分标准 + 扣分原因 + 修改对比 + 五维度速查（含原 trace-criteria-detail、trace-rubric 内容）
- references/calibration-guide.md — 校准规则 + 反模式案例 + 调幅指南
- references/trace-anti-patterns.md — Skill 创作者自检反模式案例集（来源：skill-trace-checker/东四联周博远）
- references/trace-skill-checklist.md — 一页纸自检清单（scoring-criteria 浓缩版）（来源：skill-trace-checker/东四联周博远）
- references/trace-sample-reports.md — 真实评分报告案例集（来源：skill-trace-checker/东四联周博远）
- references/trace-faq-deep.md — TRACE 深度 FAQ（来源：skill-trace-checker/东四联周博远）
- examples/trace-report.generated.md — 真实评测输出样例（Markdown）
- examples/trace-report.generated.html — 真实评测输出样例（HTML 雷达图）
---
Keywords
English: trace-evaluation, trace-scoring, trace-report, skill-quality, five-dimension-evaluation
中文： TRACE 评测, TRACE 评分, TRACE 报告, 五维度评估, T/R/A/C/E 评估, 技能质量评测, Trace 严选, 严格评测, 快速检查
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://cdn.tailwindcss.com"></script>
<title>TRACE 评测报告 — {SKILL_NAME}</title>
<style>
@media print { body { background: white !important; } .no-print { display: none !important; } }
</style>
</head>
<body class="bg-gray-50">
<div class="pb-8 max-w-5xl mx-auto px-4 pt-6">
<!-- ====== Header ====== -->
<div class="mb-6 flex flex-col sm:flex-row items-start sm:items-center justify-between gap-3">
<div>
<h1 class="text-2xl font-bold text-gray-900">{SKILL_NAME}</h1>
<p class="text-sm text-gray-500 mt-0.5">{SKILL_PATH}</p>
</div>
<div class="flex items-center gap-2 text-xs text-gray-400">
<span>评测时间：{TIMESTAMP}</span>
<span class="px-2 py-0.5 rounded bg-green-50 text-green-700 font-medium">Official: Pass</span>
</div>
</div>
<!-- ====== TRACE 维度说明卡 ====== -->
<div class="mb-6 rounded-2xl overflow-hidden border" style="border-color:rgba(63,94,255,0.16)">
<div class="h-1" style="background:linear-gradient(90deg,#3f5eff 0%,#af52de 100%)"></div>
<div class="p-5" style="background:linear-gradient(135deg,rgba(63,94,255,0.04) 0%,rgba(175,82,222,0.04) 100%)">
<div class="flex items-start gap-3">
<div class="w-9 h-9 rounded-xl bg-gradient-to-br from-blue-500 to-purple-600 flex items-center justify-center flex-shrink-0 mt-0.5 shadow-sm">
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="w-[18px] h-[18px] text-white"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg>
</div>
<div>
<h3 class="text-[15px] font-semibold text-gray-900 mb-1.5">TRACE 评测维度说明</h3>
<p class="text-[13px] leading-relaxed text-gray-600">
SkillHub TRACE 评测体系从 <span class="font-medium text-gray-800">可信任度（Trust）</span>、<span class="font-medium text-gray-800">可靠性（Reliability）</span>、<span class="font-medium text-gray-800">适用性（Adaptability）</span>、<span class="font-medium text-gray-800">规范性（Convention）</span>、<span class="font-medium text-gray-800">有效性（Effectiveness）</span> 五个维度全面评估 Skill 的质量。该体系基于 SkillHub 平台的长期运营实践及腾讯新闻团队的内容生产经验沉淀而成，旨在帮助用户快速识别高质量 Skill。
</p>
<p class="text-[12px] text-gray-500 mt-2 flex items-center gap-1">
<span class="inline-block w-1.5 h-1.5 rounded-full bg-amber-400"></span>
特别说明：本报告不是官方报告，而是 TRACE 评测体系的模拟检测，最终测评结果以 SkillHub 为准。
</p>
<p class="text-[12px] text-gray-400 mt-1">
等级阈值：≥4.7 优秀（Excellent） | ≥4.2 良好（Good） | ≥3.5 一般（Fair） | <3.5 待改进（Needs improvement）
</p>
</div>
</div>
</div>
</div>
<!-- ====== Overall Score + Radar ====== -->
<div class="mb-6 p-6 rounded-2xl bg-white border border-gray-100 shadow-sm">
<div class="flex flex-col lg:flex-row items-center gap-8">
<!-- SVG Radar -->
<div class="w-full lg:w-[320px] h-[260px] flex-shrink-0">
<svg width="320" height="260" viewBox="0 0 320 260">
<!-- 五轴骨架线 -->
<line stroke="#e5e7eb" stroke-width="0.5" x1="160" y1="130" x2="160" y2="40"/>
<line stroke="#e5e7eb" stroke-width="0.5" x1="160" y1="130" x2="245.595" y2="102.188"/>
<line stroke="#e5e7eb" stroke-width="0.5" x1="160" y1="130" x2="212.901" y2="202.812"/>
<line stroke="#e5e7eb" stroke-width="0.5" x1="160" y1="130" x2="107.099" y2="202.812"/>
<line stroke="#e5e7eb" stroke-width="0.5" x1="160" y1="130" x2="74.405" y2="102.188"/>
<!-- 5层同心五边形网格 (20%/40%/60%/80%/100%) -->
{RADAR_GRID}
<!-- 轴标签 -->
<text font-size="12" text-anchor="middle" fill="#4B5563" x="160" y="28">T 可信任度</text>
<text font-size="12" text-anchor="start" fill="#4B5563" x="257" y="98">R 可靠性</text>
<text font-size="12" text-anchor="start" fill="#4B5563" x="220" y="213">A 适用性</text>
<text font-size="12" text-anchor="end" fill="#4B5563" x="100" y="213">C 规范性</text>
<text font-size="12" text-anchor="end" fill="#4B5563" x="63" y="98">E 有效性</text>
<!-- 数据多边形 (T=pct_T, R=pct_R, A=pct_A, C=pct_C, E=pct_E) -->
<!-- 各轴坐标公式：T轴=(160, 130-(pct_T*90)), R轴=(160+(pct_R*85.595), 130-(pct_R*27.812)), A轴=(160+(pct_A*52.901), 130+(pct_A*72.812)), C轴=(160-(pct_C*52.901), 130+(pct_C*72.812)), E轴=(160-(pct_E*85.595), 130-(pct_E*27.812)) -->
{RADAR_POLYGON}
{RADAR_POINTS}
</svg>
</div>
<div class="flex-1 min-w-0">
<div class="flex items-baseline gap-3 mb-4">
<span class="text-[48px] font-bold text-gray-900 leading-none">{OVERALL}</span>
<span class="text-[16px] text-gray-400 font-medium">/ 5</span>
</div>
<div class="mb-3">
<span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-[13px] font-semibold {OVERALL_BADGE_CLASS}">{OVERALL_GRADE}</span>
</div>
<p class="text-[14px] leading-relaxed text-gray-600">{OVERALL_SUMMARY}</p>
<p class="text-[13px] text-gray-500 mt-2">{OVERALL_COMPARISON}</p>
<div class="mt-4 grid grid-cols-5 gap-2">
{MINI_SCORE_CARDS}
</div>
</div>
</div>
</div>
<!-- ====== Dimension Detail Cards ====== -->
<div class="space-y-4">
<h3 class="text-[16px] font-semibold text-gray-900">📊 五维度详析（20 子项评分）</h3>
<!-- T · Trust -->
<div class="p-5 rounded-xl border border-gray-100 bg-white">
<div class="flex items-center gap-3 mb-3">
<div class="w-8 h-8 rounded-lg flex items-center justify-center flex-shrink-0" style="background-color:rgba(16,185,129,0.082)">
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="w-4 h-4" style="color:rgb(16,185,129)"><path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z"/><path d="m9 12 2 2 4-4"/></svg>
</div>
<div class="flex-1">
<span class="text-[14px] font-semibold text-gray-900">T · Trust（可信任度）</span>
<span class="text-[12px] text-gray-500 ml-2">安全红线维度</span>
<span class="float-right text-[18px] font-bold" style="color:rgb(16,185,129)">{T_SCORE}</span>
</div>
</div>
<div class="flex items-center gap-3 mb-3">
<div class="flex-1 h-1.5 rounded-full bg-gray-100 overflow-hidden"><div class="h-full rounded-full" style="width:{T_PCT}%;background:linear-gradient(90deg,#10b981,#34d399)"></div></div>
</div>
<p class="text-[13px] text-gray-600 mb-2">{T_SUMMARY}</p>
<div class="overflow-x-auto">
<table class="w-full text-[13px]">
<tr class="bg-gray-50 text-gray-500 text-[12px]"><th class="text-left p-2">子项</th><th class="p-2 w-14">得分</th><th class="text-left p-2">证据</th><th class="text-left p-2">建议</th></tr>
{T_ROWS}
</table>
</div>
</div>
<!-- R · Reliability -->
<div class="p-5 rounded-xl border border-gray-100 bg-white">
<div class="flex items-center gap-3 mb-3">
<div class="w-8 h-8 rounded-lg flex items-center justify-center flex-shrink-0" style="background-color:rgba(59,130,246,0.082)">
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="w-4 h-4" style="color:rgb(59,130,246)"><path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8"/><path d="M21 3v5h-5"/><path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16"/><path d="M8 16H3v5"/></svg>
</div>
<div class="flex-1">
<span class="text-[14px] font-semibold text-gray-900">R · Reliability（可靠性）</span>
<span class="text-[12px] text-gray-500 ml-2">稳定性与交付</span>
<span class="float-right text-[18px] font-bold" style="color:rgb(59,130,246)">{R_SCORE}</span>
</div>
</div>
<div class="flex items-center gap-3 mb-3">
<div class="flex-1 h-1.5 rounded-full bg-gray-100 overflow-hidden"><div class="h-full rounded-full" style="width:{R_PCT}%;background:linear-gradient(90deg,#3b82f6,#60a5fa)"></div></div>
</div>
<p class="text-[13px] text-gray-600 mb-2">{R_SUMMARY}</p>
<div class="overflow-x-auto">
<table class="w-full text-[13px]">
<tr class="bg-gray-50 text-gray-500 text-[12px]"><th class="text-left p-2">子项</th><th class="p-2 w-14">得分</th><th class="text-left p-2">证据</th><th class="text-left p-2">建议</th></tr>
{R_ROWS}
</table>
</div>
</div>
<!-- A · Adaptability -->
<div class="p-5 rounded-xl border border-gray-100 bg-white">
<div class="flex items-center gap-3 mb-3">
<div class="w-8 h-8 rounded-lg flex items-center justify-center flex-shrink-0" style="background-color:rgba(245,158,11,0.082)">
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="w-4 h-4" style="color:rgb(245,158,11)"><path d="m16.24 7.76-1.804 5.411a2 2 0 0 1-1.265 1.265L7.76 16.24l1.804-5.411a2 2 0 0 1 1.265-1.265z"/><circle cx="12" cy="12" r="10"/></svg>
</div>
<div class="flex-1">
<span class="text-[14px] font-semibold text-gray-900">A · Adaptability（适用性）</span>
<span class="text-[12px] text-gray-500 ml-2">场景识别与触发</span>
<span class="float-right text-[18px] font-bold" style="color:rgb(245,158,11)">{A_SCORE}</span>
</div>
</div>
<div class="flex items-center gap-3 mb-3">
<div class="flex-1 h-1.5 rounded-full bg-gray-100 overflow-hidden"><div class="h-full rounded-full" style="width:{A_PCT}%;background:linear-gradient(90deg,#f59e0b,#fbbf24)"></div></div>
</div>
<p class="text-[13px] text-gray-600 mb-2">{A_SUMMARY}</p>
<div class="overflow-x-auto">
<table class="w-full text-[13px]">
<tr class="bg-gray-50 text-gray-500 text-[12px]"><th class="text-left p-2">子项</th><th class="p-2 w-14">得分</th><th class="text-left p-2">证据</th><th class="text-left p-2">建议</th></tr>
{A_ROWS}
</table>
</div>
</div>
<!-- C · Convention -->
<div class="p-5 rounded-xl border border-gray-100 bg-white">
<div class="flex items-center gap-3 mb-3">
<div class="w-8 h-8 rounded-lg flex items-center justify-center flex-shrink-0" style="background-color:rgba(139,92,246,0.082)">
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="w-4 h-4" style="color:rgb(139,92,246)"><path d="M12 7v14"/><path d="M3 18a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h5a4 4 0 0 1 4 4 4 4 0 0 1 4-4h5a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1h-6a3 3 0 0 0-3 3 3 3 0 0 0-3-3z"/></svg>
</div>
<div class="flex-1">
<span class="text-[14px] font-semibold text-gray-900">C · Convention（规范性）</span>
<span class="text-[12px] text-gray-500 ml-2">结构与可维护性</span>
<span class="float-right text-[18px] font-bold" style="color:rgb(139,92,246)">{C_SCORE}</span>
</div>
</div>
<div class="flex items-center gap-3 mb-3">
<div class="flex-1 h-1.5 rounded-full bg-gray-100 overflow-hidden"><div class="h-full rounded-full" style="width:{C_PCT}%;background:linear-gradient(90deg,#8b5cf6,#c4b5fd)"></div></div>
</div>
<p class="text-[13px] text-gray-600 mb-2">{C_SUMMARY}</p>
<div class="overflow-x-auto">
<table class="w-full text-[13px]">
<tr class="bg-gray-50 text-gray-500 text-[12px]"><th class="text-left p-2">子项</th><th class="p-2 w-14">得分</th><th class="text-left p-2">证据</th><th class="text-left p-2">建议</th></tr>
{C_ROWS}
</table>
</div>
</div>
<!-- E · Effectiveness -->
<div class="p-5 rounded-xl border border-gray-100 bg-white">
<div class="flex items-center gap-3 mb-3">
<div class="w-8 h-8 rounded-lg flex items-center justify-center flex-shrink-0" style="background-color:rgba(239,68,68,0.082)">
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="w-4 h-4" style="color:rgb(239,68,68)"><path d="M4 14a1 1 0 0 1-.78-1.63l9.9-10.2a.5.5 0 0 1 .86.46l-1.92 6.02A1 1 0 0 0 13 10h7a1 1 0 0 1 .78 1.63l-9.9 10.2a.5.5 0 0 1-.86-.46l1.92-6.02A1 1 0 0 0 11 14z"/></svg>
</div>
<div class="flex-1">
<span class="text-[14px] font-semibold text-gray-900">E · Effectiveness（有效性）</span>
<span class="text-[12px] text-gray-500 ml-2">任务增益与代价</span>
<span class="float-right text-[18px] font-bold" style="color:rgb(239,68,68)">{E_SCORE}</span>
</div>
</div>
<div class="flex items-center gap-3 mb-3">
<div class="flex-1 h-1.5 rounded-full bg-gray-100 overflow-hidden"><div class="h-full rounded-full" style="width:{E_PCT}%;background:linear-gradient(90deg,#ef4444,#f87171)"></div></div>
</div>
<p class="text-[13px] text-gray-600 mb-2">{E_SUMMARY}</p>
<div class="overflow-x-auto">
<table class="w-full text-[13px]">
<tr class="bg-gray-50 text-gray-500 text-[12px]"><th class="text-left p-2">子项</th><th class="p-2 w-14">得分</th><th class="text-left p-2">证据</th><th class="text-left p-2">建议</th></tr>
{E_ROWS}
</table>
</div>
</div>
</div>
<!-- ====== Baseline Comparison ====== -->
<div class="mt-4 p-5 rounded-xl border border-gray-100 bg-white">
<h3 class="text-[15px] font-semibold text-gray-900 mb-3">📊 no-skill 基线对比</h3>
<div class="overflow-x-auto">
<table class="w-full text-[13px]">
<tr class="bg-gray-50 text-gray-500 text-[12px]"><th class="text-left p-2">对比维度</th><th class="p-2">no-skill（裸模型）</th><th class="p-2">启用此 skill</th><th class="p-2 w-16">增益</th></tr>
{BASELINE_ROWS}
</table>
</div>
</div>
<!-- ====== Official Compliance ====== -->
<div class="mt-4 p-5 rounded-xl border border-gray-100 bg-white">
<h3 class="text-[15px] font-semibold text-gray-900 mb-3">📋 官方规范合规（agentskills.io）</h3>
<div class="rounded-lg p-3 mb-3" style="background:rgba(16,185,129,0.06);border-left:3px solid rgb(16,185,129)">
<span class="text-[14px] font-semibold" style="color:rgb(16,185,129)">✅ {OFFICIAL_OVERALL}</span>
<span class="text-[12px] text-gray-500 ml-2">基于 agentskills.io 官方规范</span>
</div>
<div class="overflow-x-auto">
<table class="w-full text-[13px]">
<tr class="bg-gray-50 text-gray-500 text-[12px]"><th class="text-left p-2 w-8">#</th><th class="text-left p-2">检查项</th><th class="p-2 w-16">结果</th><th class="text-left p-2">证据</th></tr>
{OFFICIAL_ROWS}
</table>
</div>
</div>
<!-- ====== Suggestions ====== -->
<div class="mt-4 p-5 rounded-xl border border-gray-100 bg-white">
<h3 class="text-[15px] font-semibold text-gray-900 mb-3">💡 优化建议（优先级排序）</h3>
<div class="space-y-2">
{SUGGESTION_ITEMS}
</div>
</div>
<!-- ====== Skill Profile ====== -->
<div class="mt-4 p-5 rounded-xl border border-gray-100 bg-white">
<h3 class="text-[15px] font-semibold text-gray-900 mb-3">📦 Skill 基础画像</h3>
<div class="grid grid-cols-2 sm:grid-cols-4 gap-3 text-[13px]">
{PROFILE_ITEMS}
</div>
</div>
<!-- ====== Footer ====== -->
<div class="mt-6 text-center text-[12px] text-gray-400 pb-4">
<p>评估依据：<strong>SkillHub TRACE 评测体系</strong></p>
<p>合规检查：<strong>agentskills.io</strong> 官方规范 · Generated {TIMESTAMP}</p>
</div>
</div>
</body>
</html>TRACE 评测报告
评估目标：{SKILL_PATH} | 评估时间：{TIMESTAMP}评估依据：SkillHub TRACE 评测体系
>
特别说明：本报告不是官方报告，而是 TRACE 评测体系的模拟检测，最终测评结果以 SkillHub 为准。
---
📊 综合评分
| 维度 | 得分 | 等级 |
|---|---|---|
| T · Trust（可信任度） | {T_SCORE} | {T_GRADE} |
| R · Reliability（可靠性） | {R_SCORE} | {R_GRADE} |
| A · Adaptability（适用性） | {A_SCORE} | {A_GRADE} |
| C · Convention（规范性） | {C_SCORE} | {C_GRADE} |
| E · Effectiveness（有效性） | {E_SCORE} | {E_GRADE} |
| 综合 | {OVERALL} | {OVERALL_GRADE} |
等级阈值：≥4.7 优秀（Excellent） | ≥4.2 良好（Good） | ≥3.5 一般（Fair） | <3.5 待改进（Needs improvement）
---
一句结语
{ONE_SENTENCE}
---
🛡️ T · Trust（可信任度）— {T_SCORE} / 5.0
衡量 Skill 在安全、合规和可控性方面是否可信，是整个评估体系中的红线维度。
| 子项 | 得分 | 关键证据 | 风险/建议 |
|---|---|---|---|
| T1 安全性扫描 | {T1} | {T1_EVIDENCE} | {T1_RISK} |
| T2 国内适配性 | {T2} | {T2_EVIDENCE} | {T2_RISK} |
| T3 边界/权限控制 | {T3} | {T3_EVIDENCE} | {T3_RISK} |
| T4 安全声明 | {T4} | {T4_EVIDENCE} | {T4_RISK} |
T 维总结
| 亮点 | 待改进 |
|---|---|
| {T_STRENGTH} | {T_WEAKNESS} |
---
🔄 R · Reliability（可靠性）— {R_SCORE} / 5.0
衡量 Skill 在评测运行中的稳定性、可复现性和交付可靠性。
| 子项 | 得分 | 关键证据 | 风险/建议 |
|---|---|---|---|
| R1 异常处理 | {R1} | {R1_EVIDENCE} | {R1_RISK} |
| R2 可运行性 | {R2} | {R2_EVIDENCE} | {R2_RISK} |
| R3 交付物完整性 | {R3} | {R3_EVIDENCE} | {R3_RISK} |
| R4 降级处理 | {R4} | {R4_EVIDENCE} | {R4_RISK} |
R 维总结
| 亮点 | 待改进 |
|---|---|
| {R_STRENGTH} | {R_WEAKNESS} |
---
🎯 A · Adaptability（适用性）— {A_SCORE} / 5.0
衡量 Skill 是否适合其声明的使用场景，以及在真实候选环境中是否容易被正确识别和调用。
| 子项 | 得分 | 关键证据 | 风险/建议 |
|---|---|---|---|
| A1 边界清晰度 | {A1} | {A1_EVIDENCE} | {A1_RISK} |
| A2 Description 触发质量 | {A2} | {A2_EVIDENCE} | {A2_RISK} |
| A3 国内适用性 | {A3} | {A3_EVIDENCE} | {A3_RISK} |
| A4 场景覆盖广度 | {A4} | {A4_EVIDENCE} | {A4_RISK} |
A 维总结
| 亮点 | 待改进 |
|---|---|
| {A_STRENGTH} | {A_WEAKNESS} |
---
📐 C · Convention（规范性）— {C_SCORE} / 5.0
衡量 Skill 是否具备清晰、可维护、可复用的结构基础。
| 子项 | 得分 | 关键证据 | 风险/建议 |
|---|---|---|---|
| C1 用途/适用说明 | {C1} | {C1_EVIDENCE} | {C1_RISK} |
| C2 渐进披露 | {C2} | {C2_EVIDENCE} | {C2_RISK} |
| C3 元信息结构 | {C3} | {C3_EVIDENCE} | {C3_RISK} |
| C4 Gotchas 与指令规范 | {C4} | {C4_EVIDENCE} | {C4_RISK} |
C 维总结
| 亮点 | 待改进 |
|---|---|
| {C_STRENGTH} | {C_WEAKNESS} |
---
⚡ E · Effectiveness（有效性）— {E_SCORE} / 5.0
衡量 Skill 是否真正提升任务结果，以及这种提升是否值得付出相应代价。
| 子项 | 得分 | 关键证据 | 风险/建议 |
|---|---|---|---|
| E1 任务完成度 | {E1} | {E1_EVIDENCE} | {E1_RISK} |
| E2 正确性/权威性 | {E2} | {E2_EVIDENCE} | {E2_RISK} |
| E3 交付物质量 | {E3} | {E3_EVIDENCE} | {E3_RISK} |
| E4 增益归因 | {E4} | {E4_EVIDENCE} | {E4_RISK} |
E 维总结
| 亮点 | 待改进 |
|---|---|
| {E_STRENGTH} | {E_WEAKNESS} |
---
📊 no-skill 基线对比
| 对比维度 | no-skill（裸模型） | 启用此 skill | 增益 |
|---|---|---|---|
| 概念准确性 | {BASELINE_ACCURACY} | {SKILL_ACCURACY} | {GAIN_ACCURACY} |
| 适用场景判断 | {BASELINE_FIT} | {SKILL_FIT} | {GAIN_FIT} |
| 反模式/错误检测 | {BASELINE_AP} | {SKILL_AP} | {GAIN_AP} |
| 知识可追溯性 | {BASELINE_TRACE} | {SKILL_TRACE} | {GAIN_TRACE} |
| Token 成本 | 0 | ~{TOKEN_COST} tokens | {COST_LEVEL} |
---
📋 官方规范合规（agentskills.io）
| # | 检查项 | 结果 | 证据 |
|---|---|---|---|
| 1 | SKILL.md 存在 | ✅/❌ | {OFFICIAL_O1} |
| 2 | Name 与目录名一致 | ✅/❌ | {OFFICIAL_O2} |
| 3 | Name 格式有效（kebab-case） | ✅/❌ | {OFFICIAL_O3} |
| 4 | Description 有效（1-1024 chars） | ✅/❌ | {OFFICIAL_O4} |
| 5 | License 字段 | ✅/⚠️/❌ | {OFFICIAL_O5} |
| 6 | 目录结构规范 | ✅/⚠️ | {OFFICIAL_O6} |
| 7 | 渐进式披露质量 | ✅/⚠️ | {OFFICIAL_O7} |
| 8 | Description 触发质量 | ✅/⚠️ | {OFFICIAL_O8} |
| 9 | 脚本安全性 | ✅/⚠️/N/A | {OFFICIAL_O9} |
| 10 | 密钥/敏感信息扫描 | ✅/❌ | {OFFICIAL_O10} |
---
💡 优化建议（优先级排序）
| 优先级 | 维度 | 建议 |
|---|---|---|
| P1 | {P1_DIM} | {P1_SUGGESTION} |
| P2 | {P2_DIM} | {P2_SUGGESTION} |
| P3 | {P3_DIM} | {P3_SUGGESTION} |
---
📦 Skill 基础画像
| 指标 | 值 |
|---|---|
| 路径 | {SKILL_PATH} |
| SKILL.md | {BODY_LINES} lines · {BODY_CHARS} chars |
| References | {REF_COUNT} files · {REF_SUBDIRS} subdirs |
| Examples | {EX_COUNT} files |
| Scripts | {SCRIPT_COUNT} files |
| License | {LICENSE} |
| Secrets | {SECRETS_DETECTED} |
| Gotchas | {GOTCHAS_COUNT} domain-specific |
| 中文化 | {CHINESE_STATUS} |
| Skill Type | {SKILL_TYPE} |
---
评估依据 SkillHub TRACE 评测体系
官方规范合规检查基于 agentskills.io 标准
Generated {TIMESTAMP} · {SKILL_NAME}
Apache-2.0
TRACE 校准规则与反模式案例
本文档定义从基分到最终分的校准规则，以及 AI 评分时最常见的错误模式。
---
校准规则
规则按优先级排列。1-3 是必须执行的，4-6 是条件触发的。
规则 1：仅在有语义信号时调整
读完正文后再判断是否调整基分。如果脚本计算的基分已准确反映内容质量，不要为"凑到某个数"而调整。
判断方法： 对照 scoring-criteria.md 中该子项的"满分标准 + 扣分原因"。正文中能看到扣分模式 → 下调。正文中能看到上调信号 → 上调。都看不到 → 保持基分。
规则 2：调幅范围 ±0.3
单子项最多上调 0.3 或下调 0.3。不能把 4.5 跳到 5.0（最大 4.8）或 3.5 跳到 3.2（最小 3.2）。
规则 3：附调整理由
每个校准必须附一句中文理由，引用文件中的具体内容。格式："正文 xxx.md 中[具体内容]→ 调整 ±x.x"
规则 4：去重降档
directory.ref_names 存在 ≥ 3 个同版本前缀文件（如 jimeng-3.0-prompt-guide.md、jimeng-3.0-vocabulary.md、jimeng-3.0-word-library.md——前缀 jimeng-3.0 出现 3 次）→ C2、E2 基分降一档（最高 4.5）。此降档不占用 ±0.3 额度。
检测方法：读取 ref_names 列表，对每个文件名提取版本前缀（如 jimeng-3.0、seedream-5.0），统计每个前缀的出现次数。任一前缀 ≥ 3 次即触发。
规则 5：完美阈值缓冲
同一维度所有 4 子项的最终分（基分+校准后）都可达到 5.0 时，检查以下隐性瑕疵：
- 正文缺少某类边界说明（如纯文档型未声明数据安全 → T4 不应 5.0）
- 资源文件虽多但部分为模板自动生成（如
.generated.html类文件） - Gotchas 数量达标但深度不够（只列错误不解释原因 → C4 不应 5.0）
任一存在 → 该维度最高 4.8（非 5.0）。
规则 6：类型感知
脚本已内置 CLI/Prompt/Doc 差异化到基分公式中。AI 校准时注意：
- CLI 型技能的 C2 阈值用 150 行代替 200 行，E2 满分用 4 exs 代替 25 exs
- Prompt 型技能期望 examples 丰富，CLI 型不需要
- Doc 型技能 C2/E2 标准介于两者之间
---
反模式案例
以下做法一律视为不合格评估：
反模式 1：无论据就调基分
❌ T1 基分 4.8 → "感觉安全性不错，调到 5.0"
问题：没有引用任何文件中的内容，纯主观判断
✅ T1 基分 4.8 + 正文 "This skill does not access user files" → "正文有明确安全声明 → +0.2 → 5.0"反模式 2：只改报告不改 Skill
评分变化必须有对应的文件改动支持。如果两次评估之间分数变化了，但 SKILL.md 没有变化，评估失败。
反模式 3：CLI 和 Prompt 同一标准
❌ CLI 型只有 4 个 examples → "examples 太少，E2 给 3.5"
问题：CLI 型 4 个 exs 覆盖所有子命令已满分
✅ CLI 型 4 个 exs + 覆盖 4 个子命令 → E2=5.0（脚本已按 CLI 阈值计算）反模式 4：FAQ 充数判满分
❌ C4 基分 4.8 → 正文有 FAQ 章节 → "FAQ 完善，不调"
实际：FAQ 内容 "Q: 怎么使用？A: 按说明使用即可" ——充数
✅ C4 基分 4.8 → 读 FAQ 发现回答空洞 → "FAQ 充数，实质价值低 → -0.3 → 4.5"反模式 5：忽视去重信号
❌ E2 基分 5.0 → "exs=35 完美" → 不调
实际：ref_names 中 jimeng-3.0-* 出现 3 次 → 内容冗余
✅ E2 基分 5.0 → 检测到去重信号 → 降一档 → E2=4.5（最高）---
校准调幅指南
| 信号强度 | 幅度 | 示例 |
|---|---|---|
| 强正信号（正文有精确匹配满分标准的内容） | +0.3 | 有交互式引导模板、有三分类边界、有 ≥3 个可复制开场白 |
| 中正信号（有方向但不够系统） | +0.2 | 有边界说明但例子偏少、有参数选择但不系统 |
| 弱正信号（勉强可以看到相关元素） | +0.1 | 隐含了目标用户、正文偶见注意事项 |
| 弱负信号 | -0.1 | 个别地方表述模糊 |
| 中负信号（有明显缺口） | -0.2 | 缺少中间态边界、FAQ 偏浅 |
| 强负信号（与满分标准直接矛盾） | -0.3 | 无任何边界说明、Gotchas 只列错误不教改对、FAQ 充数 |
TRACE 评分细则：20 子项 ×（满分标准 + 扣分原因）
本文档是 skill-trace-evaluation 的核心评分参考。每个子项含：满分标准（5.0 锚点）、基分公式、扣分常见原因、可上调/下调信号、修改对比（需要时）。
AI 评分流程：脚本计算基分 → 阅读正文 → 对照本文档的满分标准 + 扣分原因 → 校准 ±0.3 → 终分。
---
五维度速查（高分信号 + 常见扣分）
T · Trust
高分信号： 有第三方安全报告或多引擎扫描证据；最小权限原则明确；无敏感信息硬编码；脚本行为清晰无自启动。 常见扣分： 出现敏感信息模式或疑似凭据；未说明权限/数据边界；依赖/脚本行为不透明；强依赖不可达的外部服务。
R · Reliability
高分信号： 输入要求清晰（格式、范围、前置条件）；异常输入有自检与提示；有可重复的流程与校验步骤；不可完成时解释原因并给建议。 常见扣分： 输入不符合要求时无反馈或返回空/错/幻觉；缺少失败路径处理建议。
A · Adaptability
高分信号： 明确"什么时候该用/不该用"；有 near-miss 边界（易误触发的相邻任务）；提示典型坑点并给规避方式；能力边界与输出结构清晰可预期。 常见扣分： 描述过泛导致误触发；能力边界不清或与相邻技能冲突。
C · Convention
高分信号： 结构清晰（快速上手→流程→示例→限制→进阶）；渐进式披露合理（细节放 references/）；模板/示例充分可复制；命名一致、版本说明清楚。 常见扣分： 只有大段描述无模板/示例；内容堆在 SKILL.md 缺索引/目录。
E · Effectiveness
高分信号： 产出能直接用于任务；高质量示例覆盖主流场景；能显著减少返工（常见翻车点+修复）；输出完整且格式符合预期。 常见扣分： 只能完成浅层输出用户仍需大量重做；高级场景缺乏可操作指导。
---
T · Trust（可信任度）— 4 子项
T1 · 安全性扫描
满分标准（5.0）： secrets_detected=false + has_scripts=false（纯文档型零风险），正文有安全声明。或 has_scripts=true 但每个脚本有 --help、非交互、无硬编码密钥、有 dry-run。
基分公式： 4.5 + no_scripts(+0.3) + secdecl(+0.2) - secrets_detected(-1.0每项)
扣分常见原因：
- 脚本报错直接抛出技术异常（ImportError / FileNotFound），不是用户语言
- 声称能访问用户平台账号后台数据（P0 红线）
- 引导用户分享账号密码（P0 红线）
has_scripts=true但正文无任何安全考量
可上调（+0.2~0.3）： 有第三方安全报告或多引擎扫描证据。
可下调（-0.2~0.3）： 脚本有交互式输入（input() / read -p），或依赖不透明。
---
T2 · 国内适配性
满分标准（5.0）： has_chinese=true，正文全中文，示例基于国内真实平台（微信/淘宝/小红书/飞书），专有名词用国内习惯叫法（"公众号"而非"WeChat Official Account"）。
基分公式： has_chinese ? 5.0 : 2.0
扣分常见原因： 示例混有英文平台（Slack/Twitter），触发词只有英文。
修改对比：
❌ "Write a Twitter thread about..."
✅ "写一组微博/小红书/公众号推文..."---
T3 · 边界透明度
满分标准（5.0）： 有独立边界章节，明确三类（✅能做 / ⚠️需条件 / ❌超范围），每类 ≥ 3 个具体例子。
基分公式： boundary ? 4.5+0.3(when_to_use) : 3.0
扣分常见原因： 边界只有一句话（"适用：Skill 质量检查。不适用：普通聊天"），无"需要条件"中间态。
4.5 vs 5.0 比对：
4.5（边界存在但弱）："适用场景：Skill 质量检查。不适用：普通聊天。"
5.0（三分类 + 每类 3 例）：
### ✅ 擅长处理
1. 检查新创建的 Skill：逐维度打分
2. 定位具体扣分原因：哪个子项、怎么改
3. 验证修改效果：重新打分确认提升
### ⚠️ 需要素材
1. 完整自检需要 SKILL.md 路径
2. 针对性建议需描述使用场景
### ❌ 超出范围（附替代方案）
1. 帮你写 Skill 内容 → 用 skill-creator
2. 评测非 Skill 文档 → 用对应工具
3. 自动发布 → 手动完成---
T4 · 数据隐私规范
满分标准（5.0）： 纯文档型自动 4.5。若正文/FAQ 明确声明"不收集/不处理用户数据" → 5.0。若涉及文件读写/API 调用 → 需说明处理方式。
基分公式： 4.5 + secdecl(+0.5) - has_scripts(-0.2)
扣分常见原因： 涉及文件上传/外部 API 但无隐私声明。
---
R · Reliability（可靠性）— 4 子项
R1 · 异常处理
满分标准（5.0）： 有 Gotchas/FAQ + 交互式引导模板："信息不足时先给假设版本 + 列具体缺少什么"，明确禁止笼统提示（"请提供更多信息"）。
基分公式： gotchas ? 4.0+0.5(validation) : 3.0
扣分常见原因： 有 Gotchas 但只列错误不教怎么改对——这与官方评语精确对应：官方对 jimeng-prompt-text2video 的 R1 评语"写错了主要靠对照长长的规则表排查，对新手不太友好"就是典型扣分模式。
修改对比：
❌ "请提供更多关于您产品的信息"
✅ "先给你一个示例版本，如果要精准化，需要补充：
1. 产品核心卖点（天然原料/香味/适合肤质）
2. 定价区间（影响文案档次定位）
3. 目标买家（文案完全不同）"可上调（+0.2~0.3）： Gotchas 含交互式引导模板。
可下调（-0.2~0.3）： Gotchas 只列错误不教改对，或 FAQ 充数。
---
R2 · 功能完善性
满分标准（5.0）： has_workflow_steps=true（CLI 型 cli_sections >= 3），场景覆盖无死角，每个声明的功能都有对应 example。
基分公式： WF ? 4.5+0.3(steps≥5 或 exs≥10) : (cli_secs≥3 ? 4.0 : 3.5)
扣分常见原因： 有流程但场景覆盖有缺口，或 CLI 型流程在代码块内非标题格式。
---
R3 · 运行稳定性
满分标准（5.0）： has_gotchas=true 或 has_rules=true，且有校验清单或 plan-validate-execute 循环，输出可重复稳定。
基分公式： 4.0 + (gotchas 或 rules ? +0.3) + (validation ? +0.2)
扣分常见原因： 无约束规则，完全依赖模型自由发挥；指令矛盾或模糊。
---
R4 · 降级兜底
满分标准（5.0）： 超出范围时给出替代工具引导 + 输入模糊时先给假设版本再反问 + 多任务时按优先级排序。
基分公式： boundary ? 4.5 : 3.5
扣分常见原因： 能识别超出范围但只说了"不支持"，无替代方案。超出范围时产生幻觉。
---
A · Adaptability（适用性）— 4 子项
A1 · 能力边界定义
满分标准（5.0）： has_boundary=true + has_when_to_use=true，有场景化判断逻辑（"什么时候该用/不该用/模糊情况怎么判"）。
基分公式： boundary+when_to_use ? 4.5 : 4.0
扣分常见原因： 只有一句话声明，无场景化判断逻辑。
---
A2 · 触发方式
满分标准（5.0）： description_length >= 100，使用用户意图语言，每个功能有精确触发条件（场景化路由，非关键词堆砌）。
基分公式： desc≥100 ? 5.0 : (desc≥50 ? 4.5 : 3.5)
扣分常见原因： 只有关键词列表无场景路由。
4.5 vs 5.0 比对：
4.5（关键词堆砌）："关键词：文章、脚本、文案、月刊、播客"
5.0（场景化路由）：
"需要创作文字类内容（文章/脚本/文案）→ 直接触发内容创作模块
需要排期或策划 → 触发内容策划子模块
需要多平台适配 → 触发多平台适配子模块"---
A3 · 受众广度
满分标准（5.0）： 明确说明适用用户类型 + 非主要用户使用指引，或提供不同经验级别的使用路径。
基分公式： 4.0 + chinese(+0.3)
扣分常见原因： 隐含目标用户但未明确说明，专业术语和基础概念混杂。
---
A4 · 定制化支持
满分标准（5.0）： 提供用户传递偏好的机制（风格卡片/场景参数/配置文件）。CLI 型天然有参数定制 = 5.0。Prompt 型有风格/场景选择。
基分公式： type=cli 或 exs≥10 ? 4.5 : 4.0
扣分常见原因： 输出完全固定，用户只能按预设路径使用。
---
C · Convention（规范性）— 4 子项
C1 · 文档质量
满分标准（5.0）： examples_files >= 10（CLI 型 >= 4），示例可直接复制使用，格式规范。
基分公式： exs≥阈值(cli=4/prompt=10) ? 5.0 : (exs≥3 ? 4.5 : 3.5)
扣分常见原因： 示例需要额外解释才能使用，格式不规范。
---
C2 · 渐进式披露
满分标准（5.0）： 三层结构：第1层正文 30 秒上手 → 第2层功能详情 → 第3层 references/ 深度文档。references_files >= 8 + body_lines < 200（CLI 型 < 150）。
基分公式： refs≥8+body<阈值 ? 5.0 : 3.0~4.5+trigger_hints(+0.2)
检查方法： 问自己"一个完全不了解这个 Skill 的人，看到第一屏能知道怎么开始用吗？"
扣分常见原因： references_files = 0 + body_lines > 350，全部堆在 SKILL.md 中。
---
C3 · 结构清晰
满分标准（5.0）： name 符合规范 + references_subdirs >= 2（如 rules/word-library/），文件名自解释，层次分明。
基分公式： 4.5 + name_valid(+0.2) + ref_subdirs≥2(+0.3)
扣分常见原因： 结构混乱，文件命名不直观，或 frontmatter 缺失。
---
C4 · 反模式与 FAQ
满分标准（5.0）： Gotchas ≥ 5 条覆盖核心陷阱 + FAQ ≥ 6 题且非充数（每个答案让用户真正解决问题）。
基分公式： gotchas ? 4.5+0.3(gc≥5) : 3.5
扣分常见原因： FAQ 充数——"Q: 怎么使用？A: 按照说明使用即可"——回答和没回答一样。
---
E · Effectiveness（有效性）— 4 子项
E1 · 输出准确性
满分标准（5.0）： 不同场景的执行路径区分明确，用户不容易选错方向。有"禁止在不确定领域胡编"规则或等效约束。
基分公式： WF ? 4.5+0.3(validation) : 4.0
扣分常见原因： 场景覆盖有缺口，指导模糊或存在可验证错误。
---
E2 · 内容完整度
满分标准（5.0）： Prompt 型 examples_files >= 25；CLI 型 >= 4 覆盖所有子命令；Doc 型 >= 5。
基分公式： exs≥阈值(prompt=25/cli=4/doc=5) ? 5.0 : (exs≥10 ? 4.5 : 3.0~4.0)
扣分常见原因： 场景缺口明显，高级场景缺端到端示例。
内容冗余降档： 若 ref_names 存在 ≥3 个同版本前缀文件 → 降一档（最高 4.5）。
---
E3 · 创造力与增值
满分标准（5.0）： 不只告诉"怎么做"——还告诉"怎么评估质量""不同方案有什么区别""哪些坑要避开""为什么这样做"。references_subdirs >= 2 是深度正信号。
基分公式： ref_subdirs≥2 ? 4.5+0.2(refs≥10) : 4.0
扣分常见原因： 内容较浅，仅覆盖基础操作，无超出"操作手册"的领域知识。
---
E4 · 开箱即用度
满分标准（5.0）： WF steps + validation + 有快速开始章节或 ≥ 3 个可复制开场白，用户无需阅读全文就能上手。
基分公式： 4.0 + WF(+0.3) + val(+0.3) + gotchas(+0.2) + cli_secs≥3(+0.2)
扣分常见原因： 只有功能说明没有入门引导，需要读完全文才知道怎么开始。
4.5 vs 5.0 比对：
4.5（只有功能说明）："功能列表：月刊撰写、播客脚本..."
5.0（有新手30秒入门）：
"直接把需求发过来就行。几个典型开场白：
'帮我写这个月的博客月刊，主题是 AI 工具盘点'
'有客户投诉质量问题，帮我写回复'"TRACE 自检反模式案例集
来源声明： 本文档来源于 skill-trace-checker by 东四联周博远。
本文档收录 Skill 创作者在进行 TRACE 自检时最常犯的错误模式，每类附"错误示例 ❌ → 正确示例 ✅"对比。
参考本文档可避免在同一坑里反复踩。
---
反模式 1：用"美化措辞"代替实质改进
这是最常见也最致命的反模式。当 AI 被要求提高 TRACE 分数时，如果只修改评分报告的描述文字，而不修改 Skill 文件本身，就是在作弊。
❌ 错误做法：
评分报告显示"A-能力边界 4.5分"
→ 修改报告措辞为"边界清晰，说明充分"
→ 声称已提升到 5.0 分
问题：SKILL.md 里实际上没有"能力边界说明"章节，只有一句话"适合 Skill 作者使用"
✅ 正确做法：
评分报告显示"A-能力边界 4.5分"
→ 在 SKILL.md 中增加独立的"能力边界说明"章节
→ 添加三分类（✅擅长/⚠️需素材/❌超范围），每类 ≥3 个具体例子
→ 重新打分验证，确认真实提升判断依据： 分数提升必须有对应的文件改动。如果只改报告，没有改任何 .md 文件，一律视为反模式。
---
反模式 2：FAQ 挂名充数
FAQ 部分有标题但内容空洞，或者只有 2～3 题应付检查，没有真正帮到用户解答困惑。
❌ 错误示例（FAQ 充数）：
## FAQ
Q: 这个 Skill 有什么用？
A: 帮助检查 Skill 质量。
Q: 怎么使用？
A: 按照说明使用即可。
问题：
- 没有具体操作步骤
- 没有覆盖用户实际会遇到的问题
- 回答和没回答一样
✅ 正确示例：
Q: 我只改了 Skill 的 FAQ，需要重新做 TRACE 吗？
A: 要看改动性质。如果 FAQ 新增覆盖了原来没回答的边缘场景，或改正了错误信息
→ 建议重新检查 C·规范性 维度中的"FAQ 深度"子项。
如果只是修正了错别字或改了措辞
→ 可以不做，但建议记录一下修改内容以备审查。满分标准： 主文档 ≥6 题，且每个答案能让用户真正解决问题，而非继续猜测。
---
反模式 3：能力边界描述模糊
只写一句"适合 Skill 作者"或"不适用于一般用户"，没有具体说明能做什么、不能做什么。
❌ 错误示例（模糊边界）：
## 适用范围
本 Skill 适合需要检查 Skill 质量的用户，不适合普通聊天场景。
问题：
- 用户不知道哪些具体操作支持
- 不知道遇到超范围场景该怎么办
- "普通聊天场景"是什么？太模糊
✅ 正确示例（三分类 + 具体例子）：
## 能力边界说明
### ✅ 擅长处理
1. 检查新创建的 Skill：读取文件后逐维度打分，输出结构化评分表
2. 定位具体扣分原因：精确指出是哪个子项、在哪个文件、怎么改
3. 验证修改效果：修改后重新打分，确认实质性改进
...
### ❌ 超出范围（附替代方案）
1. 帮你写 Skill 内容 → 用 skill-creator 创建 Skill
2. 评测非 Skill 类文档 → 找代码审查工具
...---
反模式 4：触发条件写成关键词堆砌
只列一堆关键词，没有说明"什么情况下触发哪个功能"，用户自己猜。
❌ 错误示例（关键词堆砌）：
触发词：TRACE, 质量检查, 评测, 自检, Skill质量, 打分, 审查
问题：
- 用户不知道"打分"和"自检"有什么区别
- 不知道是对自己的 Skill 打分还是对别人的
- 不知道触发后会发生什么
✅ 正确示例（场景化触发判断）：
**什么时候该用本 Skill：**
- 刚写完 SKILL.md → 触发全量 TRACE 自检
- 修改了 FAQ / 反模式 / 行为规范等核心内容 → 触发重新评测（只检查受影响维度）
- 用户明确要求"检查 Skill 质量" → 触发全量检查
- 想知道"某项扣分了怎么改" → 触发专项维度检查
**不该用本 Skill 的情况：**
- 想创作一个新 Skill → 用 skill-creator
- 想执行某个 Skill 的功能 → 直接调用目标 Skill---
反模式 5：渐进式披露只有一层
整个 SKILL.md 是一个长页面，没有分层结构，用户进来就被全量信息淹没。
❌ 错误结构（单层平铺）：
# Skill 名称
一大段介绍文字 + 全部功能说明 + 全部示例 + 全部FAQ + 所有注意事项
→ 用户需要从头到尾读完才能开始使用
✅ 正确结构（三层渐进）：
第1层（30秒上手）：
- 是什么 / 什么时候用 / 3 个直接可用的触发示例
第2层（按需查阅）：
- 详细功能说明 + 能力边界 + 操作流程
第3层（深度参考）：
- references/ 目录：scoring-criteria.md, calibration-guide.md, trace-anti-patterns.md 等检查方法： 问自己"完全陌生的用户只看第一屏，能知道怎么开始用吗？"如果答案是不能，就需要加入门章节。
---
禁忌用法清单
以下做法在 TRACE 自检中一律视为不合格：
| 禁忌行为 | 为什么不行 | 解决方案 |
|---|---|---|
| 没有 references/ 目录 | 深度文档缺失，C·规范性 多项无法满分 | 创建目录并填充核心参考文件 |
| FAQ 少于 6 题 | C-FAQ深度 必然扣分 | 主文档 ≥6 题 + faq-deep.md ≥8 题 |
| 能力边界只有一句话 | A-能力边界定义 最多 4.0 | 添加三分类结构，每类 ≥3 例 |
| 没有新手入门章节 | C-渐进式披露、E-开箱即用 双双扣分 | 在文档开头添加 30 秒入门区块 |
| 修改报告不修改文件 | TRACE 自检的根本目的是改进 Skill 本身 | 每次评分变化都要有对应文件改动 |
| 错误提示只说"信息不足" | R-异常处理 无法满分 | 必须指出缺少哪[N]项 + 如何补充 |
TRACE 深度 FAQ
来源声明： 本文档来源于 skill-trace-checker by 东四联周博远。
本文档覆盖边缘场景、工具兼容性、安全合规等主文档 FAQ 未涵盖的进阶问题。
主文档 FAQ（第1-6题）已覆盖通用使用问题，本文档从第7题开始继续。
---
第 7 题：我用的是第三方 Skill 平台（不是 Skillhub），TRACE 标准还适用吗？
适用，但有调整空间。TRACE 五维度（T/R/A/C/E）是通用质量框架，不依赖特定平台。 需注意以下差异：
- T-国内适配性：如果目标用户是海外用户，可将"中文示例/国内平台"替换为对应地区的标准
- C-规范性：不同平台对 references/ 文件结构的支持不同，若平台不支持多文件，可将所有内容合并在单文件中，但需标注层级
- 其余三维度（R/A/E）标准不变
---
第 8 题：TRACE 自检通过了，但 Skillhub 官方评测还是扣分，正常吗？
正常。原因有二： 1. 官方评测包含用户行为数据：实际用户的使用率、满意度、完成率都是评分因子，AI 自检无法模拟 2. 官方有人工审核层：某些标准（如是否含有违规内容、品牌语气是否符合平台调性）需人工判断
建议：把 TRACE 自检作为"发布前保底检查"，官方评测作为"发布后持续改进参考"，两者互补。
---
第 9 题：Skill 里需要用到用户的真实数据（如工资、业绩），怎么满足 T-数据隐私？
需要在 FAQ 或专项章节中明确说明以下内容：
1. 数据去向：用户输入的数据只用于本次会话，不会被存储或用于训练 2. 脱敏建议：提供示例脱敏操作，如"可以把真实金额替换为相对比例，如'A 比 B 高 30%'" 3. 最小化原则：说明哪些数据是必须的，哪些是可选的，让用户自主决定提供多少
示例说明文字（可直接放入 FAQ）：
Q: 我需要输入真实数据吗？会不会泄露？
A: 本 Skill 只在当前对话中使用你输入的数据，关闭对话后数据不会保留。
如果你处理的是敏感数据（如工资/业绩），建议使用脱敏版本：
- 用代号替换姓名（张三 → 员工A）
- 用区间替换精确数字（月薪18500 → 月薪1-2万区间）---
第 10 题：Skill 生成的内容可以商用吗？TRACE 里需要说明吗？
需要在 FAQ 中明确说明，否则 T-边界透明度 会扣分。标准说明方式：
Q: 用这个 Skill 生成的内容可以直接商用吗？
A: 可以。本 Skill 生成的内容版权归用户所有，可用于商业用途。
注意：如果生成内容中引用了特定第三方素材（如品牌名称、歌词），
请确认相关权利不涉及版权侵犯，本 Skill 不对引用内容的商用合规性负责。---
第 11 题：多个 Skill 协同工作时（如"地图指挥官"调用三个子 Skill），TRACE 如何评测？
评测原则：每个 Skill 独立评测，主 Skill 额外要求。
- 子 Skill：按正常 TRACE 标准各自评测
- 主 Skill（编排/路由层）额外检查：
- A-触发方式：是否清楚说明了"什么需求路由到哪个子 Skill"
- R-降级兜底：某个子 Skill 不可用时，主 Skill 是否有降级处理策略
- T-边界透明度：用户能否清楚知道自己在和哪个子 Skill 交互
---
第 12 题：我的 Skill 只有一个很简单的功能（比如"帮我格式化代码"），也需要 references/ 目录吗？
不是强制的，但要通过 TRACE，必须：
- 如果没有 references/：在 SKILL.md 里必须完整覆盖 FAQ ≥6 题、反模式说明、以及能力边界三分类
- 如果有 references/：可以将 FAQ、反模式、示例分散到子文件，SKILL.md 可以更简洁
实用建议： 对于功能简单的 Skill，建议用"单文件扩展方案"——在 SKILL.md 底部加 ## 常见问题、## 注意事项、## 使用示例 三个章节，代替 references/ 多文件。
---
第 13 题：references/ 文件有哪些是"必须有"，哪些是"建议有"？
| 文件 | 必须 / 建议 | 缺失影响 |
|---|---|---|
examples.md | 必须（若功能复杂） | E-内容完整度、C-文档质量 扣分 |
anti-patterns.md | 必须 | C-反模式与FAQ 会扣分 |
faq-deep.md | 必须（FAQ<6题时） | C-FAQ深度 扣分 |
sample-reports.md | 建议（评测类Skill专用） | E-内容完整度 轻微扣分 |
system-prompt.md | 建议（若有复杂行为规范） | R-功能完善性 轻微扣分 |
---
第 14 题：触发词写了很多，但 AI 有时候还是没有自动调用，这影响 TRACE 评分吗？
影响 A-触发方式精确度。 原因通常是：触发词太模糊，与其他 Skill 产生冲突。改进方法：
- 换用"行为+对象"组合触发词，而非单个名词（"检查 Skill 质量" > "质量"）
- 在触发词旁边加场景说明（"当用户提到...时触发"）
- 在 SKILL.md 的触发条件章节列出典型触发句型（整句话，不只是关键词）
---
第 15 题：我对同一个 Skill 做了 3 次 TRACE，每次分数都不一样，正常吗？
正常，±0.3 分属于可接受的 AI 评分波动。 超过 0.5 分的波动通常意味着：
- 该子项的满分标准本身描述模糊 → 对照
trace-criteria-detail.md的"5.0 vs 4.5 对比案例"，找到客观标准 - AI 对该文件理解不一致 → 在 SKILL.md 中把该子项的满足方式写得更明确，减少解读空间
实用建议： 分数在 4.8 及以上时，可以视为达到实用标准，不必无限追求字面上的 5.0。
真实评分报告案例集
本文档展示四种典型场景的完整评分报告，帮助用户理解"好的评测报告是什么样的"。
所有报告使用与 SKILL.md 报告模板 一致的格式。
---
案例 A：不合格 Skill（综合 3.8 分 ❌）
Skill 概述： 某"情绪日记助手"Skill，只有 SKILL.md 一个文件，内容约 500 字，无 references/ 目录。
# TRACE Evaluation Report
Target: `~/.workbuddy/skills/emotion-diary-skill`
## Overall Assessment
**Overall Score: 3.8 / 5**
**Overall Rating: Good (良好)**
仅500字单文件 Skill，边界、隐私、反模式、FAQ 四项核心缺失，需要大幅修改。
## Evaluation Details
### T · Trust — 4.0 / 5
全中文且示例含微信场景，但专业领域无免责声明，边界和隐私均未涉及。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 安全性 | 4.5 | 无 P0/P1 风险，但未声明"不能替代心理医生" |
| 国内适配性 | 5.0 | 全中文，示例含微信/朋友圈场景 |
| 边界透明度 | 3.5 | 缺少三分类章节，只有一句"适合记录情绪" |
| 数据隐私 | 3.0 | 涉及用户情绪/私密内容，完全没有隐私说明 |
### R · Reliability — 4.0 / 5
基本场景覆盖但异常处理和降级兜底不足。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 异常处理 | 4.0 | 情绪难以描述时只说"请详细说明"，无交互式引导模板 |
| 功能完善性 | 4.5 | 基本场景覆盖，缺"情绪复盘"功能 |
| 运行稳定性 | 4.0 | 用户说"心情不好"时直接提问，没有先给共情回应 |
| 降级兜底 | 3.5 | 没有说明"需要专业帮助"时怎么处理 |
### A · Adaptability — 3.5 / 5
边界和受众描述严重不足。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 能力边界定义 | 3.0 | 没有边界章节 |
| 触发方式 | 4.5 | 触发词完整，但无场景路由 |
| 受众广度 | 3.5 | 没有说明不同用户（青少年/职场人/老年人）的使用差异 |
| 定制化支持 | 3.0 | 没有风格定制机制 |
### C · Convention — 2.9 / 5
规范性全面缺失——无 references/、无新手入门、FAQ 仅 1 题。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 文档质量 | 4.0 | 基本分层，但无表格和模板示例 |
| 渐进式披露 | 3.5 | 无新手入门，无 references/，单层平铺 |
| 结构清晰 | 4.0 | 层次基本清晰，但无 references 子目录 |
| 反模式与FAQ | 2.0 | 无反模式说明 + FAQ 只有 1 题 |
### E · Effectiveness — 3.8 / 5
功能基础但缺乏增值和入门引导。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 输出准确性 | 4.5 | 有基本准确性约束 |
| 内容完整度 | 3.5 | 缺情绪复盘/情绪追踪等核心功能 |
| 创造力与增值 | 3.5 | 只是记录，无任何增值特性 |
| 开箱即用度 | 3.5 | 无新手入门，无示例 |
## Improvement Suggestions
1. **新增能力边界三分类章节**：✅擅长（情绪记录/每日复盘）→ ⚠️需素材（具体事件背景）→ ❌超范围（心理治疗→寻求专业帮助）
2. **创建 references/ 目录**：至少含 anti-patterns.md + faq-deep.md，FAQ 从 1 题扩到 ≥6 题
3. **添加隐私声明 + 心理健康免责**：声明数据只在当前会话使用，明确"不能替代心理医生"---
案例 B：修改后达标（综合 5.0 分 ✅）
背景： 同一个 emotion-diary-skill，经过两轮修改后达标。
主要修改： 1. 新增 references/ 目录，创建 anti-patterns.md / faq-deep.md / examples.md 2. 在 SKILL.md 增加"新手30秒入门"章节和能力边界三分类 3. 系统提示词添加"心理健康声明"和"情绪不明确时先给共情版本"规则 4. FAQ 从 1 题扩展到 8 题，faq-deep.md 覆盖 10 个边缘场景
# TRACE Evaluation Report
Target: `~/.workbuddy/skills/emotion-diary-skill`
## Overall Assessment
**Overall Score: 5.0 / 5**
**Overall Rating: Excellent (优秀)**
修改后文档体系完整，边界清晰，FAQ 深入，已全面达到 TRACE 满分标准。
## Evaluation Details
### T · Trust — 5.0 / 5
全中文，国内场景适配完善，安全声明和隐私说明完整。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 安全性 | 5.0 | 新增"不能替代心理医生"免责声明，无 P0/P1 风险 |
| 国内适配性 | 5.0 | 全中文，示例含微信/朋友圈/小红书场景 |
| 边界透明度 | 5.0 | 三分类（✅5项/⚠️3项/❌3项）每类含替代方案 |
| 数据隐私 | 5.0 | FAQ 明确声明"数据仅本次会话使用，关闭后不保留" |
### R · Reliability — 5.0 / 5
异常处理完善，降级兜底有替代方案引导。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 异常处理 | 5.0 | 情绪不明确时先给共情版本+列"需补充：1.具体事件 2.持续时间" |
| 功能完善性 | 5.0 | 覆盖情绪记录/复盘/趋势分析/疏导建议四大场景 |
| 运行稳定性 | 5.0 | plan-validate-execute 循环，输出格式说明完整 |
| 降级兜底 | 5.0 | 超出范围时输出"建议咨询心理咨询师热线：xxx" |
### A · Adaptability — 5.0 / 5
场景化路由清晰，受众差异化指导完备。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 能力边界定义 | 5.0 | 三分类有场景化判断逻辑 |
| 触发方式 | 5.0 | 场景化路由：情绪记录/复盘/趋势/疏导 → 各自路由 |
| 受众广度 | 5.0 | 分青少年/职场人/老年人三种使用路径 |
| 定制化支持 | 5.0 | 支持风格参数：轻松/严肃/简洁 |
### C · Convention — 5.0 / 5
三层渐进式披露，FAQ 深度充足。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 文档质量 | 5.0 | examples/ ≥ 10 个，可直接复制使用 |
| 渐进式披露 | 5.0 | 30秒入门→功能详情→references/ 三层，body < 200 行 |
| 结构清晰 | 5.0 | references/ 含 3 个子目录，命名语义清晰 |
| 反模式与FAQ | 5.0 | Gotchas 6 条覆盖核心陷阱 + FAQ 8 题 + faq-deep.md 10 题 |
### E · Effectiveness — 5.0 / 5
增值特性丰富，开箱即用体验优秀。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 输出准确性 | 5.0 | 场景区分明确，有"禁止替代专业诊断"约束规则 |
| 内容完整度 | 5.0 | examples 覆盖全部四大场景，有端到端示例 |
| 创造力与增值 | 5.0 | 情绪趋势分析 + 疏导建议 + 多用户路径，3 项增值 |
| 开箱即用度 | 5.0 | 新手入门含 3 个可复制开场白 |
## Improvement Suggestions
无需修改，全部 20 子项达到 5.0 ✅---
案例 C：高质量 Skill（综合 5.0 分，附亮点说明）
Skill 概述： opc-skill（一人公司运营助手），功能完整，文档体系健全。
# TRACE Evaluation Report
Target: `~/.workbuddy/skills/opc-skill`
## Overall Assessment
**Overall Score: 5.0 / 5**
**Overall Rating: Excellent (优秀)**
文档体系健全，三分类边界清晰，异常处理有固化格式模板，FAQ 深度达 20 题。
## Evaluation Details
### T · Trust — 5.0 / 5
全中文专为国内一人公司场景打造，安全声明和隐私说明完整。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 安全性 | 5.0 | 有禁止行为列表，无 P0/P1 风险，专业领域有免责声明 |
| 国内适配性 | 5.0 | 全中文，示例基于微信/飞书/企业微信等国内平台 |
| 边界透明度 | 5.0 | 三分类每类≥3例，超范围每项附替代方案（"SEO→专业SEO工具"） |
| 数据隐私 | 5.0 | 声明"不存储用户数据"，提供脱敏操作指导 |
### R · Reliability — 5.0 / 5
异常处理有固化格式模板，降级兜底有替代工具引导。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 异常处理 | 5.0 | 系统提示词固化格式："缺少[N]项才能精准输出：1.xxx 2.xxx" |
| 功能完善性 | 5.0 | 覆盖内容/运营/财务/客户四大场景，无盲区 |
| 运行稳定性 | 5.0 | plan-validate-execute 循环，输出可重复 |
| 降级兜底 | 5.0 | 每个超范围项都有替代工具引导 |
### A · Adaptability — 5.0 / 5
每个模块有三级路由，场景化触发精确。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 能力边界定义 | 5.0 | 场景化判断逻辑，有 near-miss 边界说明 |
| 触发方式 | 5.0 | 三级路由：主关键词→功能分类→子功能触发 |
| 受众广度 | 5.0 | 分个人创业者/小团队/自由职业者三种使用路径 |
| 定制化支持 | 5.0 | 风格卡片机制（正式/口语化/极简） |
### C · Convention — 5.0 / 5
三层渐进式披露，FAQ 主文档 8 题 + faq-deep.md 12 题。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 文档质量 | 5.0 | 示例可直接复制使用，格式规范 |
| 渐进式披露 | 5.0 | 30秒入门→功能详情→references/，body 179 行 |
| 结构清晰 | 5.0 | references/ 含 4 个子目录，文件命名语义清晰 |
| 反模式与FAQ | 5.0 | Gotchas 7 条 + FAQ 8 题 + faq-deep.md 12 题（覆盖隐私合规/多人协作/商用授权） |
### E · Effectiveness — 5.0 / 5
新手入门含 5 个可复制开场白，覆盖 5 个不同使用场景。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 输出准确性 | 5.0 | 禁止胡编规则 + 每个输出注明决策逻辑 |
| 内容完整度 | 5.0 | 场景覆盖 80%+ 一人公司常见需求 |
| 创造力与增值 | 5.0 | 风格定制 + 多平台适配 + 主动询问调整意愿，3 项增值 |
| 开箱即用度 | 5.0 | 新手入门含 5 个可复制开场白，零学习成本 |
## Improvement Suggestions
无需修改，全部 20 子项达到 5.0 ✅---
案例 D：边界情况（综合 4.9 分，可接受但有已知局限）
背景： 一个功能极简的"番茄钟提醒"Skill，功能单一，不适合建完整 references/ 体系。
# TRACE Evaluation Report
Target: `~/.workbuddy/skills/pomodoro-skill`
## Overall Assessment
**Overall Score: 4.9 / 5**
**Overall Rating: Excellent (优秀)**
功能极简但文档完整，扣分项均为功能定位导致的天然局限，非设计缺陷。
## Evaluation Details
### T · Trust — 5.0 / 5
纯文档型零风险，边界和隐私说明完整。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 安全性 | 5.0 | 纯文档型，无 scripts/，无敏感操作 |
| 国内适配性 | 5.0 | 全中文，支持口语化触发 |
| 边界透明度 | 5.0 | 三分类（✅计时提醒/⚠️需自定义时长/❌项目管理） |
| 数据隐私 | 5.0 | 声明"不需要任何用户数据" |
### R · Reliability — 5.0 / 5
异常处理和降级兜底到位。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 异常处理 | 5.0 | 时长未指定时默认 25 分钟，未指定休息时默认 5 分钟 |
| 功能完善性 | 5.0 | 覆盖开始/暂停/休息/统计四大场景 |
| 运行稳定性 | 5.0 | 有 validate-plan-execute 循环 |
| 降级兜底 | 5.0 | 超范围时引导使用"Trello/Notion"做项目管理 |
### A · Adaptability — 4.7 / 5
受众和定制化受功能定位限制。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 能力边界定义 | 5.0 | 三分类清晰，每类 3 例 |
| 触发方式 | 5.0 | 场景化路由 |
| 受众广度 | 4.5 | 功能极简，团队协作场景天然不适用——非设计缺陷 |
| 定制化支持 | 4.5 | 时长已支持参数传入，但无法做更复杂个性化——符合功能定位 |
### C · Convention — 5.0 / 5
文档结构清晰，FAQ 完整。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 文档质量 | 5.0 | 示例可直接复制使用 |
| 渐进式披露 | 5.0 | 三层结构，body 98 行 |
| 结构清晰 | 5.0 | 命名规范，层次分明 |
| 反模式与FAQ | 5.0 | Gotchas 4 条（适配简洁功能）+ FAQ 6 题 |
### E · Effectiveness — 4.7 / 5
创造力和增值受功能定位限制。
| Sub-item | Score | Commentary |
|----------|-------|------------|
| 输出准确性 | 5.0 | 有约束规则 |
| 内容完整度 | 5.0 | 场景全覆盖 |
| 创造力与增值 | 4.5 | 工具型 Skill，功能本身无需增值特性——非设计缺陷 |
| 开箱即用度 | 5.0 | 3 个可复制开场白 |
## Improvement Suggestions
无需强制修改。扣分项均为功能定位导致的天然局限（A3: 团队不适用，A4: 无复杂个性化，E3: 功能无需增值特性）。综合 4.9 达到实用标准 ✅Skill TRACE 自检清单（一页纸版本）
来源声明： 本文档来源于 skill-trace-checker by 东四联周博远。
内容关系： 本文档是 scoring-criteria.md 的一页纸浓缩版，所有满分标准均衍生自 scoring-criteria.md 的 20 子项定义。详细修改对比和基分公式请查阅 scoring-criteria.md。
创建或修改 Skill 后，逐项打勾。所有项目通过后才能交付。
---
T · Trust 可信任度
- [ ] SKILL.md 全文为中文，触发词包含中文关键词
- [ ] 所有示例场景基于国内真实平台
- [ ] 系统提示词有"禁止行为"列表，无 P0/P1 安全风险
- [ ] 有"能力边界说明"独立章节（三分类 + 各类 ≥3 个具体例子）
- [ ] 有数据隐私/安全使用说明（FAQ 或专项章节）
---
R · Reliability 可靠性
- [ ] 系统提示词规定：信息不足时先给假设版本 + 列具体补充清单
- [ ] 明确禁止"请提供更多信息"等笼统提示
- [ ] 所有主要使用场景有覆盖，每个功能有输出格式说明
- [ ] 超范围请求有替代工具引导说明
- [ ] 多任务场景有优先级处理说明
---
A · Adaptability 适用性
- [ ] 每个功能模块有"精确触发条件"（主触发 + 子模块路由）
- [ ] 能力边界三分类各有具体例子（不是泛泛而谈）
- [ ] 说明了不同类型用户（垂直行业/团队等）的使用方式
- [ ] 有定制化使用指南（风格卡片或参数传递机制）
---
C · Convention 规范性
- [ ] 有快速导航/新手入门章节（第一屏30秒能上手）
- [ ] references/ 目录存在且文件名语义清晰
- [ ] references/ 下有 trace-anti-patterns.md：≥3类反模式 + 改进对比 + 禁忌清单
- [ ] 主文档 FAQ ≥6 题（通用问题）
- [ ] references/faq-deep.md：≥8 题（边缘场景/工具兼容/安全合规）
---
E · Effectiveness 有效性
- [ ] 系统提示词有输出准确性约束（禁止在不确定领域胡编）
- [ ] 功能点覆盖该领域 80%+ 的常见需求
- [ ] 有 ≥3 项超出基础功能的增值特性
- [ ] 有"新手入门"章节 + ≥3 个可直接复制的开场白示例
- [ ] references/examples.md：每个主要模块有真实输出示例（三元组格式）
---
最终确认
[ ] 全部 25 项通过 → 输出 TRACE 评分表，综合 5.0 / 5.0 ✅
[ ] 有未通过项 → 修改对应文件后重新检查，不允许交付#!/usr/bin/env python3
"""
Hybrid TRACE evaluator: static base score + evidence packet.
This script computes a deterministic base score for each TRACE sub-item from
measurable evidence fields. The AI (loaded with skill-trace-evaluation SKILL.md)
then applies a semantic adjustment (±0.3) based on reading the SKILL.md body.
Final score per sub-item = clamp(base + adjustment, 1.0, 5.0).
"""
from __future__ import annotations
import argparse
import json
import re
import sys
from dataclasses import dataclass, field
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple
FRONTMATTER_BOUNDARY = re.compile(r"^---\s*$")
NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
SECRET_RE = re.compile(
r"(AKIA[0-9A-Z]{16}|sk-[A-Za-z0-9]{16,}|"
r"(api[_-]?key|secret|token|password)\s*[:=]\s*['\"][^'\"]+['\"])",
re.IGNORECASE,
)
SECURITY_DECLARATION_RE = re.compile(
r'(?:does not (?:access|collect|upload|send|transmit|share|leak|store|log)'
r'|no (?:sensitive|secret|credential|api.key|token|password)'
r'|不(?:访问|收集|上传|发送|传输|共享|泄露|存储|记录)'
r'|无(?:敏感|密钥|凭据|API|token|密码)'
r'|最小权限|least.privilege'
r'|安全|security.safe)',
re.IGNORECASE,
)
CLI_SECTION_RE = re.compile(
r'(?:^|\n)\s*(?:###?\s+)?(?:Prerequisites|Install(?:ation)?|Setup'
r'|Configuration|Usage|Quick\s*Start|Getting\s*Started'
r'|Environment\s*(?:Setup|Variables)|Authentication|Login'
r'|基本用法|使用方式|安装|配置|环境|登录|前置条件)',
re.IGNORECASE,
)
WORKFLOW_STEP_RE = re.compile(r'(?:^|\n)\s*(?:###?\s+)?Step\s+\d', re.MULTILINE)
@dataclass
class SubItemScore:
base: float
formula: str
evidence: Dict[str, Any] = field(default_factory=dict)
@dataclass
class DimScores:
label: str
sub_items: Dict[str, SubItemScore] = field(default_factory=dict)
@property
def avg(self) -> float:
if not self.sub_items:
return 0.0
return round(sum(s.base for s in self.sub_items.values()) / len(self.sub_items), 1)
@dataclass
class EvidencePacket:
skill_dir: str
skill_name: str
generated_at: str
frontmatter: Dict[str, Any] = field(default_factory=dict)
body: Dict[str, Any] = field(default_factory=dict)
directory: Dict[str, Any] = field(default_factory=dict)
safety: Dict[str, Any] = field(default_factory=dict)
base_scores: Dict[str, Any] = field(default_factory=dict)
def parse_args() -> argparse.Namespace:
p = argparse.ArgumentParser(
prog="trace_evaluate.py",
description="Hybrid TRACE evaluator: static base score + evidence packet for AI adjustment.",
)
p.add_argument("--skill-dir", required=True, help="Path to the target skill directory.")
p.add_argument("--format", choices=["json", "pretty"], default="json", help="Output format.")
p.add_argument("--output", default="", help="Write output to a file instead of stdout.")
return p.parse_args()
def read_text(path: Path) -> str:
return path.read_text(encoding="utf-8")
def has_chinese(text: str) -> bool:
return bool(re.search(r'[\u4e00-\u9fff]', text))
def count_files(dir_path: Path) -> int:
if not dir_path.exists():
return 0
return sum(1 for p in dir_path.rglob("*") if p.is_file())
def count_subdirs(dir_path: Path) -> int:
if not dir_path.exists():
return 0
return sum(1 for p in dir_path.iterdir() if p.is_dir())
def list_ref_names(dir_path: Path) -> List[str]:
if not dir_path.exists():
return []
return sorted([p.name for p in dir_path.rglob("*") if p.is_file()])
def parse_frontmatter(skill_md: str) -> Tuple[Dict[str, Any], str]:
lines = skill_md.splitlines()
if not lines or not FRONTMATTER_BOUNDARY.match(lines[0]):
return {}, skill_md
i = 1
fm_lines: List[str] = []
while i < len(lines) and not FRONTMATTER_BOUNDARY.match(lines[i]):
fm_lines.append(lines[i])
i += 1
if i >= len(lines):
return {}, skill_md
body = "\n".join(lines[i + 1 :]).lstrip("\n")
fm: Dict[str, Any] = {}
for raw in fm_lines:
if not raw.strip() or raw.strip().startswith("#"):
continue
if ":" not in raw:
continue
k, v = raw.split(":", 1)
fm[k.strip()] = v.strip()
return fm, body
def collect_facts(skill_dir: Path) -> Tuple[Dict[str, Any], Dict[str, Any], Dict[str, Any], Dict[str, Any], str]:
"""Collect all raw facts from the skill directory."""
skill_md_path = skill_dir / "SKILL.md"
if not skill_md_path.exists():
return {}, {}, {}, {}, ""
raw = read_text(skill_md_path)
fm, body = parse_frontmatter(raw)
frontmatter = {
"name": (fm.get("name") or "").strip(),
"name_valid": bool(fm.get("name") and NAME_RE.match(fm["name"].strip())),
"name_matches_dir": (fm.get("name") or "").strip() == skill_dir.name,
"description": (fm.get("description") or "").strip()[:200],
"description_length": len((fm.get("description") or "").strip()),
"description_valid": 1 <= len((fm.get("description") or "").strip()) <= 1024,
"license": (fm.get("license") or "").strip(),
}
body_lower = body.lower()
body_facts = {
"body_lines": len(body.splitlines()),
"body_chars": len(body),
"has_chinese": has_chinese(body),
"has_workflow_steps": bool(WORKFLOW_STEP_RE.search(body)),
"step_count": len(WORKFLOW_STEP_RE.findall(body)),
"has_rules_section": bool(
"## rules" in body_lower
or "## writing rules" in body_lower
or re.search(r'(?:^|\n)##\s+.*[Rr]ules', body) is not None
),
"has_gotchas_section": "## gotchas" in body_lower,
"has_validation": bool(
re.search(r'(?:validation|校验|自检|checklist|verify|验证)', body_lower)
),
"has_boundary": bool(
"不该用" in body or "不适用" in body
or "should not" in body.lower()
or "not use" in body.lower()
or "do not use" in body.lower()
),
"has_when_to_use": bool("什么时候" in body or "When to" in body),
"has_trigger_hints": bool(re.search(
r'(?:加载|load|when to read|read.*if|打开.+文件|参考.*文件)', body_lower
)),
"has_security_declaration": bool(SECURITY_DECLARATION_RE.search(body)),
"cli_sections_count": len(CLI_SECTION_RE.findall(body)),
"bash_blocks_count": len(re.findall(r'```(?:bash|shell|sh|zsh)', body)),
"tool_reference_count": len(re.findall(
r'(?:dreamina|uvx|npx|pipx|bunx|deno\s+run|go\s+run|curl|wget)\b',
body, re.IGNORECASE
)),
"prompt_keyword_count": len(re.findall(
r'(?:提示词|prompt|word-library|vocabulary|场景|scenario|category|模板|template)',
body, re.IGNORECASE
)),
"gotchas_count": len(re.findall(
r'(?:^|\n)\d+\.\s+\*\*', body
)) + len(re.findall(r'(?:^|\n)\d+\.\s', body)),
}
cli_score = body_facts["bash_blocks_count"] + body_facts["tool_reference_count"]
if cli_score >= 3:
body_facts["skill_type"] = "cli"
elif body_facts["prompt_keyword_count"] >= 8:
body_facts["skill_type"] = "prompt"
else:
body_facts["skill_type"] = "doc"
directory = {
"has_scripts": (skill_dir / "scripts").exists(),
"scripts_files": count_files(skill_dir / "scripts"),
"has_references": (skill_dir / "references").exists(),
"references_files": count_files(skill_dir / "references"),
"references_subdirs": count_subdirs(skill_dir / "references"),
"has_examples": (skill_dir / "examples").exists(),
"examples_files": count_files(skill_dir / "examples"),
"has_license_file": (skill_dir / "LICENSE.txt").exists(),
"ref_names": list_ref_names(skill_dir / "references"),
}
safety = {
"secrets_detected": False,
"secret_findings": [],
"has_interactive_patterns": [],
}
for p in skill_dir.rglob("*"):
if p.is_dir():
continue
if p.suffix.lower() not in {".md", ".txt", ".json", ".yaml", ".yml", ".py", ".sh"}:
continue
try:
text = read_text(p)
except Exception:
continue
m = SECRET_RE.search(text)
if m:
safety["secrets_detected"] = True
safety["secret_findings"].append(f"{p.relative_to(skill_dir)}: {m.group(0)[:60]}")
if "input(" in text or "read -p" in text:
safety["has_interactive_patterns"].append(
f"{p.relative_to(skill_dir)}: may require interactive input"
)
return frontmatter, body_facts, directory, safety, body
# ══════════════════════════════════════════════════════════════════
# Base score formulas — one function per sub-item.
# Each returns a SubItemScore with base in [1.0, 5.0] and the
# formula string explaining how the score was computed.
# ══════════════════════════════════════════════════════════════════
def _clamp(v: float) -> float:
return round(max(1.0, min(5.0, v)), 1)
# ── T · Trust ──
def score_T1(fm, body, directory, safety) -> SubItemScore:
s = safety["secrets_detected"]
ss = safety.get("secret_findings", [])
hs = directory["has_scripts"]
sd = body["has_security_declaration"]
base = 4.5
if s:
base = max(2.0, 3.5 - 0.5 * len(ss))
else:
base = 4.5
if not hs:
base += 0.3
else:
base -= 0.3
if sd:
base += 0.2
return SubItemScore(
base=_clamp(base),
formula=f"4.5 + (no_scripts:{not hs} ? +0.3 : -0.3) + (secdecl:{sd} ? +0.2 : 0) - (secrets_detected:{s} ? -1.0 : 0)",
evidence={"secrets_detected": s, "has_scripts": hs, "has_security_declaration": sd},
)
def score_T2(fm, body, directory, safety) -> SubItemScore:
hc = body["has_chinese"]
bl = body["body_lines"]
base = 5.0 if hc else 2.0
return SubItemScore(
base=_clamp(base),
formula=f"has_chinese={hc} → {base}",
evidence={"has_chinese": hc},
)
def score_T3(fm, body, directory, safety) -> SubItemScore:
hb = body["has_boundary"]
hw = body["has_when_to_use"]
base = 4.5 if hb else 3.0
if hb and hw:
base += 0.3
return SubItemScore(
base=_clamp(base),
formula=f"boundary={hb}(+0.3) + when_to_use={hw}(+0.3) off 4.5 base → {base}",
evidence={"has_boundary": hb, "has_when_to_use": hw},
)
def score_T4(fm, body, directory, safety) -> SubItemScore:
hs = directory["has_scripts"]
sd = body["has_security_declaration"]
base = 4.5
if sd:
base += 0.5
if hs:
base -= 0.2
return SubItemScore(
base=_clamp(base),
formula=f"4.5 + (secdecl:{sd} ? +0.5 : 0) - (has_scripts:{hs} ? -0.2 : 0)",
evidence={"has_security_declaration": sd, "has_scripts": hs},
)
# ── R · Reliability ──
def score_R1(fm, body, directory, safety) -> SubItemScore:
hg = body["has_gotchas_section"]
hv = body["has_validation"]
base = 4.0 if hg else 3.0
if hg and hv:
base += 0.5
return SubItemScore(
base=_clamp(base),
formula=f"gotchas={hg}→4.0 + (validation:{hv} ? +0.5)",
evidence={"has_gotchas_section": hg, "has_validation": hv},
)
def score_R2(fm, body, directory, safety) -> SubItemScore:
hw = body["has_workflow_steps"]
sc = body["step_count"]
cs = body["cli_sections_count"]
ex = directory["examples_files"]
st = body["skill_type"]
base = 4.5 if hw else (4.0 if cs >= 3 else 3.5)
if sc >= 5 or ex >= 10:
base += 0.3
return SubItemScore(
base=_clamp(base),
formula=f"WF={hw}({sc}steps) CLI={cs} exs={ex} type={st} → {base}",
evidence={"has_workflow_steps": hw, "step_count": sc, "cli_sections_count": cs, "examples_files": ex},
)
def score_R3(fm, body, directory, safety) -> SubItemScore:
hg = body["has_gotchas_section"]
hr = body["has_rules_section"]
hv = body["has_validation"]
base = 4.0
if hg or hr:
base += 0.3
if hv:
base += 0.2
return SubItemScore(
base=_clamp(base),
formula=f"gotchas={hg} rules={hr} validation={hv} → {base}",
evidence={"has_gotchas_section": hg, "has_rules_section": hr, "has_validation": hv},
)
def score_R4(fm, body, directory, safety) -> SubItemScore:
hb = body["has_boundary"]
base = 4.5 if hb else 3.5
return SubItemScore(
base=_clamp(base),
formula=f"boundary={hb} → {base}",
evidence={"has_boundary": hb},
)
# ── A · Adaptability ──
def score_A1(fm, body, directory, safety) -> SubItemScore:
hb = body["has_boundary"]
hw = body["has_when_to_use"]
base = 4.5 if (hb and hw) else 4.0
return SubItemScore(
base=_clamp(base),
formula=f"boundary={hb} + when_to_use={hw} → {base}",
evidence={"has_boundary": hb, "has_when_to_use": hw},
)
def score_A2(fm, body, directory, safety) -> SubItemScore:
dl = fm["description_length"]
dv = fm["description_valid"]
base = 5.0 if dl >= 100 else (4.5 if dl >= 50 else 3.5)
if not dv:
base = min(base, 3.0)
return SubItemScore(
base=_clamp(base),
formula=f"description_length={dl} valid={dv} → {base}",
evidence={"description_length": dl, "description_valid": dv},
)
def score_A3(fm, body, directory, safety) -> SubItemScore:
hc = body["has_chinese"]
bl = body["body_lines"]
base = 4.0
if hc:
base += 0.3
return SubItemScore(
base=_clamp(base),
formula=f"chinese={hc} → {base}",
evidence={"has_chinese": hc},
)
def score_A4(fm, body, directory, safety) -> SubItemScore:
ex = directory["examples_files"]
rf = directory["references_files"]
st = body["skill_type"]
base = 4.5 if (ex >= 10 or st == "cli") else 4.0
return SubItemScore(
base=_clamp(base),
formula=f"type={st} exs={ex} refs={rf} → {base}",
evidence={"skill_type": st, "examples_files": ex, "references_files": rf},
)
# ── C · Convention ──
def score_C1(fm, body, directory, safety) -> SubItemScore:
ex = directory["examples_files"]
st = body["skill_type"]
threshold = 4 if st == "cli" else 10
base = 5.0 if ex >= threshold else (4.5 if ex >= 3 else 3.5)
return SubItemScore(
base=_clamp(base),
formula=f"type={st} exs={ex}>={threshold} → {base}",
evidence={"skill_type": st, "examples_files": ex},
)
def score_C2(fm, body, directory, safety) -> SubItemScore:
rf = directory["references_files"]
bl = body["body_lines"]
th = body["has_trigger_hints"]
st = body["skill_type"]
base = 4.0
body_threshold = 150 if st == "cli" else 200
if rf >= 8 and bl < body_threshold:
base = 5.0
elif rf >= 3 and bl < 350:
base = 4.5
elif rf > 0:
base = 4.0
else:
base = 3.0
if th and rf > 0:
base += 0.2
return SubItemScore(
base=_clamp(base),
formula=f"type={st} refs={rf} body={bl} trigger_hints={th} → {base}",
evidence={"references_files": rf, "body_lines": bl, "has_trigger_hints": th},
)
def score_C3(fm, body, directory, safety) -> SubItemScore:
nv = fm["name_valid"]
nm = fm["name_matches_dir"]
rs = directory["references_subdirs"]
base = 4.5
if nv and nm:
base += 0.2
if rs >= 2:
base += 0.3
return SubItemScore(
base=_clamp(base),
formula=f"name_valid={nv} name_matches={nm} ref_subdirs={rs} → {base}",
evidence={"name_valid": nv, "name_matches_dir": nm, "references_subdirs": rs},
)
def score_C4(fm, body, directory, safety) -> SubItemScore:
hg = body["has_gotchas_section"]
gc = body.get("gotchas_count", 0)
base = 4.5 if hg else 3.5
if gc >= 5:
base += 0.3
return SubItemScore(
base=_clamp(base),
formula=f"gotchas_section={hg} gotchas_count≈{gc} → {base}",
evidence={"has_gotchas_section": hg, "gotchas_count_approx": gc},
)
# ── E · Effectiveness ──
def score_E1(fm, body, directory, safety) -> SubItemScore:
hw = body["has_workflow_steps"]
hv = body["has_validation"]
st = body["skill_type"]
base = 4.5 if hw else 4.0
if hv:
base += 0.3
return SubItemScore(
base=_clamp(base),
formula=f"type={st} WF={hw} validation={hv} → {base}",
evidence={"skill_type": st, "has_workflow_steps": hw, "has_validation": hv},
)
def score_E2(fm, body, directory, safety) -> SubItemScore:
ex = directory["examples_files"]
st = body["skill_type"]
thresholds = {"prompt": 25, "cli": 4, "doc": 5}
t = thresholds.get(st, 5)
base = 5.0 if ex >= t else (4.5 if ex >= 10 else (4.0 if ex >= 3 else 3.0))
return SubItemScore(
base=_clamp(base),
formula=f"type={st} exs={ex}>={t} → {base}",
evidence={"skill_type": st, "examples_files": ex},
)
def score_E3(fm, body, directory, safety) -> SubItemScore:
rs = directory["references_subdirs"]
rf = directory["references_files"]
base = 4.5 if rs >= 2 else 4.0
if rf >= 10:
base += 0.2
return SubItemScore(
base=_clamp(base),
formula=f"ref_subdirs={rs} refs={rf} → {base}",
evidence={"references_subdirs": rs, "references_files": rf},
)
def score_E4(fm, body, directory, safety) -> SubItemScore:
hw = body["has_workflow_steps"]
hv = body["has_validation"]
hg = body["has_gotchas_section"]
cs = body["cli_sections_count"]
base = 4.0
if hw:
base += 0.3
if hv:
base += 0.3
if hg:
base += 0.2
if cs >= 3:
base += 0.2
return SubItemScore(
base=_clamp(base),
formula=f"WF={hw} val={hv} gotchas={hg} cli_secs={cs} → {base}",
evidence={"has_workflow_steps": hw, "has_validation": hv, "has_gotchas_section": hg, "cli_sections_count": cs},
)
# ── Master table ──
SCORE_FUNCTIONS: Dict[str, callable] = {
"T1": score_T1, "T2": score_T2, "T3": score_T3, "T4": score_T4,
"R1": score_R1, "R2": score_R2, "R3": score_R3, "R4": score_R4,
"A1": score_A1, "A2": score_A2, "A3": score_A3, "A4": score_A4,
"C1": score_C1, "C2": score_C2, "C3": score_C3, "C4": score_C4,
"E1": score_E1, "E2": score_E2, "E3": score_E3, "E4": score_E4,
}
def compute_base_scores(fm, body, directory, safety) -> Dict[str, Any]:
dims = {"T": [], "R": [], "A": [], "C": [], "E": []}
for key, fn in SCORE_FUNCTIONS.items():
dim = key[0]
sub = fn(fm, body, directory, safety)
dims[dim].append(sub)
result = {}
for dim, subs in dims.items():
avg = round(sum(s.base for s in subs) / len(subs), 2) if subs else 0.0
result[dim] = {
"avg": avg,
"sub_items": {f"{dim}{i+1}": {"base": subs[i].base, "formula": subs[i].formula, "evidence": subs[i].evidence} for i in range(len(subs))},
}
result["overall"] = round(
sum(result[d]["avg"] for d in ["T", "R", "A", "C", "E"]) / 5.0, 2
)
return result
def main() -> int:
args = parse_args()
skill_dir = Path(args.skill_dir).expanduser().resolve()
fm, body, directory, safety, _ = collect_facts(skill_dir)
if not fm:
return 1
base_scores = compute_base_scores(fm, body, directory, safety)
packet = {
"skill_dir": str(skill_dir),
"skill_name": (fm.get("name") or skill_dir.name).strip(),
"generated_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
"frontmatter": fm,
"body": body,
"directory": directory,
"safety": safety,
"base_scores": base_scores,
}
if args.format == "pretty":
out = json.dumps(packet, ensure_ascii=False, indent=2, default=str)
else:
out = json.dumps(packet, ensure_ascii=False, indent=2, default=str)
if args.output:
out_path = Path(args.output).expanduser().resolve()
out_path.parent.mkdir(parents=True, exist_ok=True)
out_path.write_text(out, encoding="utf-8")
return 0
sys.stdout.write(out)
return 0
if __name__ == "__main__":
raise SystemExit(main())
Related skills
Find SkillsSo their agent can intelligently recommend and install the right modular skills from the open ecosystem when they ask how to do something.3M27.9k
Lark Skill MakerRapidly create custom skills for Lark (Feishu) that can be invoked by their AI agents and automation workflows.513k
Skill CreatorGenerate, test, and iterate on new reusable agent skills directly inside their Claude or Cursor workflow.337k166k
BrainstormingTurn vague product ideas into clear, approved designs and specifications through guided collaborative dialogue before writing any code.307k265k
Writing Great SkillsCreate high-quality, reusable agent skills that other developers can discover and install from the Skillselion catalog.290k200k
Find SkillsInstantly surface the best relevant agent skills, MCP servers, and workflows across multiple registries before starting any new project.226k12Skill Developmentagents