@spardutti/claude-skills 1.0.3 → 1.1.0

package/README.md

@@ -8,11 +8,21 @@ Interactive CLI to install reusable [Claude Code](https://docs.anthropic.com/en/
 npx @spardutti/claude-skills
 ```
 
-This will:
+Run this from your project's root directory. The CLI will:
 
 1. Fetch the latest skills from [GitHub](https://github.com/Spardutti/claude-skills)
 2. Let you interactively select which skills to install
 3. Copy them into your project's `.claude/skills/` directory
+4. Ask to set up **automatic skill evaluation** (hook + CLAUDE.md rule)
+
+## Automatic Skill Evaluation
+
+Skills alone don't guarantee Claude will use them. The CLI can optionally set up enforcement:
+
+- **Hook** (`.claude/hooks/skill-forced-eval-hook.sh`) — Runs on every prompt, injects a mandatory skill evaluation sequence into Claude's context
+- **CLAUDE.md rule** (`skill_evaluation` block) — Instructs Claude to list every skill as ACTIVATE/SKIP before writing any code
+
+Together, these force Claude to explicitly evaluate and activate relevant skills instead of silently ignoring them.
 
 ## Available Skills
 
@@ -23,6 +33,13 @@ This will:
 | `react-query` | TanStack React Query with query-key-factory patterns |
 | `tailwind-tokens` | Enforce Tailwind CSS design tokens — no arbitrary values when a token exists |
 
+## GitHub Authentication
+
+The CLI fetches skills via the GitHub API. Unauthenticated requests are limited to 60/hour. To avoid rate limits:
+
+- Install the [GitHub CLI](https://cli.github.com) and run `gh auth login` — the token is detected automatically
+- Or set `GITHUB_TOKEN` / `GH_TOKEN` as an environment variable
+
 ## What are Claude Code Skills?
 
 Skills are markdown files placed in `.claude/skills/` that give Claude Code domain-specific knowledge and guidelines. They help Claude follow your team's patterns and best practices automatically.

package/bin/cli.mjs

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 
+import { confirm } from "@inquirer/prompts";
 import { fetchSkills } from "../lib/github.mjs";
 import { promptSkillSelection } from "../lib/prompt.mjs";
 import { installSkills } from "../lib/install.mjs";
+import { setupHook } from "../lib/setup-hook.mjs";
+import { setupClaudeMd } from "../lib/setup-claude-md.mjs";
 
 async function main() {
   console.log("\n  Claude Skills Installer\n");
@@ -24,6 +27,19 @@ async function main() {
 
   console.log();
   await installSkills(selected);
+
+  console.log();
+  const shouldSetup = await confirm({
+    message: "Set up skill evaluation hook + CLAUDE.md rule? (Recommended)",
+    default: true,
+  });
+
+  if (shouldSetup) {
+    console.log();
+    await setupHook();
+    await setupClaudeMd();
+  }
+
   console.log(`\n  Done! ${selected.length} skill(s) installed.\n`);
 }
 

package/lib/github.mjs

@@ -1,16 +1,45 @@
+import { execSync } from "node:child_process";
+
 const REPO_OWNER = "Spardutti";
 const REPO_NAME = "claude-skills";
 const CONTENTS_API = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/contents/skills`;
 const RAW_BASE = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main/skills`;
 
+function getAuthHeaders() {
+  const headers = { "User-Agent": "claude-skills-cli" };
+
+  // 1. Explicit env var
+  const envToken = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  if (envToken) {
+    headers.Authorization = `Bearer ${envToken}`;
+    return headers;
+  }
+
+  // 2. Try gh CLI token
+  try {
+    const token = execSync("gh auth token", {
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    if (token) {
+      headers.Authorization = `Bearer ${token}`;
+    }
+  } catch {
+    // gh not installed or not authenticated — continue unauthenticated
+  }
+
+  return headers;
+}
+
 export async function fetchSkills() {
-  const res = await fetch(CONTENTS_API, {
-    headers: { "User-Agent": "claude-skills-cli" },
-  });
+  const headers = getAuthHeaders();
+
+  const res = await fetch(CONTENTS_API, { headers });
 
   if (!res.ok) {
-    if (res.status === 403) {
-      throw new Error("GitHub API rate limit exceeded. Try again later.");
+    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}`);
   }
@@ -22,9 +51,7 @@ export async function fetchSkills() {
     dirs.map(async (dir) => {
       try {
         const url = `${RAW_BASE}/${dir.name}/SKILL.md`;
-        const r = await fetch(url, {
-          headers: { "User-Agent": "claude-skills-cli" },
-        });
+        const r = await fetch(url, { headers });
 
         if (!r.ok) {
           console.warn(`  Warning: No SKILL.md found in ${dir.name}, skipping`);

package/lib/setup-claude-md.mjs

@@ -0,0 +1,42 @@
+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 MARKER = "skill_evaluation:";
+
+export async function setupClaudeMd(targetDir = process.cwd()) {
+  const resolved = resolve(targetDir);
+  const claudeMdPath = join(resolved, "CLAUDE.md");
+
+  let existing = "";
+  try {
+    existing = await readFile(claudeMdPath, "utf-8");
+  } catch {
+    // File doesn't exist — will create
+  }
+
+  // Don't add duplicate block
+  if (existing.includes(MARKER)) {
+    console.log("  CLAUDE.md already has skill_evaluation block — skipped.");
+    return;
+  }
+
+  // Append the block (after trailing ``` if the file uses a yaml code fence)
+  const trimmed = existing.trimEnd();
+  const content = trimmed.length > 0
+    ? trimmed + "\n" + SKILL_EVAL_BLOCK + "\n"
+    : SKILL_EVAL_BLOCK.trimStart() + "\n";
+
+  await writeFile(claudeMdPath, content, { mode: 0o644 });
+  console.log("  CLAUDE.md updated with skill_evaluation block.");
+}

package/lib/setup-hook.mjs

@@ -0,0 +1,91 @@
+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
+
+cat > /dev/null
+
+DIR="\${CLAUDE_PROJECT_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}"
+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"
+exit 0
+`;
+
+const HOOK_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 settingsPath = join(resolved, ".claude", "settings.json");
+
+  // Write the hook script
+  await mkdir(hooksDir, { recursive: true });
+  await writeFile(hookPath, HOOK_SCRIPT, { mode: 0o755 });
+  await chmod(hookPath, 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);
+  } catch {
+    // File doesn't exist or is invalid — start fresh
+  }
+
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+
+  const hookEntry = {
+    hooks: [{ type: "command", command: hookPath }],
+  };
+
+  // Check if UserPromptSubmit already has this hook to avoid duplicates
+  if (Array.isArray(settings.hooks.UserPromptSubmit)) {
+    const alreadyInstalled = settings.hooks.UserPromptSubmit.some((entry) =>
+      entry.hooks?.some((h) => h.command?.endsWith(HOOK_FILENAME))
+    );
+    if (!alreadyInstalled) {
+      settings.hooks.UserPromptSubmit.push(hookEntry);
+    }
+  } else {
+    settings.hooks.UserPromptSubmit = [hookEntry];
+  }
+
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", {
+    mode: 0o644,
+  });
+
+  console.log(`  Hook installed: .claude/hooks/${HOOK_FILENAME}`);
+  console.log(`  Settings updated: .claude/settings.json`);
+}

package/package.json

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