Why compose skills at all?
Skills are easy to add and quietly expensive to carry. The default — a global pile that every repo inherits — has five hidden costs. Composition is what turns a pile into a tight, vetted set.
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.
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 step"
It does — one command, spindle bind, between installing skills
and using them. That's a fair objection, so here's the honest accounting of why
the step earns its place.
First, it's cheap and it's amortized. A bind is deterministic and cached; re-binding an unchanged surface is nearly free. The advance team can precompute the blend for every known surface ahead of time, so a repo is already composed before anyone opens it — the step disappears into a warm cache.
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.
Rendering proves a skill is available. Only a held-out evaluation proves it helped.
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.