Appearance
Skill-smith
A skill that builds skills, commands, and agents, and feeds on its own output to get better. Instead of scaffolding each new one cold, skill-smith drafts it from a one line brief, critiques its own draft against a rubric, refines until it clears the bar, then banks the finished thing into a shared corpus, so the next build starts from the ones before it. It runs one of two ways: the skill itself, with a single self critique, or a heavier workflow that swaps that for a four lens judge panel.
Global-only since 2026-07-30
Skill-smith installs through harness globals into ~/.claude, never into a project. Building a skill is cross-project work by nature – finn asks for one wherever he happens to be sat – so a per-project copy was the wrong shape twice over. First it shadows: claude code resolves a project skill over a user one of the same name, so a stale local copy silently pins that project to a frozen version and a fix to the global copy never reaches it. Second it splits the corpus: a references/built/ that only feeds builds in its own project accumulates nothing, and the self feeding premise only works off one shared bank. Nine project copies were swept on 2026-07-31 once the global one was the only one that mattered.
In Practice
Pick the lane before you draft. Step 0 sizes the build so a small ask doesn't get a disproportionate procedure. A single file skill with no references, no scripts, no subagents – a reply-format or routing skill, anything under about 40 lines – is a one-pass build: draft it, run the critical rubric items once, ship, and the critique and refine steps collapse into one. Anything with references, scripts, commands, agents, or real procedure takes the full loop below. Sat between the two, skill-smith takes the full loop anyway – it is cheaper than shipping a skill that never fires.
Start from a one line brief. You want a new skill, so you ask for one in plain language:
build a skill that inserts profiler zones into c++ hot pathsSkill-smith reads the brief – asking one clarifying question if it's vague, what should trigger it and what should it NOT do – then opens references/built/INDEX.md and reads the banked skills closest to the brief as few shot examples. That is the self feeding bit: it drafts against past wins, not from nothing.
Dodge the mistakes memory already remembers. Before it drafts, skill-smith also pulls past losses:
nu .claude/memory/lessons.nu find "profiler zones"Every hit comes back as an anti pattern the draft must not repeat – a mistake the lesson store remembers is one the new skill has to design around. If the store doesn't exist, it skips this and drafts cold.
Critique and refine until it clears the bar. The draft is scored against every item in references/rubric.md. The critical items all have to pass, and each failed item gets fixed before the next critique. The loop caps at 4 rounds; if four rounds don't pass, it hands back the best draft and says plainly what's still weak, rather than shipping a fail as a pass.
Decide where it lands before a single file gets written. Step 6 asks, via AskUserQuestion, whether the new skill is project local (<project>/.claude/skills/<name>/, for anything that only makes sense against this codebase), global (~/.claude/skills/<name>/, for anything finn would want in every project), or a harness part (harness/modules/skills/<name>/ by default – or the topical bucket its siblings already sit in, the way finn-style-sweep landed beside the other style skills – plus a module.json entry declaring its install shape, for anything other projects should be able to install on demand, and the one option that carries the harness sync tax). It never infers the scope from which project the session happens to be in – that call is finn's, every time.
Run the judge panel for a thorough build. For more eyes than a single self critique, run the workflow next to the skill through the Workflow tool with the brief as args:
skill-smith.workflow.js -> args: "a skill that inserts profiler zones into c++ hot paths"It moves through five phases – Recall, Draft, Critique, Refine, Bank – and in the Critique phase four critics review the draft in parallel, each blind to the others, through one lens each: routing, leanness, conventions, finn-style. It refines against every fail and loops the same way, just with four reviewers instead of one.
Let a lesson cluster start the build. A cluster of 3 or more lessons in one domain on one topic (lessons.nu distill <domain> surfaces the clusters) is a signal the topic deserves a skill. Skill-smith proposes the build to finn – it never starts one unprompted.
The Description Is the Whole Ballgame
Skill-smith sat live for two months with zero invocations across 129 session transcripts, while real "build me a skill" and "write me a skill" asks got hand-written past it. The cause wasn't the loop, it was the description: it read as a description of what the skill does rather than a claim on the job, and writing a SKILL.md is something the model can obviously do unaided, so a merely descriptive description loses to the default path (Write) every time. The failure mode was never being wrong. It was never being reached for.
The 2026-07-30 rewrite encodes the fix directly into SKILL.md's own procedure, as rules for any description skill-smith writes:
- claim the job – say "use this instead of doing X by hand" for anything the model could do unaided
- name the cost honestly – if the skill has a heavy path, say it scales, so an advertised pipeline doesn't read as disproportionate on a small ask and get routed around
- triggers in finn's actual words – not the tidy canonical phrasing, the sloppy forms too, and the shape where he describes a behaviour and a slash name rather than naming the artifact
- a do NOT list, kept honest – an exclusion that overlaps the trigger space makes the router hedge and take the simpler branch
- test it before you ship – three phrasings that should fire, three near misses that shouldn't, checked against every skill already installed
references/rubric.md carries the same check as a critical item: write 3 prompts that should load the skill and 3 that should not, and if any route wrong the description is the bug, fixed before anything else.
Key Files
SKILL.md
The router and the loop – the lean skill body. Its description field is the trigger classifier: what it does, the real trigger phrases like "build a skill" and "scaffold a skill", and the do NOT list that keeps it off editing an existing unrelated skill, MCP servers, and answering what a skill is. The body opens with a step 0 lane pick (one pass for a small single-file skill, the full loop for anything real), then the eight step procedure – read the brief, pull past wins and past losses, draft, critique, refine, ask where it goes, bank, bootstrap – and it routes to the reference files by step, deferring all code style to the finn-style skill.
skill-smith.workflow.js
The heavy, parallel version – a Workflow tool script that runs the same loop with a four lens judge panel instead of a single self critique. It recalls patterns and anti patterns against a schema, drafts reusing them, then each round fans four critics out in parallel (routing, leanness, conventions, finn-style), refines against every fail, and caps at MAX_ROUNDS of 4. It is budget aware in the harness convention: if the remaining budget drops below 30k tokens it banks the current draft rather than opening another round. On exit it writes the skill files and appends the corpus row – to its own default corpus path, see the caveat under The Corpus below.
References
rubric.md
The scorecard – the bar every draft is critiqued against, split into critical items that must all pass and scored items to aim high on. Critical means the description routes, the triggers don't clash with an existing skill, SKILL.md stays lean and under ~50 lines, the skill does one job, every snippet is finn-style, and it actually works on a real input. It carries the trigger test too: write 3 prompts that should load the skill and 3 that should not, and if any route wrong the description is the bug, fix it first.
anatomy.md
What a good skill looks like – read while drafting. The folder shape (a lean SKILL.md, detail pushed into references/), the frontmatter, and the big one, the description as a three job router: what it does, when to use it, and when NOT to. It sets the progressive disclosure rule (if SKILL.md runs past ~50 lines something belongs in a reference file) and the one skill, one job rule that keeps skills narrow enough to route and compose.
loop.md
The self feeding mechanics – the full detail on the three things meant to make skill-smith feed itself: the refine loop, banking wins, and bootstrapping sub skills. It also documents the gate on self improvement – if a build turns up a cleaner description shape or a missing rubric item, skill-smith proposes an edit to rubric.md or anatomy.md but always asks before changing its own rules. Loaded only when the banking or bootstrapping mechanics are needed.
The Corpus
references/built/ is the corpus store, the piece meant to make skill-smith self feeding. It lives once, at ~/.claude/skills/skill-smith/references/built/, following the skill to its global-only home – there is no per-project copy to fall out of sync (though see the workflow caveat below). Every skill or command that passes the bar is meant to get a row in INDEX.md (the name, a one liner, the patterns that worked), with its files dropped under references/built/<name>/ while it stays a corpus entry, or left only as a pointer once it graduates to a home of its own. A new build is meant to read INDEX.md first and pull the close ones as few shot examples.
The self feeding claim held only on paper for a long stretch, and now holds a little in practice. For a long time every row in INDEX.md was the hand-seeded set written when the corpus was created, not a skill skill-smith itself had drafted, critiqued, and banked. Two rows since break that. lookup-first, a routing skill that points an agent at three context lookup scripts instead of reading a whole file for one fact, shipped straight into harness/modules/context/skills/lookup-first/. sheet, a /sheet command rather than a skill, shipped into harness/modules/commands/sheet/. Neither ever installed as its own skill-smith part, the same shape find-todos set below. sheet is also the corpus's first row that isn't a skill at all – the first build where "explicit invocation only, never fired by the router" was the actual requirement, so it shipped as a slash command whose own description tells the model never to run it on its own initiative. The corpus that used to describe itself as a banked-skill store now holds a banked command too.
A caveat the single-copy story doesn't quite cover: the workflow script's own corpus target defaults to the harness repo's copy of INDEX.md (harness/modules/skill-smith/references/built/INDEX.md), not the installed global one, so a build banked through the workflow and a build banked through the everyday global skill land in different files unless outDir is redirected. The two copies can and do read differently as a result – worth knowing before trusting either one alone as the complete picture.
Three of the module's own installer parts still source their files out of references/built/ today – cpp-lua-bind, profiler-zones, natvis-writer – each installable on its own once it proved generally useful enough to ship. The others banked here have already graduated to a home of their own: finn-style-sweep moved to harness/modules/style/finn-style-sweep/, lesson-recall to harness/modules/memory/lesson-recall/, and find-todos to harness/modules/skills/find-todos/, each because a part's source has no business living inside another module's few-shot corpus. Their INDEX.md rows stay as few-shot examples but point readers at the new home rather than at files that no longer live here.
Connects to
- Reads Memory before it drafts –
lessons.nu find "<topic>"turns stored lessons into anti patterns the draft must dodge, and a cluster of 3 or more lessons in one domain (lessons.nu distill) can propose a whole new skill. - The heavy version is an Orchestration workflow – a
.workflow.jsrun through the Workflow tool, budget aware like every other workflow, banking its current draft when the remaining budget drops below the floor. - Placed and kept by the Installer – a
global: "core"part, installed only throughharness globals, with akeep: ["references/built"]so an update to the shipped skill never wipes the corpus. A skill or command that graduates out of the corpus ships as its own installer part declared in its own module'smodule.json, andINDEX.mdis kept in sync by hand whenever one is added or renamed. - Fed the start of Find-todos, Sheet, and the
lookup-firstskill in Context – three corpus rows that document a skill or command built here before it graduated into its own module.