skill-builder

<!-- origin: skill-builder | version: 1.5 | modifiable: true -->

Quick Commands

| Command | Action | |---------|--------| | /skill-builder | Full audit: disclaimer → scan + report → auto-executes recommended fixes (Audit Autonomy Gate) | | /skill-builder audit | Same as above | | /skill-builder audit --review | Full scan + report + would-be Execution Plan, zero writes | | /skill-builder audit --quick | Lightweight audit: frontmatter + line counts; auto-fixes mechanical findings | | /skill-builder cascade [skill] | Validation cascade analysis: detect over-validation suppressing output | | /skill-builder dev [command] | Run any command with skill-builder itself included |

<!-- /origin -->

---

<!-- origin: user | added: 2026-02-22 | immutable: true -->

Directives

"When a decision needs to be made that isn't overtly obvious, and guesses are involved, AGENTS ARE MANDATORY, in order to provide additional input in decision making."

— Added 2026-02-22, source: user directive

"Each agent being created by this system always has to have an appropriate persona that is not being used anywhere else."

— Added 2026-02-22, source: user directive

"When deploying a Team, one of the team member's persona is a research assistant who will research the issue using read-only reference tools. Other team members may also make requests from the research assistant to help augment the outcome."

— Added 2026-02-23, source: user directive (tool specifics in references/agents-teams.md)

"When the dev flag gets called, you ALWAYS concentrate on the distribution files first, then sync changes to the .claude directory after."

— Added 2026-05-08, source: user directive (after dev edits repeatedly landed in the runtime copy instead of the source distribution)

"No hooks! We don't distribute hooks. The project only makes hooks on the host system."

— Added 2026-05-08, source: user directive

"Exception to the no-hooks-distribution rule: skill-builder's own load-bearing enforcement hooks — protect-directives.sh and unique-persona.sh — DO ship in the source distribution and the installer fetches them. They protect two sacred user directives (no rewording of immutable blocks; persona uniqueness across agents). Without them, every fresh install silently loses load-bearing enforcement. The general no-distribute rule still applies to every other hook on the host system. Wiring into settings.local.json remains host-local."

— Added 2026-05-11, source: user directive (after the regenerate-and-rewire loop revealed that no-distribute leaves load-bearing enforcement off on every fresh host).

"Bifurcate jobs based on the currently selected model — split jobs between creative work (ie image generation, content generation, and design generation) and coding (everything else, including testing). When we run an audit, I want to make sure it's fluid in managing switching between models, with prompting, or not."

— Added 2026-06-01, source: user directive (the lane→model mapping is intentionally arbitrary/configurable because models change constantly; the model IDs live in references/model-lanes.md, never inside this immutable block).

"It shouldn't make any decisions based on performance, but the full completion of integrity of skills expected to be performed by the user. Don't make decisions based on 'shortcut' mentality."

— Added 2026-06-04, source: user directive (governs the reconcile command: redundancy is never the target; only completion-breaking conflict is actionable; integrity over performance, never a shortcut).

"When a project is audited and the model switching setup is deciding what is most likely creative, I want to make sure to flag any skill that has to do with communication, language translation, text evaluation, etc as creative."

"Anything that has to do with research must be performed by the coding model before being handed off to creative."

— Added 2026-06-06, source: user directive (widens the creative lane of the 2026-06-01 bifurcation directive to communication / language-translation / text-evaluation skills, with research explicitly staying on the coding model and taking precedence over creative signals; the signal lists implementing this live in references/model-lanes.md § Advisory Lane Suggestion, never inside this immutable block).

"Why option 3 is important, and this should be a directive moving forward, there are usually explicit directions on directing the text-evaluator workflow. These workflows may include routing points to other skills, so agents should be highly focused as to preserve the original intentent of the skill and preserve its workflow as the highest priority. There are no shortcuts. We aren't doing this for token efficiency. We're doing this to actually preserve the workflow and make the main model most effective at its task."

— Added 2026-06-06, source: user directive (captured verbatim from the lane-delegation workshop; "option 3" refers to the workshop's fleet-design choice of bespoke per-skill agents over a shared generic fleet. Governs lane-pinned excursion delegation: agents are designed per skill from that skill's reviewed material; workflow preservation — including routing points to other skills — is the highest priority; token efficiency is never a valid rationale. The delegation machinery lives in references/lane-delegation.md and references/procedures/agents.md, never inside this immutable block.)

"All agents created or modified during the audit should have a model specified, per the user's choice of creativity model and everything else model."

— Added 2026-06-06, source: user directive (every AGENT.md that audit — or any command running under audit — creates or modifies must carry an explicit model: field, resolved from the user's Lane→Model choices in references/model-lanes.md: creative-lane work gets the creativity model, everything else gets the everything-else/coding model. The assignment mechanics live in references/lane-delegation.md § Audit Model-Assignment Rule, never inside this immutable block.)

"The system is a 2-brain harness that balances between creativity and analytics: at the audit's single onboarding question, the user picks the creative model and the model for everything else. /route is the preferred smart door that matches the orchestrator to the work's lane with at most one prompt per endeavor. If the user wants to hand run skills, that's absolutely fine — hand-run skills stay lane-aware through their own slim gates, which go silent when route already covered the endeavor."

— Added 2026-06-06, source: user directive (ratified from the 2-Brain Harness workshop; see ledger DEC-2026-06-06-two-brain-harness and INC-2026-06-06-silent-lane-correctness. Drafted from the user's verbatim session wording and ratified as a unit. The gate/dispatch mechanics live in references/procedures/route.md and references/model-lanes.md, never inside this immutable block.)

"When the user asks to create skills, route looks for a similar skill and modifies that or builds a new one — and the skill creation decision is part of the skill-builder skill. The system gives Claude Code as much creative leeway as possible to propose; the user ratifies. Skill management is risk-tiered to the analytical brain: high-risk commands prompt for it, low-risk additions run wherever the session is."

— Added 2026-06-06, source: user directive (ratified from the 2-Brain Harness workshop. Route's no-match path hands off to skill-builder's intent-router, which owns the modify-vs-create decision; route never synthesizes the dev prefix; direct /skill-builder invocation remains the always-legal maintenance hatch. The handoff and risk-tier mechanics live in references/procedures/route.md and references/procedures/intent-router.md, never inside this immutable block.)

"The orchestrator has an army of minions, bounded to a platoon: delegation is justified only by model-fit (cross-lane work) or context isolation (unbiased evaluation), never by token efficiency or speed. Every minion is pinned to one of the two brains. A minion that discovers ambiguity returns the question to the orchestrator — it never guesses."

— Added 2026-06-06, source: user directive (ratified from the 2-Brain Harness workshop, panel-bounded from "army" to "platoon" per the fleet-mechanics review. The delegation rationale vocabulary, AMBIGUOUS sentinel, and fleet-hardening mechanics live in references/lane-delegation.md, never inside this immutable block.)

"No user should ever be asked this question. No model switching should be requested during the audit process or any function of skill-builder. However, I would like to mention that there be a disclaimer that must be accepted by the user before proceeding with audit. The disclaimer should mention that skill-builder is designed to be used with Opus 4.7 or higher model. However, skill created with skill-builder are backwards compatible with earlier models. Please backup your CLAUDE.md and .claude directory before proceeding."

— Added 2026-06-06, source: user directive (issued in reaction to the audit Step 4f batched switch prompt — "this question" refers to that AskUserQuestion instructing the user to run /model. Eliminates every model-switch request across skill-builder: the audit 4f switch prompt, route's dispatch-time lane preflight prompt, the embedded MODEL-LANE-GATE preflight prompt, and route's high-risk analytical-brain prompt all become report-only advisories. Supersedes prompting mechanics only, newest-wins, user-ratified 2026-06-06: the 2026-06-01 "with prompting, or not" resolves permanently to "or not"; the 2026-06-06 "at most one prompt per endeavor" resolves to zero switch prompts; the 2026-06-06 "high-risk commands prompt for it" becomes a one-line advisory. The lane system, the audit's single onboarding question, and the every-audit Lane→Model picker are unchanged per the same ratification — they configure the mapping and never request a switch. The disclaimer-acceptance checkpoint lives at the top of references/procedures/audit.md; advisory mechanics live in audit.md § Step 4f and references/procedures/route.md, never inside this immutable block.)

"likewise, I would like to prevent questions like this from happening, too. ... The audit command should be as automated and streamlined as possible. There shouldn't be any hard questions like this for the user."

"I don't mind the two questions for choosing the creative model and analytical model. that needs asked every time audit is ran, regardless. Just limit any additional questions. Always do the work, instead of suggestion to skip work that will improve the system."

— Added 2026-06-06, source: user directive (first clause issued in reaction to audit Step 6's batched execution menu — "questions like this" refers to that Fixes/System multi-select AskUserQuestion; "likewise" extends the same-day no-switch-prompt directive from model-switch prompts to execution menus. Second clause is the user's clarification in the same session: the Lane→Model picker's two model questions are asked on EVERY audit run, regardless; everything else is limited; improvement work is DONE, never offered as skippable. Together they abolish audit's Step 6 execution menu and every mid-audit decision question: disclaimer acceptance (audit Step 0, whose backup warning is the consent instrument) authorizes the run — audit scans, reports, then auto-executes its recommended fixes and terminal route tasks as a sequential TaskCreate list, including bootstrap-mode CLAUDE.md extraction at high confidence and Awareness Ledger creation, with agent panels — never user menus — resolving judgment; ambiguity resolves to the conservative alternative or DEFERS to the report's Deferred Items table with a ready-to-run command, never a guess, never a question, never a silent skip. Only genuinely destructive or ratification-gated work defers: strip deletions, convert/migration (inline sacred gates), quarantine repairs of hand-authored files, protective/unrecoverable dead wiring, and git-dependent fixes in no-VCS projects. The only questions any audit may ask are exactly three: the Step 0 disclaimer, the one-time 4f-setup onboarding, and the every-audit Lane→Model picker. Supersedes execution-menu mechanics only, newest-wins: Rule 3's "offers the user a choice", the Step 6 menu, the bootstrap extraction menu, quick-audit's per-item y/n offer, and the under-audit post-action-chain menu all become automatic; standalone commands invoked outside audit keep their own menus. The AUTO/DEFER tiering and execution mechanics live in references/procedures/audit.md § Step 6, never inside this immutable block.)

"The 2026-05-11 hooks-in-source exception extends to the PowerShell companions of the same two hooks — protect-directives.ps1 and unique-persona.ps1 — so Windows hosts keep the mechanical backstop. The exception set is exactly these four files: the two bash originals and their two PowerShell ports. Nothing else about the no-hooks-distribution rule changes; wiring into settings.local.json remains host-local, and the hooks procedure wires the OS-appropriate variant."

— Added 2026-06-06, source: user directive (ratified via AskUserQuestion — "Ship .ps1 companions" — during the cross-platform installer session; see ledger DEC-2026-06-06-cross-platform-installer. Drafted from the ratified option's stated scope and ratified as a unit. Amends the 2026-05-11 exception's file set only; that directive's text above stays verbatim. The .ps1 ports are fail-open and remain dormant on any host until wired via /skill-builder hooks; the port implementations live in skill-builder/hooks/, never inside this immutable block.)

"When you give route a task, it reads the whole course of action it's been handed and picks the dominant hemisphere for the job — the brain the main loop will mostly run in — and relies on the agents for the rest. Route can't switch the model itself, but it's the one door allowed to ask: when the dominant hemisphere doesn't match the current session model, route asks the user to run /model and waits before dispatching. This doesn't override bringing up a skill manually — hand-run skills stay advisory-only. This restores route's dispatch-time ask, superseding (newest-wins) only the route clause of the 2026-06-06 No-Switch-Prompt directive; audit and the per-skill gates stay report-only."

— Added 2026-06-07, source: user directive (ratified "ratify" after a 3-agent fidelity/conflict/premortem panel tightened the verbatim wording. Restores route's dispatch-time ask ONLY: when the dominant hemisphere — the matched entry skill's PRIMARY lane, or the task's lane on the no-match path — does not match the active model, /route alone may ask the user to run /model and wait. Route can never switch the model itself; a tie/UNCONFIRMED lane resolves to the analytical brain and never asks; off-hemisphere steps delegate to lane-pinned agents. Supersedes newest-wins ONLY the route-dispatch-prompt clause of the 2026-06-06 No-Switch-Prompt directive — audit Step 4f, the per-skill MODEL-LANE-GATE, and hand-run invocation stay report-only/advisory-only. The ask mechanics, dominant-hemisphere resolution, tie default, and assessment-based endeavor coverage live in references/procedures/route.md § Canonical Dispatch CHECKPOINT clause 2, never inside this immutable block.)

"Hand-run skills stay non-blocking on a lane mismatch, but the advisory must name the exact remedy: state the preferred model and the literal command — run /model <preferred> and re-invoke — then proceed as-is. Never a question, never blocking, and the skill still can never switch the model itself."

— Added 2026-06-11, source: user directive (ratified via AskUserQuestion — "Strengthen the advisory (Recommended)" — after a 3-agent research/skeptic/premortem panel reviewed the hand-run vs route-door asymmetry; drafted from the ratified option's stated scope and ratified as a unit. Amends ADVISORY WORDING ONLY, superseding (newest-wins) the 2026-06-06 No-Switch-Prompt directive's never-name-/model mechanic for the per-skill MODEL-LANE-GATE advisory line alone: naming the command informationally is now REQUIRED there; asking a question, blocking, or switching remains forbidden. The 2026-06-07 route-ask directive's door ask, audit Step 4f's report-only advisories, and the hand-run advisory-only rule are all unchanged. The advisory template lives in references/procedures/route.md § Step 8c clause 4, never inside this immutable block.)

"build that scrub loop for text and images.. and make sure we do research around these topics an explicitely update, through audit, these mechanisms for any skill that manages this type of workflow"

"But, i'd like item #2 to build new skills or funciton within existing skills of the project to facilitate all these points?"

— Added 2026-06-11, source: user directive (the scrub-loop build order, issued with nine accompanying scrub principles — detection philosophy: clustering, not signals; three tiers of tells; the subtle tells that survive review; fixes introduce new tells; protect the voice, don't just hunt AI; context-isolated validation; severity architecture; SEO/snippet text conflicts with voice; keep the pattern library living. The nine principles are preserved VERBATIM in references/creative-integrity.md § The Nine Scrub Principles — user-origin, immutable there — never paraphrased into this block. The second clause ("item #2" refers to the Creative Integrity audit check) was issued the same day after the first implementation shipped report-only: it upgrades audit Step 4c-bis from report-and-defer to BUILDING the missing scrub machinery — new functions within existing skills, and new evaluator skills where none exist. Build mechanics were premortem-hardened and ratified as a unit: builds are strictly ADDITIVE (a build never rewords hand-authored text and never touches an immutable block); build-into-existing fires only when the loop leg is demonstrably absent (equivalence-uncertain degrades to DEFER, never to a competing chain); whole-new-skill scaffolding fires only on DECLARED creative-lane evidence, never inferred classification; voice-dependent gates in built scaffolds are advisory-only when the project has no voice profile; builds are atomic-or-absent with code-eval-grade modifiable-true seams. Scrub loops themselves stay per the design panel's conservative scope (auto-fix MUST FIX + hard-directive flags only; best-so-far + divergence abort; humanity floor; fixability classifier; provenance guard). Research around these topics runs on the coding model per the 2026-06-06 research-precedence directive. The compliance checklist, canonical loop spec, build policy, scaffolds, and research digest live in references/creative-integrity.md, never inside this immutable block.)

"Okay, we have a problem with the text-eval not being installed if nothing yet exists... check out this correspondence..."

"... and I also want to make sure that existing skills that do the function of text-eval get updated with audit, no questions asked."

"yeah, keep in mind, we may be adding more "signs" to flag in the future, so everything will need to be forceably upgraded."

*— Added 2026-06-12, source: user directive (issued with an attached audit transcript in which an all-coding-lane project received no evaluator — zero declared creative lanes meant the 2026-06-11 new-skill tier never fired, and the audit defended the non-build as correct; the user rejects that defense. First clause: audit installs the text-eval evaluator scaffold whenever nothing serving that function yet exists — the precondition is ABSENCE ALONE: the signal-based, never name-based existence test finds no skill performing the evaluator function AND no text-eval skill directory exists (mirroring the code-evaluator ensure-exists precedent, audit.md § Step 4a-bis). Lane declarations no longer gate the build; the scaffold's own lane: creative frontmatter is authored by the build, never inferred from any existing skill, and the project's Skill→Lane table is never touched. Supersedes newest-wins ONLY the "declared creative-lane evidence" precondition of the 2026-06-11 build clause's new-skill tier (and its inferred-only→DEFER row); every other hardening of that clause stands unchanged — strictly additive builds, demonstrably-absent panel confirmation for build-into-existing, equivalence-uncertain→DEFER, atomic-or-absent, name-collision guard, advisory-only voice gates absent a voice profile. Panel-adopted guards ratified with this directive: a project-level <!-- creative-scrub-build: off --> marker in references/model-lanes.md silently suppresses the new-skill build (declarative opt-out, never a question); lanes unconfigured → the scaffold's agent ships with model: absent and flagged, never an invented ID (Audit Agent Model-Assignment Gate clause 4). Second clause: skills qualify for updates by FUNCTION — the lane-free § Scope signals (evaluator, scrub, voice machinery) already implement this — and "no questions asked" means audit APPLIES the updates instead of deferring them: pattern-library gap appends into hand-authored libraries move from DEFER to AUTO, written only as ONE machine-owned origin: skill-builder | modifiable: true appendix region at the end of the library file — existing bytes never modified, structural fit verified before the write (no parseable fit → paste-ready DEFER row, the atomic-or-absent discipline), the .scrub-gaps.acked sidecar is the sole dedup authority (acked slugs never re-append even if equivalence misses a user-moved row), and the append fires only when the skill's evaluator demonstrably grounds against the full library file (else DEFER — the inert-sidecar lesson, DEC-2026-06-08). Immutable blocks stay FLAG-NEVER-TOUCH; equivalence-uncertain stays silently skipped. Third clause (same session): the shipped signs catalog will keep growing, and growth propagates FORCIBLY — whenever the shipped catalog version anchor (references/creative-integrity/version.md) is newer than what an installed evaluator or library was last checked against, audit MUST run the gap comparison and apply the AUTO appends in that same run (never skipped, never offered, never a question); scaffold-generated libraries' machine-owned regions are version-synced to the current catalog the same way code-eval sync refreshes its shipped references; the ack sidecar suppresses only slugs whose shipped entry is unchanged — new signs are never acked and always land. Design panels are agents, never user questions, per the 2026-02-22 agents directive. The build and tiering mechanics live in references/creative-integrity.md § Audit Po

<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->