@spardutti/claude-skills 2.31.0 → 2.32.0

package/hooks/skill-gate-automark.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# PostToolUse on Skill: marks gate satisfied + records loaded skill.
+
+INPUT=$(cat)
+
+SESSION_ID=$(printf '%s' "$INPUT" | grep -o '"session_id":"[^"]*"' | head -1 | sed 's/"session_id":"//; s/"$//')
+if [ -z "$SESSION_ID" ]; then
+  exit 0
+fi
+
+# Keyed exactly as the gate keys it. A subagent carries the parent's
+# session_id, so both scripts fall back to agent_id when one is present — and
+# they must agree, or a loaded skill writes a marker the gate never looks for
+# and every edit is denied forever.
+AGENT_ID=$(printf '%s' "$INPUT" | grep -o '"agent_id":"[^"]*"' | head -1 | sed 's/"agent_id":"//; s/"$//')
+KEY="$SESSION_ID"
+if [ -n "$AGENT_ID" ]; then
+  KEY=$(printf '%s' "$AGENT_ID" | tr -cd 'A-Za-z0-9_-')
+fi
+
+touch "/tmp/claude-skill-gate-$KEY"
+
+SKILL_NAME=$(printf '%s' "$INPUT" | grep -o '"skill":"[^"]*"' | head -1 | sed 's/"skill":"//; s/"$//')
+if [ -n "$SKILL_NAME" ]; then
+  # Sanitize: only allow [A-Za-z0-9_-] in the marker filename.
+  SAFE_NAME=$(printf '%s' "$SKILL_NAME" | tr -cd 'A-Za-z0-9_-')
+  if [ -n "$SAFE_NAME" ]; then
+    touch "/tmp/claude-skill-loaded-$KEY-$SAFE_NAME"
+  fi
+fi
+
+exit 0

package/hooks/skill-gate.sh

@@ -0,0 +1,192 @@
+#!/bin/bash
+# PreToolUse gate: forces skill evaluation before file-writing tools run.
+
+INPUT=$(cat)
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(dirname "$(dirname "$SCRIPT_DIR")")"
+
+if ! find "$PROJECT_DIR" -path '*/.claude/skills/*/SKILL.md' 2>/dev/null | grep -q .; then
+  exit 0
+fi
+
+SESSION_ID=$(printf '%s' "$INPUT" | grep -o '"session_id":"[^"]*"' | head -1 | sed 's/"session_id":"//; s/"$//')
+if [ -z "$SESSION_ID" ]; then
+  exit 0
+fi
+
+# A subagent reports the PARENT's session_id — measured, not assumed: a probe
+# hook dumped its own stdin from the main thread and from inside a subagent and
+# the two ids were identical. So a worker spawned to implement part of a plan
+# inherited the main thread's cleared markers and edited with none of the
+# skills loaded in its own context.
+#
+# agent_id is present only inside a subagent, and holds steady across that
+# subagent's turns, so keying on it gives each worker its own namespace and
+# costs it one Skill call per skill, not one per turn.
+AGENT_ID=$(printf '%s' "$INPUT" | grep -o '"agent_id":"[^"]*"' | head -1 | sed 's/"agent_id":"//; s/"$//')
+KEY="$SESSION_ID"
+if [ -n "$AGENT_ID" ]; then
+  KEY=$(printf '%s' "$AGENT_ID" | tr -cd 'A-Za-z0-9_-')
+fi
+
+# The marker is checked at the very bottom now, not here. A skill the edited
+# file's own stack demands is not something an already-cleared gate excuses,
+# so the required-skill scan below runs first.
+MARKER="/tmp/claude-skill-gate-$KEY"
+
+# Write|Edit|MultiEdit is not the only way to change a file. A session that edits
+# through `python3 - <<'PY'` in Bash walked past this gate entirely — twelve
+# source files, not one prompt — and some harnesses actively tell the model to
+# prefer Bash for edits. So Bash is gated too, but only for commands that can
+# write, and only until the gate is cleared once for the session.
+
+# Skills are about code. Blocking a plan document to ask how the React rules
+# apply is pure noise, and a repo full of PLAN_*.md hits it on every write.
+# Config files stay gated — skills do have rules about tsconfig and compose.
+PROSE_EXT='md|mdx|txt|rst|adoc|png|jpg|jpeg|gif|svg|webp|ico'
+CODE_EXT='ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|swift|sql|sh|json|ya?ml|toml'
+
+TOOL=$(printf '%s' "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | sed 's/.*:"//; s/"$//')
+
+# Every file this call would write, collected for the required-skill scan below.
+TARGETS=""
+
+if [ "$TOOL" != "Bash" ]; then
+  # The structured tools name their target outright.
+  TARGET=$(printf '%s' "$INPUT" | grep -o '"file_path":[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
+  case "$TARGET" in
+    # The settings file that configures the escape hatch cannot sit behind the
+    # gate, or a denied ack has no way to be un-denied. The bare relative form
+    # matters: a skill claiming **/* gated it, and nothing could re-open it.
+    .claude/settings.json|.claude/settings.local.json) exit 0 ;;
+    */.claude/settings.json|*/.claude/settings.local.json) exit 0 ;;
+    *.*) printf '%s' "$TARGET" | grep -qiE ".($PROSE_EXT)$" && exit 0 ;;
+  esac
+  TARGETS="$TARGET"
+fi
+if [ "$TOOL" = "Bash" ]; then
+  CMD=$(printf '%s' "$INPUT" | grep -o '"command":[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//')
+
+  # Never gate the command that clears the gate, or this deadlocks.
+  case "$CMD" in
+    *claude-skill-gate-*|*claude-skill-acked-*|*claude-skill-loaded-*) exit 0 ;;
+    *.claude/settings.json*|*.claude/settings.local.json*) exit 0 ;;
+  esac
+
+  # /dev/null redirects are not file writes; drop them before looking for one.
+
+  # A command that names a prose file and no code file is writing prose.
+  if printf '%s' "$CMD" | grep -qiE ".($PROSE_EXT)([^A-Za-z0-9]|$)"      && ! printf '%s' "$CMD" | grep -qiE ".($CODE_EXT)([^A-Za-z0-9]|$)"; then
+    exit 0
+  fi
+  STRIPPED=$(printf '%s' "$CMD" | sed 's![12]*>>*[[:space:]]*/dev/null!!g')
+  WRITES=""
+  case "$STRIPPED" in
+    *">"*|*"tee "*|*"sed -i"*|*"cp "*|*"mv "*|*"truncate "*|*"dd "*) WRITES=1 ;;
+  esac
+  # An interpreter given inline code or a heredoc can write anything, and the
+  # shell shows no redirect at all — this is the shape that got past the gate.
+  case "$CMD" in
+    *"<<"*|*python*" -c"*|*node*" -e"*|*perl*" -e"*|*ruby*" -e"*) WRITES=1 ;;
+  esac
+  [ -z "$WRITES" ] && exit 0
+  # A Bash write names its files in the command itself. Dockerfile and
+  # .dockerignore carry no extension, so they are matched by name.
+  TARGETS=$(printf '%s' "$CMD" | grep -oiE "[A-Za-z0-9_./-]+.($CODE_EXT)|[A-Za-z0-9_./-]*(Dockerfile[A-Za-z0-9_.-]*|.dockerignore)" 2>/dev/null)
+fi
+
+# --- mandatory skills -------------------------------------------------------
+# The generic gate below asks the model to rate every skill ACTIVATE or SKIP,
+# and hands it an all-SKIP escape. A session took that escape, touched the
+# marker, and edited React files with none of the React rules loaded. It had
+# followed the hook exactly: the hook let it decide.
+#
+# So a skill that declares BOTH paths: and tracks: stops getting a vote. If the
+# edited file matches its paths AND this project depends on a package it
+# tracks, that skill is mandatory and only Skill(<name>) clears it. Skills
+# without both fields keep the old behaviour, so this tightens nothing that was
+# not deliberately declared.
+MISSING=""
+MANIFESTS=""
+if [ -n "$TARGETS" ]; then
+  MANIFESTS=$(find "$PROJECT_DIR" -maxdepth 4 \( -name node_modules -o -name .git -o -name .venv -o -name dist \) -prune -o \( -name package.json -o -name pyproject.toml -o -name requirements.txt \) -print 2>/dev/null)
+fi
+if [ -n "$TARGETS" ]; then
+  for SKILL_FILE in $(find "$PROJECT_DIR" -path '*/.claude/skills/*/SKILL.md' 2>/dev/null); do
+    # Read gate-paths from under metadata:, never a bare paths: key. A bare
+    # paths: made Claude Code drop the skill from its registry outright —
+    # every Skill(name) call returned "Unknown skill" and, with no SKIP for a
+    # mandatory skill, the session could not edit code at all. metadata is
+    # documented as free-form and ignored by Claude Code, and the docs say in
+    # so many words not to reuse paths as a key inside it.
+    #
+    # The value must be quoted in YAML either way: a scalar opening with * is
+    # an alias indicator.
+    UNQUOTE='s/^["'"'"']//; s/["'"'"']$//'
+    SPATHS=$(sed -n 's/^[[:space:]]*gate-paths:[[:space:]]*//p' "$SKILL_FILE" | head -1 | sed "$UNQUOTE")
+    STRACKS=$(sed -n 's/^tracks:[[:space:]]*//p' "$SKILL_FILE" | head -1 | sed "$UNQUOTE")
+    SNAME=$(sed -n 's/^name:[[:space:]]*//p' "$SKILL_FILE" | head -1 | sed "$UNQUOTE")
+    [ -z "$SPATHS" ] && continue
+    [ -z "$SNAME" ] && continue
+
+    HIT=""
+    for G in $(printf '%s' "$SPATHS" | tr ',' ' '); do
+      # Claude Code writes these gitignore-style. A case glob has no **, but *
+      # already crosses / here, so dropping the **/ prefix is equivalent.
+      G=$(printf '%s' "$G" | sed 's!\*\*/!!g')
+      case "$G" in \**|/*) ;; *) G="*$G" ;; esac
+      for T in $TARGETS; do
+        case "$T" in $G) HIT=1 ;; esac
+      done
+    done
+    [ -z "$HIT" ] && continue
+
+    # A .tsx file is not proof of React — it could be Astro, Solid or Preact.
+    # The packages the skill tracks are the proof, so the manifests decide.
+    #
+    # Some skills need no such proof: a .sql file is SQL and a Dockerfile is a
+    # Dockerfile, and no package declares either. A skill that names paths and
+    # no tracks is taken at its word.
+    PY=""
+    case "$STRACKS" in *pypi*) PY=1 ;; esac
+    DEP=""
+    [ -z "$STRACKS" ] && DEP=1
+    for P in $(printf '%s' "$STRACKS" | tr ',' ' '); do
+      case "$P" in *@*) ;; *) continue ;; esac
+      PKG=$(printf '%s' "$P" | sed 's/@[^@]*$//')
+      [ -z "$PKG" ] && continue
+      for M in $MANIFESTS; do
+        if [ -n "$PY" ]; then
+          grep -qiE "(^|[^A-Za-z0-9_.-])$PKG([^A-Za-z0-9_.-]|$)" "$M" 2>/dev/null && DEP=1
+        else
+          grep -qs "\"$PKG\"" "$M" && DEP=1
+        fi
+      done
+    done
+    [ -z "$DEP" ] && continue
+
+    SAFE=$(printf '%s' "$SNAME" | tr -cd 'A-Za-z0-9_-')
+    [ -f "/tmp/claude-skill-loaded-$KEY-$SAFE" ] && continue
+    case " $MISSING " in *" $SNAME "*) ;; *) MISSING="$MISSING $SNAME" ;; esac
+  done
+fi
+
+if [ -n "$MISSING" ]; then
+  LIST=$(printf '%s' "$MISSING" | sed 's/^ //; s/ /, /g')
+  FIRST=$(printf '%s' "$MISSING" | awk '{print $1}')
+  cat <<EOF
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"BLOCKED: this file's stack has mandatory skills that are not loaded: $LIST.\n\nThere is no SKIP for these. The file matches each skill's declared paths AND this project depends on a package that skill tracks, so they apply as a matter of fact, not judgement. Touching the gate marker will not clear them.\n\nCall Skill($FIRST) now — then every other name in the list — and retry the edit."}}
+EOF
+  exit 0
+fi
+
+if [ -f "$MARKER" ]; then
+  exit 0
+fi
+
+
+cat <<EOF
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"BLOCKED: skill evaluation required before file edits in this session.\n\nStep 1 — evaluate every available skill as ACTIVATE or SKIP with a one-line reason.\n\nStep 2 — you MUST take EXACTLY ONE of these tool actions to clear the gate. Listing skills in text is NOT enough; retrying the edit without doing one of these will be denied again:\n  (a) If any skill is ACTIVATE → call Skill(name) for it. This auto-clears the gate.\n  (b) If ALL skills are SKIP → run this Bash tool call: touch /tmp/claude-skill-gate-$KEY\n\nStep 3 — only after Step 2 completes, retry the file edit."}}
+EOF
+exit 0

package/hooks/version-check.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# version-check.sh — SessionStart. Says once a day when a newer catalog exists.
+#
+# SessionStart stdout is added to the model's context, so this does not draw a
+# banner: it tells the assistant, and the assistant mentions it. That is the
+# whole reach of this hook — it never installs anything and never asks a
+# question the user has to answer before working.
+#
+# The rule that keeps it invisible: NEVER touch the network in the foreground.
+# A session start that waits on npm is a session start that hangs on a bad
+# connection, and a version nudge is not worth one second of that. So it reads
+# a cache written by the PREVIOUS session's background refresh, and kicks off
+# the next refresh detached. The first session after an install therefore says
+# nothing, and after that the answer is at worst a day old — which is the right
+# resolution for "there is a new version" anyway.
+#
+# Silent when: no manifest, no cache yet, offline, already current, or the user
+# has already been told today.
+#
+#   CLAUDE_SKILLS_NO_VERSION_CHECK=1   turns it off entirely
+
+set -uo pipefail
+
+[ -n "${CLAUDE_SKILLS_NO_VERSION_CHECK:-}" ] && exit 0
+
+PKG="@spardutti/claude-skills"
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+MANIFEST="$PROJECT_DIR/.claude/.claude-skills.json"
+
+# No manifest means the CLI never installed here, so there is nothing to update.
+[ -f "$MANIFEST" ] || exit 0
+
+INSTALLED=$(sed -n 's/.*"catalogVersion"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$MANIFEST" | head -1)
+[ -n "$INSTALLED" ] || exit 0
+
+# One cache for the whole machine, not one per project: the answer is the same
+# everywhere, and a developer with ten repos should still cost one request.
+CACHE_DIR="${HOME:-/tmp}/.claude"
+CACHE="$CACHE_DIR/.claude-skills-version"
+STAMP="$CACHE_DIR/.claude-skills-version-told"
+mkdir -p "$CACHE_DIR" 2>/dev/null
+
+NOW=$(date +%s 2>/dev/null || echo 0)
+DAY=86400
+
+# Refresh in the background, fully detached. Nothing downstream waits on it: all
+# three streams are closed, or the session start blocks until curl gives up.
+refresh() {
+  AGE=$DAY
+  if [ -f "$CACHE" ]; then
+    MTIME=$(date -r "$CACHE" +%s 2>/dev/null || echo 0)
+    AGE=$((NOW - MTIME))
+  fi
+  [ "$AGE" -lt "$DAY" ] && return
+  command -v curl >/dev/null 2>&1 || return
+  ( curl -fsS --max-time 5 "https://registry.npmjs.org/$PKG/latest" \
+      | sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' \
+      | head -1 > "$CACHE.tmp" 2>/dev/null
+    # Only replace the cache with something that parsed. A truncated reply that
+    # overwrote it would nudge toward a version that does not exist.
+    if [ -s "$CACHE.tmp" ]; then mv "$CACHE.tmp" "$CACHE"; else rm -f "$CACHE.tmp"; fi
+  ) </dev/null >/dev/null 2>&1 &
+}
+refresh
+
+[ -f "$CACHE" ] || exit 0
+LATEST=$(head -1 "$CACHE" | tr -d '[:space:]')
+[ -n "$LATEST" ] || exit 0
+[ "$LATEST" = "$INSTALLED" ] && exit 0
+
+# sort -V puts the newer one last. Equal versions were already handled, so the
+# only case left to reject is a cache that is BEHIND the install — which happens
+# normally right after publishing from the machine that publishes.
+NEWER=$(printf '%s\n%s\n' "$INSTALLED" "$LATEST" | sort -V | tail -1)
+[ "$NEWER" = "$LATEST" ] || exit 0
+
+# Once a day, however many sessions that day holds.
+if [ -f "$STAMP" ]; then
+  TOLD=$(date -r "$STAMP" +%s 2>/dev/null || echo 0)
+  [ $((NOW - TOLD)) -lt "$DAY" ] && exit 0
+fi
+: > "$STAMP"
+
+echo "A newer version of the $PKG catalog is available: $INSTALLED installed, $LATEST published."
+echo "Mention this to the user ONCE, in a single line, and only when the current task is done."
+echo "Do not interrupt what they are doing, and do not run the installer unless they ask."
+echo "To update, they run: npx $PKG"
+exit 0