@spardutti/claude-skills 2.46.0 → 2.47.0

package/README.md

@@ -137,6 +137,7 @@ Portable slash commands installed to `.claude/commands/`. Some orchestrate paral
 | `/optimize` | Make one measured job faster without changing what it proves — fixes a benchmark and a result that must not move, sends 4 read-only subagents to find suspects, then changes one thing per round with a prediction written first, keeping only what beats the noise. Profiles after every wrong prediction, reruns before judging a result that flipped, and ends by writing the cause as a skill rule for you |
 | `/handoff` | Write a handoff doc so a fresh session picks the work up — captures what auto-compaction loses: decisions made and rejected, dead ends already ruled out, why the tree is dirty, and the one next step |
 | `/lockdown` | Per-repo supply-chain hardening — detects the package managers, Dockerfiles, and CI in use, then guides you through and applies install-time, deploy, and pipeline hardening for npm/pnpm, pip/uv, Docker, and GitHub Actions |
+| `/skill-report` | Which installed skills earn their place in this repo — every `/ship` skills audit is logged by a hook, and this tallies it: how often each skill applied, how often it caught a violation, and the rule it catches most. Names rules that break often enough to become a script check, and skills that never flag and may be dead weight |
 
 ## How It Works
 
@@ -193,6 +194,7 @@ scripts/       validate-skills.mjs — checks skill length caps and reference in
                ship-gate.sh — /ship's file-length, folder-structure and mutation checks, behind an exit code
                ship-gate-hook.sh — refuses gh pr create/merge without a ship-gate receipt
                version-check.sh — SessionStart nudge when a newer catalog is published
+               skill-flags-record.sh — logs each /ship skills-audit verdict; skill-report.mjs tallies it
                gauntlet-selftest.sh — behavioural tests for the hooks (runs on pre-push)
                gauntlet-survey.sh — what the hook would do in every repo under a directory
                preflight.sh — everything that must pass before a release

package/hooks/skill-flags-record.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# SubagentStop: appends each gauntlet-skills verdict to .claude/skill-flags.jsonl.
+
+INPUT=$(cat | tr -d '\n')
+
+case "$INPUT" in
+  *'"agent_type":"gauntlet-skills"'*) ;;
+  *) exit 0 ;;
+esac
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(dirname "$(dirname "$SCRIPT_DIR")")"
+
+# Kept JSON-escaped as it arrived, so the line stays valid JSON without a parser.
+REPLY=$(printf '%s' "$INPUT" | sed -nE 's/.*"last_assistant_message":"(([^"\\]|\\.)*)".*/\1/p')
+[ -z "$REPLY" ] && exit 0
+
+TRANSCRIPT=$(printf '%s' "$INPUT" | grep -o '"agent_transcript_path":"[^"]*"' | head -1 | sed 's/.*:"//; s/"$//')
+MODEL=""
+[ -f "$TRANSCRIPT" ] && MODEL=$(grep -o '"model":"[^"]*"' "$TRANSCRIPT" | tail -1 | sed 's/.*:"//; s/"$//')
+
+printf '{"ts":"%s","model":"%s","reply":"%s"}\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$MODEL" "$REPLY" \
+  >> "$PROJECT_DIR/.claude/skill-flags.jsonl"
+
+exit 0

package/hooks/skill-report.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Prints, per skill, how often the /ship skills audit applied it and flagged a violation.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_LOG = fileURLToPath(new URL("../skill-flags.jsonl", import.meta.url));
+
+function parseVerdict(line) {
+  try {
+    const { model, reply } = JSON.parse(line);
+    return { model, verdict: JSON.parse(reply.slice(reply.indexOf("{"), reply.lastIndexOf("}") + 1)) };
+  } catch {
+    return null;
+  }
+}
+
+function tally(lines) {
+  const skills = new Map();
+  const models = new Map();
+  let unreadable = 0;
+  for (const line of lines) {
+    const parsed = parseVerdict(line);
+    if (!parsed?.verdict?.skill) { unreadable++; continue; }
+    const { model, verdict } = parsed;
+    if (!(verdict.checked > 0)) continue;
+    const s = skills.get(verdict.skill) ?? { audits: 0, flagged: 0, rules: new Map() };
+    s.audits++;
+    const violations = Array.isArray(verdict.violations) ? verdict.violations : [];
+    if (violations.length) s.flagged++;
+    for (const v of violations) s.rules.set(v.rule, (s.rules.get(v.rule) ?? 0) + 1);
+    skills.set(verdict.skill, s);
+    if (model) models.set(model, (models.get(model) ?? 0) + 1);
+  }
+  return { skills, models, unreadable };
+}
+
+function topRule(rules) {
+  const [rule] = [...rules].sort((a, b) => b[1] - a[1])[0] ?? ["-"];
+  return rule.length > 60 ? rule.slice(0, 57) + "..." : rule;
+}
+
+function render({ skills, models, unreadable }) {
+  if (!skills.size) return "No skill audits recorded yet. Run /ship to record some.";
+  const rows = [...skills].sort((a, b) => b[1].flagged - a[1].flagged || a[0].localeCompare(b[0]));
+  const width = Math.max(5, ...rows.map(([name]) => name.length));
+  const out = [`${"skill".padEnd(width)}  audits  flagged  top rule broken`];
+  for (const [name, s] of rows) {
+    out.push(`${name.padEnd(width)}  ${String(s.audits).padStart(6)}  ${String(s.flagged).padStart(7)}  ${topRule(s.rules)}`);
+  }
+  if (models.size) out.push("", "models: " + [...models].map(([m, n]) => `${m} (${n})`).join(", "));
+  if (unreadable) out.push(`unreadable lines: ${unreadable}`);
+  return out.join("\n");
+}
+
+let text = "";
+try {
+  text = readFileSync(process.argv[2] ?? DEFAULT_LOG, "utf-8");
+} catch {
+  // no log yet
+}
+console.log(render(tally(text.split("\n").filter(Boolean))));

package/lib/hook-settings.mjs

@@ -11,6 +11,7 @@ const GAUNTLET_FILENAME = "gauntlet.sh";
 const SHIP_GATE_FILENAME = "ship-gate.sh";
 const SHIP_GATE_HOOK_FILENAME = "ship-gate-hook.sh";
 const VERSION_CHECK_FILENAME = "version-check.sh";
+const SKILL_FLAGS_FILENAME = "skill-flags-record.sh";
 const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
 const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
 
@@ -116,6 +117,16 @@ export async function registerHooks(settingsPath) {
     settings.hooks.Stop = [gauntletEntry];
   }
 
+  // No matcher: the script filters on agent_type itself.
+  const skillFlagsCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${SKILL_FLAGS_FILENAME}`;
+  const skillFlagsEntry = { hooks: [{ type: "command", command: skillFlagsCommand }] };
+
+  if (Array.isArray(settings.hooks.SubagentStop)) {
+    upsert(settings.hooks.SubagentStop, SKILL_FLAGS_FILENAME, skillFlagsEntry);
+  } else {
+    settings.hooks.SubagentStop = [skillFlagsEntry];
+  }
+
   // Both gates clear by touching a marker under /tmp. The hook scripts let those
   // commands through themselves, but auto mode's permission classifier does not:
   // a touch whose only purpose is to unlock a gate is exactly what it refuses.

package/lib/setup-hook.mjs

@@ -20,6 +20,8 @@ import { homedir } from "node:os";
 //   ship-gate-projects.sh     sourced by ship-gate.sh — project detection, reuse
 //   ship-gate-hook.sh         PreToolUse on Bash — no commit without a receipt
 //   version-check.sh          SessionStart — a line when a newer catalog exists
+//   skill-flags-record.sh     SubagentStop — logs each skills-audit verdict
+//   skill-report.mjs          read by /skill-report — tallies that log
 
 const GATE_FILENAME = "skill-gate.sh";
 const AUTO_MARK_FILENAME = "skill-gate-automark.sh";
@@ -31,6 +33,8 @@ const SHIP_GATE_STRUCTURE_FILENAME = "ship-gate-structure.sh";
 const SHIP_GATE_FILES_FILENAME = "ship-gate-files.sh";
 const SHIP_GATE_HOOK_FILENAME = "ship-gate-hook.sh";
 const VERSION_CHECK_FILENAME = "version-check.sh";
+const SKILL_FLAGS_FILENAME = "skill-flags-record.sh";
+const SKILL_REPORT_FILENAME = "skill-report.mjs";
 const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
 const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
 
@@ -112,6 +116,8 @@ export async function setupHook(targetDir = process.cwd()) {
     SHIP_GATE_FILES_FILENAME,
     SHIP_GATE_HOOK_FILENAME,
     VERSION_CHECK_FILENAME,
+    SKILL_FLAGS_FILENAME,
+    SKILL_REPORT_FILENAME,
   ]) {
     const dest = join(hooksDir, name);
     await writeFile(dest, await readHookSource(name), { mode: 0o755 });
@@ -133,5 +139,6 @@ export async function setupHook(targetDir = process.cwd()) {
   console.log(`  Hook installed: .claude/hooks/${GAUNTLET_FILENAME}`);
   console.log(`  Installed: .claude/hooks/${SHIP_GATE_FILENAME} (used by /ship)`);
   console.log(`  Hook installed: .claude/hooks/${SHIP_GATE_HOOK_FILENAME}`);
+  console.log(`  Hook installed: .claude/hooks/${SKILL_FLAGS_FILENAME}`);
   console.log(`  Settings updated: .claude/settings.json`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.46.0",
+  "version": "2.47.0",
   "description": "Guardrails for Claude Code — best-practice skills, planning commands, and delivery gates.",
   "type": "module",
   "repository": {
@@ -11,7 +11,7 @@
     "claude-skills": "bin/cli.mjs"
   },
   "scripts": {
-    "prepack": "cp ../README.md README.md && mkdir -p hooks && cp ../scripts/skill-gate.sh ../scripts/skill-gate-automark.sh ../scripts/skill-application-gate.sh ../scripts/gauntlet.sh ../scripts/ship-gate.sh ../scripts/ship-gate-projects.sh ../scripts/ship-gate-structure.sh ../scripts/ship-gate-files.sh ../scripts/ship-gate-hook.sh ../scripts/version-check.sh hooks/",
+    "prepack": "cp ../README.md README.md && mkdir -p hooks && cp ../scripts/skill-gate.sh ../scripts/skill-gate-automark.sh ../scripts/skill-application-gate.sh ../scripts/gauntlet.sh ../scripts/ship-gate.sh ../scripts/ship-gate-projects.sh ../scripts/ship-gate-structure.sh ../scripts/ship-gate-files.sh ../scripts/ship-gate-hook.sh ../scripts/version-check.sh ../scripts/skill-flags-record.sh ../scripts/skill-report.mjs hooks/",
     "postpack": "git checkout -- README.md && rm -rf hooks"
   },
   "engines": {