AI Guides › Skills & Agents
Your Skill Library Is A Codebase Now — Treat It Like One
By Nigel Guy · 2 min read
Once you have more than a handful of skills, you have something that
behaves like software, whether or not you think of it that way: files that
depend on external tools, that can go stale, that interact with each other,
and that someone (probably future you) will need to understand without the
context you have right now.
The rule: once your skill collection grows past a handful, apply the same
basic discipline you'd want from any codebase — naming, versioning, and
documentation — rather than letting it stay a pile of individually
reasonable files.
The mechanism
- Name skills so their purpose is obvious without opening them. A
consistent naming pattern saves real time the moment you have more than
ten of these.
- Note when each one was last verified working, somewhere you'll
actually see it. This turns "I think this still works" into something
checkable.
- Document what each skill assumes about its environment or connected
tools. When something breaks later, this is what tells you where to
look first.
- Treat a change to a shared dependency as a reason to re-check every
skill that touches it — the same way a shared library update in real
software prompts a regression check.
- Retire deliberately, don't just abandon. A skill nobody's touched in
a year should be explicitly archived or deleted, not left in an ambiguous
state where nobody's sure if it still works.
What to skip
Skip building elaborate tooling around a handful of skills — this discipline
earns its keep once the collection is large enough that you can't hold it
all in memory, not before. And skip treating documentation as optional
because "it's just a skill, not real code" — the maintenance burden is real
regardless of what you call it.
Guardrails
- The moment a skill's output affects something you didn't build yourself —
a teammate, a client, a real decision — the documentation stops being
optional, regardless of collection size.
- A skill library with no ownership record (who wrote it, who's responsible
for it) is a liability the moment more than one person is using it.
- This discipline is proportional to stakes and scale — a personal library
of three low-stakes skills doesn't need the same rigour as a shared team
library of forty.
All 751 AI guides · JulieMango plans from £17/mo