@spardutti/claude-skills 2.3.0 → 2.4.0

package/lib/setup-hook.mjs

@@ -1,4 +1,4 @@
-import { mkdir, writeFile, readFile, chmod } from "node:fs/promises";
+import { mkdir, writeFile, readFile, chmod, unlink } from "node:fs/promises";
 import { join, resolve } from "node:path";
 
 // PreToolUse gate on Write|Edit|MultiEdit. Blocks the tool call unless
@@ -39,9 +39,12 @@ EOF
 exit 0
 `;
 
-// PostToolUse on Skill: auto-creates the per-session gate marker.
+// PostToolUse on Skill: auto-creates the per-session gate marker AND a
+// per-skill "loaded" marker. The application gate uses the loaded marker
+// to require the model to explicitly apply each loaded skill before the
+// first Write/Edit in this session.
 const AUTO_MARK_SCRIPT = `#!/bin/bash
-# PostToolUse on Skill: auto-marks the skill-gate as satisfied for the session.
+# PostToolUse on Skill: marks gate satisfied + records loaded skill.
 
 INPUT=$(cat)
 
@@ -51,16 +54,25 @@ if [ -z "$SESSION_ID" ]; then
 fi
 
 touch "/tmp/claude-skill-gate-$SESSION_ID"
+
+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-$SESSION_ID-$SAFE_NAME"
+  fi
+fi
+
 exit 0
 `;
 
-// PreToolUse audit runner: runs each installed skill's audit.sh against the
-// write target. Denies the write if any audit exits 2. Defers (exits 0) when
-// the skill-gate marker isn't set yet — the gate handles that case.
-//
-// Honors .claude/skill-audit-ignore (one skill name per line, # comments OK).
-const AUDIT_RUNNER_SCRIPT = `#!/bin/bash
-# PreToolUse skill-audit runner.
+// PreToolUse application gate: requires the model to explicitly apply each
+// loaded skill before the first Write/Edit. Reads SKILL.md's Rules section
+// and inlines it in the deny message. One ack per skill per session.
+const APPLICATION_GATE_SCRIPT = `#!/bin/bash
+# PreToolUse application gate: blocks file edits until each loaded skill
+# has been explicitly applied (acked) for this session.
 
 INPUT=$(cat)
 
@@ -72,26 +84,51 @@ if [ -z "$SESSION_ID" ]; then
   exit 0
 fi
 
-# Defer until the skill-gate has been satisfied in this session.
+# Defer to the loading gate until it's been satisfied this session.
 if [ ! -f "/tmp/claude-skill-gate-$SESSION_ID" ]; then
   exit 0
 fi
 
-FILE_PATH=$(printf '%s' "$INPUT" | grep -o '"file_path":"[^"]*"' | head -1 | sed 's/"file_path":"//; s/"$//')
-if [ -z "$FILE_PATH" ]; then
+# Find the first loaded-but-unacked skill (handle one at a time; the next
+# blocked write will surface the next skill).
+UNACKED=""
+for marker in /tmp/claude-skill-loaded-$SESSION_ID-*; do
+  [ ! -f "$marker" ] && continue
+  skill_name="\${marker##/tmp/claude-skill-loaded-$SESSION_ID-}"
+  if [ ! -f "/tmp/claude-skill-acked-$SESSION_ID-$skill_name" ]; then
+    UNACKED="$skill_name"
+    break
+  fi
+done
+
+if [ -z "$UNACKED" ]; then
   exit 0
 fi
 
-SKILLS_DIR="$PROJECT_DIR/.claude/skills"
-[ ! -d "$SKILLS_DIR" ] && exit 0
+SKILL_MD="$PROJECT_DIR/.claude/skills/$UNACKED/SKILL.md"
+RULES=""
+if [ -f "$SKILL_MD" ]; then
+  RULES=$(awk '/^## Rules/{flag=1} /^## /{if(flag && !/^## Rules/)exit} flag' "$SKILL_MD")
+fi
+if [ -z "$RULES" ]; then
+  RULES="(Rules section not found in $SKILL_MD — refer to the loaded skill content already in context.)"
+fi
 
-IGNORE_FILE="$PROJECT_DIR/.claude/skill-audit-ignore"
-is_ignored() {
-  [ ! -f "$IGNORE_FILE" ] && return 1
-  grep -qE "^[[:space:]]*\${1}[[:space:]]*(#.*)?$" "$IGNORE_FILE"
-}
+MSG="BLOCKED: skill '$UNACKED' was loaded but not yet applied to your work.
+
+Before this Write/Edit, you must:
+
+1. State the specific rules from '$UNACKED' that apply to the file you're about to write.
+2. State how your next write respects each rule.
+3. Then ack the application by running this Bash tool call:
+     touch /tmp/claude-skill-acked-$SESSION_ID-$UNACKED
+
+One ack per skill per session. After acking, retry the Write/Edit.
+
+Rules from $UNACKED/SKILL.md:
+
+$RULES"
 
-# Portable JSON string escape for the deny reason.
 json_escape() {
   local s="$1"
   s="\${s//\\\\/\\\\\\\\}"
@@ -102,38 +139,23 @@ json_escape() {
   printf '"%s"' "$s"
 }
 
-for audit in "$SKILLS_DIR"/*/audit.sh; do
-  [ ! -f "$audit" ] && continue
-  [ ! -x "$audit" ] && continue
-  skill_name=$(basename "$(dirname "$audit")")
-  if is_ignored "$skill_name"; then
-    continue
-  fi
-
-  output=$("$audit" "$FILE_PATH" 2>&1 >/dev/null)
-  rc=$?
-
-  if [ $rc -eq 2 ]; then
-    reason=$(json_escape "$output")
-    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":%s}}\\n' "$reason"
-    exit 0
-  fi
-done
-
+REASON=$(json_escape "$MSG")
+printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":%s}}\\n' "$REASON"
 exit 0
 `;
 
 const GATE_FILENAME = "skill-gate.sh";
 const AUTO_MARK_FILENAME = "skill-gate-automark.sh";
-const AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
+const APPLICATION_GATE_FILENAME = "skill-application-gate.sh";
 const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
+const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
 
 export async function setupHook(targetDir = process.cwd()) {
   const resolved = resolve(targetDir);
   const hooksDir = join(resolved, ".claude", "hooks");
   const gatePath = join(hooksDir, GATE_FILENAME);
   const autoMarkPath = join(hooksDir, AUTO_MARK_FILENAME);
-  const auditRunnerPath = join(hooksDir, AUDIT_RUNNER_FILENAME);
+  const applicationGatePath = join(hooksDir, APPLICATION_GATE_FILENAME);
   const settingsPath = join(resolved, ".claude", "settings.json");
 
   await mkdir(hooksDir, { recursive: true });
@@ -141,8 +163,15 @@ export async function setupHook(targetDir = process.cwd()) {
   await chmod(gatePath, 0o755);
   await writeFile(autoMarkPath, AUTO_MARK_SCRIPT, { mode: 0o755 });
   await chmod(autoMarkPath, 0o755);
-  await writeFile(auditRunnerPath, AUDIT_RUNNER_SCRIPT, { mode: 0o755 });
-  await chmod(auditRunnerPath, 0o755);
+  await writeFile(applicationGatePath, APPLICATION_GATE_SCRIPT, { mode: 0o755 });
+  await chmod(applicationGatePath, 0o755);
+
+  // Remove the legacy audit-runner hook file from prior installs (2.3.x).
+  try {
+    await unlink(join(hooksDir, LEGACY_AUDIT_RUNNER_FILENAME));
+  } catch {
+    // not present — fine
+  }
 
   let settings = {};
   try {
@@ -162,6 +191,13 @@ export async function setupHook(targetDir = process.cwd()) {
     }
   }
 
+  // Clean up legacy PreToolUse audit-runner hook (2.3.x — removed in 2.4.0).
+  if (Array.isArray(settings.hooks.PreToolUse)) {
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
+      (entry) => !entry.hooks?.some((h) => h.command?.endsWith(LEGACY_AUDIT_RUNNER_FILENAME))
+    );
+  }
+
   // Register PreToolUse gate.
   const gateCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${GATE_FILENAME}`;
   const gateEntry = {
@@ -178,16 +214,16 @@ export async function setupHook(targetDir = process.cwd()) {
     settings.hooks.PreToolUse = [gateEntry];
   }
 
-  // Register PreToolUse audit runner (after the gate).
-  const auditCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${AUDIT_RUNNER_FILENAME}`;
-  const auditEntry = {
+  // Register PreToolUse application gate (after the loading gate).
+  const applicationCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${APPLICATION_GATE_FILENAME}`;
+  const applicationEntry = {
     matcher: "Write|Edit|MultiEdit",
-    hooks: [{ type: "command", command: auditCommand }],
+    hooks: [{ type: "command", command: applicationCommand }],
   };
-  const auditAlreadyRegistered = settings.hooks.PreToolUse.some((entry) =>
-    entry.hooks?.some((h) => h.command?.endsWith(AUDIT_RUNNER_FILENAME))
+  const applicationAlreadyRegistered = settings.hooks.PreToolUse.some((entry) =>
+    entry.hooks?.some((h) => h.command?.endsWith(APPLICATION_GATE_FILENAME))
   );
-  if (!auditAlreadyRegistered) settings.hooks.PreToolUse.push(auditEntry);
+  if (!applicationAlreadyRegistered) settings.hooks.PreToolUse.push(applicationEntry);
 
   // Register PostToolUse auto-mark on Skill.
   const autoMarkCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${AUTO_MARK_FILENAME}`;
@@ -209,6 +245,6 @@ export async function setupHook(targetDir = process.cwd()) {
 
   console.log(`  Hook installed: .claude/hooks/${GATE_FILENAME}`);
   console.log(`  Hook installed: .claude/hooks/${AUTO_MARK_FILENAME}`);
-  console.log(`  Hook installed: .claude/hooks/${AUDIT_RUNNER_FILENAME}`);
+  console.log(`  Hook installed: .claude/hooks/${APPLICATION_GATE_FILENAME}`);
   console.log(`  Settings updated: .claude/settings.json`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "CLI to install Claude Code skills from the claude-skills collection",
   "type": "module",
   "bin": {