技能自检 · 边做边质检（SkillHub TRACE 风格）
把 SkillHub 官方 evaluation 那套 5 维度 × 子项 评分框架，拿来评审我们自己写的 skill，
产出一份带分值、理由和「缺漏清单」的报告，方便迭代改进。
概述
离线、零依赖的 skill 质量评审器：对齐 SkillHub 官方 evaluation 的 5 维度框架，对自己写的 skill 跑结构检查 + 人工语义评估，产出带分值 / 理由 / 缺漏清单的 HTML 报告。无需 LLM 端点、无需 API Key、无需联网。使用方法见下方工作流程（Step 1–5）。
何时使用（触发条件）
满足以下任一即触发本 skill：
- 刚写完一个 skill、达到"能用"程度，想看看哪里还缺、怎么补。
- 改完 skill 后做回归体检（"评估一下""评分""质量审查""查漏补缺""review skill"）。
- 想横向比较多个自有 skill 的质量（批量扫描 + 雷达 / 排名）。
- 定期给自有 skill 做质量体检。
评分框架（详细口径见 references/rating-framework.md）
| 维度 | 子项 | 谁来评 |
|---|---|---|
| 适配性 adaptability | boundary 能力边界 / trigger 触发清晰度 | 结构启发式 |
| 规范性 convention | antiPatternFaq 反模式FAQ / docQuality 文档质量 / progressive 渐进式 / structure 结构 | 结构启发式 |
| 有效性 effectiveness | accuracy 准确性 / creativity 创造性 / completeness 完整性 / usability 可用性（语义级） | 评审员（你） |
| 可靠性 reliability | errorHandling 错误处理 / func 功能完备 / stability 稳定性 | 结构启发式（双路径） |
| 可信度 trust | domestic 国产合规 / scan 安全扫描（按官方 TRACE 固定 skipped，不评分） | 结构启发式 |
满分 5，每维度取子项均值，overall 取维度均值。
工作流程
> 关键约定：所有路径用 Windows 风格（C:/... 或 C:\...），原生 Python 不认 /c/...。
> 不需要联网、不需要 LLM 端点、不需要 API Key。
> 跨设备分享：脚本纯标准库、零依赖，整目录拷到目标机的 ~/.workbuddy/skills/skill-quality-reviewer/ 即可。
> 解析 Python 解释器（按优先级，自动适配不同机器）：
> 1. 托管 Python：%USERPROFILE%/.workbuddy/binaries/python/versions/<最新版本>/python.exe
> （若该确切版本路径不存在，列 versions/ 目录取其一即可）
> 2. 兜底：直接用 PATH 里的 python / python3（脚本只用到标准库，普通 Python 3 即可）。
Step 1 — 确定目标
用户给 skill 路径/名字，或默认扫描用户级 skills 父目录：
%USERPROFILE%/.workbuddy/skills（脚本实际用 ~/.workbuddy/skills 自动展开当前用户，无需手改用户名）
（也可直接传单个 skill 目录或项目级 .../.workbuddy/skills/<name>，脚本两种都支持）
Step 2 — 跑结构检查（语义子项先标「待评」）
SET PY=%USERPROFILE%/.workbuddy/binaries/python/versions/3.13.12/python.exe
SET SK=%USERPROFILE%/.workbuddy/skills/skill-quality-reviewer/scripts/skill_quality_struct.py
"%PY%" "%SK%" --skill-dir "<目标目录>" --json struct.json --html review.html
> 若上面的 PY 路径不存在（版本号不同或没装托管 Python），改成 SET PY=python（用 PATH 里的 Python 3）。
这一步自动算出所有结构子项的分，语义子项先用启发式占位并标黄「待评」。
Step 3 — 评审员亲自做语义评估（本 skill 的核心价值）
读目标 skill 的 SKILL.md 全文 + references/（若有），对照 5 个语义子项口径
（references/rating-framework.md），给出你自己的真实判断，写入 semantic_review.json：
{
"<skillId>": {
"accuracy": {"score": 4.5, "reason": "中文：核心逻辑是否准确、有无误导", "userReason": "用户视角一句话"},
"creativity": {"score": 4.3, "reason": "...", "userReason": "..."},
"completeness": {"score": 4.2, "reason": "...", "userReason": "..."},
"usability": {"score": 4.6, "reason": "...", "userReason": "..."},
"docQuality": {"score": 4.4, "reason": "...", "userReason": "..."}
}
}
score 为 0~5（允许 .5），不要送分——只有 skill 真展现该质量才给高分；reason 写评审视角的具体依据，userReason 写用户视角一句话。
不要照搬 Step 2 的启发式占位分，那是结构近似，语义要靠你真读。
Step 4 — 合并出终稿
"%PY%" "%SK%" --skill-dir "<目标目录>" --semantic semantic_review.json ^
--official "ezr-data-source:%USERPROFILE%/.workbuddy/skills/skill-quality-reviewer/references/evaluation_ezr.json" ^
--json final.json --html review.html
--official仅在评估 ezr-data-source 时加（自带官方真值 4.67 作对照验证）；其他 skill 省略。- 合并后语义子项标绿「已评」，结构子项标蓝「启发」，报告即最终版。
Step 5 — 交付
present_files打开review.html给用户看。- 文字给出缺漏清单：列出所有
<4.0的子项，按维度归类，并针对每个短板给一句改进建议
（例如「trigger 仅 3.0：缺显式『何时使用』章节，建议补## 何时使用+ 命令示例」）。 - 清理中间产物
struct.json、semantic_review.json、review_struct.html（可选）。
进阶用法
- 批量评审多个 skill：直接传父目录（如
%USERPROFILE%/.workbuddy/skills），脚本逐个扫描，
并在报告顶部生成「维度雷达（多 skill 叠加）」+「横向排名（按综合分）」，一眼看出谁强谁弱。 - 对照官方真值：仅评
ezr-data-source时加--official "ezr-data-source:<path>/evaluation_ezr.json"，
报告并排显示本地分 vs 官方分（官方 4.67），验证评分对齐度；评其它 skill 省略即可，官方数据不污染。 - 只评一个 skill：
--skill-dir <单个 skill 目录>同样支持（支持项目级.../.workbuddy/skills/<name>）。
备注
- 本工具是对 SkillHub 官方 TRACE 评测（5 维度 × 15 子项）的同构复刻：维度与子项结构 1:1 一致，
结构子项用本地启发式，语义子项由评审员本人评估（等价于官方用 LLM 评的那部分），因此完全离线、零配置。 - JSON 官方兼容：输出 JSON 与 SkillHub 官方 TRACE schema 完全一致（5 维齐全、每维度含
reason/userReason、
根级含summary/userSummary、trust.scan固定status:"skipped"）。自带校验器scripts/validate_trace_schema.py
（由官方 validator 收编而来）可直接校验产出：python scripts/validate_trace_schema.py review.json→OK。 - 安全扫描口径：
trust.scan按官方约定固定跳过、不评分；本地静态粗判结论仅写入该项的reason/userReason
供参考。重要修复：静态检查现在只扫真实代码（围栏代码块 +scripts/下脚本），不再扫 markdown 正文，
因此文档里举例提到subprocess/os.system等字样不再被误判为风险（此前 windows-tray-startup 因此被错扣）。 - 零依赖：纯标准库实现，无需
pip install任何包；没装托管 Python 时SET PY=python用系统 Python 3 即可。 - 原子写：报告 JSON/HTML 先写
.tmp再os.replace落盘，中断也不会留半截文件；读目标文件失败会跳过并提示，不中断整批扫描。 - 错误处理：找不到任何 SKILL.md 会提示并以退出码 1 结束；读单个目标文件失败自动跳过并提示，不中断整批扫描；官方 / evaluation 文件解析失败静默跳过。报错均给出原因与排查方向。
references/evaluation_ezr.json是 ezr-data-source 的官方 evaluation 真值，仅供对照、不污染其它 skill。- 可靠性双路径评分（关键设计）：
reliability维度不再对所有技能套同一套信号。脚本先判定技能类型—— - 在线/有状态类（会真正联网或调外部服务，
net或overseas_risky命中）：仍用timeout/retry/atomic这类信号评估稳定性、struct_err/exit_code评估错误处理（原逻辑）。 - 离线/文档型（无网络请求）：改用另一条口径——
stability看幂等可重跑 / 中断可续 / 步骤可复现，errorHandling看故障排查文档 / 退出码 / 依赖提示。这样文档型技能不会因为"没有网络重试"这种它本不需要的东西被不公平扣分。 - 两类都仍奖励真实存在的工程化设计（如原子写
os.replace、语义化退出码）。 - 判定信号：
rerun_safe（重新/重跑/幂等/中断/半截/可复现等）、troubleshoot（排查/兜底/故障/异常处理/失败应对/排错等），由collect_signals采集。
