@spardutti/claude-skills 1.26.0 → 1.27.0

package/README.md

@@ -101,24 +101,29 @@ The CLI will:
 
 After installing skills, the CLI asks if you want to set up automatic skill evaluation. If you say yes, it will:
 
-- **Create a hook** at `.claude/hooks/skill-forced-eval-hook.sh` that runs on every prompt
-- **Update your `CLAUDE.md`** with a `skill_evaluation` rule
+- **Create a PreToolUse gate hook** at `.claude/hooks/skill-gate.sh`
+- **Update your `CLAUDE.md`** with the skill-evaluation rule
 
-This forces Claude to explicitly evaluate every installed skill before writing code — listing each skill as ACTIVATE or SKIP with a reason, then calling the relevant ones. Without this, Claude may silently ignore your skills.
+The gate hard-blocks `Write`, `Edit`, and `MultiEdit` tool calls until Claude has evaluated the available skills and emitted the literal token `[skills-checked]` in its response. Once emitted, every subsequent edit in that turn passes through. The next user prompt resets the gate.
+
+Unlike a soft reminder injected into context (which Claude can ignore), the gate denies the tool call outright — so the only path forward is to actually evaluate skills.
+
+The gate auto-passes when the project has no skills installed, so it's safe to leave on globally.
 
 ### What gets created
 
-**`.claude/settings.json`** — Registers the hook:
+**`.claude/settings.json`** — Registers the gate on file-writing tools:
 
 ```json
 {
   "hooks": {
-    "UserPromptSubmit": [
+    "PreToolUse": [
       {
+        "matcher": "Write|Edit|MultiEdit",
         "hooks": [
           {
             "type": "command",
-            "command": ".claude/hooks/skill-forced-eval-hook.sh"
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-gate.sh"
           }
         ]
       }
@@ -127,19 +132,7 @@ This forces Claude to explicitly evaluate every installed skill before writing c
 }
 ```
 
-**`CLAUDE.md`** — Appends the evaluation rule:
-
-```yaml
-skill_evaluation:
-  mandatory: true
-  rule: |
-    BEFORE writing ANY code, you MUST:
-    1. List EVERY skill from the system-reminder's available skills section
-    2. For each skill, write: [skill-name] → ACTIVATE / SKIP — [one-line reason]
-    3. Call Skill(name) for every skill marked ACTIVATE
-    4. Only THEN proceed to implementation
-    If you skip this evaluation, your response is INCOMPLETE and WRONG.
-```
+**`CLAUDE.md`** — Appends the evaluation rule, including the `[skills-checked]` sentinel that the gate looks for.
 
 ## Manual Install
 

package/lib/setup-claude-md.mjs

@@ -8,9 +8,10 @@ BEFORE writing ANY code, you MUST:
 1. List EVERY skill available: check \`.claude/skills/\` (project) and \`~/.claude/skills/\` (global). The system-reminder's available-skills section is a hint, not the source of truth — if it's missing or empty, still check the directories.
 2. For each skill, write: [skill-name] → ACTIVATE / SKIP — [one-line reason]
 3. Call Skill(name) for every skill marked ACTIVATE
-4. Only THEN proceed to implementation
+4. Emit the literal token \`[skills-checked]\` on its own line
+5. Only THEN proceed to implementation
 
-If you skip this evaluation, your response is INCOMPLETE and WRONG.`;
+A PreToolUse gate hook blocks Write/Edit/MultiEdit until the \`[skills-checked]\` token appears in your response since the most recent user prompt. The gate fires once per turn — the first blocked edit is the signal to evaluate skills, then retry. If you skip the evaluation, your response is INCOMPLETE and WRONG.`;
 
 const FILE_SIZE_BODY = `## File Size Enforcement
 

package/lib/setup-hook.mjs

@@ -1,95 +1,99 @@
 import { mkdir, writeFile, readFile, chmod } from "node:fs/promises";
 import { join, resolve } from "node:path";
 
-const HOOK_SCRIPT = `#!/bin/bash
-# UserPromptSubmit hook that forces explicit skill evaluation
+// PreToolUse gate on Write|Edit|MultiEdit. Blocks the tool call unless
+// the assistant has emitted the literal sentinel [skills-checked] since
+// the most recent user prompt. Resets every user turn, runs once per
+// turn (subsequent edits in the same turn pass through).
+//
+// Pass-through cases:
+//   - project has no .claude/skills/*/SKILL.md files
+//   - transcript_path missing or unreadable
+//   - no user prompt found in transcript
+//
+// tool_result lines (which include the gate's own deny message) are
+// filtered out of the sentinel scan to prevent self-satisfaction.
+const GATE_SCRIPT = `#!/bin/bash
+# PreToolUse gate: forces skill evaluation before file-writing tools run.
+
+INPUT=$(cat)
 
-cat > /dev/null
-
-# Derive project root from the hook's own location
-# .claude/hooks/script.sh → go up two levels → project root
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-DIR="$(dirname "$(dirname "$SCRIPT_DIR")")"
-
-# Build skill list from project skills
-SKILL_LIST=""
-while IFS= read -r skillfile; do
-  name=$(grep -m1 '^name:' "$skillfile" 2>/dev/null | sed 's/^name: *//' | sed 's/^"//' | sed 's/"$//')
-  desc=$(grep -m1 '^description:' "$skillfile" 2>/dev/null | sed 's/^description: *//' | sed 's/^"//' | sed 's/"$//')
-  if [ -n "$name" ] && [ -n "$desc" ]; then
-    SKILL_LIST="\${SKILL_LIST}  - \${name}: \${desc}\\\\n"
-  fi
-done < <(find "$DIR" -path '*/.claude/skills/*/SKILL.md' 2>/dev/null | sort -u)
-
-INSTRUCTION="INSTRUCTION: MANDATORY SKILL ACTIVATION SEQUENCE\\\\n\\\\n"
-INSTRUCTION+="<available_skills>\\\\n"
-INSTRUCTION+="System skills (from system-reminder):\\\\n  - Check system-reminder for built-in skills\\\\n"
-
-if [ -n "$SKILL_LIST" ]; then
-  INSTRUCTION+="Project skills:\\\\n\${SKILL_LIST}"
+PROJECT_DIR="$(dirname "$(dirname "$SCRIPT_DIR")")"
+
+if ! find "$PROJECT_DIR" -path '*/.claude/skills/*/SKILL.md' 2>/dev/null | grep -q .; then
+  exit 0
+fi
+
+TRANSCRIPT=$(printf '%s' "$INPUT" | grep -o '"transcript_path":"[^"]*"' | head -1 | sed 's/"transcript_path":"//; s/"$//')
+if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then
+  exit 0
 fi
 
-INSTRUCTION+="</available_skills>\\\\n\\\\n"
-INSTRUCTION+="Step 1 - EVALUATE (do this in your response):\\\\n"
-INSTRUCTION+="For each skill in <available_skills>, state: [skill-name] - YES/NO - [reason]\\\\n\\\\n"
-INSTRUCTION+="Step 2 - ACTIVATE (do this immediately after Step 1):\\\\n"
-INSTRUCTION+="IF any skills are YES -> Use Skill(skill-name) tool for EACH relevant skill NOW\\\\n"
-INSTRUCTION+="IF no skills are YES -> State 'No skills needed' and proceed\\\\n\\\\n"
-INSTRUCTION+="Step 3 - IMPLEMENT:\\\\n"
-INSTRUCTION+="Only after Step 2 is complete, proceed with implementation.\\\\n\\\\n"
-INSTRUCTION+="CRITICAL: You MUST call Skill() tool in Step 2. Do NOT skip to implementation."
-
-printf '{"additionalContext": "%s"}\\n' "$INSTRUCTION"
+LAST_PROMPT=$(grep -n '"type":"user"' "$TRANSCRIPT" 2>/dev/null | grep -v 'tool_use_id' | tail -1 | cut -d: -f1)
+if [ -z "$LAST_PROMPT" ]; then
+  exit 0
+fi
+
+if tail -n +"$LAST_PROMPT" "$TRANSCRIPT" | grep -v 'tool_use_id' | grep -qF '[skills-checked]'; then
+  exit 0
+fi
+
+cat <<'EOF'
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Skill evaluation required before writing or editing code. List each available skill as ACTIVATE or SKIP with a one-line reason, call Skill() for any ACTIVATE entries, then emit the literal token [skills-checked] (square brackets included) on its own line. Then retry the tool call."}}
+EOF
 exit 0
 `;
 
-const HOOK_FILENAME = "skill-forced-eval-hook.sh";
+const GATE_FILENAME = "skill-gate.sh";
+const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
 
 export async function setupHook(targetDir = process.cwd()) {
   const resolved = resolve(targetDir);
   const hooksDir = join(resolved, ".claude", "hooks");
-  const hookPath = join(hooksDir, HOOK_FILENAME);
+  const gatePath = join(hooksDir, GATE_FILENAME);
   const settingsPath = join(resolved, ".claude", "settings.json");
 
-  // Write the UserPromptSubmit hook script
   await mkdir(hooksDir, { recursive: true });
-  await writeFile(hookPath, HOOK_SCRIPT, { mode: 0o755 });
-  await chmod(hookPath, 0o755);
+  await writeFile(gatePath, GATE_SCRIPT, { mode: 0o755 });
+  await chmod(gatePath, 0o755);
 
-  // Merge into existing settings.json (don't clobber other config)
   let settings = {};
   try {
-    const raw = await readFile(settingsPath, "utf-8");
-    settings = JSON.parse(raw);
+    settings = JSON.parse(await readFile(settingsPath, "utf-8"));
   } catch {
-    // File doesn't exist or is invalid — start fresh
+    // missing or invalid — start fresh
   }
+  if (!settings.hooks) settings.hooks = {};
 
-  if (!settings.hooks) {
-    settings.hooks = {};
+  // Clean up legacy UserPromptSubmit eval hook (replaced by the gate).
+  if (Array.isArray(settings.hooks.UserPromptSubmit)) {
+    settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(
+      (entry) => !entry.hooks?.some((h) => h.command?.endsWith(LEGACY_EVAL_FILENAME))
+    );
+    if (settings.hooks.UserPromptSubmit.length === 0) {
+      delete settings.hooks.UserPromptSubmit;
+    }
   }
 
-  // --- UserPromptSubmit hook (forced eval via command) ---
-  const hookCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${HOOK_FILENAME}`;
-  const promptHookEntry = {
-    hooks: [{ type: "command", command: hookCommand }],
+  // Register PreToolUse gate.
+  const gateCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${GATE_FILENAME}`;
+  const gateEntry = {
+    matcher: "Write|Edit|MultiEdit",
+    hooks: [{ type: "command", command: gateCommand }],
   };
 
-  if (Array.isArray(settings.hooks.UserPromptSubmit)) {
-    const alreadyInstalled = settings.hooks.UserPromptSubmit.some((entry) =>
-      entry.hooks?.some((h) => h.command?.endsWith(HOOK_FILENAME))
+  if (Array.isArray(settings.hooks.PreToolUse)) {
+    const exists = settings.hooks.PreToolUse.some((entry) =>
+      entry.hooks?.some((h) => h.command?.endsWith(GATE_FILENAME))
     );
-    if (!alreadyInstalled) {
-      settings.hooks.UserPromptSubmit.push(promptHookEntry);
-    }
+    if (!exists) settings.hooks.PreToolUse.push(gateEntry);
   } else {
-    settings.hooks.UserPromptSubmit = [promptHookEntry];
+    settings.hooks.PreToolUse = [gateEntry];
   }
 
-  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", {
-    mode: 0o644,
-  });
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o644 });
 
-  console.log(`  Hook installed: .claude/hooks/${HOOK_FILENAME}`);
+  console.log(`  Hook installed: .claude/hooks/${GATE_FILENAME}`);
   console.log(`  Settings updated: .claude/settings.json`);
 }

package/package.json

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