scientiacapital 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.
| ID | Check | Rule | Auto-fix |
|---|---|---|---|
| S1 | YAML frontmatter exists | SKILL.md starts with --- |
No |
| S2 | name field present |
Required, non-empty string | No |
| S3 | name format valid |
^[a-z0-9-]+$, max 64 chars |
Yes — slugify |
| S4 | description field present |
Required, non-empty string | No |
| S5 | description length |
Max 1024 chars | Yes — truncate |
| S6 | description has no XML tags |
No <tags> in value |
Yes — strip tags |
| S7 | description is a string |
Not YAML array/object | Yes — join if array |
| S7b | Frontmatter keys valid | All keys in valid set (see below) | Warning |
| S8 | SKILL.md exists | Must exist in skill directory | No |
| S9 | config.json exists | Must exist in skill directory | Yes — generate from SKILL.md |
| S10 | config.json is valid JSON | Must parse without error | No |
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.
Detection for S7b: Valid frontmatter keys are: name, description, disable-model-invocation, user-invocable, allowed-tools, model, context, agent, argument-hint, hooks. Any other key is a WARNING (not an error — unknown keys are ignored by Claude Code, not rejected).
Layer 2: Content Quality (HIGH)
These checks verify the skill follows library conventions for discoverability.
| ID | Check | Rule | Auto-fix |
|---|---|---|---|
| C1 | <objective> section exists |
Must be present in SKILL.md body | Yes — add stub |
| C2 | <quick_start> section exists |
Must be present in SKILL.md body | Yes — add stub |
| C3 | <success_criteria> section exists |
Must be present in SKILL.md body | Yes — add stub |
| C4 | Line count | Body ≤ 500 lines (warning only) | Warning |
| C5 | Dead reference links | Internal reference/ links must resolve |
Yes — remove dead |
| C6 | Naming convention | Directory ends with -skill |
Warning |
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.
| ID | Check | Rule | Auto-fix |
|---|---|---|---|
| I1 | config.json has standard keys | Must have name, version, category |
Yes — add missing |
| I2 | Uses activation_triggers key |
Not triggers (legacy name) |
Yes — rename key |
| I3 | Uses depends_on key |
Not dependencies (legacy name) |
Yes — rename key |
| I4 | Has version field |
Must have version string |
Yes — add "1.0.0" |
| I5 | No duplicate activation triggers | No trigger collisions across skills | Warning |
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:
| Check | Fix Strategy |
|---|---|
| S3 | Slugify: lowercase, replace spaces/special chars with hyphens |
| S5 | Truncate to 1024 chars at last sentence boundary |
| S6 | Strip XML tags with regex: </?[a-z_]+> → empty string |
| S7 | If array: join elements with ". ". If object: use first value |
| S9 | Generate minimal config.json from SKILL.md frontmatter |
| C1 | Add <objective>\nTODO: Add objective\n</objective> after frontmatter |
| C2 | Add <quick_start>\nTODO: Add quick start\n</quick_start> after objective |
| C3 | Add <success_criteria>\nTODO: Add success criteria\n</success_criteria> after quick_start |
| C5 | Remove dead [text](reference/...) links |
| I1 | Add missing keys with defaults from SKILL.md frontmatter |
| I2 | Rename triggers → activation_triggers in config.json |
| I3 | Rename dependencies → depends_on in config.json |
| I4 | Add "version": "1.0.0" to config.json |
Known Issue Patterns
These patterns come from real GitHub issues and library audits. The diagnostic engine checks for all of them.
| Source | Pattern | Check |
|---|---|---|
| GitHub #9817 | Whitespace before --- prevents YAML parse |
S1 |
| GitHub #11322 | Prettier reformats description to multi-line | S7 |
| GitHub #17604 | YAML array in description crashes slash commands | S7 |
| GitHub #6377 | Missing name field despite valid YAML structure |
S2 |
| GitHub #14882 | Skills consume full tokens (no progressive disclosure) | C4 |
| GitHub #14577 | /skills shows "No skills found" — frontmatter parse failure |
S1, S2 |
| Library audit | 8 skills missing XML sections | C1-C3 |
| Library audit | 9 skills using legacy config.json keys | I2, I3 |
| Library audit | 1 skill missing -skill suffix |
C6 |
What Goes Wrong
| Mistake | Fix |
|---|---|
Running --fix without reviewing diffs |
Always preview first. The protocol requires confirmation. |
| Ignoring WARNINGS | Warnings are advisory but indicate tech debt. Track them. |
| Fixing only CRITICAL issues | HIGH and MEDIUM issues affect discoverability and tooling. Fix all layers. |
| Adding XML stubs without filling them in | Stubs are placeholders. Schedule time to write real content. |
| Running heal on a single skill when library-wide issues exist | Run full scan first to see the big picture. |
Emit Outcome Sidecar
As the final step, write to ~/.claude/skill-analytics/last-outcome-heal.json:
{"ts":"[UTC ISO8601]","skill":"heal","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]"}
Use status "partial" if some stages failed but results were produced. Use "error" only if no output was generated.