用途
Skill Health Check 用于校验技能（skill）的质量，围绕路由（routing）、渐进式加载（progressive loading）和验证（verification）标准进行审计。其核心理念是：技能是按需加载的上下文包，价值来自路由精度（在正确时机触发正确的技能）和上下文效率（用最少 token 实现最大能力）。路由不佳的技能会在每次不匹配时浪费上下文；路由良好的技能则能在恰当时机把通才转变为专才。
触发方式
关键词：skill health、skill audit、skill lint、check skills、skill quality、validate skills。
不适用场景：
- 代码审查（使用 /codex-review-fast）
- 文档审查（使用 /codex-review-doc）
- 创建新技能（使用 skill-creator 插件，外部）
- .claude 目录结构检查（使用 /claude-health）
工作流程
流程为：运行自动化 lint → 人工评审维度 → 生成整合报告 → Gate。
第一步：自动化 Lint
运行命令：
node skills/skill-health-check/scripts/skill-lint.js --fix-hint
脚本 I/O 契约参数：
| 参数 | 说明 |
|---|---|
| --skills-dir <path> | 技能目录（默认：./skills） |
| --agents-dir <path> | Agent 目录（默认：./agents） |
| --json | 输出 JSON 而非 markdown |
| --fix-hint | 包含修复建议 |
退出码：
- Exit 0：全部通过
- Exit 1：仅有警告（P2）
- Exit 2：发现错误（P0/P1）
单技能检查（11 项）：
| # | 检查项 | 严重级别 | 标准 |
|---|---|---|---|
| 1 | Frontmatter 存在 | P0 | 需要 name + description |
| 2 | 路由签名 | P1 | 描述中至少包含 3 个路由线索（Use/Avoid/Output）中的 2 个；0 个线索 = P1，1 个线索 = P2 |
| 3 | When NOT 章节 | P1 | 正文包含 "When NOT to Use" 标题 |
| 4 | Output 章节 | P2 | 正文定义预期交付物 |
| 5 | Verification 章节 | P2 | 正文包含验证清单 |
| 6 | 引用路由 | P2 | 每个引用文件都在正文中被提及 |
| 7 | 脚本契约 | P2 | 每个脚本文件名都在 SKILL.md 正文中被引用 |
| 8 | 行数 | P2 | 超过 150 行警告，超过 250 行标记 |
| 9 | Agent 权限 | P2 | 正文描述 Agent() 调度但 allowed-tools 缺少 Agent |
| 10 | Task 权限 | P2 | 正文描述 Task() 调度但 allowed-tools 缺少 Task |
| 11 | 跨技能引用路径 | P1 | 本地找不到的裸引用路径但存在于其他技能中 → 必须使用 @skills/<parent>/ 前缀 |
跨技能检查（3 项）：
| # | 检查项 | 严重级别 | 标准 |
|---|---|---|---|
| 12 | 描述重叠 | P2 | Jaccard 相似度 >60% 被标记 |
| 13 | Agent 引用有效性 | P1 | 技能中的 subagent_type 引用必须存在于 agents/ 中 |
| 14 | Agent 工具语法 | P2 | Agent .md 的 tools 字段使用规范格式（ToolName 或 Bash(<prefix>:*)） |
第二步：人工评审（仅在要求全面审计时）
阅读被标记的技能并评估：
| 维度 | 问题 | 评分 |
|---|---|---|
| Why > What | 技能是否解释底层原理，而不仅是步骤？ | ⭐1-5 |
| 范围适配 | 技能是否聚焦？能否拆分？ | ⭐1-5 |
| 渐进式加载 | 重内容是否放在 references/ 而非内联？ | ⭐1-5 |
| 路由精度 | 用户的请求是否会无歧义地触发此技能？ | ⭐1-5 |
仅在用户明确要求深度审计时运行第二步。默认：仅第一步。
输出
输出为 Skill Health Check Report，包含：
- Summary 表格：扫描技能数、通过检查数、P0（必须修复）、P1（应当修复）、P2（建议）数量
- Per-Skill Results 表格：列出每个技能的 Routing、When-NOT、Output、Verification、Refs、AgEnt、TskEnt、Lines、Status 等列
- P0（必须修复）：技能名 → 问题 → 修复建议
- P1（应当修复）：技能名 → 问题 → 修复建议
- P2（建议）：技能名 → 问题 → 修复建议
- Gate：✅ 全部通过 / ⛔ N 个问题需要修复
验证
- 已执行自动化 lint（检查退出码）
- 所有 P0/P1 发现都有修复建议
- 每技能表格包含所有被扫描的技能
- 存在 Gate 哨兵供 hook 解析
参考
references/routing-signature-guide.md — 如何编写有效的路由签名（修复 P1 路由问题时阅读）
示例
- 输入：/skill-health-check → 运行 skill-lint.js → 输出 markdown 报告 + Gate
- 输入：/skill-health-check --deep → 运行 skill-lint.js → 人工评审被标记技能 → 整合报告
- 输入：Are my skills well-designed? → 触发健康检查 → 报告 + 改进建议