peckworks-skills-laboratory: Project Brief (read me first)

A workshop for developing, testing, and refining skills for Claude and other LLM agents. Each skill is a self-contained SKILL.md (plus supporting files) in a flat skills/ namespace.

Privacy: this repo is PUBLIC (github.com/srfinch17/peckworks-skills-laboratory, since 2026-07-08; every push ships to the world). NEVER write the maintainer's real name into any file here (code, comments, docs, skills). Refer to "the user" / "the maintainer". Personal, identity-specific content (a personal logbook, a real reader profile, named companies from the job search, private-memory-store paths) lives in the maintainer's PRIVATE memory or in gitignored local files; only *.template.md schemas are tracked. The full pre-public history lives ONLY in the local private-history branch: NEVER push it anywhere.

The rule covers DISCLOSURE, not just IDENTITY (widened 2026-08-10, after a sweep found the name rule had correctly caught nothing while two other categories leaked for weeks):

• No verbatim quotes of the maintainer, and nothing about their emotional state, health, well-being, or job-search status. A field case is logged for its defect, dated and specific; the person in it is third-person and generic. The mechanism is never the quote.
• No absolute machine paths. ~/, %USERPROFILE%, or <repo> — never C:\Users\<name>\, which leaks the OS username and, through it, the GitHub handle and the person.
• The test is not "would this embarrass me?" but "does this let a stranger who found this repo learn something about the maintainer they did not consent to publish?" These files are attributable, permanent, and indexed; a push cannot be taken back.

Layout

skills/<skill-name>/SKILL.md   # one skill per folder; required frontmatter: name, description
_template/SKILL.md             # copy to start a new skill
docs/specs/                    # design specs (YYYY-MM-DD-<topic>-design.md)
install.sh                     # idempotent: links every skills/* into ~/.claude/skills
README.md · CONTRIBUTING.md    # what a skill is · the test-first workflow + conventions

How we work here

• Test-first (TDD for skills). No skill ships without first watching an agent behave WITHOUT it (baseline), then verifying the skill changes that behavior. RED → GREEN → REFACTOR. Full process in CONTRIBUTING.md. This applies to edits too, not just new skills.
• Frontmatter rules: name (letters/numbers/hyphens only); description third-person, starts with "Use when...", describes ONLY triggering conditions; never summarize the workflow (agents follow the summary and skip the skill body if you do). Write the description as a folded block (description: >-). A plain one-line value that contains a colon-space is invalid YAML; the loader silently drops it and the skill never triggers (four skills sat that way for weeks until 2026-09-30). python tools/check_frontmatter.py catches it.
• Match the form to the failure: prohibitions + rationalization tables for discipline failures; positive recipes/contracts for wrong-shaped output.
• One excellent example beats five mediocre ones. Separate files only for heavy reference or reusable tools.
• Cost discipline: low-judgment work (bulk mechanical edits, sweeps, memory/notes housekeeping, CLAUDE.md touch-ups) goes to cheap subagent models (haiku); the main model writes the rules, reviews the output (cheap models introduce real defects), and owns anything committed or pushed.
• Build-subagent model policy (the biggest token lever — a plan build fans out to 15-20 subagents; a token audit 2026-07-21 measured ~1-2.3M/build, dominated by premium-model reviewers, not implementation): implement/transcribe subagents and per-task reviews run on haiku (a light regression check); sonnet only for a genuinely hard implement; fable/ opus reserved for the ONE final whole-branch review and the adversarial panel. Never let bulk build subagents inherit the premium main-model tier. The thorough pass is the single final review, not a premium review after every task. No duplicate review rounds (same discipline as review-court). Right-size decomposition too: fewer, coherent tasks beat 20 tiny ones, since each subagent re-pays context-read overhead.

Installing these skills

The skills/ folder is the workshop, not a discovery path. Claude Code loads skills from ~/.claude/skills/, so each skill is symlinked there (edit in the repo → the installed copy updates; one source of truth). Run bash install.sh to (re)create the links: it is idempotent, auto-discovers every skills/*/SKILL.md, and won't clobber a real non-symlink. On Windows without Developer Mode it falls back to directory junctions (no privilege needed; added 2026-09-30 after a machine turned out to have ZERO lab skills installed because ln -s failed). Per-machine bring-up is driven from the Dropbox global memory (ClaudeGlobalMem/technical/skills_manifest.md + install-skills.sh), which calls this script.

Per-machine, and not synced by Dropbox: ~/.claude/ lives outside Dropbox, so the install symlinks (and any hook wiring in ~/.claude/settings.json) must be reconstituted on each machine; install.sh handles the symlink half. Skills load at session start, so restart to pick up changes. (.gitattributes pins *.sh to LF so the script can't get CRLF-mangled.)

Skills here

managing-assumption-debt (status: deployed + tested + hooked)

Catches high-leverage unstated assumptions early, before they compound into expensive misunderstandings. Two-tier design:

• Engine (here, shareable): skills/managing-assumption-debt/SKILL.md + LOGBOOK.template.md + hooks/. The concept, the four debt types + tells, the triage formula, the bidirectional escalation vocabulary (light flag / "I'm willing to fight about this" / sunk-cost call), the trigger moments, and the logbook loop.
• Fuel (the maintainer's PRIVATE memory, not in this repo): a personal logbook of real assumption-debt episodes. The engine only says "if a personal logbook exists, consult it."
• Hooks (hooks/, generic, logbook path passed as an argument): inject_standing_layer.py (SessionStart: re-injects the logbook's standing layer each session
  • a 7-day human reminder) and capture_on_compact.py (PreCompact: prompts a capture pass before context is summarized). Wired in the maintainer's live ~/.claude/settings.json.
• Design of record + full test log: docs/specs/2026-06-30-assumption-debt-design.md.

Key lesson from testing this skill (applies to ANY memory-type skill): a SKILL.md does not self-improve, and modern models already have strong in-the-moment judgment whenever the facts are in context. The failure this skill prevents is context LOSS across sessions/compaction, which is NOT reproducible in single-shot subagent tests (any fact in the prompt is present and attended to). So the load-bearing value lives in the MEMORY + HOOK re-injection layer, not the judgment prose. Invest there. The engine remains worth keeping: it is safe (does not over-fire), it adds scope-probing + a shared escalation vocabulary, and it gives the discipline to consult the logbook.

Data audit 2026-11-05 (178 episodes mined, see the spec's last section): the logbook half works and has seeded three skills and five guards; the live-protocol half left no trace in 108 sessions, 29 percent of episodes were admitted repeats, and the injected layer had not changed in 36 episodes. Revised: seven observed classes replace the four types (artifact-trust holds 46 percent), every episode carries a Class / Recurs line, the hook injects the top three recurring classes with repeat counts, nudges when ten episodes land with no change to the standing weights, and names episodes over 150 words. Success measure for the next audit: the repeat share over the newest 30 episodes (18 of 30 at revision).

Next (optional): a PreToolUse boundary guard (advisory-inject hard-stop before push/publish/send).

iterative-lesson-refinement (status: field-proven engine port, 2026-07-05)

Hardens a teaching/study artifact into defend-cold form by testing it against ISOLATED persona subagents (NOOB / BASICS / EXPERT), grading an escalating cold quiz, and folding generalizable teaching lessons back into the skill. Two-tier, like assumption-debt: the lab holds the scrubbed engine (the loop, quiz design, the 18 teaching lessons, the cheap 2-agent "targeted validation" mode for revamps); the maintainer's topic-specific run logs stay in the private workspace. Provenance: 3 topics, 6+ passes, documented RED baseline (a clean-reading page scored 10/10 on recall while hiding real holes) and GREEN results in the skill's Provenance section. Single source of truth (2026-07-05): the maintainer's former personal copy was archived to private memory and replaced with the install.sh symlink, so this lab copy IS the live skill. Future "fold the lesson back into the skill" steps edit THIS file, which lands in a public repo, so each added lesson must stay generalizable and scrubbed (the skill already mandates recording only generalizable lessons, never learner-specific facts).

nemesis-review (status: field-proven; deployed)

An adversarial review run by a fictional expert who wants you to fail but whose ego depends on being unassailable, so he will not fabricate, inflate, or cry wolf. He concedes (through gritted teeth) whatever is genuinely sound. The hostility is a lens for candor and effort; the honesty gate keeps the output signal. Three load-bearing elements: motivated (professional, not personal) hostility, the honesty gate, and a mandatory concession section (the trust anchor and highest-value signal). Skill: skills/nemesis-review/SKILL.md, with the reusable dispatch charter inline.

• Orchestration rules: run the nemesis as an ISOLATED subagent beside 2 to 4 dispassionate domain skeptics (breadth), then verify every finding yourself before acting; hostility's failure mode is false positives. Its sibling paladin-review (below) runs INDEPENDENTLY — convene it by risk (author-outcome / footgun / under-sell), not automatically; default review = nemesis + one (mandatory-pairing rule reversed 2026-07-21 after a token audit).
• Provenance: first proven 2026-07-01 on the peckworks-bonsai trunk-engine plan (found net-new issues the polite reviewers missed; its concessions independently validated the architecture). Full episode lives in the maintainer's PRIVATE memory (nemesis-review-works), not this repo.

paladin-review (status: born here 2026-07-19; RED/GREEN tested)

The supportive mirror of nemesis-review: a reviewer who owes you an unpayable life-debt (you saved his child) and repays it only by making you WIN and keeping you from harm. Same rigor, opposite motive — the nemesis attacks whether the work is sound; the paladin protects your outcome, hunting the two things a soundness reviewer structurally can't: where you're about to hurt yourself (a destructive / irreversible / secret-leaking footgun) and where you're under-selling a real win. The whole safety lives in a dual honesty gate — comfort-is-betrayal (no flattery) AND a-false-alarm-gets-you-tuned-out (no crying wolf) — guarding both sides of its two-sided failure mode. Skill: skills/paladin-review/SKILL.md, dispatch charter inline.

• Orchestration: run it ISOLATED beside nemesis-review + domain skeptics; as orchestrator, verify every alarm (paranoia over-reports, the mirror of the nemesis's false positives) and DISCOUNT its praise (motivated), weighting its warnings. Never substitute it for a correctness review — a capable neutral reviewer already catches most defects and secret leaks.
• Provenance: RED/GREEN at authoring (2026-07-19). Two neutral baselines caught the planted secret leak but MISSED and inverted the under-sell; the charter surfaced it plus the fixed bug's blast radius, while visibly refusing to flatter or cry wolf. Design spec: docs/specs/2026-07-19-paladin-review-design.md.

review-court (status: born here 2026-07-19)

The review-time half of the "holy spirit," completing the trinity: nemesis and paladin are JUDGES; the court is the HARNESS that guarantees the whole ceremony runs instead of a hand-rolled partial one (the founding failure: 2026-07-07, seven hand-rolled reviews silently dropped the pairing rule). The ceremony: (0) intent packet first — the author's verbatim ask, the artifact's purpose, the irreversible boundary in play, handed to EVERY reviewer so action-vs-intent is reviewable; (1) invoke each CHOSEN reviewer skill freshly, never from memory; (2) size the panel to the risk (default nemesis + one; full court ≤4, no auto re-run); (3) one isolated parallel batch; (4) orchestrator verify-pass (verify findings, re-derive numbers, cross-check concessions, DISCOUNT paladin praise); (5) archive receipts BEFORE any cleanup; (6) converged-first report + same-session provenance. Orchestrates only, never judges; complements (never replaces) the mechanical tripwire. Dialed down 2026-07-21 (token audit): no mandatory pairing, court capped at 4 reviewers, the automatic second re-verify round removed. Cross-session discipline skill — value lives in reading the checklist at convening time, same testability class as the memory-type skills. Skill: skills/review-court/SKILL.md.

avoid-sycophantic-blowback (status: field-proven; 3 validations logged)

Kills the hype-then-crash cycle when reporting news: calibration in the same breath as the event (never below the fold), a signal-strength taxonomy stated out loud, mood counterweighting in both directions, and the one-word interrupt codeword. Born 2026-07-13 from a staffing firm's templated shortlist email that got amplified into a real emotional crash. Genericized 2026-08-10: the four field cases were rewritten third-person after a privacy sweep found this file was the repo's most personal, carrying verbatim quotes about the maintainer's job search and well-being under a public, attributable handle. The rules were untouched — the mechanism was never the quotes. Log future cases the same way: dated and specific about the defect, generic about the person.

capturing-judgment-as-data (status: born here 2026-07-29; extended 4×)

When correctness is a human's opinion (visual, tone, taste, UX feel), their verdicts must become a reproducible record instead of unrepeatable comments. Laws for structuring rounds, frozen baselines

• rollback as first-class, and the screening failure mode (looking FOR fixes instead of AT the work).

look-driven-iteration (status: field-proven; synced from live 2026-08-08)

The cheap-render → grounded-feedback → measure-then-fix loop for work judged by eye. Its core claim is a spending rule: never burn expensive verification on a look the human has not approved yet. Sibling of capturing-judgment-as-data (that one records the verdict; this one gets it cheaply).

guarding-silent-failures (status: born here 2026-08-09)

Operations that fail while returning valid-looking output — CAD booleans, renderers, cleanup scripts, bulk edits. Distilled from one peckworks-cadmesh day that hit six of them, including a cleanup that reported removing twelve files it never touched. The rule that generalizes furthest: a clean result from a probe is only evidence if the probe was first shown to fail.

cadquery-modeling (status: field-proven technical recipe; harvested 3×)

CadQuery/OpenCASCADE recipes: picking edges by what they ARE (with an asserted count) rather than by point selectors that lie, and topological selection when no geometric test can work. Pure recipe skill — its evidence is the recipes, not a field-win log.

stretching-frontier-tokens (status: ported into the lab 2026-08-10)

Spending the strongest model only where the frontier matters: measure the transcript before theorizing, climb DOWN the ladder (script it → cheapest capable model → frontier only for diagnosis/design/human-facing prose), and the delegation-contract rules. This is the skill that encodes the build-subagent model policy cited above. Lived only in ~/.claude/skills/ until 2026-08-10 — unversioned and unbacked-up; ported so the policy has a source of truth.

deletion-tripwire (status: born here 2026-07-19; TDD'd; wired live same day)

The MECHANICAL third member beside the review pair: a PreToolUse hook that blocks destructive shell commands (rm -r*, Remove-Item -Recurse, robocopy /MIR, git reset --hard, ...) until the enumerate → confirm → ledger → approve protocol runs. Born from a public field disaster (a Windows.old cleanup that followed junctions into live Documents/Pictures after the agent predicted "safe") and a same-day local miniature ("clean up any junk" deleted a skill's test receipts). Two rules it enforces: blast radius = everything REACHABLE (links included), and safety comes from ENUMERATION, never prediction. Personas can't catch this class - no court is in session during a casual cleanup - so it is a hook, not a prompt. Engine: skills/deletion-tripwire/ (SKILL.md + hooks/guard_destructive.py + assert-based test suite). Wiring is per-machine in ~/.claude/settings.json (PreToolUse, Bash|PowerShell, ledger default ~/.claude/deletion-ledger/); install.sh handles only the symlink. Proof at wiring: the hook blocked the author's own harmless rm -rf probe live in-session. Spec: docs/specs/2026-07-19-deletion-tripwire-design.md.

educational-html-prep (status: field-proven; ported from personal 2026-07-05)

The Feynman teaching-page craft: plain-claim → analogy → inline-SVG diagram → defend-cold Q&A, the mission-control THEME tokens, the reusable assets/teaching-kit.css component kit, the inline-SVG patterns (references/svg-diagrams.md), and the serve+screenshot visual-verify workflow. The maintainer's most-used homegrown skill (11 invocations at port time). Scrubbed port of a personal skill that accreted rules across ~15 pages; some content is specific to the maintainer's career workspace (dashboard registration, back-link): kept because this is the live skill (symlinked), not a genericized fork.

emoting-on-8x8 (status: field-proven; ported from personal 2026-07-05)

Designing legible expressions/animations for a 64-pixel LED matrix at low brightness: the silhouette test, brightness-band color math, downsample-don't-freehand, motion-carries-meaning, iterate-live-promote-winners. Companion to the maintainer's public esp32s3matrix repos.

versioning (status: field-proven; ported from personal 2026-07-05)

One canonical VERSION file stamped into every independently-deployed artifact, each made self-reporting, plus a drift check and the "a bump is not live until its artifact redeploys" rule. Distilled from the esp32s3matrix/expression-studio repo split; also the pattern behind clipmeta's release flow.

feynman-explanation (status: born here 2026-07-10; scrubbed; RED/GREEN tested)

The plain-language explanation discipline: one idea at a time, a real-world analogy before the code, define the SYMBOL (not just the logic) and spell out the acronym the FIRST time each appears, kill "obviously", open the real code instead of quizzing memory, and proofread output for jargon density + length at write-time. Includes the field-proven techniques (map-first and "I'll hold it", explain with actual values not abstractions, collapse overwhelm to one next action, the whole-tiny-TDD-loop unit of progress, explain-back checkpoints) and the training-wheels protocol (a per-project "mastered" list; once the learner owns an item, stop re-glossing it, per item). Two-tier like the others:

• Engine (here, shareable): skills/feynman-explanation/SKILL.md + MASTERED.template.md (the mastered-list schema). Scrubbed to "the learner"/"the user".
• Fuel (per-project, local): the real MASTERED.md lives in whatever project is being worked in and is gitignored; only the template is tracked here.
• Scrubbed public port of the maintainer's private, high-priority communication rule (preferences.md, Communication, 2026-07-09: ADD + new-to-a-language + Feynman duty, training-wheels-off-on-request, spell-out-acronyms). Seeded from field notes taken during the 2026-07-09/10 codebase-rag eval + CI build, where the method demonstrably kept an overwhelmed learner engaged and able to defend the result. Testability note: unlike the memory-type skills, most of this one is write-time output shaping and so is genuinely testable in a single isolated run; only the mastered-list persistence is the un-testable cross-session layer.

sandwich-test (status: born here 2026-07-22; RED/GREEN/REFACTOR tested; shipped + first field win same day)

Closes the intent–interpretation gap at instruction handoff — the PB&J-game failure where an agent executes a plausible-but-wrong literal reading while feeling fully compliant. Two halves: a live tiered protocol (silent check → state-the-reading in one line → hard-stop ask at the destructive/irreversible/external line, plus a rationalization table) and a cold-reader audit ("sandwich-test this") that rebuilds the game's barrier with isolated haiku subagents given ONLY the artifact text, because an agent cannot honestly play the naive reader for instructions whose intent it already knows. Five-class misread taxonomy (wrong means, wrong object/scope, literal-vs-intended, missing done-criteria, scope-creep). Fires one layer earlier than its neighbors: assumption-debt (sessions), nemesis/court (soundness), deletion-tripwire (execution). Spec + full test log: docs/specs/2026-07-22-sandwich-test-design.md.

rehearsing-against-a-counterparty (status: born here 2026-08-24; field-developed over 31 runs)

Tests what a high-stakes message CAUSES someone to do, not whether it reads well — the class of defect no review pass finds, because reviewers evaluate the document. Run N independent counterparty agents (fresh general-purpose subagents, never forks of yourself, which just reproduce your own conclusions) against the VERBATIM artifact, with your own replies governed by a written protocol rather than a script. The distribution across runs is the finding; any single run is an anecdote.

• The central finding, from a controlled pair: the reply protocol wins the headline number, but the DOCUMENT wins every term underneath it (a question absent from the artifact can never be answered). A review that only hardens the prose is doing the half that was never at risk.
• Two rules that generalize past negotiation: run past the concession (rounds that stopped when the number settled all reported success; four messages deeper they were dodging 6 of 7 written items), and harden the opponent each round with the tactics the last round's debriefs revealed.
• Highest-yield debrief question in the method: "what did they fail to ask that you were RELIEVED they did not ask?" — it names the hidden information that would have collapsed their bluff.
• Two-tier, like the other fuel skills: the engine + KIT.template.md (the dispatch-brief skeleton, scrubbed) live here; filled kits stay in the maintainer's PRIVATE memory — a real one holds the verbatim artifact, a named counterparty, and their hidden economics. The 31 run transcripts are gone (they lived in subagent contexts); the 6 surviving kits were archived out of a temp scratchpad to private memory on 2026-08-25, before cleanup could reap them. No design spec: there is no log left to write one from, and the findings are already harvested into the SKILL.md.
• Privacy note: the Field notes section is a scrubbed third-person field case per the disclosure rule above — dated and specific about the defects, generic about the person, and explicitly labelled so the simulation's figures can never be read as terms of a real agreement.