@spardutti/claude-skills 2.2.0 → 2.4.0

package/lib/github.mjs

@@ -67,17 +67,57 @@ async function fetchListing({ apiUrl, label, entryFilter, buildRawUrl, mapEntry,
   return results.filter(Boolean);
 }
 
-export function fetchSkills() {
-  return fetchListing({
-    apiUrl: CONTENTS_API,
-    label: "skills",
-    entryFilter: (e) => e.type === "dir",
-    buildRawUrl: (dir) => `${RAW_BASE}/${dir.name}/SKILL.md`,
-    mapEntry: (dir, content) => {
-      const { name, description, category } = parseFrontmatter(content, dir.name);
-      return { dirName: dir.name, name, description, category, content };
-    },
-  });
+export async function fetchSkills() {
+  const headers = getAuthHeaders();
+  const res = await fetch(CONTENTS_API, { headers });
+
+  if (!res.ok) {
+    if (res.status === 403 || res.status === 429) {
+      throw new Error("GitHub API rate limit exceeded. Try again later or install gh CLI (https://cli.github.com).");
+    }
+    throw new Error(`Failed to list skills: ${res.status} ${res.statusText}`);
+  }
+
+  const dirs = (await res.json()).filter((e) => e.type === "dir");
+
+  const skills = await Promise.all(
+    dirs.map(async (dir) => {
+      try {
+        const listRes = await fetch(`${CONTENTS_API}/${dir.name}`, { headers });
+        if (!listRes.ok) {
+          console.warn(`  Warning: Failed to list skill ${dir.name}, skipping`);
+          return null;
+        }
+        const files = (await listRes.json()).filter((e) => e.type === "file");
+
+        const fetched = await Promise.all(
+          files.map(async (f) => {
+            const r = await fetch(`${RAW_BASE}/${dir.name}/${f.name}`, { headers });
+            if (!r.ok) {
+              console.warn(`  Warning: Failed to fetch ${dir.name}/${f.name}, skipping`);
+              return null;
+            }
+            return { name: f.name, content: await r.text(), executable: f.name.endsWith(".sh") };
+          })
+        );
+
+        const valid = fetched.filter(Boolean);
+        const skillMd = valid.find((f) => f.name === "SKILL.md");
+        if (!skillMd) {
+          console.warn(`  Warning: ${dir.name}/SKILL.md missing, skipping`);
+          return null;
+        }
+        const peerFiles = valid.filter((f) => f.name !== "SKILL.md");
+        const { name, description, category } = parseFrontmatter(skillMd.content, dir.name);
+        return { dirName: dir.name, name, description, category, content: skillMd.content, peerFiles };
+      } catch {
+        console.warn(`  Warning: Failed to fetch ${dir.name}, skipping`);
+        return null;
+      }
+    })
+  );
+
+  return skills.filter(Boolean);
 }
 
 export function fetchCommands() {

package/lib/install.mjs

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, writeFile, chmod } from "node:fs/promises";
 import { join } from "node:path";
 import chalk from "chalk";
 
@@ -24,6 +24,13 @@ export async function installSkills(skills, targetDir = process.cwd()) {
     const skillDir = join(baseDir, skill.dirName);
     await mkdir(skillDir, { recursive: true });
     await writeFile(join(skillDir, "SKILL.md"), skill.content);
+
+    for (const peer of skill.peerFiles ?? []) {
+      const peerPath = join(skillDir, peer.name);
+      await writeFile(peerPath, peer.content);
+      if (peer.executable) await chmod(peerPath, 0o755);
+    }
+
     console.log(`  ${chalk.green("✔")} ${chalk.bold(humanName(skill))} ${chalk.dim(`→ .claude/skills/${skill.dirName}/`)}`);
   }
 }

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,18 +54,108 @@ 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 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)
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(dirname "$(dirname "$SCRIPT_DIR")")"
+
+SESSION_ID=$(printf '%s' "$INPUT" | grep -o '"session_id":"[^"]*"' | head -1 | sed 's/"session_id":"//; s/"$//')
+if [ -z "$SESSION_ID" ]; then
+  exit 0
+fi
+
+# Defer to the loading gate until it's been satisfied this session.
+if [ ! -f "/tmp/claude-skill-gate-$SESSION_ID" ]; then
+  exit 0
+fi
+
+# 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
+
+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
+
+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"
+
+json_escape() {
+  local s="$1"
+  s="\${s//\\\\/\\\\\\\\}"
+  s="\${s//\\"/\\\\\\"}"
+  s="\${s//$'\\n'/\\\\n}"
+  s="\${s//$'\\r'/\\\\r}"
+  s="\${s//$'\\t'/\\\\t}"
+  printf '"%s"' "$s"
+}
+
+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 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 applicationGatePath = join(hooksDir, APPLICATION_GATE_FILENAME);
   const settingsPath = join(resolved, ".claude", "settings.json");
 
   await mkdir(hooksDir, { recursive: true });
@@ -70,6 +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(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 {
@@ -89,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 = {
@@ -105,6 +214,17 @@ export async function setupHook(targetDir = process.cwd()) {
     settings.hooks.PreToolUse = [gateEntry];
   }
 
+  // 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: applicationCommand }],
+  };
+  const applicationAlreadyRegistered = settings.hooks.PreToolUse.some((entry) =>
+    entry.hooks?.some((h) => h.command?.endsWith(APPLICATION_GATE_FILENAME))
+  );
+  if (!applicationAlreadyRegistered) settings.hooks.PreToolUse.push(applicationEntry);
+
   // Register PostToolUse auto-mark on Skill.
   const autoMarkCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${AUTO_MARK_FILENAME}`;
   const autoMarkEntry = {
@@ -125,5 +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/${APPLICATION_GATE_FILENAME}`);
   console.log(`  Settings updated: .claude/settings.json`);
 }

package/package.json

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