claude-kit

A shareable kit of Claude Code assets — skills, agents, hooks, and rules — for orchestrating multi-step work, running bias-resistant review, and keeping Claude Code's own configuration and memory hygienic. It can be installed as a Claude Code plugin or wired directly into ~/.claude/ via symlinks; see the two install sections below (they are not equivalent — read the "rules/ is a co-install dependency" section).

Contents

Skills (skills/):

• dispatch — batch fan-out: run independent small-to-medium tasks in parallel worktrees, each ending in a reviewed draft PR.
• orchestrate-creator — scaffold a project-owned /orchestrate skill (plan → issue → worktree → implement → review → PR) from a template, baking the project's parameters in at generation time; re-run it to diff a generated skill against the current template. The kit deliberately ships no runnable orchestrate: personal-scope skills override same-named project skills (documented precedence — agents resolve the other way round, project wins), so a symlink-installed one would shadow every project's own.
• promote-memories — triage per-user memory into durable rules and retire shipped trackers.
• risk-review — multi-perspective, bias-resistant risk review of a diff or design decision.
• skill-retro — monthly evidence-driven retro of this kit's skills; proposes fixes as a draft PR.
• work-log — extract and format a work log from conversation history.
• write-adr — draft a new ADR into the repo's ADR directory, matching that repo's own format, then verify it with a two-reviewer loop.

Agents (agents/):

• critic — bias-resistant reviewer using pre-mortem axis generation and rubric-based evaluation.
• implementer — executes implementation work from a finalized plan.
• code-reviewer — project-agnostic PASS/FAIL reviewer for the Step 4 gate of a generated orchestrate skill; reads the project's CLAUDE.md plus the .claude/rules/** whose paths: match the changed files. A project's own .claude/agents/code-reviewer.md shadows it (project scope wins).

Hooks (hooks/):

• block-force-push.sh — PreToolUse guard that blocks git push --force to protected branches.
• guard-secret-reads.sh — turns Bash commands referencing secret paths (.ssh/, .aws/, .env, …) into a confirmation ask; closes the gap that Read() permission denies don't cover Bash.
• gated-runner.sh — runs a wrapped hook only when the Bash command matches a given prefix (e.g. gh pr ).
• pre-pr-docs-check.sh — pre-PR docs freshness check.
• pre-pr-review-gate.sh — review gate with teeth: denies the first ready-making gh pr command per branch, telling the agent to run a review skill (/code-review or /risk-review) before retrying. It cannot verify that one ran — it buys the interruption and trusts the agent for the rest.
• post-pr-reflection.sh — post-PR reflection prompt.
• _pr-lib.sh — shared helpers used by the PR-related hooks above.

The hook scripts live in hooks/; their plugin registration lives in hooks-plugin/ (its own plugin root, with hooks/hooks.json plus symlinks to the scripts), so the claude-kit plugin can ship without the hooks.

Maintainer note — don't collapse this into one plugin root. Two Claude Code plugin-loading behaviours force the split: (1) a marketplace entry's explicit component list does not suppress default component auto-discovery, so a single root's hooks/hooks.json is always picked up and the hooks can't be dropped; and (2) a strict: false entry conflicts with the mere presence of a plugin.json, even one that declares no components. Separate plugin roots are the only clean way to ship skills/agents without the hooks.

Rules (rules/) — see the co-install section below before assuming these are installed.

Docs (docs/) — on-demand reference, deliberately outside rules/ so it costs no per-turn context. install.sh symlinks it to ~/.claude/kit-docs/, which Claude Code does not auto-load (verified 2026-08-12 on Claude Code 2.1.228, re-run 2026-08-13 on 2.1.229; volatile, re-verify on upgrade — method and probe: docs/code-review-path-scoped-rules.md), so a citation resolves from any project and still costs nothing.

How to cite a doc depends on how far the citing file travels — a repo-relative path inside a machine-wide file resolves against whatever project happens to be open and silently finds nothing:

citing file	cite as
loaded machine-wide (rules/, agents/, skills/)	~/.claude/kit-docs/<name>.md — plus ${CLAUDE_PLUGIN_ROOT}/docs/<name>.md in agents/ and skills/, which plugins do ship; only a hand-copied rules/*.md is left with citations and no target
this repo's own .claude/rules/*.md	repo-relative docs/<name>.md — these load only inside this checkout, where the relative path is right, and in a worktree it beats the symlink (which points at the main checkout)

Either way a skill or rule that cites a doc still inlines the load-bearing fact and treats the path as depth-only.

• automation-output-contract.md — the contract an unattended generator (a skill that files PRs or issues on its own) must satisfy so it never bankrupts the reviewer's attention; plus the gh read-surface traps for Draft-triage automation. No kit skill is a generator yet — this is a spec for the next one, and for consuming projects that copy it. Cited from docs/subagent-output-cap.md.
• claim-verification.md — which source settles which kind of claim, the four ways a claim you author (a why-comment, a guard, a count, a gap list) goes wrong, and how a probe's outcome gets misread in both directions. Cited from rules/knowledge-layering.md, which keeps the discipline and the three moments it fires at, and delegates the per-shape checks here; and from the suppression section below.
• code-review-path-scoped-rules.md — why path-scoped .claude/rules/** are invisible to local /code-review, what the orchestrate template's Step 4 does instead, and the InstructionsLoaded probe used for both the kit-docs and claudeMdExcludes measurements. Cited from agents/code-reviewer.md, skills/write-adr/SKILL.md, and the suppression section below.
• subagent-output-cap.md — how the per-model output caps in rules/subagent-usage.md were obtained (catalog extraction plus four controls), and how to re-measure them in about two seconds after a Claude Code upgrade; plus why the split thresholds are not cap-derived. Cited from rules/subagent-usage.md, which keeps the numbers and the decisions and delegates the rest here.

Install as a plugin

The marketplace splits the kit into two plugins so a project can take the skills/agents without the hooks:

• claude-kit — the 7 skills and 3 agents. No hooks.
• claude-kit-hooks — the PR-workflow hooks (hooks/hooks.json). Install this only if your project does not already register its own force-push guard / PR review gate / PR docs-check / PR reflection hooks — otherwise both copies fire on every matching tool call.

/plugin marketplace add <owner>/claude-kit
/plugin install claude-kit@claude-kit
/plugin install claude-kit-hooks@claude-kit   # optional, see above

(For a private repository, substitute the git URL — this works with your normal git credentials, no extra auth setup needed.)

Plugin-delivered skills and agents are namespaced (/claude-kit:orchestrate-creator, claude-kit:critic), so they never collide with a project's own same-named assets.

To pin the marketplace for everyone who clones a consuming project, add to that project's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "claude-kit": {
      "source": { "source": "github", "repo": "<owner>/claude-kit" }
    }
  },
  "enabledPlugins": { "claude-kit@claude-kit": true }
}

This delivers skills and agents only (plus hooks if you opted in).

Install via symlinks (rules included)

./install.sh

This symlinks agents/, skills/, hooks/, and rules/ from this repo into ~/.claude/, plus docs/ as ~/.claude/kit-docs/ (see the Docs entry above), so edits here are live immediately — intended for the author's own machine.

• ./install.sh doctor — diagnose the current state of ~/.claude's top-level symlinks (OK / DANGLING / NOT-LINKED / MISSING), useful after moving or removing this repo, or after a release adds a link you have not installed yet. doctor is read-only and safe from anywhere; installing refuses to run from a git worktree, which would repoint ~/.claude at a directory you are about to delete.
• jq is required for the hook guards (e.g. block-force-push.sh) to parse tool input; without it they fail open (silently no-op) rather than block anything. install.sh warns if jq is missing.

⚠ rules/ is a co-install dependency

Claude Code plugins cannot distribute rules/ — /plugin install only delivers skills, agents, and hooks. The rules/*.md files in this repo are the canonical source, but they only reach ~/.claude/rules/ via ./install.sh or a manual copy.

If you installed claude-kit as a plugin only, the rules are simply absent. The skills in this kit are written to degrade gracefully in that case — falling back to inline defaults — but for full behavior, co-install the rules with ./install.sh (or copy rules/*.md into your own ~/.claude/rules/ by hand — and docs/ to ~/.claude/kit-docs/, or the ~/.claude/kit-docs/… citations inside those rules will not resolve).

Suppressing these rules in a project that keeps its own copy

rules/*.md are always-loaded — 20,834 B (cat rules/*.md | wc -c, 2026-08-21) paid on every turn of every session on the machine. A consuming project that has already copied them into its own .claude/rules/ pays for both copies. claudeMdExcludes drops the kit's, leaving the project's alone:

// <project>/.claude/settings.local.json
{
  "claudeMdExcludes": [
    "/abs/path/to/claude-kit/rules/knowledge-layering.md",
    "/abs/path/to/claude-kit/rules/subagent-usage.md",
    "/abs/path/to/claude-kit/rules/context-budget.md",
    "/abs/path/to/claude-kit/rules/delegation.md",
    "/abs/path/to/claude-kit/rules/session-hygiene.md",
    "/abs/path/to/claude-kit/rules/skill-feedback.md"
  ]
}

Generate that block for your machine (readlink -f turns the ~/.claude/rules/ symlinks into the paths the matcher wants), then delete every line this project has no copy of — the loop emits the whole kit, plus any personal rules of your own on a hand-copy install:

for f in ~/.claude/rules/*.md; do readlink -f "$f"; done | jq -R . | jq -s '{claudeMdExcludes: .}'

What the procedure depends on:

• Only where the project keeps its own copy. With no local copy the kit rules are the baseline, so excluding them deletes it rather than slimming it — pasting the generated block wholesale is exactly that mistake. That case is what the always-loaded files are kept dense for; it has no suppression answer.
• Enumerate full paths; do not glob. A …/claude-kit/rules/*.md glob does match (measured), but it also swallows rules added to the kit later — ones this project has no copy of, and so would be suppressing to nothing. The enumeration degrades the safe way instead: a new kit rule simply shows up until someone adds it deliberately.
• Write an absolute path. A literal ~ silently matches nothing. The matcher does no tilde expansion, so "~/.claude/rules/subagent-usage.md" is a no-op — no error, no warning, the rule just keeps loading. Prefer the symlink-resolved path the generator above emits; per-form results (including the expanded home path) are in docs/code-review-path-scoped-rules.md.
• Per-machine, never committed. The paths are absolute and machine-specific, and settings.local.json is gitignored. The kit can carry the procedure and nothing else.

Verify it took effect with an InstructionsLoaded hook (matcher session_start) logging file_path — a control arm with no claudeMdExcludes must show the kit paths, and a bogus-path arm must leave them all loaded, or the instrument is proving nothing (docs/claim-verification.md; the same hook, wired up, plus the per-form table, is in docs/code-review-path-scoped-rules.md). Re-verify on a Claude Code upgrade; last measured 2026-08-13 on 2.1.228 and 2.1.229.

Scrubbing / privacy

This repo starts from fresh git history and contains no personal memory or machine settings. scripts/scrub-check.sh is the committed leak-check gate — run it before pushing:

./scripts/scrub-check.sh

It runs automatically in CI (.github/workflows/ci.yml) on every push to main and every pull request, alongside shellcheck and manifest/symlink integrity checks. You can also wire it as a local pre-push hook.

License

MIT