AI Guides › Skills & Agents

The First Sign A Skill Needs Retiring, Not Patching

By Nigel Guy · 3 min read

A skill that breaks doesn't usually announce that it's time to rebuild it — it announces that one thing needs fixing, you fix that one thing, and it runs fine again. The trouble is that "fine again" is doing less work than it sounds like, because the second time this happens, you're not looking at a skill with one problem any more. You're looking at a skill that's accumulating problems faster than you're noticing the pattern.

The mechanism

1. Log every patch you make to a skill, however small it feels. A one-line tweak counts. The point of logging isn't the individual fix — it's being able to see the pattern of fixes over time, which you can't do from memory alone.
2. Treat the second patch to the same skill within a short window as a trigger, not a coincidence. One fix is normal maintenance. Two, close together, usually means the first fix didn't address the actual problem — it addressed the symptom that happened to surface first.
3. When that trigger fires, ask honestly: patch again, or rebuild? Compare what a clean rewrite would actually cost against what continuing to patch is likely to cost over the next few months, not just the next fix. Patching almost always looks cheaper in the moment; that's exactly why this comparison needs to be explicit rather than assumed.
4. Watch for guardrails growing to cover cases the mechanism was never designed for. If the guardrails section has become longer than the actual mechanism, that's a strong independent signal alongside the patch count — it means the skill's core design no longer matches what it's actually being asked to do.
5. Retire deliberately once the case is made — archive it, don't leave it live while you build its replacement, unless you genuinely need the old version running in parallel during a transition.

What to skip

Skip patching indefinitely on the reasoning that a rewrite feels like more upfront work — that comparison is usually wrong once you count the second, third, and fourth patch honestly instead of judging each one in isolation. And skip treating a single patch as damning on its own; every skill needs an occasional fix, and one patch is normal maintenance, not a signal of anything deeper.

Guardrails

• The "short window" for counting a second patch is a judgement call, not a fixed number — a skill patched twice in a week is a much stronger signal than one patched twice across a year, and you're the one who has to weigh that based on how often the skill actually runs.
• This overlaps with the general quarterly-audit habit elsewhere in this library, but it's a sharper, earlier trigger — the audit catches rot on a schedule; this catches it the moment the pattern shows up, which is usually well before the next scheduled audit would.
• Rebuilding isn't automatically the right call even when the pattern fires — sometimes the honest answer is that the underlying task has genuinely changed shape, and no version of the skill, old or rebuilt, is the right tool for it any more.

All 751 AI guides · JulieMango plans from £17/mo