description: Diagnose and fix a skill that didn't work correctly in the current session argument-hint: [optional: path to skill file]

/heal-skill — Skill Self-Repair

Analyze the current conversation to find where a skill misbehaved, diagnose the root cause, and propose targeted fixes.

When to Use

After running a skill that:

Skipped steps it should have followed
Followed the description instead of the body (CSO trap)
Stopped too early or went too far
Produced wrong output format
Missed context it should have loaded
Behaved differently than intended

Process

1. Identify the skill

If $ARGUMENTS is provided, read that file. Otherwise, analyze the conversation to detect which skill was running. Look for:

/command-name invocations
Skill descriptions that appeared in system context
Workflow patterns that match known skills

Ask the user to confirm: "It looks like [skill-name] didn't work as expected. Is that right?"

2. Gather evidence

From the conversation, extract:

What was expected — what the skill file says should happen (read the actual skill file)

What actually happened — trace Claude's actual behavior step by step:

Which steps were followed?
Which steps were skipped or altered?
Where did behavior diverge from the skill's instructions?

The gap — specific delta between expected and actual behavior

Present this as a before/after comparison:

Expected (from skill):     Actually happened:
1. Ask for intent          1. Asked for intent ✓
2. Configure frontmatter   2. Skipped — jumped to writing ✗
3. Write body              3. Wrote body (partial) ~
4. Quality checklist       4. Skipped entirely ✗
5. Create files            5. Created files ✓

3. Diagnose root cause

Common failure modes to check:

| Symptom | Likely Cause | |---------|-------------| | Steps skipped | Description summarizes workflow (CSO trap) — Claude shortcuts | | Wrong workflow chosen | Description too vague, triggers on wrong queries | | Stopped too early | No success criteria defined | | Output format wrong | No template or example provided | | Context not loaded | File references too deep or ambiguous | | Inconsistent behavior | Conflicting instructions between sections | | Over-executed | No clear stopping point or "wait for user" gate |

Ask: "Does this diagnosis match what you saw?"

4. Propose fixes

For each root cause, show the specific edit:

## Fix 1: CSO Trap in description

File: ~/.claude/skills/my-skill/SKILL.md, line 3

Before:
  description: Dispatches subagent per task with code review between tasks

After:
  description: Use when executing implementation plans with independent tasks

Why: The old description leaked workflow details, causing Claude to
follow the description as a shortcut instead of reading the full skill.

Show all proposed fixes as diffs. Include the "why" for each — the user needs to understand the fix, not just apply it.

5. Apply with approval

Ask: Which fixes should I apply?

All fixes — apply everything
Pick and choose — list fixes by number, let user select
None — just keep the diagnosis, fix manually

After applying fixes, suggest: "Want to test the skill again to verify the fix?"

Principles

Evidence first — always trace actual behavior from the conversation before diagnosing
One root cause at a time — don't propose 10 fixes at once. Find the primary failure, fix it, re-test
The skill is the bug — if Claude didn't follow the skill, the skill's instructions weren't clear enough. Don't blame the model, fix the instructions
Show your work — every fix needs a "why" that the user can evaluate

Skill Self-Repair Diagnostic

Recommended for