skills for coding agents v0.4

Keep a small house. Find the rest when the work calls for it.

Spindle gives every agent you run the same short list of rules and skills, a large catalog of pinned skills it searches only when a task needs one, and a record of whether each skill actually helped.

Claude Code, Codex, Hermes any runtime that can read a file nothing third-party is executed MIT licensed

Skills are instruction files an agent loads to do a kind of work well. Good ones are everywhere now: your own, your team's, and public collections with hundreds each. Installing all of them makes agents worse. A harness shows the model every installed skill's name and description, and the model picks less accurately as that list grows. Spindle splits the list in two: a few skills that are always on, and everything else, which is searched, judged, and handed over only for the task at hand.

Three parts

The house

One versioned directory of rules every harness loads and a small kernel of skills linked into every harness. Install it per machine with one command; projects opt into named patterns.

spindle house

The catalog

Skill sources pinned to exact commits, indexed without running anything in them. Hundreds of skills stay available and none of them crowd the model's list.

spindle catalog

Choose and learn

For each task, rank the catalog, let a judge decide whether any skill would materially help, hand it over by path, then record how the work was judged. The next choice uses that record.

find · use · brief · report

Two minutes in

bash

# install the CLI, then point this machine at your house
$ uv tool install "git+https://github.com/lavallee/spindle@v0.4.2"
$ spindle house init ~/src/my-skills/house
$ spindle house setup                # rules + kernel into every harness found
$ spindle catalog sync               # export pinned sources, build the index

# during work: what would help with this task?
$ spindle find "vet a benchmark result before reporting the speedup"
* 0.88  upstream/benchmark-checklist   Vet a perf measurement before you report it
  0.46  upstream/verification          Use before claiming work is complete
$ spindle use upstream/benchmark-checklist      # prints the SKILL.md path to read
$ spindle report --outcome accepted --helped upstream/benchmark-checklist

The first column is the judge's probability that the skill would materially improve the work; a star marks a selection. With no judge configured, find returns a ranked shortlist and says so, and whoever receives it does the judging. Selecting nothing is a valid answer: asking for help renaming a variable returns no skill at all.

Who it is for

You run several harnesses →

Keep one set of house rules and kernel skills, and install them into Claude Code, Codex, and Hermes on every machine from the same directory.

You want public skill collections →

Pin them by commit, see exactly what a newer commit would change, and reach any skill on demand without installing the collection.

You dispatch agent jobs →

One call before dispatch picks the skills, one call after grading records the outcome, and the job's receipt says exactly which skill bytes the agent was given.

You need to vet a skill first →

Inspect it without running it, try it in a disposable session, lease it, and adopt it only with evidence. Every step is reversible.

What makes it different

Selection is judged: Text search finds the neighbourhood but cannot tell "relevant" from "shares words with the task". A judge model gives a calibrated yes-or-no per candidate, and an optional expander turns a commission into the phrases a skill description would use.
Outcomes close the loop: Every offer, read, and graded outcome lands in a local ledger. Skills that keep helping rise; skills that keep getting rejected sink. Reviewers can see what guidance a producer was given.
Pins, not floating installs: A source is a full commit. Moving the pin shows the skills added, changed, and removed, and any new network, credential, or shell indicators, before you accept it as a reviewed diff.
Nothing third-party runs: Sources are exported without hooks, install scripts, or package managers. Spindle reads skill text; it never executes a catalog skill's code.
Your rules travel: House rules land in a managed block of each harness's always-loaded instruction file. Text outside the block is never touched, and a project can embed the rules for environments that never run setup.

A skill should earn its place in the context, task by task, with a record of whether it helped.The always-on list stays short so both it and the long tail stay useful.

Deeper: the vetting lifecycle

Some skills belong in a harness's native list, or need more care than a file read: a skill with scripts, a team-wide default, a skill under evaluation. For those, Spindle keeps the full lifecycle it started with: inspect explains a package without executing it, try opens one disposable session, borrow grants an expiring lease, startup verifies the exact desired set, and only adopt creates lasting custody. Paired evaluations decide whether a skill improves held-out work. See the lifecycle and evaluation.