Why manage a skill lifecycle at all?
Skills are easy to install and quietly expensive to understand, combine, keep current, and remove. Composition turns a pile into a coherent set; lifecycle custody makes that set temporary, exact, evidenced, and reversible.
Agent skills are one of the best ideas to arrive in coding agents: a small file of hard-won instructions that makes the agent reliably good at a task. The trouble starts not with any one skill but with the twentieth. Skills accumulate the way dependencies do — and, like dependencies, an unmanaged pile carries costs that don't show up until they compound.
Cost 0 — install and hope
The usual workflow compresses several different decisions into one action: copy a skill into a discovery directory and hope the model notices it, the harness loads the intended version, its permissions are acceptable, it does not conflict with ambient state, and somebody will retest it after the next model upgrade. Installation answers none of those questions.
Ambient dependency
- Presence stands in for intent and authority.
- The installed name stands in for exact bytes.
- Configuration stands in for activation.
- Old anecdotes stand in for current evidence.
Evidence-bearing custody
- Inspect before granting authority.
- Try or borrow before adopting.
- Verify exact startup and per-agent activation.
- Rebaseline, update, roll back, and retire explicitly.
The instinct is to install every useful skill globally so it's always available. It's the right instinct and the wrong result. A global pile is never vetted as a set: it was assembled one convenient addition at a time, by different authors, for different situations. Below is what that costs, and what composition buys instead.
The pile
- Every repo gets every skill.
- Instructions crowd the context window.
- Skills from different authors collide.
- Each skill grows to cover every case.
- Guardrails can be edited or crowded out.
The blend
- Each surface gets the subset it justifies.
- Only relevant skills spend context.
- The set is linted for coherence before it lands.
- Skills stay small; coherence lives in composition.
- Guardrails accumulate and can't be dropped.
Cost 1 — context budget
Every skill an agent loads is instruction it reads before it does any work. A pile of forty skills is forty skills' worth of preamble competing with the task for attention and tokens — most of it irrelevant to the repo in front of it. A React app doesn't need the database-migration skill; a data pipeline doesn't need the accessibility-audit skill. Loading them anyway is pure overhead, and the overhead is worst exactly when the task is hardest and the context is fullest.
Cost 2 — incoherent blends
Skills authored independently combine in ways no author ever tested. Two
skills both bind the /review command. One assumes the output format
another produces. A planning skill says "always write tasks to the tracker"
while a lightweight skill says "never leave the working directory." When you pour
many upstreams into one agent, you get a pidgin: a combination that no
single upstream ever vetted as a whole.
Blending sources risks a combination no single upstream ever vetted. Coherence has to be checked where the blend is made.The anti-pidgin guard, from Spindle's composition layer.
Spindle resolves a blend as a first-class object and lints it before anything is written: it catches command collisions and duplicate skills, records every override as a shadow, and refuses to materialize an incoherent set unless you force it. The check runs at the one place that has the whole picture — the surface where the skills will actually run together.
Cost 3 — one-size-fits-all skills
There's a tempting way to make a skill "just work everywhere": keep adding caveats and special cases until it covers every situation. The result is a skill that is long, generic, and slightly worse for every specific surface — it spends its words hedging instead of helping. And it never fully succeeds, because the situations genuinely conflict.
Spindle takes the opposite position, and it is the load-bearing idea:
Coherence belongs at the composition layer — not inside ever-larger skills.
Keep each skill small and canonical: write it once, for the case it's actually good at. Let composition — which skills travel together, in what order, phrased for which surface — carry the burden of making them work as a set. A small skill that's right for this surface beats a big skill that's adequate for all of them.
Cost 4 — the wrong surface
"The right skills" is surface-relative in three independent ways, and a flat global pile can express none of them:
App type
A Python network service and a React frontend want different skills. Spindle classifies the repo and resolves per-cluster channels accordingly.
Harness
A Claude harness and a Codex harness phrase and locate skills differently. The harness is both a selection key and a rendering dialect.
Model
A frontier model reads faster without restated context and worked examples a smaller model relies on. Rendering trims scaffolding by model tier.
Same source skill, three surfaces, three different materialized results — computed, not hand-maintained. Rendering is how one canonical skill becomes the right text for each target.
Cost 5 — guardrails you can't accidentally drop
The moment an agent can recompose its own skills, it can — in principle —
compose away its own safety rules. Spindle makes that structurally impossible
in two places. Absolutes (the ALWAYS/NEVER rules a
channel puts in force) are unioned across every layer and are never
dropped by precedence: guardrails only accumulate. And at render time, every
guardrail clause present in a skill's source must survive, word for word, in
the rendered output — if a paraphrase or an LLM rewrite drops one, the bind
fails closed and materializes nothing.
"But it adds a control plane"
It does. The payoff is that the decisions already being made implicitly—what to load, which version, for how long, under which authority, and whether it helped—become inspectable and reversible. The correct-state path stays small: cached bootstrap and stable native hooks verify desired state without network access or evaluation in the startup callback.
Composition is deterministic and cached; re-binding an unchanged surface is nearly free. Startup uses local metadata and content identities. The advance team can precompute managed blends, while lease and adoption changes remain mutable state behind stable hook definitions.
Second, the step is where the value is created. It's the one moment that has enough context to make the pile coherent, sized, phrased, and safe. Skip it and you haven't saved work — you've pushed that work onto the agent at runtime, where it's slower, less reliable, and unverifiable. And when a surface needs something ad-hoc, the liaison logs the request as a demand signal, so today's one-off becomes tomorrow's precomputed skill.
Third — and this is what makes the step more than bookkeeping — binding proves a skill is present and coherent, but never that it's good. Spindle separates those questions on purpose and answers the second one with real evidence.
Availability is not activation, and activation is not improvement. Each deserves its own evidence.
That's the payoff a pile can never give you: a skill set that is not just present but sized, coherent, surface-fit, guardrail-safe, and — where it matters — measured.