Claude Code Skills

Personal skills and companion CLIs for Claude Code, tailored to my own workflows and preferences. These are shared for reference and inspiration, not as ready-made solutions. If you use them, expect to adapt them to your own setup — don't reuse blindly.

Shell utilities that partner with the skills. Not invoked by Claude — you run them from your terminal.

Design principles and key behaviors shared across /jr-audit, /jr-review, /jr-ship, /jr-skill-audit, /jr-i18n and /jr-mermaid. Detailed phase-by-phase logic lives in each skill's SKILL.md. (/jr-doctor is intentionally simpler — it's a low-effort diagnostic that runs no reviewer/implementer swarm and no validation — the only agents it spawns are the Group J capability probe's two throwaway haiku self-tests of the reviewer→lead channel (default-on, --no-probe skips); the conventions below do not apply to it. /jr-skill-audit participates in the conventions that apply to its scope: phased execution, parallel-first dispatch, silent agents, severity rubric, finding format. Conventions tied to code modifications — fix verification, auto-learning, validation — do not apply because skill-audit is findings-only in v1.)

• Phased execution — every skill runs in numbered phases, each with a prominent header and a cumulative timeline (Phase 1 ✓ (3s) → Phase 2 ✓ (18s) → ...).
• Parallel-first — tracks within a phase run simultaneously; independent reads, greps, and bash calls are batched into a single message.
• Silent agents, noisy lead — reviewer/implementer subagents only report via task messages; only the lead prints progress to the user.
• Declared effort: a session /effort change does not move the effort-adaptive settings (reviewer breadth, convergence defaults and /jr-review's codebase-memory-mcp graph probe). On Claude Code 2.1.133 and later, CLAUDE_EFFORT reaches Bash so each skill's declared frontmatter tier applies, and the two effort-adaptive skills (/jr-audit, /jr-review) both declare max. Below 2.1.133 the variable is not exposed; each read falls back to the skill's own pinned tier, so those settings behave as max there too rather than dropping a tier. /jr-skill-audit also declares max but reads the variable nowhere: it has no effort-adaptive overlay, and its advisor threshold is flat for that reason (see its entry under Advisor integration). Where max applies, /jr-review's probe is no longer gated on a 20-file diff, so any non-headless run may offer to index the whole repo.

• Content-excerpt sanity check (/jr-audit, /jr-review) — every reviewer finding must include a 3-line verbatim excerpt from the cited file. The lead re-reads the cited range and rejects findings whose excerpt doesn't match — catches both line-number and content hallucinations. A per-reviewer 25%+ rejection rate escalates to the final report as ACTION REQUIRED.
• Claim verification (/jr-audit, /jr-review, /jr-skill-audit, /jr-i18n, /jr-mermaid) — the lead independently classifies each finding as code-internal (provable from local files) or external-authority (API deprecation, version behavior, CVE, WCAG/OWASP). For external-authority findings, it by default fetches an authoritative source (raw .md / gh api, never a lone WebFetch) to confirm or refute the claim before surfacing it. Refuted claims are rejected under [REJECTED — CLAIM REFUTED BY SOURCE]; unverifiable ones cap to speculative and are never auto-applied. Pass --no-verify-claims to skip the fetch (offline/speed). Canonical doctrine: shared/claim-verification.md.
• Fix verification (/jr-audit, /jr-review Phase 5.55) — after implementers mark findings "addressed", the lead re-reads the cited file:line (±5 lines) and classifies each as verified / unverified / moved. Soft flag: informs the user, does not auto-revert.
• Cache semantic re-verification — cached lint/typecheck commands are probed with --version / --help before use. Stale caches (PATH change, removed binary, pruned devDependencies) are invalidated rather than silently trusted.
• Dimension ownership + severity rubric — strict reviewer boundaries and a critical | high | medium | low × certain | likely | speculative grid prevent duplicate findings and keep noise low (see shared/reviewer-boundaries.md).

Both /jr-audit and /jr-review support --converge[=N]: a re-audit/re-review loop that wraps Phases 2–6 in a repeatable cycle with auto-approval, iterating until no remaining findings, no files modified, or the iteration cap is hit.

• /jr-review --converge has an effort-adaptive iteration default and caps at 10. After convergence, a fresh-eyes security pass runs with a clean reviewer context to catch regressions introduced by auto-fixes. From iteration 3+ the lead calls advisor() to spot compound drift before another iteration fires.
• /jr-audit --converge caps at 5, tighter than /jr-review, because the per-iteration blast radius is higher (full-codebase scope vs. PR diff). Pre-iteration advisor() fires from iteration 2+ for the same drift detection.
• Convergence passes scale down reviewer count regardless of the original full/quick setting to keep tokens bounded as iterations stack: /jr-review caps at max 2 reviewers (small-diff scaling); /jr-audit runs the top 3 dimensions only.

The advisor() tool (stronger reviewer model that sees the full transcript) is consulted at irreversible / high-blast-radius junctures:

• /jr-ship --merge before gh pr merge — single-PR and each multi-PR merge (only fires when --merge is set; the new default stops after CI without merging).
• /jr-ship before committing to a split plan — pushing the wrong split is hard to undo.
• /jr-review Phase 4 pre-approval when finding count ≥ 20 OR a single dimension contributes ≥ 60% of all findings (mirrors /jr-audit's skewed-reviewer cue).
• /jr-review Phase 5 pre-dispatch — auto-approved findings drive substantive code edits; mirrors /jr-audit Phase 5.
• /jr-review Phase 6 stuck-loop — fires once when regression-fix retry count == maxRetries and new failures persist (single-fire guard prevents budget burn).
• /jr-review --converge before iteration 3+ — wasteful passes compound quickly.
• /jr-audit Phase 4 pre-approval (skewed-dimension trigger as above).
• /jr-audit Phase 5 pre-dispatch — multi-implementer parallel modifications across the full codebase are the highest blast radius.
• /jr-audit --converge before iteration 2+ — lower bar than /jr-review because /jr-audit's iteration cap is also lower.
• /jr-skill-audit Phase 4 pre-approval (finding count ≥ 20 OR skewed-dimension, as above).
• /jr-skill-audit Phase 7 declare-done — gated on non-triviality (findingCount ≥ 3 (flat, not effort-derived, since effort: max is pinned), OR dimensionCount ≥ 3 OR rejectionCount ≥ 1 OR unverifiableCount ≥ 1 OR unreportedCount ≥ 1 OR dimensionCount == 0 (total loss of coverage: every other counter reads 0 because nothing was ever spawned) OR an abort fired) so trivially-clean small runs don't burn budget. Per shared/advisor-criteria.md's "Unconditional advisor on every run" anti-pattern.
• /jr-review Phase 7 declare-done — gated on non-triviality (findingCount ≥ 5 OR dimensionCount ≥ 3 OR rejectionCount ≥ 1 OR any fix applied in Phase 5/6 OR abortMode).
• /jr-audit Phase 7 declare-done — same gate as /jr-review.
• /jr-i18n Phase 4 pre-approval (findings ≥ 20 OR one locale holds ≥ 60%), and Phase 7 declare-done (findings ≥ 5 OR locales ≥ 3 OR rejections ≥ 1 OR an abort fired).
• /jr-mermaid declare-done before the --out write — fires when the diagram is non-trivial (roughly ≥ 8 nodes/edges) or --out will write into a file, so an invented or dropped node is caught before it lands.
• /jr-ship CI-fix stuck-loop — single-fire, after the 2nd fix cycle also ends non-green (ciFixAdvisorFired guard).

Advisor is advisory-only; the user still gates the action if advisor flags concerns. Canonical rules for when and how to call advisor (substantive-edit boundaries, declare-done points, single-fire guards, conditional triggers) live in shared/advisor-criteria.md and are consumed by /jr-skill-audit's advisor-coverage-reviewer.

When codebase-memory-mcp is available and the repo is indexed:

• Reviewers prefer search_graph / trace_path / detect_changes over grep for structural questions (call-chain impact, dead-code detection, import edges).
• /jr-ship Phase 2 uses detect_changes + trace_path for split-plan dependency detection.
• /jr-audit dead-code sweeps use search_graph(max_degree=0, exclude_entry_points=true).

grep fallback is preserved — nothing breaks if the MCP is unavailable or the repo isn't indexed.

Rejection patterns feed back into future runs:

• Per-repo — 2+ same-pattern rejections in one run write a suppression to .claude/review-config.md.
• Cross-run promotion — 2+ same-pattern rejections in 2+ separate runs prompt to promote the rule to user-global feedback_*.md memory. Explicit consent required; security dimension excluded. (Lowered from 3+, which empirically never fired in practice.)
• Cross-skill shared state — /jr-audit and /jr-review write to the same .claude/audit-history.json schema (runs[], runSummaries[], reviewerStats[], lastPromptedAt), so a rejection in one skill counts toward promotion thresholds in the other and lastPromptedAt suppresses re-prompts across both.
• FP-rate calibration — running rejection rate per reviewer dimension is computed from reviewerStats[]; any dimension averaging ≥ 25% rejected gets a calibration note prepended to its Phase 2 prompt.

• bin/tackle bootstraps a Claude Code session in an isolated worktree at .claude/worktrees/<id>/ with PR/MR/issue context pre-loaded into CLAUDE.local.md (auto-loaded, never committed, git-excluded). The forge (gh for GitHub, glab for GitLab) is auto-detected from the repo's remote.
• tackle --scratch drops a marker at <worktree>/.git/info/scratch-session. /jr-ship detects the marker and renames the placeholder branch in place from the derived conventional-commit name instead of creating a new branch.
• /jr-ship detects tackle worktrees via the /.claude/worktrees/ path segment and auto-cleans them once CI passes (worktree remove + branch delete). With --merge, cleanup runs after the merge succeeds; without --merge (the default), cleanup runs as soon as CI is green and the PR stays open for review. Cleanup is skipped only on --draft, CI failure, or --merge with required-but-not-yet-granted reviews — in those cases the worktree persists and you can come back manually, with tackle --cleanup, or with /jr-ship --merge resume mode.
• tackle uses raw git worktree add rather than claude -w to preserve deferred branch naming (claude -w forces a worktree-<name> prefix that would conflict with /jr-ship's conventional-commit branch derivation).

Canonical sources for rules referenced at Phase 1 Track A of /jr-audit, /jr-review, /jr-skill-audit and /jr-i18n (and at single-track Phase 1 by /jr-mermaid). /jr-ship reads its subset inline in Phase 1; /jr-doctor Group D smoke-parses every file at runtime (warn-only) rather than consuming the rules; /jr-tackle cross-references a few without reading them. Each file is the single source of truth; the skills read them at startup and enforce a hard-fail guard (if any file is missing, empty, or fails a structural smoke-parse, Phase 1 aborts immediately rather than silently degrading coverage). /jr-doctor Group I additionally checks for inline duplication of these files' load-bearing strings without a corresponding shared/<file> reference — drift catches up quickly when the canonical pattern leaks into per-skill copies.

Two narrative docs explain the framework when you need it (loaded on-demand via @docs/<file>.md so they don't pay the per-session token cost):

• docs/skill-anatomy.md — the five-tier content layout (SKILL.md body / shared/*.md / <skill>/protocols/*.md / <skill>/scripts/*.sh / <skill>/templates/*), where new content goes (decision tree), the smoke-parse anchor + hard-fail guard convention, allowed-tools narrowing rules, anti-patterns, and a checklist for adding a new skill. Read this before extracting content from a SKILL.md or adding a new skill.
• docs/worktree-architecture.md — the bin/tackle ↔ /jr-ship contract: worktree layout, marker conventions, scratch-session flow, primary-vs-secondary worktree cleanup paths, and the explicit anti-patterns (don't use claude -w, don't commit markers, etc.). Read this before modifying tackle or /jr-ship's worktree handling.

git clone git@github.com:julienroussel/skills.git ~/.claude/skills
ln -sf ~/.claude/skills/bin/tackle ~/.local/bin/tackle
ln -sf ~/.claude/skills/bin/tackle-top ~/.local/bin/tackle-top

# Install the native reviewer/implementer agent types so the /jr-audit, /jr-review,
# /jr-i18n, /jr-skill-audit swarms resolve them in ANY repo (restart Claude Code after):
mkdir -p ~/.claude/agents
ln -sf ~/.claude/skills/.claude/agents/jr-reviewer.md   ~/.claude/agents/jr-reviewer.md
ln -sf ~/.claude/skills/.claude/agents/jr-implementer.md ~/.claude/agents/jr-implementer.md

After installing, run /jr-doctor from any repo to verify the setup is wired up — it checks CLI tools, plugins, settings.json keys, installed skills, shared protocol files, hooks, and (per-repo) .gitignore coverage. /jr-doctor --fix appends missing patterns to the current repo's .gitignore (per-change confirmation; never edits settings.json or installs anything).

macOS only — one-time Accessibility permission for tackle's prompt prefill: System Settings → Privacy & Security → Accessibility → enable your terminal app (Terminal.app or iTerm2). Without it, tackle still works but the starter prompt won't be pre-typed into Claude's input box. Edit the PROMPT_*_TEMPLATE constants at the top of bin/tackle to customize the starter prompts.

Vanilla-first: no required third-party plugin. The reviewer/implementer swarms use two repo-local native agent types: jr-reviewer (no Write/Edit) and jr-implementer, defined in .claude/agents/*.md and installed at ~/.claude/agents/ by the Setup step above. No plugin, no experimental flag. (They replaced agent-teams@claude-code-workflows; see issue #72.)

Optional integrations (make a skill better when present; documented fallback when absent, never an abort):

• codebase-memory-mcp (MCP server) — when available and the repo is indexed, /jr-audit, /jr-review, and /jr-ship use graph queries (search_graph, trace_path, detect_changes) for cross-file impact analysis, dead-code detection, and split-analysis dependency detection. Grep fallback preserved when unavailable or unindexed.
• advisor tool — used at irreversible / high-blast-radius junctures and declare-done checkpoints across /jr-ship, /jr-audit, /jr-review, /jr-skill-audit, /jr-i18n, /jr-mermaid and /jr-tackle (full list in the Advisor integration section above; canonical "when to call" rules in shared/advisor-criteria.md). Advisory-only; the user still gates the action. Without --merge, /jr-ship stops after CI is green and the merge advisor never fires (safer default for team review).

Some reviewer methodologies were inlined into prompts from plugins that are never spawned and are not dependencies (/jr-doctor does not check for them; their absence changes nothing): pr-review-toolkit@claude-plugins-official and security-scanning@claude-code-workflows. The full plugin→dimension mapping lives in CLAUDE.md under "Methodology credits" (kept in one place to avoid drift).

/jr-audit and /jr-review read user-global and project-scoped auto-memory at Phase 1 Track A:

• Project memory: ~/.claude/projects/<encoded-cwd>/memory/ — all memory types (user, feedback, project, reference) apply to this project. Bootstrap a fresh project quickly with bin/seed-project-memory (see Companion CLIs).
• User-global memory: ~/.claude/projects/"${HOME//[.\/]/-}--claude-skills"/memory/ (derived from $HOME, portable) — only user_*.md entries are consumed globally (role, expertise, communication preferences). feedback_*.md and others stay strictly per-repo to avoid framework-specific preferences leaking across stacks.

Phase 4.5 auto-learns rejections: 2+ same-pattern rejections in one run write to .claude/review-config.md (repo-local); 2+ across 2+ separate runs prompt to promote the rule to user-global feedback_*.md (explicit consent, security dimension excluded).