Claude Skills by randommonicle

claude-skills

What this is

A set of guardrails for Claude Code, the AI coding tool. Each one is a short rule that Claude loads by itself, at the moment it is about to do the thing that rule covers. Almost every one exists because that mistake already shipped on a real project.

They are not prompts or personas. They came out of the lessons-learned records of four production codebases, one of them a regulated UK property-management platform, so the examples are concrete and a few are specific to that domain. Install the lot, fork it, or read two and steal the ideas. The two that change the most behaviour for the least reading are verify-the-effect, which says never call something done because a command exited without error, and prove-it-can-fail, which says a test that cannot go red is not a test.

Four kinds of thing live here.

• Skills: short playbooks Claude reads at the right moment. The table below lists all 56.
• Hooks: small scripts that run automatically around what Claude does. One stops and asks you before Claude uploads any code to GitHub. One checks a file Claude has just edited for mistakes, using whatever checker that project already uses. One looks up what has changed in your project since you last worked on it, so Claude is not working from an out-of-date picture.
• Norms: six one-line rules that apply in every session, listed in NORMS.md.
• Agents: reviewers Claude can hand a change to for a second opinion, listed under Agents.

It installs once per machine and applies to every project on it. You never run any of it by hand.

This repository is licensed under Apache-2.0 (see the LICENSE file). The three unslop-* skills and the four legal skills (contract-review, legal-citation-integrity, statute-to-obligations-register, legal-notice-handling) are forks and carry their upstream's terms, recorded in their own UPSTREAM.md; the unslop skills also carry a LICENSE file, which goes into their .skill archives. hooks/check-licences.mjs fails the build if a fork loses its notice.

Install

About five minutes.

1. Install Claude Code, git and Node.js. For the checks that read your project's state, also the GitHub CLI, then run gh auth login.
2. In a Claude Code session, run /plugin marketplace add randommonicle/claude-skills, then /plugin install ash@ash-skills.
3. Check it worked: /plugin should list the installed plugin, and asking Claude to do something a skill guards (say, write a test) should visibly load that skill.
4. Optional, for the two-model code review (cross-agent-review, where Claude has Gemini and GPT argue over a change): install the agy and codex command-line tools and copy one settings file. Steps in cross-agent-review/SKILL.md.

The manual route, what each hook does, and what to know before installing are in Install on a new machine further down.

What changes afterwards: a confirmation prompt before Claude uploads anything; a note about your project's state at the start of each session; a report when Claude edits a JavaScript or TypeScript file in a project that has a checker configured; and Claude visibly loading a named rule before it writes a test, changes a database, or calls an AI model.

Where things are: the skills in the table below; the agents in agents/; what each hook does in hooks/HOOKS.md; what went wrong on real jobs in LESSONS_LEARNED.md; standing choices in DECISIONS.md; how the library gates itself in docs/ARCHITECTURE.md; house rules for changing it in CONTRIBUTING.md.

Skills are installed at the user level, so they apply to every project on the machine with no per-project setup.

The library is organised as a four-layer architecture (hooks / always-on norms / lifecycle hubs / narrow leaves) so 60 skills coexist without diluting description-trigger matching. Design and rationale: docs/SKILL_PROPOSALS_2026-07-23.md; the three-lens committee review that ratified it: docs/REVIEW_2026-07-23_skill_proposals.md. Most skills were distilled from the lessons-learned corpora of four real repos; recurrence across repos is the admission criterion.

Layers

• Hooks (hooks/HOOKS.md) — deterministic enforcement in ~/.claude/settings.json, per machine: push gate (with a live freshness block in the ask), surgery gate (destructive SQL asks, carrying the target script's own header), secret-echo guard (a command that would print a secret value is denied with the safe form in the reason), kill guard (a process kill chosen by name or pattern is denied with the by-PID form in the reason), skill fire log, session recon, and the warn family that fires where descriptions cannot: schedule-cost, migration-write, test-write, lint-after-edit.
• Norms (NORMS.md) — six always-on one-liners copied into the global ~/.claude/CLAUDE.md; each points at its skill playbook.
• Hubs — skills owning a workflow moment, each with a routing table to leaves.
• Leaves — narrow triggers, orthogonal vocabulary, one "does not fire on" line each.

Skills

Skill	Layer / role	What it does
verify-the-effect	norm + playbook	Never conclude success from a proxy signal; assert the actual effect or artifact.
live-state-first	norm + playbook	Probe live state before building from any described state; the catalog settles disagreements.
no-silent-data-drop	norm + playbook	Filters and gates hide empty things, never drop content; clamp model-emitted routing keys.
honest-failure-surfacing	norm + playbook	One message per failure mode; pressable controls that explain; error level for terminal states only.
prove-it-can-fail	norm + hub (tests/checks)	Every test, seed, gate, or check must demonstrably be able to fail. Routes: safe-smokes, mass-red-triage, prove-it-can-pass.
prove-it-can-pass	leaf (routed by prove-it-can-fail)	The other half of a gate: prove it lets real innocent input through and catches the violating forms nobody pictured. Real corpora not invented ones, your own mandated command shapes, the domain's ordinary vocabulary, recoverable refusals, and a curated list checked for omissions.
findings-are-evidence	norm + playbook	Agent/reviewer reports are evidence, not findings; re-derive Critical/High and regulatory claims.
one-real-ride	hub (done gate)	One real end-to-end invocation through the real seams before "done". Routes: verify-the-effect, email-delivery-verification, env-change-verification, reproduce-the-real-build.
parallel-work-recon	hub (session boundary)	Fetch/PR/log recon at session start AND pre-commit; identifier claims scan all refs; worktree path discipline.
plan-first	hub (plan gate)	File list, test list, out-of-scope before code; plan step zero is a grep. Routes: blast-radius-grep, enforce-invariants-in-build, flag-deferred-items.
db-migration-verification	hub (schema work)	Post-apply catalog verification plus the full cross-repo trap bundle (FK embeds, live definitions, privileges read-back, verbatim re-issues). Routes: live-data-surgery, blast-radius-grep.
ai-surface-discipline	hub (LLM surfaces)	Input minimisation, output discipline, human gate, rules-bind-in-the-prompt pillar, guard hardening. Routes: no-silent-data-drop, guard-the-spend-paths, outbound-side-effect-idempotency.
verified-citations	hub (citing docs)	Quoted-line citations, provenance by command, statutory facts against primary sources. Routes: deliverable-integrity, substantiate-outward-claims, handover, legal-citation-integrity.
blast-radius-grep	leaf (Tier 1)	The unit of change is the action or fact; grep app, tests, seeds, branches, and built output; drift-check denormalised copies. Completion gate: an errored sweep found nothing, and never truncate a matched line below the match.
enumerate-the-set	leaf (Tier 1)	Blast-radius-grep's twin: it enumerates the places a fact lives, this enumerates the members a change must decide. List fields, kinds, statuses, legs, exit paths and anchors from their source, decide each one in code and in a test, give every start an end, and ask a reviewer which member is uncovered.
trace-one-record	leaf	Two correct figures can make a wrong total: name what each source contains and trace one record end to end through both before combining them; a stated check is not a performed check.
env-change-verification	leaf (Tier 1)	An env change is not live until the reading artifact is rebuilt/redeployed; validate the value, not its presence.
enforce-invariants-in-build	leaf (Tier 1)	A rule asserted only in prose is a comment; back invariants with a test, constraint, or trigger.
lock-at-the-chokepoint	leaf	Serialise shared ops at the module-level chokepoint; check-then-act is not a lock; bounded resumable retry loops.
mass-red-triage	leaf	Classify a broadly-red suite before debugging: root failure, rate-limit walls, truncated runs, environment defects.
rerun-before-verdict	leaf	No verdict from one uncontrolled run: fixes re-run the failing case, deadness needs with/without, good news needs three datapoints or a controlled diff.
earn-every-line	leaf	Nothing enters a file without a present need: code needs a present caller, comments carry what code cannot, flexibility needs a stated requirement; both over-correction ditches fenced.
live-data-surgery	leaf	Fixed protocol for ad-hoc destructive operations on shared data outside tests.
email-delivery-verification	leaf	2xx means accepted, not delivered; suppression lists, every recipient leg, attachment-class blocks.
guard-the-spend-paths	leaf	Per-IP caps on every money/shared-state endpoint from day one; a fail-open guardrail is inert until closed.
price-the-spend	leaf	Price recurring spend before it ships (billed unit x frequency x month, as a % of the allowance); report per-action burn after it runs.
commission-the-roster	leaf (commission moment)	Publish a roster (role / model tier / budget / scope / single artifact) for approval before spawning a fleet; tier by decision class; brief pre-verified facts, not questions.
context-economy	hub (context window)	Every token in the window is re-sent on every later turn: read slices not files, cap output before it lands, keep the cache prefix stable, clear rather than compact between unrelated tasks. Provider mechanics in its references/.
outbound-side-effect-idempotency	leaf	Choose which failure harms the recipient less; claim states, not read-then-write pre-checks.
substantiate-outward-claims	leaf	Customer-facing certification/statistic claims need a primary source or explicit attribution.
deliverable-integrity	leaf	Generated documents: claim-by-claim rewrite diff, loud placeholders for owner-only facts, re-extract-and-assert for parsers, and structural assertions a text diff cannot see (ships a .docx leading-blank-page checker).
server-side-authority	leaf	Derive paths/ids server-side; column-scope RLS self-updates; RLS-or-revoke every table; escape admin output.
reproduce-the-real-build	leaf (micro)	Run the exact production build locally; prove toolchain fixes from tracked manifests alone.
unordered-events	leaf	Webhooks and queues arrive in any order: guard each status write by the states it may move from, test every (event, state) pair, and answer a missing prerequisite retryably.
pin-to-what-was-seen	leaf	An action on displayed state sends that state; the server compares-and-sets on it (409 on a change); a 409 or an answer in doubt closes the editor and redraws; two remedies share one predicate.
fixtures-from-reality	leaf	Fixtures recorded from the pinned provider version, fakes that carry the service's failures, setups by production's path, real output fed across seams, and each claim's runtime named.
measure-per-route	leaf	A measured platform fact holds for the route, build, timing and machine it was measured on; measure again elsewhere, compare whole ranges, subtract the environment, prove a stop by its effect.
spawn-from-declared-state	leaf	A spawned child inherits settings, CLAUDE.md, auto-memory, tokens and its parent's lifetime unless the launch declares otherwise; check what it loaded before its output reaches anyone.
instrument-reports-itself	leaf (routed by honest-failure-surfacing)	A broken instrument keeps producing readings: make failure a distinct value, never a sentinel, zero or an absent key; one message per terminal unattended failure, sent before it is marked handled; check as often as the thing can fail; alarm on no result at all.
tool-layer-bytes	leaf (with a hook)	Code with backslashes goes to disk through the Write tool, never a heredoc or -e/-c string; no sed -i on CRLF checkouts; prove the bytes after any scripted edit.
date-parse-utc-safe	leaf (micro)	Parse date-only strings as explicit local components; UTC runtimes render the previous day.
constant-time-secret-compare	leaf (micro)	Hash then timingSafeEqual for any secret comparison.
secrets-in-output	leaf + hook (secret-echo-guard.mjs)	Nothing that can carry a secret value reaches a tool result: presence and length only, names not values, .env by its keys, provider status and API responses captured and allowlisted; the hook denies the command shapes that print one.
dependency-upgrade-verification	leaf (micro)	npm pack both versions and diff the deciding file when runtime data can't distinguish success from failure.
safe-smokes	leaf (routed by prove-it-can-fail)	Never destructive against shared data in tests; flip-and-restore; teardown asserts its row counts.
confirm-before-push	policy behind the push-gate hook	Per-action authorisation for pushes, merges, and remote branch deletion, with the deletion preflight.
flag-deferred-items	leaf	Grep-able anchors at the deferred work's landing site; .fixme() carries the anchor; dormant controls say so.
checkpoint-log	leaf	Per-commit checkpoint notes in a committed WORKLOG.md for multi-commit units; close with an explicit checklist walk, wiring steps included.
handover	leaf	Structured handover from a real context reading (/context, or the desktop app's get_usage tool), or an honestly recorded gap where neither exists; supersession stamps; carry-forwards cite live state.
team-loop	leaf (candidate)	The team-lead loop. Stage 1: team/NOW.md as an overwritten resume board that session-recon checks against git, one Ask queue per project (a private claude.ai board for unregulated projects, team/ASK.md for regulated ones) read at every start, and effort pins on agents. Stage 2, per project: the tl- role agents, a board of work packages, a living spec, a ledger, and a gate script that decides a merge from git and the package's own checks.
committee-review	process	Three-lens review with shared evidence, attribution-stripped consolidation, and voting.
cross-agent-review	process	Adversarially review a scoped change/design/finding by debating one or more independent AI agents (Gemini via the agy CLI or GPT via the codex CLI, driven by Claude itself with no pasting; or a chat you drive; several seats at once) over a shared file relay, grounded in live read-only evidence; converge or two positions.
skill-library-builder	process	Turn a repo into a project-specific skill library; skills encode mechanical steps, not awareness.
contract-review	leaf (domain)	Review a contract or lease for one named party; every graded finding quotes its clause, caps and exits are read with their interacting clauses, and statutory points go to a verification list unless retrieved. Fork, see its UPSTREAM.md.
legal-citation-integrity	leaf (routed by verified-citations)	Audit every citation in a finished or received legal document; extracted count must equal table rows, and Confirmed needs a named retrieval. Fork, see its UPSTREAM.md.
statute-to-obligations-register	leaf (domain)	Turn a statute, regulation or code into an obligations register read from the current official text; no empty cell, every extracted item accounted for, commencement status from the page. Fork, see its UPSTREAM.md.
legal-notice-handling	leaf (domain)	Draft, reply to, or analyse a legal notice; every deadline a calendar date with its arithmetic, every threatened consequence confirmed and lawfully available, every admission of fact kept apart from the legal conclusion. Fork, see its UPSTREAM.md.
ai-surface-discipline / unslop-ui / unslop-text / unslop-code	see rows above / forks	The three unslop-* skills are forks of JCarterJohnson/vibecoded-design-tells with local patches — see each skill's UPSTREAM.md.

Agents

Reviewers in agents/ that Claude can hand a named change to for a second opinion. Each returns a verdict and findings ranked by severity with file:line evidence, and recommends rather than edits. With the plugin installed they are namespaced under it, so you can call one directly, for example @agent-ash:property-reg-reviewer.

Agent	What it reviews
code-reviewer	A specific diff or file, as an independent second opinion on correctness, security, failure modes and test adequacy.
property-reg-reviewer	A change touching service-charge maths, demands, client money, leaseholder-facing output, retention or erasure, or AI surfaces, against LTA 1985, the RICS Service Charge Code, TPI, BSA 2022 and UK GDPR. Run it as well as code-reviewer on regulated changes.

The team-loop skill's stage 2 adds four role agents. They build and research rather than review, each pinned to model, effort and maxTurns, and none can spawn agents of its own.

Agent	What it does
tl-researcher	One topic, one team/research/<topic>/FINDINGS.md, with sources and options.
tl-builder	An unregulated work package in its own worktree: tests first in their own commit, then the build when resumed.
tl-test-writer	A regulated package's tests, from the spec, independently of the builder.
tl-builder-regulated	A regulated package, built on top of the test writer's commit.

Install on a new machine

Prerequisites. Claude Code, git, and node on PATH (every hook is a node script). The session-recon and push-gate hooks also shell out to git and gh, so install the GitHub CLI and run gh auth login if you want their live repo state. Everything degrades quietly rather than breaking: a missing node or gh means the affected hook produces nothing, which looks identical to nothing being wrong. If a hook seems inert, check the prerequisite first.

What installing changes about your sessions, stated plainly because none of it is obvious afterwards and one item can interrupt you:

• Ten command hooks are wired, listed in hooks/HOOKS.md. Two are gates that ask for confirmation rather than warn: push-gate intercepts git push, gh pr merge and remote branch deletion, and sql-surgery-warn intercepts destructive SQL in an execution context. Both match the Bash and PowerShell tools, which is load-bearing on Windows desktop: a Bash-only matcher leaves both gates absent on the PowerShell path, and shipped that way until 2026-09-16. If you do not want a confirmation prompt on every push, do not install the plugin mode; take the skills only. Two more deny rather than ask: secret-echo-guard (a command that would print a secret value) and kill-guard (a process kill chosen by name or pattern, such as Stop-Process -Name or pkill; kills by PID pass).
• A SessionStart hook runs git fetch and gh pr list in your repo at the start of every session, and injects the result as context. That is network activity in your repo, on your credentials, without a prompt.
• skill-fire-log.mjs appends the skill name, its arguments and your cwd to ~/.claude/skills/FIRE_LOG.jsonl every time a skill loads, and unrecognised event shapes to FIRE_LOG_DEBUG.jsonl beside it. Both are local-only and gitignored, and nothing in them is transmitted anywhere. The only network activity any hook performs is the git fetch and gh pr list named above, on your own credentials. Delete the files or remove the hook if you would rather not keep them.
• The six norms are injected into every session as instructions, per NORMS.md.

Two modes — pick ONE per machine (both at once double-registers every skill and double-fires every hook):

Plugin (recommended — skills, hooks and norms in one step):

/plugin marketplace add randommonicle/claude-skills
/plugin install ash@ash-skills

The repo doubles as a plugin marketplace (.claude-plugin/marketplace.json). The plugin serves the skills from the repo root ("skills": "./" in plugin.json), loads the agents from agents/, wires all Layer 0 hooks via hooks/hooks.json, and injects the NORMS.md block at every session start (hooks/norms-inject.mjs) — no manual CLAUDE.md or settings.json editing. Updates arrive when the machine refreshes the marketplace (no version field is set, so every push to main counts as a new version). The repo is public, so no credentials are needed to read it.

Check it worked, rather than assuming:

node ~/.claude/skills/hooks/check-index.mjs

That prints ok: N skills, all indexed, ... and exits 0. In a session, /plugin lists the installed plugin, and asking Claude to do something a skill guards (say, write a test) should visibly load the relevant skill. If skills are present but nothing ever fires, the hooks are the part that did not install.

To remove it: /plugin uninstall ash@ash-skills, then delete FIRE_LOG.jsonl, FIRE_LOG_DEBUG.jsonl and SURGERY_LOG.jsonl from ~/.claude/skills/ if you want the local logs gone.

Direct clone (the maintainer's dev machine only):

git clone https://github.com/randommonicle/claude-skills.git ~/.claude/skills

Then copy the NORMS.md block into ~/.claude/CLAUDE.md, install the hooks per hooks/HOOKS.md, and copy the agents to where Claude Code reads user agents, which is not the clone:

mkdir -p ~/.claude/agents && cp ~/.claude/skills/agents/*.md ~/.claude/agents/

Copy again after pulling a change to an agent; session-recon names a copy that is missing or out of date at the start of every session. This mode is for editing the skills; a machine on this mode must NOT also install the plugin.