AI Guides › Skills & Agents
Retiring A Skill Properly Instead Of Letting It Quietly Rot
By Nigel Guy · 2 min read
Skills rarely get deleted. They get ignored — left in the library while
everyone quietly stops trusting them, works around them, or forgets they
exist, until one day someone new finds it, runs it, and gets an answer
built on assumptions nobody's checked in a year. Rot is worse than absence,
because absence is at least visible.
The rule: a skill that no longer earns its place needs an actual
retirement, with a record of why — leaving it in the library unused is not
a neutral choice, it's a decision to let the next person find it by
accident.
The mechanism: the Retirement Checklist
- State the reason, specifically. Not "not needed anymore" — "the
underlying tool changed its API," "the task it handled moved to a
different skill," "it was never actually reliable and nobody trusted
its output." Vague reasons get re-litigated; specific ones don't.
- Check who or what depends on it. Other skills that call it, routines
that trigger it, people who reach for it out of habit. Retiring a skill
with live dependants isn't retirement, it's an outage waiting to
happen.
- Redirect, don't just remove. If there's a replacement, point to it
explicitly in the retirement note — the goal is that the next person
who goes looking finds the answer, not a gap.
- Move it, don't delete it, at least at first. An archived-but-visible
state (clearly marked as retired, with the reason attached) lets you
recover it if the retirement turns out to be premature, without leaving
it live and discoverable in the meantime.
- Announce it where the people who used it will actually see it. A
retirement nobody hears about isn't a retirement, it's a surprise for
whoever reaches for it next.
What to skip
Skip quietly renaming a skill to "old-" or "deprecated-" and leaving it in
the same place with no note — that satisfies nobody: it's still
discoverable, still runnable, and now also unlabelled as to why. And skip
treating "nobody's used it in a while" as sufficient reason on its own;
usage data tells you it's stale, not why, and the why is what stops the
next person from rebuilding the same broken thing.
Guardrails
- Retiring a skill is not the same as fixing the underlying gap it left. If
the task it handled still needs doing, retirement without a replacement
just moves the problem back onto a person.
- Keep the retirement record somewhere durable, not in a chat thread that
scrolls away — the whole point is that someone finds it later.
- A skill retired in error should be easy to bring back. If reviving it
means reconstructing it from scratch, the retirement process itself was
too destructive.
All 751 AI guides · JulieMango plans from £17/mo