CLAUDE.md — working in this repo

This is a library of Claude Code skills (skills/<name>/SKILL.md) plus a small Node CLI (bin/, lib/) that installs them. The skills are the product; the CLI is plumbing.

Commands

npm test                          # node --test test/cli.test.js test/skills.test.js test/draw-options.test.js test/context-diet.test.js — run before reporting any change done
node bin/claude-skills.js list    # what the CLI renders from skills/*/SKILL.md frontmatter

There is no build step and no linter. Formatting is by hand; match the surrounding file.

Rules for skills

1. Skills are independent. A skill may reference another skill only if it lives in this repo's skills/, always as "if installed" with a complete inline fallback. Never reference, depend on, or credit third-party skill packs (superpowers, gsd, plugin skills). Grep skills/ for external names before finishing. A skill that composes with several others (see autopilot) lists them in a routing table — one row per skill with an observable predicate, a probe command that decides present/absent, and the inline fallback — and its report carries a "Skills used" slot, so a present skill cannot be skipped silently: "if installed" alone was observed to let a weaker model take the fallback with the skill present.
2. Frontmatter is real YAML. name: equals the directory name. description: is at most 1024 characters and is written as a folded block scalar (>-) when it wraps; the CLI parser strips the indicator (lib/skills.js) and test/skills.test.js fails if one leaks. Validate with a real YAML parser when in doubt, not only npm test.
3. Descriptions say what, never how. Outcome and scope in the first sentence, then Use this skill whenever the user says "…", "…", "…" — even if they don't name the skill, then optional non-triggers naming the near-neighbor skill. No workflow steps in the description — a model that reads the steps skips the body. Three trigger phrases is the floor.
4. Bodies are written for the weakest executing model. Every load-bearing rule carries a ❌/✅ pair. Every assertion the skill asks for has an evidence gate. Report-producing skills state that zero findings is a valid outcome. Command-running skills state that an unobserved result is not run, never passed. Prefer a required slot in a template over a prose reminder, and a conditional on an observable predicate over a rule with exemptions.
5. Keep SKILL.md near 150 lines; long reference material goes to skills/<name>/references/. _template/SKILL.template.md at the repo root is the scaffold (it lives outside skills/ on purpose so it is never published or installed). A skill that runs tools keeps them inside its own directory — scripts/ for executables, docker/ for container build contexts, assets/ for config templates — and install copies the whole directory, so they ship. record-browser-test predates this and keeps its Node scripts in references/; match the skill you are editing.
6. The write-a-skill skill is the authoring path. It encodes the rules above, requires a baseline-versus-skill behavior test for discipline skills, and updates the README table. Use it rather than hand-writing.
7. Nothing sensitive lands here. This library is public and its history is permanent, so credentials and tokens, personal data (names, emails, usernames, paths carrying them), internal hostnames and IP ranges, real repo/system/database names, organization and client names, ticket numbers, and real record IDs never enter a skill — not in an example, not in a reference file, not in a commit message. Use placeholders (<org>, example.invalid, <repo>, ~/projects/<name>) and invent examples rather than sanitizing real ones; a redacted real case still leaks its shape. Porting a skill in from another machine is where this breaks, so check the draft before saving — write-a-skill step 9 carries the class list. Every skill should read as if anyone could have written it, anywhere. A skill that is only useful with a real host, path or IP does not belong in this library at all: keep it in a separate private skills folder outside this repo and link it into ~/.claude/skills the way the library skills are linked (a junction on Windows, a symlink elsewhere).
8. A skill change is not done until the docs match — standing rule. Any edit under skills/ (new skill, rename, removal, or a material change to what a skill does or how it composes with others) is finished only when, in the same change:
   • README.md is updated: the skill's row in the skills table (alphabetical, long-form voice, links to the skills it composes with), the "Which skill?" routing tables if the routing changed, and the "How the skills fit together" section plus docs/skills-flow.svg if the flow changed.
   • CLAUDE.md is updated if the change adds or alters a convention, a command, a file location, or the flow described here.
   • npm test passes — test/skills.test.js fails when a skill directory has no README row, so the row is enforced; the rest is on you. Before reporting done, re-read both files' affected sections and state what you updated.
9. A skill that runs tools is verified in three layers, and the report names which ran. (a) Parse-check: PowerShell with [System.Management.Automation.Language.Parser]::ParseFile, Node with node --check. (b) A logic harness: a throwaway directory with real git repos, a fake CLI first on PATH (a docker.ps1 that appends its arguments to a log and answers ps), and assertions on what was generated or called — cover every branch, including the refusals. (c) One real run of the whole lifecycle — start, observe, stop, clean up — against the real dependency, leaving the host exactly as found. Layer (c) must exercise every distinct way the tool talks to the real dependency (each protocol, each endpoint), because a stub answers whatever it was written to answer: a browser-control call that only ever ran against a stub is not run, even when its output said success. Every such call checks the response and fails loudly; never swallow an empty one. A layer that was not run is not run. Tools never modify tracked files in the user's application repo, say where they keep state, and refuse to run on placeholder config.

Skills that ship tooling

• worktree-sandbox — scripts/wt.ps1 (PowerShell 7), docker/browser/ (a Chromium image with a noVNC live view and a CDP endpoint), assets/config.example.json, references/. Contracts a change must not break: the application repo's tracked files are never written (the only repo-side change is the worktree entries wt creates); one stack per branch, each with its own slot and ports; worktrees are named <repo>-wt-<branch without feature/>; a new branch starts from the fetched base; shared base worktrees refresh only when behind and only the service on them restarts; docker.context plus docker.pathMap translate every bind path and refuse a path the daemon cannot see; a newly started stack opens its pages (startUrl plus extraUrls) only once their services answer, and wt reload does the same; wt dashboard is a self-updating page that probes every slot's live-view port and re-reads the slot-to-branch names from a small file wt rewrites on every up and down -Purge (tiles and names update with no reload) and needs no tooling beyond the script; hooks.afterUp runs once for a newly started stack (never when it was already running, never with -NoHook) and only warns when it fails. Verify with the harness in rule 9: the stub docker.ps1, throwaway repos, and a bare repo acting as origin so develop can be moved between runs.
• dotnet-conventions — scripts/audit.sh (bash; git and, for the analyzer pass, the dotnet SDK) and eight files in references/. Contracts a change must not break: the script audits only lines added since HEAD (modified tracked files plus new untracked .cs files), maps each changed file to its nearest .csproj, builds with analyzers only on SDK-style net5.0+ projects and reports CA1849, CA2016, CA1031, CA2200, CA2000 on added lines, says why it skipped anything, and exits 1 on a hit; a .NET Framework target never raises TargetFramework or LangVersion; existing code is never edited except an optional CancellationToken ct = default parameter; the five report slots stay required. Verify with a throwaway git repo per case (clean, swallowing catch, blocking call, untracked file, src/ and tests/ layout, .NET Framework skip) and fixture runs scored from the diffs, not from the agent's report.
• draw-options — scripts/oc.mjs (Node 20+, no packages), layout builders in assets/ (common.js plus columns.js, matrix.js, tree.js, concatenated behind a const SPEC = … line and run inside the app), and references/protocol.md. Contracts a change must not break: check runs first and a non-ready state ends the canvas path with Canvas: not run; files are created by open under the task name in ~/.claude/diagrams/ (never inside a repo, never renamed afterwards); the skill only draws on a document it created or opened itself; draw validates the spec before contacting the app (unknown keys are errors), lints only the shapes it made, and throws on a remaining lint (the app rolls the draw back); remove deletes only a .tldraw file directly inside the folder (links are resolved) and only with --yes; recommended is only ever an option name the user chose; the scripts carry no comments and no machine-specific path; the skill never names another skill pack. Verify with test/draw-options.test.js (a stub HTTP server and a fake app-data folder cover the preflight states, the open/draw/finish/list/remove paths and their refusals; a fake editor runs the layout builders and checks their geometry), then one real run against the installed app pointed at a temp folder with a screenshot read — that layer is not run anywhere the app is not installed, and only Windows has been run.
• context-diet — scripts/diet.mjs (Node 20+, no packages) with its modules in scripts/lib/, a keep.json template in assets/, and references/transcript-format.md. Contracts a change must not break: scan streams ~/.claude/projects/ and emits only names, counts, sizes and dates, never transcript content; a use counts toward used and the percentage only in sessions where the item was listed; an unlisted use of a local skill still counts toward uses (so such a skill is never a candidate), and a bare-name use credits the plugin of any listed plugin:name entry with that base name; and use of a plugin's MCP tool counts for the plugin even when its server was not listed (a real-history scan caught this once, so the real scan layer must not be skipped); a plugin that supplies a PreToolUse hook, a plugin that supplies any hook, and anything in keep.json is never a candidate, and apply refuses protected ids; a plugin's hooks are read from hooks/hooks.json and from plugin.json (a path, an array of paths, or inline), a hook without a command still counts as a guard, and a plugin whose declared hooks cannot be read is protected, never a candidate; apply writes its manifest before changing anything, backs up settings.json, removes a link without touching its target, moves a real skill folder into the tool's own quarantine with a verified content hash (never the OS temp directory), refuses a git-tracked folder, and never moves a plugin's files; apply takes a before-probe (the skill text calls it the before-snapshot) and then runs verify, which takes an after-probe, both through claude -p --session-id spawned without a shell, deleting each probe transcript, and reports pass only when every entry is gone, nothing else disappeared, and the guards are intact (an unobserved check is not-observed or incomplete, never a pass); an MCP server that differs between the two probes and is not part of a changed plugin is reported as unstable, rerun and caps the verdict at incomplete instead of failing it, because servers can start intermittently (a real run saw this), while a skill, agent or hook that disappears still fails; purge needs --yes and a passing verify; the printed report slots, the Coverage: and Verdict: labels, section names (Removal candidates, Rarely used, Review by hand, Protected, Guard hooks, Same skill under several names), column names (listed, used, last seen), the protection reason text, per-item statuses (GONE, STILL PRESENT, NOT OBSERVED), FORMAT UNRECOGNIZED, unstable, rerun, verdict spellings (printed upper-case, PASS FAIL INCOMPLETE NOT-OBSERVED; lower-case in --json) and exit code 2 meaning "nothing it can judge" (exit codes 0/3/4/5 distinguish pass/fail/not-observed/incomplete) are quoted by SKILL.md, so changing any of them means updating the skill text in the same change; a skill name must be a single path segment and a skill path must sit directly in the personal skills folder of the configured home or in a <project>/.claude/skills folder (no .. segments, no prefix-sharing siblings), both in apply and in restore (which also confines a quarantined copy to the quarantine folder); scan aborts on an unreadable keep.json or settings.json, and an unreadable transcript is skipped and counted on the Coverage: line; apply recomputes protection from keep.json, the installed plugins and settings.json instead of trusting the report, and refuses to change anything when claude cannot be started unless --allow-unverified; state files are written atomically (a temp file renamed over the target; settings.json is edited through its real path, keeping its bytes, mode and line endings) with owner-only permissions where the OS supports them; errors print one-line messages and CONTEXT_DIET_DEBUG=1 prints stacks; the scripts carry no comments and no machine-specific path. Environment: CONTEXT_DIET_HOME is the whole Claude home (projects, settings.json, plugins and the state folder), wins over CLAUDE_CONFIG_DIR, and is passed to the probe as CLAUDE_CONFIG_DIR; CONTEXT_DIET_CLAUDE is a path to a .js stub run through node (a test hook only); CONTEXT_DIET_SETTLE_MS is the pause between checks for the probe transcript (default 500); CONTEXT_DIET_MODEL is the probe model (default haiku); CONTEXT_DIET_DEBUG=1 prints stacks. Verify with test/context-diet.test.js (transcripts, plugins, settings and a stub claude synthesized in a temp home; the stub answers differently on its first and second call, so the before and after probes differ), then a real scan over the real history and, with the owner's approval, one real disable-verify-restore cycle on a candidate plugin and a candidate junction. A layer that was not run is not run.
• record-browser-test — plain Node scripts in references/ (Node 22+, Chrome found automatically, nothing to install, no network). Contracts: output goes outside every repo (~/.claude/recordings/), --rehearse runs the checks without recording, play-check.mjs must replay the finished file, the receipt page is self-contained, and a default run is headless and opens nothing (--foreground and --open are opt-ins) so it never takes the user's cursor or focus. Verify with a rehearsal, one real recording, and the play-check.

Rules for the CLI

• No new npm dependencies without a reason stated in the PR; the parser in lib/skills.js is deliberately hand-rolled.
• Behavior the README documents is a contract: list, installed, install, remove, the -g/-p/-f flags. Add a test in test/cli.test.js for any new flag or output.

Git

• Commits are authored solely by Dennis Rongo. No Co-Authored-By trailers and no attribution to Claude.
• Do not commit, push, tag, or release unless asked. Releases follow the "Releasing" section of the README (npm version, push with tags, GitHub Release triggers npm publish).
• Run identifier scans in a separate command from git commit. A commit-time scrub hook matches the scan's own pattern text and blocks the commit even when the files are clean; scan first, then commit with a plain command line.
• Working files created while running skills (.claude/design-briefs/, .claude/goal-runner/, .claude/handoffs/, .claude/worktrees/) are project scratch. Keep them out of commits unless deliberately promoting a brief to documentation.

Evaluating a skill change

A skill edit is verified when a fresh sub-agent on a weaker model, given a real task in an isolated worktree, behaves differently with the skill loaded than without it, and the difference is the one the edit intended. Record what was observed. A skill you never watched change behavior is documentation. For a skill that drives real tools, give the two agents the scenario as a plan-only task (no execution) and compare what they would run, then do one real run yourself — the plan test shows the decisions, the real run shows the tool.