heal-skill

诊断并自动修复损坏的技能。运行 `/heal-skill` 扫描整个库，或运行 `/heal-skill ` 诊断单个技能。按严重程度报告问题并进行健康度评分，同时提供自动修复选项，需经用户确认。

<quick_start>

/heal-skill              → Full library scan (all skills)
/heal-skill <name>       → Single skill diagnosis
/heal-skill --fix        → Apply all auto-fixes (with confirmation)
/heal-skill --fix <name> → Fix single skill (with confirmation)

</quick_start>

<success_criteria>

• 所有 YAML frontmatter 均通过 Anthropic 规范验证
• 所有必需的 XML 章节均存在（<objective>、<quick_start>、<success_criteria>）
• 所有 config.json 文件均使用标准架构，且键正确
• 报告健康度评分：每个技能通过 X/Y 项检查
• 仅在用户确认后应用自动修复（先预览差异）
• 自测通过：/heal-skill heal-skill 报告 0 个问题 </success_criteria>

<core_content>

3 层诊断引擎

引擎按严重程度顺序运行检查。每一层都基于前一层的结果。

Layer 1: STRUCTURAL (CRITICAL)     → Files exist, YAML parses, required fields present
Layer 2: CONTENT (HIGH)            → XML sections, line count, naming conventions
Layer 3: INTEGRATION (MEDIUM)      → config.json schema, duplicate triggers, cross-refs

第 1 层：结构验证（严重）

这些检查用于确认技能是否能够加载。此处的检查失败意味着技能已损坏。

ID	检查项	规则	自动修复
S1	YAML frontmatter 存在	SKILL.md 以 --- 开头	否
S2	存在 name 字段	必填，非空字符串	否
S3	name 格式有效	^[a-z0-9-]+$，最多 64 个字符	是 — 转换为 slug
S4	存在 description 字段	必填，非空字符串	否
S5	description 长度	最多 1024 个字符	是 — 截断
S6	description 不含 XML 标签	值中不得有 <tags>	是 — 移除标签
S7	description 是字符串	不是 YAML 数组/对象	是 — 若为数组则合并
S7b	frontmatter 键有效	所有键都在有效集合中（见下文）	警告
S8	SKILL.md 存在	必须存在于技能目录中	否
S9	config.json 存在	必须存在于技能目录中	是 — 根据 SKILL.md 生成
S10	config.json 是有效 JSON	必须能无错误解析	否

S1-S2 的检测方式： 读取前 5 行；检查 --- 分隔符和 name: 键。 S3 的检测方式： 对 name 值应用正则表达式 ^[a-z0-9-]+$，检查 length <= 64。 S6 的检测方式： 对 description 值应用正则表达式 <[a-z_]+>。 S7 的检测方式： 解析 YAML — 检查类型是否为字符串，而非数组/对象。 S7b 的检测方式： 有效的 frontmatter 键包括：name、description、disable-model-invocation、user-invocable、allowed-tools、model、context、agent、argument-hint、hooks。任何其他键都会触发警告（而非错误 — Claude Code 会忽略未知键，不会拒绝它们）。

第 2 层：内容质量（高）

这些检查用于确认技能符合库的约定，便于发现。

ID	检查项	规则	自动修复
C1	存在 <objective> 章节	必须出现在 SKILL.md 正文中	是 — 添加占位内容
C2	存在 <quick_start> 章节	必须出现在 SKILL.md 正文中	是 — 添加占位内容
C3	存在 <success_criteria> 章节	必须出现在 SKILL.md 正文中	是 — 添加占位内容
C4	行数	正文 ≤ 500 行（仅警告）	警告
C5	失效的引用链接	内部 reference/ 链接必须有效	是 — 移除失效链接
C6	命名约定	目录名以 -skill 结尾	警告

C1-C3 的检测方式： 在 SKILL.md 正文（frontmatter 之后）中搜索 <objective>、<quick_start>、<success_criteria>。 C4 的检测方式： wc -l SKILL.md。 C5 的检测方式： 从 [text](reference/...) 链接中提取路径，并验证文件是否存在。 C6 的检测方式： 检查目录名是否以 -skill 结尾。

### 第 3 层：集成健康度（中）

这些检查用于验证库内的一致性。

ID	检查项	规则	自动修复
I1	config.json 包含标准键	必须包含 name、version、category	是 — 添加缺失项
I2	使用 activation_triggers 键	不能使用 triggers（旧名称）	是 — 重命名键
I3	使用 depends_on 键	不能使用 dependencies（旧名称）	是 — 重命名键
I4	包含 version 字段	必须包含字符串类型的 version	是 — 添加 "1.0.0"
I5	激活触发条件不重复	不同技能之间不能有触发条件冲突	警告

I2 的检测方式： 检查 config.json 是否使用了键 triggers，而不是 activation_triggers。 I3 的检测方式： 检查 config.json 是否使用了键 dependencies，而不是 depends_on。

---

诊断流程

1. DISCOVER
   - Scan active/ and stable/ directories
   - Build skill inventory (name, path, has SKILL.md, has config.json)

2. LAYER 1 — STRUCTURAL
   - For each skill: parse YAML frontmatter, validate fields
   - STOP on critical failures (no SKILL.md = skip remaining checks)

3. LAYER 2 — CONTENT
   - For each skill: search for XML sections, check line count
   - Check naming convention

4. LAYER 3 — INTEGRATION
   - For each skill: validate config.json schema
   - Cross-skill: check for duplicate triggers

5. REPORT
   - Generate health report grouped by severity
   - Calculate health score
   - List available auto-fixes

---

输出格式

请严格按以下格式生成报告：

SKILL HEALTH REPORT
════════════════════════════════════════════════
Scanned: X skills | Health Score: Y/Z (N%)

CRITICAL (n):
  ✗ skill-name: Description of issue [CHECK-ID]

HIGH (n):
  ⚠ skill-name: Description of issue [CHECK-ID]

MEDIUM (n):
  ℹ skill-name: Description of issue [CHECK-ID]

WARNINGS (n):
  ~ skill-name: Description of advisory [CHECK-ID]

════════════════════════════════════════════════
AUTO-FIX AVAILABLE: N issues can be auto-fixed
  Run /heal-skill --fix to preview and apply

单技能模式 — 格式相同，但仅针对一个技能。

严重级别定义：

• 严重： 技能无法加载或激活（S1-S10 失败）
• 高： 技能已加载，但缺少预期章节（C1-C3）
• 中： 影响库工具的一致性问题（I1-I5）
• 警告： 仅供参考，无需采取行动（C4、C6）

---

自动修复协议

指定 --fix 时，请严格遵循以下协议：

1. PREVIEW
   - Show each proposed change as a diff:
     ```
     FIX: skill-name — [CHECK-ID] Description
     --- before
     +++ after
     @@ change description @@
     -old content
     +new content
     ```

2. CONFIRM
   - Ask user: "Apply N fixes? (yes/no/select)"
   - "select" lets user pick individual fixes

3. APPLY
   - Make changes to files
   - Re-run affected checks to verify fix worked

4. RE-VALIDATE
   - Run full scan on fixed skills
   - Report new health score

各检查项的自动修复策略：

检查项	修复策略
S3	转换为 slug：转为小写，并将空格／特殊字符替换为连字符
S5	在最后一个句子边界处截断至 1024 个字符
S6	使用正则表达式剥离 XML 标签：</?[a-z_]+> → 空字符串
S7	如果是数组：用 ". " 连接各元素。如果是对象：使用第一个值
S9	根据 SKILL.md frontmatter 生成最简 config.json
C1	在 frontmatter 后添加 <objective>\nTODO: Add objective\n</objective>
C2	在 objective 后添加 <quick_start>\nTODO: Add quick start\n</quick_start>
C3	在 quick_start 后添加 <success_criteria>\nTODO: Add success criteria\n</success_criteria>
C5	移除失效的 [text](reference/...) 链接
I1	使用 SKILL.md frontmatter 中的默认值添加缺失的键
I2	在 config.json 中将 triggers 重命名为 activation_triggers
I3	在 config.json 中将 dependencies 重命名为 depends_on
I4	在 config.json 中添加 "version": "1.0.0"

---

已知问题模式

这些模式来自真实的 GitHub 问题和库审计。诊断引擎会检查所有这些模式。

来源	模式	检查项
GitHub #9817	--- 前的空格会导致 YAML 解析失败	S1
GitHub #11322	Prettier 将 description 重新格式化为多行	S7
GitHub #17604	description 中的 YAML 数组会导致斜杠命令崩溃	S7
GitHub #6377	YAML 结构有效，但缺少 name 字段	S2
GitHub #14882	技能消耗全部 token（没有渐进式披露）	C4
GitHub #14577	/skills 显示 "No skills found" — frontmatter 解析失败	S1、S2
库审计	8 个技能缺少 XML 章节	C1-C3
库审计	9 个技能使用旧版 config.json 键	I2、I3
库审计	1 个技能缺少 -skill 后缀	C6

</core_content>

<common_mistakes>

常见问题

错误	修复方法
未查看差异就运行 --fix	始终先预览。协议要求先确认。
忽略警告	警告仅供参考，但表明存在技术债务。请跟踪记录。
只修复严重问题	高级别和中级别问题会影响可发现性和工具功能。请修复所有层级的问题。
添加 XML 存根但不填写内容	存根只是占位符。请安排时间编写实际内容。
库中存在全局问题时，仅对单个技能运行 heal	请先运行完整扫描，了解全局情况。

写入结果附属文件

作为最后一步，写入 ~/.claude/skill-analytics/last-outcome-heal-skill.json：

{"ts":"[UTC ISO8601]","skill":"heal-skill","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"skills_scanned":[n],"issues_found":[n],"fixes_applied":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

如果部分阶段失败，但已生成结果，请使用状态 "partial"。只有在未生成任何输出时，才使用 "error"。

</common_mistakes>