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>

• All YAML frontmatter validates against Anthropic spec
• All required XML sections present (<objective>, <quick_start>, <success_criteria>)
• All config.json files use standard schema with correct keys
• Health score reported: X/Y checks passing per skill
• Auto-fixes applied ONLY with user confirmation (preview diff first)
• Self-test passes: /heal-skill heal-skill reports 0 issues </success_criteria>

<core_content>

3-Layer Diagnostic Engine

The engine runs checks in order of severity. Each layer builds on the previous.

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

Layer 1: Structural Validation (CRITICAL)

These checks verify the skill can even load. Failures here mean the skill is broken.

Detection for S1-S2: Read first 5 lines; check --- delimiter and name: key. Detection for S3: Regex ^[a-z0-9-]+$ on name value, check length <= 64. Detection for S6: Regex <[a-z_]+> in description value. Detection for S7: YAML parse — check type is string, not array/object.

Layer 2: Content Quality (HIGH)

These checks verify the skill follows library conventions for discoverability.

Detection for C1-C3: Search SKILL.md body (after frontmatter) for <objective>, <quick_start>, <success_criteria>. Detection for C4: wc -l SKILL.md. Detection for C5: Extract paths from [text](reference/...) links, verify file exists. Detection for C6: Check directory name ends with -skill.

Layer 3: Integration Health (MEDIUM)

These checks verify consistency across the library.

Detection for I2: Check if config.json has key triggers instead of activation_triggers. Detection for I3: Check if config.json has key dependencies instead of depends_on.

Diagnostic Flow

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

Output Format

Generate the report in this exact format:

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

Single skill mode — same format but for one skill only.

Severity definitions:

• CRITICAL: Skill cannot load or activate (S1-S10 failures)
• HIGH: Skill loads but missing expected sections (C1-C3)
• MEDIUM: Schema inconsistencies that affect library tooling (I1-I5)
• WARNING: Advisory only, no action required (C4, C6)

Auto-Fix Protocol

When --fix is specified, follow this exact protocol:

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

Auto-fix strategies by check:

Known Issue Patterns

These patterns come from real GitHub issues and library audits. The diagnostic engine checks for all of them.

</core_content>

<common_mistakes>

What Goes Wrong

</common_mistakes>