claude-skills

🧩 claude-skills

Each skill lives under skills/<name>/SKILL.md, and each agent under agents/<name>/<name>.md. These are the single source of truth: an install script links them into ~/.claude/skills/ and ~/.claude/agents/ so Claude loads them in every session, on every machine.

✨ Latest update — agents, each on its own model and effort

Switching between Opus and Sonnet, or between high and medium effort, by hand as the work changes is exactly the kind of thing nobody remembers to do. So the collection now ships agents: separate Claudes your session hands one kind of job to, each pinned to the model and effort that job deserves. Finding code runs on Haiku, routine edits on Sonnet, and building and reviewing on Opus, with nobody touching /model.

• New — five agents. scout, researcher, worker, worker-light and reviewer. See Agents.
• Updated — skills use them. /fresh-eyes reviews on reviewer. /build-it maps the code with scout and builds with worker. /raise-issue and the two audits look things up with scout. /ship-it reads other people's unreleased commits with reviewer.
• Updated — the installer links the agents the same way it links skills, ticks the ones your skills need, and warns you if a setting would quietly override their tuning.
• Earlier — recalibrated for Opus 5 and Fable 5.1. That added /build-it and the model-calibration instructions, and retired /goal-workflow and /assumption-inventory.

Already installed? git pull, then re-run node install.mjs once to add the agents. After that, git pull is the whole update: skills and agents are linked, not copied.

Tip Not a developer? Start here → SETUP-FOR-A-COLLEAGUE.md. The honest answer is that you should ask a developer to set this up for you: it takes a terminal, two clones, and a paid Claude seat to get going. That page is the checklist for them to work through on your machine. It ends with the one thing you type: /raise-issue.

Note These work best alongside other skill collections. I run them next to Matt Pocock's skills and Garry Tan's gstack for in-depth planning; the skills here add lifecycle gates around them. The installer can run both of their installers for you — off unless you tick them.

🎯 What these are for

A skill is not a way to make the model cleverer. It is already cleverer than the instructions most people have time to write, and every model release moves more of that work inside the model — the patterns that used to need spelling out are now the default, and some of the spelling-out has started to actively get in the way.

What has not moved inside the model is the two ends of the conversation:

• Getting what only you know out of your head. The model cannot read the ticket you did not write, the reason behind the decision, or the boundary you assumed was obvious. Most of these skills are shaped around asking the right small number of questions at the right moment — /build-it before the code, /raise-issue before a report reaches your team, /are-we-done before a session closes.
• Giving it back in a form a human can act on. A correct answer nobody finishes reading has not been delivered. Hence the length caps, the plain-English rules, the ban on showing raw diffs to someone who does not read code, and /ttp.

So the reliable ones here are less "Claude can now do X" and more "the prompt you would have written, if you'd had twenty minutes and remembered everything". That is why so much of this collection is questions and report formats rather than clever machinery — and it is the reason a skill gets retired here when the model stops needing it.

🧭 A workflow to try

A good way to feel how these fit together, end to end. The planning step can be whatever planning command, skill, or process you like; the rest are from this repo. Run them in order — though most are useful on their own, too.

Tip Most of these skills are useful standalone — you don't have to run the whole chain. Reach for /build-it whenever a ticket is ready, or /fresh-eyes after any finished diff.

🧰 Skills

/build-it

A ticket is a compressed message. It records what somebody decided and almost never why — because the why was obvious in the room, and the room is gone by the time anyone implements it. Build straight from the ticket text and you are building from the compression artefact.

Point it at the work. A ticket number is the tidiest input — it reads the whole issue, body, comments and linked tickets, because the comment that reversed the decision is rarely folded back into the description — but a plan file, a description typed straight after the command, or nothing at all (in which case it takes the plan agreed in the conversation above) all work the same way. No issue tracker is required.

Then it reads the code those words actually name, and only then asks you anything — and only what neither the source nor the code could answer. There is no question quota: a well-written ticket often gets none, a one-line request earns as many as it genuinely takes. What is fixed is the rule, not the number — never ask what you could have read.

If what you have handed it turns out to be big and still foggy, it says so rather than building into the fog, and points at a planning pass first: /wayfinder when the decisions are not made yet, /grilling when the idea needs stress-testing. That is a recommendation, not a refusal — say build it anyway and it will.

Then it writes the scope down before it writes any code: what will change, and — the part that earns the file — what will not, each with a line on why not and where it goes instead. Scope does not creep because someone decides to expand it. It creeps because nobody wrote down where the edge was, so every individual step past it looked like ordinary diligence. A written edge turns those steps back into visible decisions. It goes to disk, so it survives compaction on a long build and gives /fresh-eyes a concrete bar to check against rather than the implementer's memory of intent.

Then it builds that, and stops — naming the next step rather than running it. --scope-only pins the scope and writes no code. --commit turns on commits; without it, version control stays with you.

When to use: something is ready to implement — most often a ticket you want a fresh session to pick up, but equally the plan you just finished agreeing, or a change you can describe in a sentence. It is the natural partner to whatever files your tickets — /raise-issue here, or Matt Pocock's /wayfinder and /to-tickets.

/fresh-eyes

A subagent with zero conversation history reads your finished diff blind; the main context then reconciles that read against the work's actual intent — the divergence is the signal. Report-only by default; --fix / --iterate apply changes.

When to use: work is complete and you want unbiased confirmation nothing was missed before shipping.

/are-we-done

A close-out gate, not a review. It asks one question — can this session close? — where done means nothing is still undecided, not that everything is finished. An item parked with a reason is closed; an item nobody ruled on is not, however small.

It sweeps the same seven sources every run: the todo list, the promises the session made to itself ("leaving that for now", questions you never answered), the state of the work tree, TODO markers the diff itself introduced, whether tests actually ran after the last edit, every issue or PR number mentioned — each resolved to its real title, never left as a bare #123 — and the background shells and processes the session (or its subagents) left running. Then each hit lands in exactly one bucket: done, won't do, deferred, blocker, or undecided.

It is strict by default — a dirty tree and a suite not re-run since the last edit are open points — but the floor lifts on evidence about how your project actually works: if CI runs the suite on every push and this session pushed, testing was not left undecided. Where it sees a stable pattern it can offer, once, to remember it for the project, so later sessions inherit the floor. It never assumes; and if the session was compacted it says so rather than reporting a source it can only half-read as clean.

A clean sweep gets two lines and no more, plus a paste-ready Parked: block if anything was deferred, so the parking outlives the session that decided it (/raise-issue files whatever