skill-improve

Skill Improve — Post-Use Skill Maintenance

Improve existing skills based on real usage experience. Always finish the current task first.

Trigger Rules

• After task completion: If a skill was used and had issues, suggest: "The <skill-name> skill had some gaps — want me to /skill-improve it?"
• Manual: /skill-improve <skill-name> or /skill-improve (defaults to most recently used skill in session)
• NEVER interrupt the current task to improve a skill. Finish first, improve after.

Improvement Flow

1. Identify Target

Determine which skill to improve:

• If <skill-name> provided, use that
• If no argument, use the most recently invoked skill in this session
• If no skill was used, ask the user which skill to improve

2. Read Current Skill

Read the target skill's SKILL.md and any bundled resources (scripts/, references/, assets/).

3. Diagnose Issues

Compare the skill's instructions against actual execution experience. Categorize problems:

Category	Example
Outdated	Tool/API changed, deprecated method
Missing	Edge case encountered that skill didn't cover
Redundant	Steps Claude already knows, wasting context
Unclear	Ambiguous instruction that caused wrong action
Wrong	Incorrect assumption or factual error

4. Generate Diff Preview

Show the user exactly what will change:

• Quote the original text
• Show the proposed replacement
• Explain why for each change

Do NOT modify the file until user confirms.

5. Apply Changes

After confirmation:

• Edit the SKILL.md (and bundled resources if needed)
• Preserve the skill's name and description structure unless the issue is there
• Keep changes minimal — fix what's broken, don't rewrite what works

6. Log the Improvement

Update or create ~/.claude/skills/learn/learned/<skill-name>.md:

If the file exists, append to the improvement record section:

### <YYYY-MM-DD>
- **Problem**: <what was wrong>
- **Fix**: <what was changed>
- **Source**: <task context that revealed the issue>

If the file doesn't exist (non-learned skill being improved for the first time), create it:

---
skill: <skill-name>
created: <YYYY-MM-DD>
last_updated: <YYYY-MM-DD>
source: improvement
---

## Improvement Record
### <YYYY-MM-DD>
- **Problem**: <what was wrong>
- **Fix**: <what was changed>
- **Source**: <task context that revealed the issue>

7. Memory Sync (Optional)

If a memory system is available and the fix revealed a universal insight (not just a skill-specific correction), save a concise one-line version to memory.

Scope Limits

• Small fixes: Apply directly (typos, outdated commands, missing steps)
• Major redesign: If the skill's entire approach is wrong, suggest using /learn to extract a new skill instead of patching
• Don't bloat: If adding content would push SKILL.md over 500 lines, suggest splitting into reference files instead