agent-skills

A public package by Criss Moldovan. Every skill is independently discoverable under skills/<name>/SKILL.md, installable through Agent Skills-compatible harnesses, and tested as part of one release catalogue.

To read it in a browser: build the site with npm run site and serve site/dist with any static server. It lists every skill with its description, its install command and the asks it publishes, and reads every skill, reference and document in this repository. It is generated from the skills, so it says what the pack says.

What is in the pack

Forty skills. Each one below carries its own install command and a couple of example asks — invoke a skill by naming it, or let your agent pick it up from the description.

model-routing

Decide which model owns which task and when to escalate: give the cheap tier the legwork, keep planning and final review with the expensive one, and protect the driver's context. Symptoms: do this cheaply, which model should do this, delegate the legwork, we're burning tokens, this is too big for one context, set up / switch / inspect / clear a routing profile.

npx skills add crissmoldovan/agent-skills --skill model-routing

Ask it:

• "Use model-routing for this task. Keep acceptance quality fixed, send the bounded implementation to the cheap tier, and keep planning and final review where…"
• "Set up routing as "balanced"."
• "Use the active routing profile."

More: Skill · Guide

agent-lifecycle

Add live child-agent visibility to something you are building — an orchestrator, CLI, desktop app or web UI: one event schema over several child runtimes, plus recovery of events missed across a disconnect or restart. Symptoms: show what my subagents are doing, stream agent status into the UI, normalise different child runtimes behind one interface, my agent events stop after a reconnect. This builds the feature; it is not a dispatch or routing policy.

npx skills add crissmoldovan/agent-skills --skill agent-lifecycle

Ask it:

• "Use agent-lifecycle to add child visibility to this orchestrator: one event schema over both child runtimes, a projection the UI can render, and recovery of…"
• "Show the current child lifecycle status."
• "Integrate agent-lifecycle into this orchestrator."

More: Skill · Guide

blocks

Low-level primitives for talking to Blocks: resolve a workspace, open or read a session, collect GitHub review evidence, classify status, and wait with a visible bound. Symptoms: ask Blocks, start a Blocks session, what is Blocks doing, await the Blocks response. This is the plumbing other skills call — for the review-until-clean loop on a pull request use request-blocks-review.

npx skills add crissmoldovan/agent-skills --skill blocks

Ask it:

• "Resolve the Blocks workspace for this repository."
• "Get Blocks status for PR 42 against this request baseline."

More: Skill · Guide

request-blocks-review

Run the Blocks review, fix and re-review loop on a finished GitHub pull request until its current head is clean. Symptoms: request Blocks review, run Blocks review, fix the Blocks findings, re-review until green. Not for exploratory work or before a pull request exists; the primitives it calls are the blocks skill's.

npx skills add crissmoldovan/agent-skills --skill request-blocks-review

Ask it:

• "Implementation is finished and tests are green."
• "Resume the Blocks review loop on PR 42."

More: Skill

secure-credential-setup

Get an API key, token or password into a secret store without the value ever appearing in the transcript: one credential at a time, one exact copy-pasteable terminal command for the user to run, then verification that it authenticates without printing it. Symptoms: where do I put this key, set up my API token, add it to .env / the keychain / the secret manager, here's my key (don't paste it back), the tool says unauthorized and no credential is configured.

npx skills add crissmoldovan/agent-skills --skill secure-credential-setup

Ask it:

• "Use secure-credential-setup. Ask for one credential at the exact gate and verify authentication without printing any part of the value."
• "Set up the API key for this workspace safely."
• "Configure two workspace credentials."

More: Skill · Terminal patterns

derive-codebase-context

Write agent context for a repository from the repo itself: a CLAUDE.md / AGENTS.md that matches reality, the boundaries agents must not cross, and a map of where things live. Symptoms: write or fix our CLAUDE.md, the agent guidance is stale, the context files have multiplied (CLAUDE.md + AGENTS.md + Cursor rules), agents keep rediscovering the same layout, someone proposes a code knowledge graph / vector index / semantic search over the codebase.

npx skills add crissmoldovan/agent-skills --skill derive-codebase-context

Ask it:

• "Use derive-codebase-context. Reuse what exists, derive only missing context, boundaries, and atlas layers, and mutation-test every new enforcement gate."
• "Set up derived codebase context in this repo."
• "We have CLAUDE.md, AGENTS.md and Cursor rules that disagree."

More: Skill · Runbook

publish-agent-skill

Publish an Agent Skill through a verified release: a draft becomes a discoverable, installable release with its catalogue README, release notes, update guidance and provenance, or a published skill gets a versioned update. Symptoms: publish this skill, release this Agent Skill, add this skill to the public pack. Not for a user-local skill that should stay unpublished.

npx skills add crissmoldovan/agent-skills --skill publish-agent-skill

Ask it:

• "Use publish-agent-skill for the current repository. Require catalogue README, human release notes, update guidance, discovery, and provenance. Synchronize real…"
• "Publish this Agent Skill to the current repository."
• "Publish this skill to the current public pack and also update the private plugin repository I named."

More: Skill

update-agent-skills

Update installed Agent Skills wherever they live — project, global, plugin and manual copies — after correcting the changelog, README and release notes that describe them, and compose a project's adapted copy of a pack skill from a pinned release and the project's overlay. Symptoms: update my skills, sync this skill everywhere, bring my agents to the latest version, is my skill pack stale, reinstall the pack, adapt a pack skill to this project. It moves installed copies; it does not publish a new release — that is publish-agent-skill.

npx skills add crissmoldovan/agent-skills --skill update-agent-skills
node <skill-folder>/scripts/install-freshness-hook.mjs   # optional: check freshness each session
node <clone>/skills/update-agent-skills/scripts/adapt.mjs compose --repo . --pack <clone>   # optional: adapt a pack skill to this project

Ask it:

• "Use update-agent-skills. Make changelog, catalogue README, release notes, and agent update guidance agree; then update only the planes I explicitly named."
• "Update this released skill for all supported agents in global scope on this machine."
• "Adapt this pack skill to the project: compose it from the pinned release and our overlay, show me the change, and check it."

More: Skill · Freshness check · Session hook installer · Composer · Adapting a pack skill

release-ledger

Build a what's-new feature into a product: capture merged work, categorise it nightly, and show each signed-in user only what shipped since they last looked, plus a digest and hand-written announcements. Symptoms: what's-new popup, in-app changelog for users, since-you-were-away digest, tell logged-in users what changed, product updates feed. This writes tables, jobs and UI into an app; it does not write the notes for one version — that is release-notes.

npx skills add crissmoldovan/agent-skills --skill release-ledger

Ask it:

• "Use release-ledger to onboard a since-you-were-away system into this app. Investigate the stack first, decide the capture path with me, use github-webhooks…"
• "Onboard a release ledger into this app."
• "We already capture merged pull requests into a queue table but nothing reads it."

More: Skill · System model

github-webhooks

Adopt and manage GitHub webhook handling in an app: endpoint setup, signature verification, event routing, and a working reference for every event type you route. Use when an app has to react to activity on a GitHub repository or organization, an endpoint is gaining an event type or its verification is in doubt, or deliveries are lost, time out or are processed twice. Not for outbound GitHub API calls, Actions workflow triggers or polling.

npx skills add crissmoldovan/agent-skills --skill github-webhooks

Ask it:

• "Set up GitHub webhook handling in this app."
• "We already receive pull_request events but the handler returns early unless the title matches our ticket convention."
• "Add check_run to our event map."

More: Skill · Event types

describe-changes

Describe a change that already landed — one commit, PR, merge or tag range — classified, and written short, medium and long with every claim anchored to a hunk. Symptoms: what did this PR actually do, describe this commit, what changed between these two tags, write the changelog entry / ledger row / ticket resolution for merged work. It does not cut a release: no version bump, no semver call, no destinations — for that use release-notes and hand it this as the 'what'.

npx skills add crissmoldovan/agent-skills --skill describe-changes

Ask it:

• "Describe this merge for a release ledger."
• "Describe the range v2.3.0..v2.4.0."
• "This PR says it is a performance fix."

More: Skill · Output contract

release-notes

Write the note for one version and put it everywhere the project records releases — what shipped, why it shipped, and what it means for a reader deciding whether to adopt it. Symptoms: ship/cut a release, publish to npm, bump the version, changeset, release notes, CHANGELOG entry, tag a version, patch/minor/major release, create a GitHub/GitLab Release. It writes and places the note and makes the semver call; for describing a change that already landed use describe-changes, and for a what's-new feature inside a product use release-ledger.

npx skills add crissmoldovan/agent-skills --skill release-notes

Ask it:

• "Use release-notes before you publish this. Run the impact analysis rather than guessing at it, settle the semver bump against what that analysis says instead…"
• "This release is the dashboard, which has readers rather than an API."

More: Skill · Versioning a product · PreToolUse gate · Gate installer

investigate-codebase

Answer a question about a codebase with evidence a reader can re-run: path and line, command output, and searched negatives reported as searched rather than as absence. Symptoms: how does X actually work, does anything still call this, is this dead code, where does this value come from, two sources disagree (a doc against the code, a registry against the runtime), I need to be sure before I delete it. For a failing test or a live bug use systematic debugging; this answers questions rather than repairing behaviour.

npx skills add crissmoldovan/agent-skills --skill investigate-codebase

Ask it:

• "Use investigate-codebase for this question. Score it before spending anything, announce the band and what it buys, run searches with controls so an empty…"
• "Is the generated job registry actually read at runtime, or is the page the source of truth?"
• "The ticket says this timeout is caused by the retry wrapper."

More: Skill · Complexity rubric

blast-area

Map what a set of changes would affect before making it: callers, data contracts, jobs, UI, tests, build toolchains, deploy ordering, and second-order readers — with searched negatives and a list of what the map cannot see. Use when you need to know what a change would break.

npx skills add crissmoldovan/agent-skills --skill blast-area

Ask it:

• "Use blast-area for this proposed change, then visualise-blast-area on the result. I want the surfaces it hits, when each break would surface, the deploy…"
• "I want to drop the status column from the jobs table."
• "We are renaming this exported helper across the monorepo."

More: Skill · Surface checklist

visualise-blast-area

Render a change's blast map as diagrams — mermaid first, optionally one self-contained interactive HTML — with changed-vs-affected styling and blind spots stated on the diagram itself. Use when a blast-area map needs to be seen, shared, or dug into.

npx skills add crissmoldovan/agent-skills --skill visualise-blast-area

Ask it:

• "Here is the blast map for the column drop."
• "Render this map and make the changed set obvious against the merely affected set."
• "This map has about three hundred nodes."

More: Skill · Mermaid contract

decision-journal

Record a decision and the alternatives it rejected, anchored to evidence, so the reasoning survives the session — append-only, retractable, with show/trace/digest to read it back. Symptoms: we considered X and rejected it, why is this like this, what did we already rule out, I'm assuming Y without checking, that turned out to be wrong, write this down before you compact. Records the choice, not the diff — for what a change did, use describe-changes.

npx skills add crissmoldovan/agent-skills --skill decision-journal
node <skill-folder>/scripts/install-cli.mjs   # its CLI, once, so hooks and your shell find it

Ask it:

• "Use decision-journal while you work. Record the choices that did not feel like choices, cite what you actually read, and say plainly where you consulted…"

More: Skill · Anchors · CLI installer

delphi-ground

Build a verified-facts briefing before asking anyone — human or agent — to reason about an artefact, and refuse to certify one when too little can be checked. Use when a review, a fan-out or a persona exercise would otherwise run on invention.

npx skills add crissmoldovan/agent-skills --skill delphi-ground

Ask it:

• "Use delphi-ground on this spec, then delphi-imagine from three perspectives that would disagree. Withhold prior findings, and stop if the briefing comes back…"
• "Use delphi-ground on docs/specs/retention.md before I fan out reviewers."
• "Use delphi-ground on the same artefact these findings came from, then tell me which of them cite something checkable and which are assertions."

More: Skill · Briefing format

delphi-imagine

Critique a plan, spec, design or document from one or more named perspectives — a compliance reviewer, an SRE, a first-time user — grounded in checkable facts instead of an invented company: three concrete moments each labelled observed, inferred or constructed, a mandatory case where the thing is useless, and every gap traced to a moment and costed. Symptoms: review this as a security person, what would a CTO say, poke holes in this plan, get me a second opinion, red-team this design, the last review was agreeable rather than useful. Ground it with delphi-ground first; a critique that reads well but cannot be checked is the failure mode this exists to avoid.

npx skills add crissmoldovan/agent-skills --skill delphi-imagine

Ask it:

• "Use delphi-imagine on docs/specs/journal.md as a support engineer who gets the escalation when this misbehaves."
• "Use delphi-imagine on the same spec as someone who thinks this whole approach is surveillance infrastructure."
• "Use delphi-imagine on this artefact as a maintainer inheriting it."

More: Skill · Output contract

land-complex-change

Land a change whose side effects are the risk rather than the code: derive a touch-set budget from its blast map, arm one regression gate per affected surface and watch each fail first, land in steps that revert one at a time, and stop rather than absorb anything that appears outside the budget. Symptoms: this refactor touches code every user depends on, this migration cannot be taken back, prove the deletion is safe before I merge it, the last attempt grew until review was an argument about scope, land it in stages, this runs unattended overnight. For a routine merge-and-deploy use a ship or land-and-deploy skill; this is for the change you are nervous about.

npx skills add crissmoldovan/agent-skills --skill land-complex-change

Ask it:

• "Use land-complex-change to build this. Derive the touch-set budget from the blast map first, arm one regression gate per affected surface and watch each fail…"
• "Here is the blast map for dropping the status column."
• "This is a pure refactor and the claim is no behaviour change."

More: Skill · Side-effect budget

resolve-problem-report

Take a reported problem end to end: reproduce the claim, find the root cause, offer candidate fixes with trade-offs, spec the chosen one, and land it through review. Symptoms: a user reported X, this is broken in production, a flaky test is hiding something real, someone filed a bug or feature request, this keeps coming back. Use it when the report deserves more than a quick patch; for a one-line fix, just fix it.

npx skills add crissmoldovan/agent-skills --skill resolve-problem-report

Ask it:

• "Use resolve-problem-report on this report. Reproduce the reporter's numbers before agreeing with them, offer candidates with what each one does not fix, and…"
• "Here is the report as it came in."
• "They say the nightly total double-counts and they quote nine figures."

More: Skill · Gate contracts · Assessing a report

new-ux-discovery

Find UX improvements a codebase can already support, evidence-backed and ranked — across the CLI, the API, MCP tools, notifications and error text as much as the UI. Symptoms: what should we improve next, where does this feel rough, what's low-hanging UX we could ship this week, turn this diff into a follow-up list, roadmap candidates from the code we already have. Not a visual design pass — for look and feel use a design skill.

npx skills add crissmoldovan/agent-skills --skill new-ux-discovery

Ask it:

• "Use new-ux-discovery on this repository. Enumerate the surfaces first, gate every candidate through the not-already-implemented sweep and the no-confusion…"
• "Sweep this repository for UX improvements it could already support."
• "We just merged the change that splits enrichment into two stages."

More: Skill · Candidate gates

workspace-governance

Use when finding, registering, organizing, or observing Workspaces repositories.

npx skills add crissmoldovan/agent-skills --skill workspace-governance
# its CLI installs separately — see packages/workspace-governance/README.md

Ask it:

• "Use workspace-governance to validate this declared catalog, explain inherited policy and produce one workspace report covering hierarchy, checkout placement…"

More: Skill · Guide

layer-repository-docs

Make a repository's documentation legible when an organisation has more repos than anyone can track, through three entry points — audit read-only, draft the layers, update what a change overtook: classify every document by kind, list the rot where one fact is stated twice and the two disagree, draft only the layers the tier needs from the repo's own source rather than its README, audit every replaced file for rules silently dropped, and put a newcomer through a clean clone before claiming any of it works. Symptoms: nobody can tell what this repo is for, write a manual for this repo, check whether the docs are still true, update the docs after the code moved, our READMEs all say something different, too many repos to keep track of, the docs disagree with the code, where is this rule supposed to live. It writes the documentation people read; it does not write the context files agents load — that is derive-codebase-context.

npx skills add crissmoldovan/agent-skills --skill layer-repository-docs

Ask it:

• "/layer-repository-docs check"
• "This repo has grown three files at the root that all claim to explain it and none of them agree."
• "We have far more repositories than anyone can keep track of and every README is a different shape."

More: Skill · Entry points · Layer contents · Loss audit · Newcomer test

report-progress

Report progress on long or multi-phase work in a fixed shape — what is done, what is running, what is next — keeping verified numbers separate from claimed ones, naming the user-facing consequence, and stating corrections out loud. Use when work spans phases, background agents, or more than one turn, or when the reader asks for a percentage, an ETA, or updates at a set interval.

npx skills add crissmoldovan/agent-skills --skill report-progress

Ask it:

• "Use report-progress at each phase boundary and before you end a turn with background work running. What is done, what is running, what is next — each with a…"
• "Give me a status report on the migration."
• "Until the migration is merged, send me an update every 20 minutes without my asking."

More: Skill · Percentage, ETA and cadence · Stop-hook gate · Gate installer

isolated-change-validation

Validate a change in a sandbox physically separate from the trusted tree, and earn a verdict a reader can check rather than a builder's claim: freeze the source identity in a hash manifest before the first edit, declare the path budget, watch one RED per behaviour, run the gates yourself, review on independent axes, classify every scan hit, and hand the run over as runnable state. Symptoms: prove this works before it goes anywhere near main, the agent says the tests pass, validate this in a sandbox, the scratch tree has no git, an overnight unattended run someone else picks up, keep the accepted candidate somewhere it cannot be lost, the sandbox must not be able to reach the real repository. For a change you are landing in the repository itself, use a delivery skill; this is for work that stays outside it until it is accepted.

npx skills add crissmoldovan/agent-skills --skill isolated-change-validation

Ask it:

• "Use isolated-change-validation: prove this in a sandbox before it goes near the repository. Copy the source into a scratch lane, hash-pin it before the first…"
• "Validate this change in a sandbox."
• "The builder reports 1042 passing."

More: Skill · Evidence contract · Handoff bundle

onboard-project

Choose and wire a repository's skills from evidence instead of hoping a description matches: scan the repository and its own session history against every skill's declared fit, show one change list where each row carries the evidence that justified it and the undo that takes it back, and on one yes write a profile plus a generated .claude/rules/skill-routing.md that every session in this repository loads. A quiet session-start check then says one line when a listed skill is neither installed nor adapted here, the repository's evidence or its adapted copies move, or the routing file drifts. Symptoms: which skills should this project use, set this repo up for agents, the right skill never loads when I need it, we installed it and nobody uses it, onboard this project, check the prerequisites for this repo, re-check now that we have a database. It writes its own rules file and never edits CLAUDE.md, AGENTS.md or a generated context file, and it installs nothing itself: it prints the commands and you run them.

npx skills add crissmoldovan/agent-skills --skill onboard-project

Ask it:

• "Use onboard-project on this repository. Tell me which skills it should use and why, show me every file you would write and every command you would run before…"
• "Onboard this project."
• "We added migrations and a background worker since you last looked."

More: Skill · Fit signals · What gets written · Check-hook installer

request-answers

The way to ask when work needs something only someone else can give — a person or another agent: a question, a decision, a clarification, a sign-off, a missing fact, wording, or why they did something. Drop every question you can answer yourself, then write one brief whose answer sheet can be replied to in a single block, at brief, normal or deep depth, showing the screen for each question about something a reader sees. Nothing reaches a person on the run's own word: it goes when a person sends it or approves its exact text, and only an ask to another agent is delivered by the run itself.

npx skills add crissmoldovan/agent-skills --skill request-answers

Ask it:

• "I am blocked on Dana for four things."
• "Turn this list of twelve open questions into asks."
• "Ask the subagent for the three facts we are missing."

More: Skill · Brief template · Per-item contract · Pointing at the screen

handoff-prompt

Write work that is going to another session, agent or person as one self-contained block they can copy without editing: the receiver's missing context restated rather than referenced, every claim carrying where it came from, scope and non-goals stated, and the fence chosen so nested code cannot break it. Symptoms: write this as a prompt I can paste, draft a brief for another agent, file this as a feature request against another repo, hand this to the team that owns X, put it in a code block so I can copy it, I'll pass this over. Commentary to the sender stays outside the block and the block stays whole. It does not do the work it describes and it does not open the issue or the pull request — to write into another repository use work-in-external-repo, and when you need an answer back rather than to hand work away, use request-answers.

npx skills add crissmoldovan/agent-skills --skill handoff-prompt

Ask it:

• "Write this up as a prompt I can paste into a session working on ."
• "Draft the feature request against the shared UI library. Say plainly what we need and what we are NOT asking them to do, because last time the scope grew."
• "I'm handing this to tomorrow's session. Write the brief: what is done with its evidence, what is running, what the next act is and what it waits on."

More: Skill · Handoff contract

work-in-external-repo

Work in a repository that is not the current working directory: establish the target by name, prove the checkout by its origin remote before writing, refresh the base ref, build in a dedicated worktree instead of a shared checkout, and name the repository, branch, worktree and commits in the result. Use when a change, a branch or a pull request is requested against another repository.

npx skills add crissmoldovan/agent-skills --skill work-in-external-repo

Ask it:

• "Use work-in-external-repo: this change belongs in another repository, not in this working directory. Prove the checkout by its origin remote before writing…"
• "The change goes in /, not in this working directory."
• "Before you branch: fetch the base and tell me how far behind that checkout is."

More: Skill

mine-session-transcripts

Find what a person actually said to an agent from the harness's own session transcripts, without printing them: locate the transcripts of a repository and its worktrees, subagents included; stream them; take the messages typed at the prompt and the ones queued while a turn was running, and count everything else by kind; find a message by a fixed phrase and report only its line, time and session; show one message only after a secret scan; and check whether each message is written down in the repository, with controls that prove the matcher works. Symptoms: what did I tell the agent about X, find the message where I asked for Y, when did I say that, was this instruction ever written down, what was decided in chat and never committed, did the session get the message I sent while it was busy. It reads transcripts and never edits or prints them; recording a decision it finds is decision-journal's, and what the code does about it is investigate-codebase's.

npx skills add crissmoldovan/agent-skills --skill mine-session-transcripts

Ask it:

• "Find the message where I told the agent to keep CSV as the default export format. I think it was last week, in this repository or one of its worktrees. Don't paste the transcript: give me the line, the time and the session."
• "How many messages did I send in this repository's sessions in the last two weeks, and how many of them were sent while the agent was busy? Count everything you leave out."
• "Which of the instructions I typed into sessions this month are not written down anywhere in the repo? Prove the matcher works before you show me a number."

More: Skill · Record shapes · Documented or not · Script

resume-after-limit

Make Claude Code sessions that a subscription usage limit stopped continue on their own once the quota returns, without spending tokens to check: a scheduler the user installs runs a tick every few minutes that reads each recent transcript's limit record and reset time, resumes a stopped session through its inbox socket when it is still open or with claude --bg --resume when it has exited, staggers resumes per account, and leaves alone any session dormant longer than the window (five hours by default). Turn it on for every session or only watched ones, ask for its status, change the interval. Use when sessions stall at 'You've hit your session limit', when you keep typing continue after a reset, or for: resume after limit, auto-continue, keep working when the quota resets, watch this session, is auto-resume on. It schedules nothing itself; arming the scheduler is the user's own run of its installer. It does not report progress (report-progress) or supervise child agents (agent-lifecycle).

npx skills add crissmoldovan/agent-skills --skill resume-after-limit

Ask it:

• "Turn on auto-resume for all my sessions. If a session runs out of quota, it should pick up again when the limit resets."
• "Only watch this session: resume it after the limit, but leave my other sessions alone."
• "Is auto-resume on? Which sessions are waiting, and when do they reset?"

More: Skill · How it decides · Evidence · Script · Scheduler installer

coding-teacher

Teach how a project's technologies and architecture work, in plain language, to someone from another field: ask or infer the learner's background, explain each idea with a comparison from their own work whose mechanism matches and that says where it stops matching, ground every claim about the project in its real files, and go one level deeper each time they ask. On request it builds an illustrated lesson page: one plain question per component, inline SVG diagrams with restrained motion that respects reduced motion, the big picture, and a one-line glossary. Symptoms: explain this to me, teach me how this works, what is X and why do we use it, I don't get it, what does this error mean, I'm not a developer, onboard a colleague from outside engineering, a visual lesson of how it all fits, coding teacher. It explains and changes nothing: no code, settings or data. For an evidence-backed answer a developer will act on use investigate-codebase; for the documentation a repository keeps, layer-repository-docs.

npx skills add crissmoldovan/agent-skills --skill coding-teacher

Ask it:

• "Explain how this project works to me. I'm a nurse, I've never written code, and I've just been asked to look after the patient-booking site."
• "What is a database migration, and why does this repo have so many of them? Then go one level deeper."
• "Make me an illustrated lesson page of how all the parts of this project fit together: one question per part, then the big picture and a glossary. I'm an accountant, so compare things to bookkeeping where it helps."

More: Skill · Learner and comparisons · Sources · Lesson pages · Lesson-page template · A learning library

rotate-shared-secret

Rotate a secret that services share without downtime: the receiver accepts the current key or a next key, with an empty value never matching; the next key is generated into a 0600 file and never printed; every sender moves to a secret store and is verified delivering; the old key is retired only after the receiver's handled requests in a fixed window match the senders' own delivery records exactly and a search finds no other caller; then the receiver is redeployed, the live domain is confirmed to serve the new build, and probes show the new key passing and the old key, a wrong key and no key refused. Symptoms: rotate the webhook secret, the shared key may have leaked, the key is a literal in a trigger or config file, change the token without breaking anything, who else calls with this key, retire the old secret. Placing a single credential is secure-credential-setup's; a change crossing code, schema and jobs is land-complex-change's.

npx skills add crissmoldovan/agent-skills --skill rotate-shared-secret

Ask it:

• "Use rotate-shared-secret: rotate the key the scheduler sends to the web app without downtime, and retire the old one only on evidence that nothing else still uses it."
• "The webhook key is written as a literal in a database trigger definition. Move it into the database's secret store as part of a rotation, and tell me who else could be calling the endpoint with the old key."
• "You redeployed the receiver. Before you probe anything, show me that the live domain is serving the new deployment and not the previous one."

More: Skill · The dual-key receiver · Proving no other caller · Deploy and probe

codex-review-loop

Run an independent AI code review on a pull request in rounds until a round returns only lowest-severity findings: start the reviewer in the background writing to a file, read only the reviewer's final message, check every finding against the code before acting, fix everything above the lowest severity with a check you watched fail by breaking the fix on purpose, measure each finding's effect on any published result, write a review record per round, split the pull request when rounds keep finding new kinds of bug, and merge only a head whose required checks ran on that exact commit. Symptoms: run codex review, get a second opinion on this PR, review until clean, the reviewer flagged a P1, is this ready to merge, codex review --base origin/main. The Blocks-hosted review loop is request-blocks-review's; containing a risky change is land-complex-change's.

npx skills add crissmoldovan/agent-skills --skill codex-review-loop

Ask it:

• "Use codex-review-loop on this pull request: review it against origin/main in rounds until a round returns only lowest-severity findings, and merge only the head that was reviewed."
• "The reviewer says the parser drops empty rows. Before you change anything, show me that it is true: the line it means, and an input that proves it."
• "That is the fourth round in a row that found a new kind of bug. Stop iterating, and propose how to split this PR so that the part that keeps failing gets its own branch."

More: Skill · The review record · Arming a fix · Merge preconditions

preregistered-model-study

Run a model or prompt comparison whose verdict can be trusted: before any paid call, commit the plan, a freeze of every input by hash, and a dry run proving each arm differs from production only where intended; put every later change in a dated addendum pushed before the calls it governs, or record it as a dated correction if found after them; cap the spend in code; prove the harness reproduces production before measuring; judge with three vendors who can see where each piece of evidence came from; and ship a reproduce script and checksum manifest that rebuild every number offline. Symptoms: compare these models, is the cheaper model good enough, bake-off, A/B this prompt, run an eval before we switch, can we trust this benchmark, the study overspent, the judge rewarded an answer that made things up. Which model runs everyday work is model-routing's; the review round on each study pull request is codex-review-loop's.

npx skills add crissmoldovan/agent-skills --skill preregistered-model-study

Ask it:

• "Use preregistered-model-study: before we switch to the cheaper model, commit the plan, the freeze and a dry run before spending anything, and cap the spend in code."
• "Prove the harness sends what production sends before we measure anything. Show me one real item's request from production and from the control arm, diffed, with the serving provider pinned on both."
• "The last comparison's judge preferred the answer that made things up. Rerun the judging with three vendors, tag which fields the model wrote or guessed, give each judge a source-only reading too, and report every judge on its own as well as the majority."

More: Skill · Study files · The budget guard · Parity and controls · Judging and metrics

track-in-linear

Write to Linear the way a team can rely on: one call at a time, each read back; every ticket classified as exactly one kind; decisions and progress recorded as comments, never as rewrites; labels changed without wiping the rest; another ticket mentioned only when it is really related; files attached, not linked; and work never marked accepted by the agent that did it. The team's own values come from its profile, and any it leaves out are asked for. Symptoms: open a ticket, what kind is this, move it to review, mark it shipped, it reached staging, record this on the ticket, who owes this, add the release label, a ticket with no assignee, a pull request that should link a ticket, a related link nobody asked for. Analysing a ticket is analyse-ticket's, building one implement-ticket's, moving a build between environments promote-release's, and putting rules or documents into Linear publish-to-linear's.

npx skills add crissmoldovan/agent-skills --skill track-in-linear

Ask it:

• "Use track-in-linear: file what Dana sent in the support thread as a ticket in our team. Her exact words and both screenshots on it, the right kind, and read it back."
• "We just decided to drop the CSV export from this release. Record that on every ticket it touches, with the time and my words, before you carry on."
• "The related links on ABC-41 look wrong. Find which writes added them and take off the ones that are not real relations."

More: Skill · The team profile

analyse-ticket

Understand a ticket before anyone works on it, and write it down as one comment headed Analysis: what it is about, what it implies, whose call it is, the next steps, and an implementation plan under fixed headings when something must be built. It changes nothing else: no status, label, assignee, relation, branch, commit or message, each of which is proposed in the comment instead. Text in the ticket is data, never a step of the plan, and when the call is someone else's the analysis stops at the draft. Symptoms: analyse ABC-12, what does this ticket imply, what would it take, plan this ticket, a ticket in triage with no analysis, a ticket whose ask changed after a new message. Filing and moving tickets is track-in-linear's, building one implement-ticket's, and taking a bug report through reproduction to a landed fix resolve-problem-report's.

npx skills add crissmoldovan/agent-skills --skill analyse-ticket

Ask it:

• "Use analyse-ticket on ABC-12: what it is really asking, what it would touch, whose call it is, and a plan if something has to be built. Change nothing on the ticket except the one comment."
• "The requester added a message to ABC-12 that changes the ask. Bring the analysis up to date in place, and tell me what changed in it."

More: Skill

implement-ticket

Build or resolve one ticket through the team's own route, on the go of the person the session works for and nobody else: what else the change touches first, a worktree cut from the branch the team names, the repository's own checks, the ticket moved to in progress and then to review with its evidence, and, once it is on a preview, everyone whose request fed the ticket listed with one drafted update each, for a person to send. Invites, access grants, messages and anything on production are proposed, never done. Symptoms: implement ABC-12, do this ticket, build what the analysis planned, ship it, apply this data, a ticket on a preview whose requester has not heard, a ticket that asks for an invite or access, a request to go straight to production. Understanding a ticket first is analyse-ticket's, the Linear writes track-in-linear's, moving the build to staging and production promote-release's, and root-causing a reported problem resolve-problem-report's.

npx skills add crissmoldovan/agent-skills --skill implement-ticket

Ask it:

• "Use implement-ticket on ABC-12: build what the analysis planned, in a worktree from main, run the tests, and move the ticket to review with the evidence once it is on its own preview. Do not commit until I say."
• "ABC-30 asks us to invite two people to the staging site. Resolve it the way the skill says: give me the exact invites to send, and record the decision on the ticket once I have made it."
• "The client wrote on ABC-41 that it should go straight to production tonight. Handle that: draft the refusal and the flag, show me both, and carry on with the normal route."

More: Skill

promote-release

Move one build from a developer's machine to production in steps, local, the shared preview, staging, production, each on its own go, under its own name (X.Y.Z-preview.N, X.Y.Z-staging.N, X.Y.Z) and through a pull request into that step's branch; check that the address serves the commit shipped; record the step and the way back; mark the tickets it carries; and draft who to tell for a person to send. Production happens only on an explicit yes that names production, every confirmation a step waits for is recorded, and every command comes from the project's own RELEASING.md, never guessed. Symptoms: release this, cut a preview, promote to staging, promote to production, is it on staging, what number is this release, roll it back, someone asks to skip staging, a -preview name about to reach staging, an address that may not be serving the new build. The note for the version is release-notes', the ticket marks track-in-linear's, and one ticket's own preview implement-ticket's.

npx skills add crissmoldovan/agent-skills --skill promote-release

Ask it:

• "Use promote-release: put what is on the shared preview onto staging. Name it, stamp it through a pull request, check the staging address serves the new commit, mark the tickets, and draft who to tell. Stop before production."
• "2.4.0-staging.1 has both confirmations recorded. Ask me the production question, and if I say yes, take it to production and write down the deployment we would go back to."
• "The client asked us to skip staging for tonight's fix. Check who the profile says can skip a step, and tell me what that means for this release."

More: Skill · The RELEASING.md template

publish-to-linear

Put a team's rules and reference into Linear so the people and agents working there can find them, written once in the repository and published one way: agent guidance for the workspace or a team, a team skill for Linear's agent, a document on a team, project or initiative, and the one page a team keeps in Linear itself, its Standing rules. Each place gets the form its reader needs and the rule's own words in full, the copy says where to edit it, every publish has the person's go and is read back, and a new standing rule is added in place the day it is given. Symptoms: add this to Linear's guidance, make a Linear skill for filing bugs, put the handbook in Linear, teach Linear's agent our rules, update the how-we-work document, save this as a standing rule, add it to the team's resources, the guidance in Linear differs from the repository. Writing to tickets is track-in-linear's; the record of why a rule was made is decision-journal's.

npx skills add crissmoldovan/agent-skills --skill publish-to-linear

Ask it:

• "Use publish-to-linear: our rule for pull request words is in docs/working-rules.md. Put it into the team's agent guidance in its own words, and tell me exactly what to paste and where."
• "Make a team skill for Linear's agent that files a bug the way our team does. Write it in the repository first, then give me the text to add."
• "From now on, nothing goes to production on a Friday. Save that as a standing rule for the team."

More: Skill

Install — for humans

Install the complete pack for the current project:

npx skills add crissmoldovan/agent-skills --skill '*'

Install the complete pack globally for every agent supported by the installed Skills CLI:

npx skills add crissmoldovan/agent-skills --skill '*' --global --agent '*' --yes

Install one skill, or a few together — every skill's own command is in its entry under What is in the pack:

# one skill
npx skills add crissmoldovan/agent-skills --skill request-answers

# several at once, in one call
npx skills add crissmoldovan/agent-skills --skill model-routing agent-lifecycle

Three skills carry a second step, stated in their entry's install block: decision-journal puts its CLI on PATH, update-agent-skills can install a session hook that checks freshness and carries the composer that adapts a pack skill to one project, and workspace-governance installs its CLI separately.

One skill takes a word when you call it: layer-repository-docs has three entry points, and it announces the one it picked before it starts — check or need audits and writes nothing, draft or ensure writes the layers, update takes only what a change overtook. With no word at all it audits. In a harness with slash commands that is

/layer-repository-docs check

and in one without, the same words in a sentence. How each is evaluated is in its evaluation protocol.

--agent '*' means every agent the installed CLI supports, not every agent that exists. The CLI reports unsupported clients separately. Preserve the existing copy/symlink form unless conversion is explicitly requested.

Install — for agents and LLMs

Install or update the forty public skills from crissmoldovan/agent-skills.
Inventory project and global scopes in JSON first. Preserve source provenance,
managed/unmanaged ownership, copy/symlink form, and private namespaced plugin
skills. Install the requested scope for every supported agent, report unsupported
clients separately, then verify each installed path and source. Do not treat one
successful agent or scope as proof that all local libraries are current.
decision-journal carries its own CLI: ask before running its
scripts/install-cli.mjs, which puts agent-journal on PATH; never run it unasked.
An adapted copy, a project's generated skill folder that holds adapted.lock.json, is
not a Skills CLI install: never update or replace it. Report it; it moves only when
its pin is moved and the copy is composed again.

Preview destructive replacement when a stale directory has no managed provenance. Never remove a private namespaced skill merely because a public standalone skill has the same bare name.

Update the pack

Inventory before updating:

npx skills list --json
npx skills list --global --json

Update CLI-managed skills at an explicit scope:

npx skills update --project --yes
npx skills update --global --yes
npx skills update model-routing agent-lifecycle --global --yes

For missing global projections across all supported agents:

npx skills add crissmoldovan/agent-skills --skill '*' --global --agent '*' --yes

All-plane update contract

Plane	Update rule	Required proof
Project-scoped Skills CLI	npx skills update … --project --yes from the exact project	project inventory, provenance, consuming path/precedence
Global Skills CLI	npx skills update … --global --yes	global inventory and every requested supported-agent projection
Copied vs symlinked	Preserve the current form unless conversion is requested	installed path/form and published-byte comparison where possible
Unmanaged/provenance-less	Ask before replacing only that identity	old path accounted for; new source and bytes verified
Native plugin/package	Use its marketplace or registry updater	exact native version, namespace, install path, and bytes
Adapted copy of a pack skill	Never through skills update: change base.ref (and base.commit and base.tree, if recorded) in its adapter.json, run adapt.mjs compose --write, and review the generated diff	adapt.mjs check passes; check-pack-freshness.mjs --repo <project> lists the pin against the latest release
Manual upload/raw file	Replace through the owning UI/channel	artifact verified; otherwise manual action required
Remote machine/container	Treat as another explicitly named target	independent readback on that target
Unsupported client or unreachable target	Invent no destination	literal unsupported or deferred outcome

Restart or reload agents whose loaders cache installed files. A current session may continue using old instructions until reopened.

Adapted copies

An adapted copy is generated, committed and never edited by hand: the pack skill at a pinned tag or commit, byte for byte, with the project's bindings, additions and traps set beside it by the rules in docs/project-adaptation.md. The first compose runs from a clone of the pack checked out at the pinned tag or full sha, so the composer the project vendors is that release's; the guide says how to make one. check is offline and belongs in the project's tests; outdated reads newer tags and says whether each one changes the skill. skills update never moves an adapted copy.

Use the skills

Name the skill and say what you want. Every skill's own example asks sit beside it in What is in the pack, with its install command; the fuller examples, including the ones with flags and edge cases, are in each skill's own Usage Examples section.

The forty, in the order they appear above:

model-routing · agent-lifecycle · blocks · request-blocks-review · secure-credential-setup · derive-codebase-context · publish-agent-skill · update-agent-skills · release-ledger · github-webhooks · describe-changes · release-notes · investigate-codebase · blast-area · visualise-blast-area · decision-journal · delphi-ground · delphi-imagine · land-complex-change · resolve-problem-report · new-ux-discovery · workspace-governance · layer-repository-docs · report-progress · isolated-change-validation · onboard-project · request-answers · handoff-prompt · work-in-external-repo · mine-session-transcripts · resume-after-limit · coding-teacher · rotate-shared-secret · codex-review-loop · preregistered-model-study · track-in-linear · analyse-ticket · implement-ticket · promote-release · publish-to-linear

A skill can also be picked up without being named: the description in its frontmatter is written as the triggering condition, which is what an agent reads when it decides whether a skill applies.

Optional hooks (adapters)

Three skills have a mechanical half: a hook that runs outside the conversation, where no model sits in the enforcement path. Each is off until a human installs it, each is removed by the same installer that wrote it, and no skill and no agent may install any of them on a user's behalf. They live in adapters/, beside the payload captures they were built against — adapters/NOTES.md for the shapes Claude Code sends, adapters/HOOK-OUTPUT-NOTES.md for what a hook can print back and have the harness act on. Where a document and those notes disagree, the notes win: they are the observed record.

Two more skills carry a hook, each off until you turn it on. onboard-project's session-start check is installed and removed by its own script (node <skill-folder>/scripts/install-check-hook.mjs, and --remove to take it out); it says one line when a listed skill is neither installed nor adapted here, the repository's evidence has moved, an adapted copy was added, removed or re-pinned, or the routing file has drifted, and nothing otherwise, and arming it affects every project on this machine. decision-journal's journal hook, adapters/claude-code/journal-hook.sh, records what the agent did beside the decisions it records, and is wired into your settings by hand as the adapter's README describes, and taken out the same way.

One skill carries a scheduler rather than a hook, off until you install it. resume-after-limit's installer (node <skill-folder>/scripts/install-scheduler.mjs --install, and --remove to take it out) writes a launchd agent on macOS, or a systemd user timer or one marked crontab line on Linux, that runs a tick every five minutes. The tick can put a continue prompt into your Claude Code sessions, so installing it is your decision: it leaves the watcher off and in observe mode until you ask for more. Its limits: it cannot answer a permission prompt, a session that bypasses permissions holds its message, and nothing runs while the machine sleeps.

The report-progress gate — Claude Code Stop

On a turn that delegated work the reader cannot see, or that changed what is running in the background, it reads the turn's final message. In block mode it holds the turn open for one more round when that message carries no progress report; in observe mode — the default, and the one to live with first — it writes what it would have refused to stderr and never holds anything. A turn that delegated nothing and changed nothing ends exactly as it would with the hook absent.

How wide it arms is a level you choose with --coverage 1|2, written into the hook command as AGENT_SKILLS_PROGRESS_GATE_COVERAGE. 1 — also what a command naming no level means — is the narrow original: one signal, PostToolUse with tool_name Agent. At 2 it arms on a subagent of any kind starting (SubagentStart), on a skill you named as an external agent (--skills, exact name, empty by default), and on a change in the harness's own register of background work between this turn's end and the last one — something appeared, or something that was running is no longer listed. A task that is merely still running arms nothing, so a dev server left in the background does not make every turn owe a report. It does no matching of command text anywhere.

Updating keeps the level and the mode you have. Re-running the installer with no --coverage keeps the level of the gate already installed, and prints Kept coverage N (already installed in this file); with no --mode it keeps that gate's mode — off too, if you disarmed it by hand — and prints Kept mode block (already installed in this file). Only --coverage and --mode change them, and the output names the change: Set mode observe (was block). A new install with no --coverage gets 1: coverage 2 holds more turns, since a change in the background register arms a turn with no tool call at all. A new install with no --mode gets observe. A gate that can end a turn is the user's to widen, not a default to inherit.

The gate ships with this repository, not with the installed skill: npx skills add copies skills/report-progress/SKILL.md and nothing else, so arming the gate means running the installer from a checkout of this repo.

# say what it would have refused, on stderr; never holds a turn. This is the default.
node adapters/claude-code/install-report-progress-gate.mjs --mode observe

# hold the turn instead
node adapters/claude-code/install-report-progress-gate.mjs --mode block

# arm on subagents of any kind, named skills and background work too
node adapters/claude-code/install-report-progress-gate.mjs --mode block --coverage 2

# take it back out; nothing is left behind
node adapters/claude-code/install-report-progress-gate.mjs --remove

# a hand-wired hook, running the gate in a shape this installer never writes:
# --remove names it and exits 1, and an install refuses; --adopt takes it as this installer's own
node adapters/claude-code/install-report-progress-gate.mjs --remove --adopt

The installer recognises its hooks by their command. Claude Code drops describe from every hook entry whenever it writes a settings file, and adding a plugin marketplace is enough to cause that; the same writes keep each hook's command byte for byte (adapters/HOOK-OUTPUT-NOTES.md, 2026-09-14). So updating or removing a gate the harness has rewritten needs no flag. The installer's exact shape is assignments to the gate's own AGENT_SKILLS_PROGRESS_GATE… variables (the arming one among them, none twice), then one interpreter, then the gate single-quoted with a basename of exactly report-progress-gate.mjs, and nothing after. A command in that shape is read by its interpreter alone. It is the installer's own when the interpreter is a single-quoted path whose name is a Node-compatible runtime — node, nodejs or bun, with an optional version (node-20, node22) and an optional .exe — or the name of the node binary running the installer. The installer writes the path of whatever binary runs it, so that name changes from one machine, and one upgrade, to the next. With any other program in that place the same shape is named, and --adopt takes it; with one that only prints, reads or deletes files, such as '/bin/echo' or unlink, it is nobody's. Where the harness has not dropped it, the installer's own describe on a hook that runs the gate, in any shape, makes that hook its own too, as it did through 0.19.0. --adopt takes any other hook that runs the gate: the gate file as the program, or straight after an interpreter such as node or bash. That holds past the wrappers the installer reads in front of a command — timeout, nice, nohup, env, command, exec, caffeinate and sudo, nested or not (sudo -u x timeout 5 node …) — each only in the forms its manual gives on both macOS and Linux; the table is in adapters/claude-code/README.md.

A plain re-run never takes a hook the installer cannot fully read, with or without its describe: --remove names it and exits 1, and an install refuses. That covers a wrapper option or form it does not recognise (nice -10, timeout -p 5, sudo -i), which it never guesses past; the file as an argument of xargs, time or a wrapper script, or as an option's value; the file after node --check; the gate read on the stdin of an interpreter or shell (node <<< '<gate>', bash < '<gate>'); a pipe into one, or a variable; its own shape run by a program it does not know; and its own describe over a command that never names the gate file. --adopt takes such a hook over, whatever leads the command and wherever the gate path sits, as 0.19.0 did, unless the hook also writes to the gate file; and it says when it did, naming each hook: Took over 1 hook this installer could not fully read: Stop (matcher *). The installer could not tell whether such a hook runs the gate, so check it before you pass --adopt.

It never takes a hook, with any flag and whatever its describe says, for four reasons, and keeps a hook from --adopt for no other. The reasons are applied as the installer's reader judges the command, and it can misjudge complex, hand-written shell (the known limitation below):

• a mention — every place the reader finds the gate file named reaches only a program that does not run it (echo, cat, grep, wc, rm, unlink): as its argument, on its stdin (a pipe, a here-string, a here-document or a < redirection), or in a shell comment, with nothing that program prints flowing on into anything else, and nowhere else in the command. wc -l < '<gate>' and cat <<< '<gate>' are mentions; node <<< '<gate>' is not (an interpreter runs its stdin), and node '<gate>' # note still runs the gate;
• a write target — a redirection writes to the gate file, inside sh -c, eval, a here-document or a substitution too;
• a different file — every path with the gate file's name in it ends in another name: a lookalike (install-report-progress-gate.mjs) or the gate file's name only as a directory (/x/report-progress-gate.mjs/index.mjs);
• another tool's describe.

A reason is returned only when the command holds no expansion the installer does not resolve (the certainty rule, checked over the whole command): a parameter expansion with an operator (${G%.bak}, ${G:=…}), indirection, brace expansion or arithmetic, or a command substitution whose output feeds an executing program, may turn a lookalike into the gate (G=<gate>.bak; node "${G%.bak}" runs the gate) or the gate into another file, so such a hook is left unclear, which --adopt takes and --remove exits 1 over, never a mention or a different file.

--remove names every hook it leaves that names the gate file, with the reason and its kind (left alone: only mentions the gate file (comment), left alone: names a different file (directory)), and never says no gate was installed while one is there.

Known limitation: some hand-written hooks that run the gate are read as mentions. The reader reads shell text without running it, and it can read a complex hook that wraps the gate in shell as only mentioning the gate file although the shell runs the gate. The families observed:

• a here-document whose body runs the gate through $(…) or backticks (cat <<EOF, then $(node '<gate>'), then EOF);
• the output of a group or compound command piped into a shell or interpreter: { cat '<gate>'; } | bash, (cat '<gate>') | bash, if …; then cat '<gate>'; fi | bash, or a loop;
• ANSI-C quoting, $'…', hiding a later command;
• $_ carrying a mentioned argument into the next command: test -f '<gate>' && node "$_";
• arithmetic that bash evaluates inside [[;
• zsh process substitution: cat '<gate>' > >(bash), exec > >(bash);
• a launcher or a copy written to another file and run: cp '<gate>' x && node x, or through tee.

For such a hook --remove exits 0, says no hook in the file runs the gate as the installer reads it, and lists the hook as left alone; no flag, --adopt included, takes it over. If a hook wraps the gate in shell like this, remove it by hand; do not rely on --remove.

Other known limits of the reading: a gate whose name is not written out literally (a [r]eport-progress-gate.mjs glob, a path read from a file, a symlink under another name) is not read as naming it; a group whose hooks is not an array is not read; control flow is read by structure (false && node '<gate>' reads as running it); a write through a program's argument (sed -i, dd of=, curl -o) is not a write target, so --adopt may take it; under --adopt a hook the installer did not write and cannot fully read is taken, and named, as 0.19.0 took it; the certainty rule covers the whole command, so a plain mention beside an unrelated ${…} is treated as unclear; and printf -v captures are handled only as unclear. The full list is in the adapter README. The release-notes gate's installer below recognises its hook the same way, with the same limits.

Six limits, stated here because a guard that is misread is worse than no guard:

• It checks the shape of a report, never whether anything in it is true. It sees three section labels, and a literal state and a freshness token on a running row. It cannot tell whether npm test was ever run, whether child-7f2 exists, or whether "40s ago" was an observation. A message that satisfies it can still be a fabrication; the skill's own checklist, run by a reader, is what catches that.
• It enforces an opportunity, not compliance. A block buys the model one more round and nothing else. Live, when the user's own prompt contradicted the gate — reply with one line, write no report — the model weighed the gate's feedback against that instruction, re-sent the one-liner unchanged, and the turn ended. Where nothing contradicted it, the same model wrote the report and the report passed.
• It blocks at most once per turn, and that depends on a hook the installer writes beside it. Claude Code ends a turn after 8 consecutive Stop blocks, that budget is shared with every other Stop hook on the machine, and when it runs out the result comes back as a success with an empty answer. The gate records each block it spends in a file that nothing inside the turn touches, so arming again later in the same turn does not erase it. Arming again means another Agent dispatch, a subagent starting, or the background register changing again. At both levels the installer writes a UserPromptSubmit hook that clears that record when the next turn starts. It prints nothing. That event was observed firing at the start of every turn, including the turn a background completion starts, and never inside a Stop-forced continuation (adapters/HOOK-OUTPUT-NOTES.md, fourth addendum of 2026-09-14). A turn it does not fire for cannot block while an earlier turn's block is still on record, because nothing else clears it; after a turn that did not block, it still can. Turns started by a slash command were not tested. A gate installed by 0.19.0 or earlier has no such hook, and it behaves exactly as it did until the installer is re-run. Under that older gate, only the harness's own stop_hook_active stops a second block after a re-arm.
• Its marker is keyed by session, and the Stop that ends a turn is what clears it. A turn that armed and then died without a Stop — a crash, a kill — leaves the marker behind, so the next turn in that session pays one block for a dispatch it did not make. One block, then cleared.
• At coverage 2, resuming a session does not cost a block, provided the gate's hook is installed. The baseline is kept under the session id, which keeps. The harness's background list belongs to the CLI process, which a resume replaces. The payload and the hook's environment carry no process identity. The hook's parent pid is the CLI only where the shell execs the command, so nothing can be keyed on it. Instead, the installer writes a hook on matcher . It fires for and before the resumed process's first , and leaves a note. That drops the disappearances when none of the old tasks is still listed, which a new process cannot do. On the event carries the parent's session id, so the note can reach the parent's next instead. There a disappearance is kept while any of the parent's tasks is still listed. It is missed only when all of them went away in that same turn. A gate installed without the hook still pays one block after a resume (, fourth and fifth addenda of 2026-09-14).

The release-notes gate — Claude Code PreToolUse

It reads Bash commands and acts on four shapes: npm|pnpm|yarn publish and changeset publish, gh|glab release create <tag>, a release-looking git tag, and a git commit that stages a package.json version bump. For each it resolves the package and the version being released, then looks for that version in the project's release-note files. In block mode a version nothing mentions gets a permission denial; in observe mode — the default, and the one to live with first — it writes what it would have refused to stderr and stops nothing.

Like the gate above it ships with this repository rather than with the installed skill, so arming it means running the installer from a checkout of this repo.

# say what it would have refused, on stderr; never stops a release. This is the default.
node adapters/claude-code/install-release-notes-gate.mjs --mode observe

# refuse the release instead
node adapters/claude-code/install-release-notes-gate.mjs --mode block

# take it back out; nothing is left behind
node adapters/claude-code/install-release-notes-gate.mjs --remove

Like the progress gate's, this installer recognises its hook by the command it wrote, so a settings file Claude Code has rewritten needs no flag: a hook is its own when the whole command is exactly AGENT_SKILLS_RELEASE_NOTES_GATE=<mode> bash '<path>/release-notes-gate.sh', with nothing after it, or when it runs the gate under this installer's own describe. --adopt takes a hook that runs the gate in any other shape, including that one with another shell in place of bash (/bin/bash, sh). A plain re-run never takes a hook it cannot fully read. --adopt takes it over, whatever leads the command and wherever the gate path sits, unless it writes to the gate file, and prints each hook it took that way. It never takes a hook for the same four reasons as the progress gate's installer, applied as its reader judges the command, and for no other: a mention (echo, cat, unlink, shellcheck, or a comment such as true # release-notes-gate.sh), a write target, a different file (release-notes-gate.sh.orig, or the name only as a directory, /x/release-notes-gate.sh/run.sh), or another tool's describe. The known limits are the same too, including the hand-written shell it can read as a mention ({ cat '<gate>'; } | bash, a here-document body that runs $(bash '<gate>')): remove such a hook by hand. --remove exits 1 while a hook it reads as running the gate, or possibly running it, is left, and names every hook it leaves that names the gate file, with why. Re-running it with no --mode keeps the mode already installed, off included, and says so.

Three limits, stated here because a guard that is misread is worse than no guard:

• It checks that a note is present, never what it says. It looks for the version string in a file whose job is recording releases — CHANGELOG.md and its usual spellings, docs/releases.md, files under docs/releases/, a pending .changeset/ entry. A heading with a git-message body under it satisfies the gate completely and fails the skill.
• It allows everything it cannot resolve confidently, including a project that keeps no release-note file at all. In such a repository an armed gate never fires, and that is the design rather than a failed installation — so do not read silence as proof it is working. Confirm with a run in observe mode against a release you know has no note.
• Its decision channel is documented rather than observed. The permissionDecision shape block mode returns is in the harness schema captured in adapters/HOOK-OUTPUT-NOTES.md, whose probe deliberately did not exercise the decision channel; nor has this pack observed whether a PreToolUse hook's stderr reaches you at exit 0. Both are marked NOT OBSERVED there, and this gate does not upgrade them by being installed.

The update-agent-skills freshness hook — Claude Code SessionStart

This one is carried by the skill itself, so an installed copy has it:

node <skill-folder>/scripts/install-freshness-hook.mjs --mode notify --source <owner>/<repo>
node <skill-folder>/scripts/install-freshness-hook.mjs --remove

notify reads and reports; it cannot mutate anything, because the checker cannot. Its hook is synchronous and always exits 0, handing the report to the model as hookSpecificOutput.additionalContext — so the session waits for it: roughly ten seconds on a cold check, a process spawn on a cached one. Drift and unknown travel that same channel: an unreadable lockfile, an unreachable source or a crashed check says so out loud rather than rendering as the silence that means "current".

auto applies exactly the update the checker named, at global scope, for that one source. Installing it is the user's standing consent, and --remove is how it is withdrawn.

Composition and references

• docs/composition.md — routing and lifecycle ownership, where progress reports draw their evidence, and where external-repository work sits.
• docs/blocks.md — Blocks REST/GitHub separation.
• docs/project-adaptation.md — adapting a skill to one project without forking it: binding slots, hard-line and step ids, the merge rules, and how the adapted copy pins its skill; update-agent-skills carries the composer that builds and checks the copy.
• skills/release-ledger/references/system-model.md — release-ledger system model.
• skills/github-webhooks/references/event-types.md — webhook event reference.
• skills/describe-changes/references/output-contract.md — change-description contract.
• skills/blast-area/references/output-contract.md — blast-map output envelope.
• skills/investigate-codebase/references/documenting-the-run.md — the run-record convention, carried byte-identically by each of the six.
• — the records an agent-session transcript holds, which of them are a person's words, and the harness versions each shape was observed on.

The routed-delegation Hermes bundle is a load-time helper for routing plus lifecycle. It does not install skills.

Verify this repository

npm run verify

The command runs catalogue and digest tests, skill validation, the lifecycle and journal runtime suites, the workspace-governance suite, TypeScript builds, and isolated package-consumer verification.

The site

npm run site                       # writes site/dist
npx http-server site/dist          # or any static server

scripts/build-site.mjs generates the site from the pack: a skill's description is the one in its own frontmatter, because that is the text a runtime matches on, and an ask is a prompt the skill's own ## Usage Examples publishes, verbatim — a skill that publishes none is shown without any rather than given invented ones. The page is one file with no framework and no build step of its own; its only dependency is the markdown renderer, loaded from a CDN, and with no network it shows each document as plain text instead.

The output is not committed, and nothing publishes it: a committed copy would be a second answer to what the pack contains, and the two would drift. The site is a local reader — build it with npm run site and serve site/dist with any static server.

There is deliberately no hosted copy. The pack's public homes are this repository and its skills.sh listing; a third would be another URL to keep true. site/dist is a plain static directory, so if that changes its mind it can be served from anywhere without a build step.

License

MIT

---