@spardutti/claude-skills 1.25.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

@@ -1,65 +1,122 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 
-const SKILL_EVAL_BLOCK = `
-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.`;
-
-const FILE_SIZE_BLOCK = `
-## File Size Enforcement
+const SKILL_BODY = `## Skills
+
+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. Emit the literal token \`[skills-checked]\` on its own line
+5. Only THEN proceed to implementation
+
+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
 
 - **Never write a file longer than 200 lines of code.** If a file would exceed 200 lines, split it into smaller modules before writing.
 - This rule applies during skill evaluation: if the code you're about to write would exceed 200 lines in any single file, refactor into multiple files first.
 - Skill evaluation must check this limit as part of every ACTIVATE decision.`;
 
-const EVAL_MARKER = "skill_evaluation:";
-const FILE_SIZE_MARKER = "## File Size Enforcement";
+const BLOCKS = [
+  {
+    id: "skill-evaluation",
+    body: SKILL_BODY,
+    legacyHeadings: ["## Skills"],
+    legacyYamlMarker: "skill_evaluation:",
+  },
+  {
+    id: "file-size",
+    body: FILE_SIZE_BODY,
+    legacyHeadings: ["## File Size Enforcement"],
+  },
+];
 
-export async function setupClaudeMd(targetDir = process.cwd()) {
-  const resolved = resolve(targetDir);
-  const claudeMdPath = join(resolved, "CLAUDE.md");
+function wrap(id, body) {
+  return `<!-- claude-skills:${id}:start -->\n${body}\n<!-- claude-skills:${id}:end -->`;
+}
 
-  let existing = "";
-  try {
-    existing = await readFile(claudeMdPath, "utf-8");
-  } catch {
-    // File doesn't exist — will create
-  }
+function spliceSentinels(content, id, replacement) {
+  const start = `<!-- claude-skills:${id}:start -->`;
+  const end = `<!-- claude-skills:${id}:end -->`;
+  const startIdx = content.indexOf(start);
+  if (startIdx === -1) return null;
+  const endIdx = content.indexOf(end, startIdx);
+  if (endIdx === -1) return null;
+  return content.slice(0, startIdx) + replacement + content.slice(endIdx + end.length);
+}
 
-  const hasEval = existing.includes(EVAL_MARKER);
-  const hasFileSize = existing.includes(FILE_SIZE_MARKER);
+function spliceLegacyHeading(content, heading, replacement) {
+  const lines = content.split("\n");
+  const startIdx = lines.findIndex((l) => l.trim() === heading);
+  if (startIdx === -1) return null;
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (lines[i].startsWith("## ")) {
+      endIdx = i;
+      break;
+    }
+  }
+  return joinSplice(lines, startIdx, endIdx, replacement);
+}
 
-  if (hasEval && hasFileSize) {
-    console.log("  CLAUDE.md already has skill_evaluation and file size rules — skipped.");
-    return;
+function spliceLegacyYaml(content, marker, replacement) {
+  const lines = content.split("\n");
+  const startIdx = lines.findIndex((l) => l.startsWith(marker));
+  if (startIdx === -1) return null;
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.length > 0 && !/^\s/.test(line)) {
+      endIdx = i;
+      break;
+    }
   }
+  return joinSplice(lines, startIdx, endIdx, replacement);
+}
 
-  let content = existing.trimEnd();
+function joinSplice(lines, startIdx, endIdx, replacement) {
+  const before = lines.slice(0, startIdx).join("\n").replace(/\s+$/, "");
+  const after = lines.slice(endIdx).join("\n").replace(/^\s+/, "");
+  const parts = [before, replacement, after].filter((s) => s.length > 0);
+  return parts.join("\n\n");
+}
 
-  if (!hasEval) {
-    content = content.length > 0
-      ? content + "\n" + SKILL_EVAL_BLOCK
-      : SKILL_EVAL_BLOCK.trimStart();
+function applyBlock(content, block) {
+  const wrapped = wrap(block.id, block.body);
+  let next = spliceSentinels(content, block.id, wrapped);
+  if (next !== null) return { content: next, action: `replaced ${block.id}` };
+  for (const heading of block.legacyHeadings ?? []) {
+    next = spliceLegacyHeading(content, heading, wrapped);
+    if (next !== null) return { content: next, action: `migrated ${block.id}` };
   }
-
-  if (!hasFileSize) {
-    content = content + "\n" + FILE_SIZE_BLOCK;
+  if (block.legacyYamlMarker) {
+    next = spliceLegacyYaml(content, block.legacyYamlMarker, wrapped);
+    if (next !== null) return { content: next, action: `migrated ${block.id}` };
   }
+  const base = content.replace(/\s+$/, "");
+  const merged = base.length > 0 ? base + "\n\n" + wrapped : wrapped;
+  return { content: merged, action: `added ${block.id}` };
+}
+
+export async function setupClaudeMd(targetDir = process.cwd()) {
+  const claudeMdPath = join(resolve(targetDir), "CLAUDE.md");
 
-  await writeFile(claudeMdPath, content + "\n", { mode: 0o644 });
+  let content = "";
+  try {
+    content = await readFile(claudeMdPath, "utf-8");
+  } catch {
+    // File doesn't exist — will create
+  }
 
-  if (!hasEval && !hasFileSize) {
-    console.log("  CLAUDE.md updated with skill_evaluation and file size rules.");
-  } else if (!hasEval) {
-    console.log("  CLAUDE.md updated with skill_evaluation block.");
-  } else {
-    console.log("  CLAUDE.md updated with file size enforcement rule.");
+  const actions = [];
+  for (const block of BLOCKS) {
+    const result = applyBlock(content, block);
+    content = result.content;
+    actions.push(result.action);
   }
+
+  await writeFile(claudeMdPath, content.replace(/\s+$/, "") + "\n", { mode: 0o644 });
+  console.log(`  CLAUDE.md: ${actions.join(", ")}.`);
 }

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.25.0",
+  "version": "1.27.0",
   "description": "CLI to install Claude Code skills from the claude-skills collection",
   "type": "module",
   "bin": {