skill-review

name

skill-review

description

Review, audit, and improve an Agent Skill for spec compliance, design quality, expression quality, and eval readiness. Use when reviewing a skill directory, checking a SKILL.md file, auditing references or scripts, diagnosing why a skill triggers poorly, or evaluating whether a skill is ready to deploy — even if the user doesn't explicitly say "skill review." Do NOT use for reviewing agents (use agent-review instead).

Skill Review

Purpose: 审查 skill 目录，发现 spec 违规、设计缺陷和证据质量问题。 Input: Skill 目录路径（用户提供）。 Output: 填好的 scaffold Markdown 文件 + 可选 html-serve HTML artifact。 Scope: SKILL.md + references/**/*.md + scripts/* + assets/**。references 在运行时被 agent 增量加载，等同 SKILL.md 的延伸指令，必须同步审查。

CLI

omp skill-review check --skill-dir <path>
omp skill-review emit-checklist --skill-dir <path> --output /tmp/review-<skill>.md
omp skill-review validate /tmp/review-<skill>.md
omp skill-review render-html /tmp/review-<skill>.md

Command	Purpose
check	运行机械一致性检查，输出 JSON。
emit-checklist	生成必须逐条填写的 Markdown scaffold。
validate	拒绝未填写 checkbox、占位符或缺少 finding 子项的报告。
render-html	将已填写 Markdown 报告渲染为 Minimal Review HTML artifact；发布时再调用 omp html-serve publish。

前置检查

如果用户未提供路径，询问：

请提供要审查的 skill 目录路径，例如：skills/my-skill

确认 SKILL.md 存在。不存在则停止并报告。

工作流

flowchart TD
    A([输入: skill-dir]) --> B[Step 1: emit-checklist 生成 scaffold]
    B --> C[Step 2: 加载 rubric.md 逐条填写 scaffold]
    C --> D[Step 3: validate 检查完整性]
    D -->|失败| C
    D -->|通过| E[Step 4: 生成并发布 HTML artifact]
    E --> F[Step 5: 输出 Markdown 报告与 HTML URL]
    F --> G([完成])

Step 1：生成 scaffold

omp skill-review emit-checklist --skill-dir <path> --output /tmp/review-<skill>.md

scaffold 包含：审查头信息、机械检查 JSON、按 13 个维度展开的 checklist。每条 checkbox 默认 [ ] 加 __STATE__ / __EVIDENCE__ 占位符。

不重新发明机械检查，不跳过此步。

Done when: 输出文件已生成，且包含「机械检查 JSON」与 13 个维度章节。

Step 2：填写 scaffold

加载 references/rubric.md，对照 scaffold 的每条 checkbox 逐一填写：

• 状态：[✓] 通过 / [✗] 违规 / [—] 不适用
• 证据：替换 __EVIDENCE__，引用文件原文、机械检查 JSON 字段或文件状态
• 维度判定：替换章节标题里的 __STATE__ 为 PASS / FINDING / N/A
• [✗] 行展开：必须紧跟 4 个子项
  • 标签：SPEC / BEST_PRACTICE / PROJECT_POLICY（可多选）
  • 影响：一句话说明对执行、触发或输出的影响
  • 修复：具体替换文本或操作步骤
  • 验证：复跑命令或检查文件状态

按需加载（发现 FINDING 时）：

维度	加载文件
B1	references/how-to-optimize-skill-descriptions.md
B2 / B3	references/agent-skills-best-practices.md
B5	references/how-to-use-scripts-in-skills.md

Done when: scaffold 中每条 checkbox 都已改为 [✓] / [✗] / [—]，且每条 finding 都附带证据。

Step 3：验证完整性

omp skill-review validate /tmp/review-<skill>.md

退出非零 → 按报错行号补全 → 重跑直到退出 0。

Done when: omp skill-review validate /tmp/review-<skill>.md 退出 0。

Step 4：生成并发布 HTML artifact

运行：

omp skill-review render-html /tmp/review-<skill>.md --output /tmp/review-<skill>.html
omp html-serve publish /tmp/review-<skill>.html --to oh-my-superpowers/skill-review/review-<skill>.html --source skill-review --tag skill-review --tag <skill>

第一条命令先校验报告完整性，再把已填写报告渲染成 Minimal Review HTML artifact；第二条命令发布到 html-serve 并返回 localhost_url 与 tailscale_url。Markdown 仍是事实来源；HTML 是便于分享和扫描 findings 的增强视图。

如果 omp html-serve publish 因 HTML_SERVE_DATA_DIR 未配置失败，只交付本地 HTML 文件，并在最终交付中说明 HTML 未发布 URL。

Done when: render-html 输出 html_path；如发布成功，omp html-serve publish 输出 localhost_url 与 tailscale_url。

Step 5：输出报告

交付通过 validate 的 Markdown 报告，并附上 HTML artifact 路径；如发布成功，同时附上 localhost_url 与 tailscale_url。

Done when: 已交付 Markdown 报告、HTML artifact 信息，且报告中不再包含未填写 checkbox 或占位符。

失败处理

• omp skill-review emit-checklist 失败 → 报告错误原文并停止
• references/rubric.md 无法读取 → 停止并报告
• omp skill-review validate 失败 → 回到 Step 2 补全，不得跳过
• omp skill-review render-html 校验失败 → 回到 Step 2 补全报告，不得发布 HTML
• omp html-serve publish 失败 → 若缺少 HTML_SERVE_DATA_DIR，交付本地 HTML；其他错误报告原文并停止

Guardrails

• 禁止跳过 emit-checklist 或 validate 任一步
• 禁止以维度级别 PASS 替代逐条 checkbox 填写
• 禁止保留 [ ]、__STATE__、__EVIDENCE__、{{...}} 占位符
• 禁止无证据的 finding：每条 finding 必须引用文件原文、文件状态或机械检查 JSON
• 禁止把项目偏好标记为 SPEC 违规，标签必须准确
• 禁止把多个独立问题合并为一条 finding
• 禁止把 HTML artifact 当作事实来源；Markdown 报告始终是 source of truth