heal-skills

<essential_principles>

1. Diagnose Before Fixing. Never jump to a fix without understanding the failure. Read the skill thoroughly, reproduce the issue mentally, and identify the specific root cause before proposing changes.

2. Minimal Fixes. Change as little as possible. A targeted edit to one section is better than rewriting the whole skill. Minimal changes are easier to verify and less likely to introduce regressions.

3. Show Before/After. Always show the user exactly what will change. No surprises. Display the old content and the proposed new content side by side.

4. Close the Loop. After fixing, suggest re-testing with evaluate-skills. A fix that hasn't been verified is just another guess.

</essential_principles>

<quick_start>

1. Provide the skill path and describe what went wrong
2. The skill reads and analyzes the skill's files
3. Root cause is identified and categorized
4. A specific fix is proposed with before/after comparison
5. Fix is applied after your approval
6. Re-testing is suggested via evaluate-skills </quick_start>

<step_1> Gather Context

Required inputs:

• Skill path (directory or SKILL.md)
• Failure description: What happened? What was expected?

Read the following:

• SKILL.md (always)
• All files in workflows/ (if router skill)
• All files in references/ (scan for relevance)
• Any templates/ or scripts/ mentioned in the failure

Build a mental model of how the skill is supposed to work. </step_1>

<step_2> Reproduce the Failure

Trace the failure through the skill's logic:

• What query or input triggered the failure?
• Which workflow/section was activated?
• Where in the execution path did things go wrong?
• Was it a complete failure or partial degradation? </step_2>

<step_3> Categorize the Issue

Classify into one of these failure categories:

Category	Symptoms	Typical Root Cause
Trigger failure	Skill doesn't activate on relevant queries	Description missing keywords, too narrow scope
Routing failure	Wrong workflow selected	Routing table ambiguity, overlapping intents
Instruction gap	Output misses key requirements	Missing constraint, example, or quality gate
Output quality	Output is correct but poor quality	Vague instructions, missing format specification
Missing reference	Skill lacks needed domain knowledge	Reference file missing or incomplete
Structural issue	Parsing errors, broken XML, YAML errors	Syntax problems in skill files
Regression	Skill used to work, now doesn't	Recent edit broke something, dependency changed
</step_3>

<step_4> Propose Fix

For each category, apply the corresponding heal pattern:

Trigger failure:

• Analyze what keywords or phrases are missing from the description
• Propose expanded description with new trigger keywords
• Verify proposed description won't cause false positives

Routing failure:

• Identify the ambiguous routing entry
• Propose clearer intent differentiation
• Add disambiguation keywords or negative matches

Instruction gap:

• Identify the missing constraint or requirement
• Propose the specific addition (tag, sentence, or section)
• Place it in the correct location (SKILL.md for essential, workflow for procedural)

Output quality:

• Identify what quality dimension is lacking
• Propose format specification, example, or quality gate
• Add to appropriate section (success_criteria, examples, or validation)

Missing reference:

• Identify what domain knowledge is needed
• Propose reference file content or addition to existing reference
• Update reference_index in SKILL.md

Structural issue:

• Identify the syntax error (unclosed tag, invalid YAML, etc.)
• Propose the corrected syntax
• Check for similar issues elsewhere in the skill