Agent systems · July 2026
Thin skills, sharp tools
I rebuilt my agent orchestration from five prose rulebooks into three tiny guides and two CLIs. The guides tell the model when and why. The CLIs make the right move the only easy one — on any harness.
The journey
The three skills, and the tool each one drives
A skill is a guide under 400 words — a limit my own test suite enforces.
It tells the model when to act and what done looks like, then points at a
CLI for everything procedural. The model reads the tool's help
the first time it needs it, and never carries the mechanics in context.
compass
Settles direction. Quick disposable prototypes, one question at a time, decision recorded on the shelf.
→ drives decision-shelfrelay
Delivers bounded work. A clear brief in, one compact receipt back — never a transcript.
→ drives deliverycairn
Preserves context between sessions in places that already own it — issue, PR, shelf, memory.
→ reads and updates bothWhat the CLIs replace
Every row on the left used to be a written rule the model had to remember — and sometimes didn't. Now it's behavior built into a command. A rule you can't forget because it isn't a rule anymore.
decision-shelf new refuses to create a record when a matching one exists, and prints the one to resume.decision-shelf bridge generates failing tests straight from the record — one red test per criterion.delivery checks discovers them from package.json, Makefile, Cargo, or Go, runs each, and reports pass, fail, or blocked.delivery receipt stamps the exact head SHA on the evidence and prints a loud DIRTY flag for uncommitted work.skills doctor audits every installed skill and flags any guide over 400 words.Under the hood
Neither CLI is clever, and that's the point. Every command reads state that already exists — git, the repo's own config, the shelf — and turns it into one honest output. One row per command:
decision-shelf new "…"decision-shelf bridgedelivery checksdelivery receiptskills doctorThe refusals, live
$ decision-shelf new "Pick a queue library"
decision-shelf: a matching record already exists — resume it instead of duplicating
$ delivery checks
pass npm test
fail npm run lint
$ delivery receipt
# Receipt: TASK
- **Evidence:** pass — npm test, at head 93c0ce8… (DIRTY working tree)
Still on the shelf
The bundle isn't everything I run — it's the orchestration core. A handful of standalone utilities survived the prune because each earns its place: it triggers only when asked and does one job.
repo-triage
What's next, what's blocked, what's dirty — across repos, branches, and worktrees, without implementing anything.
skill-maintenance
Audits, archives, and restores skills reversibly. It's what carried out the prune itself.
tdd
Red-green-refactor discipline on demand — the natural partner for the failing tests that bridge generates.
debug-tools
Diagnoses agent workflow failures: unwanted tool calls, stale input, missing proof, slow steps.
chronicle
Recent screen history, on explicit request — context for "what was I just looking at."
Everything redundant went to a dated archive, one mv away
from restoration: three security checklists, UI style packs, and browser
manuals whose knowledge the connected tools already carry.
One bundle, every harness
The whole set lives in a single marker-backed bundle that the installer symlinks into each harness's skill home. One copy to maintain, zero drift, and the shelf and receipts live outside every repo — so a Codex session picks up exactly where a Claude Code session left off.
By the numbers
Built July 2026 · @dylanmccavitt/skills v3 ·
guided by the Claude 5 context-engineering shift from rules to judgment:
fewer instructions, better interfaces, progressive disclosure.