@spardutti/claude-skills 1.19.1 → 1.21.0

package/README.md

@@ -1,67 +1,162 @@
-# @spardutti/claude-skills
+# Claude Skills
 
-Interactive CLI to install reusable [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skills into any project.
+Personal collection of reusable Claude Code **skills**, **slash commands**, and **subagents**. Install them into any project with one command — pick what you want from an interactive menu, and any subagents declared by the commands you pick get installed automatically.
 
-## Usage
+## Skills
 
-```bash
-npx @spardutti/claude-skills
-```
+### Frontend
 
-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)
+| Skill | Description |
+|-------|-------------|
+| `react-best-practices` | React 19 — component design, state management, performance, React 19 features, TypeScript integration |
+| `react-use-effect` | React 19 useEffect best practices and anti-patterns |
+| `react-query` | TanStack React Query with @lukemorales/query-key-factory patterns |
+| `react-single-responsibility` | React single responsibility — component splitting, hook isolation, file size limits, complexity rules |
+| `tanstack-router-best-practices` | TanStack Router — file-based routing, type-safe navigation, loaders, search params, auth guards |
+| `trpc-react-query` | tRPC v11 — queryOptions/mutationOptions patterns, router organization, middleware, cache invalidation, optimistic updates |
+| `tailwind-tokens` | Enforce Tailwind CSS design tokens — no arbitrary values when a token exists |
+| `zustand` | Zustand — store design, selectors, persist/immer middleware, slices pattern, devtools, transient updates |
+| `dnd-kit` | @dnd-kit — sortable lists, sensors, collision detection, drag overlays, multi-container (kanban), accessibility |
+| `framer-motion` | Motion (Framer Motion) — AnimatePresence, layout animations, variants, gestures, useAnimate, performance |
 
-## Automatic Skill Evaluation
+### Desktop
 
-Skills alone don't guarantee Claude will use them. The CLI can optionally set up enforcement:
+| Skill | Description |
+|-------|-------------|
+| `tauri-v2` | Tauri v2 — IPC commands, plugins, window management, system tray, global shortcuts, capabilities/permissions, events |
 
-- **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
+### TypeScript
 
-Together, these force Claude to explicitly evaluate and activate relevant skills instead of silently ignoring them.
+| Skill | Description |
+|-------|-------------|
+| `typescript-best-practices` | TypeScript 5.x — type design, type safety, generics, error handling, tsconfig |
 
-## Available Skills
+### Backend
 
 | Skill | Description |
 |-------|-------------|
-| `react-best-practices` | React 19 — component design, state management, performance, React 19 features, TypeScript integration |
-| `react-use-effect` | React 19 useEffect best practices and anti-patterns |
-| `react-query` | TanStack React Query with query-key-factory patterns |
-| `tanstack-router-best-practices` | TanStack Router — file-based routing, type-safe navigation, loaders, search params, auth guards |
-| `typescript-best-practices` | TypeScript 5.x — type design, type safety, generics, error handling, tsconfig |
-| `react-single-responsibility` | React single responsibility — component splitting, hook isolation, file size limits, complexity rules |
-| `tailwind-tokens` | Enforce Tailwind CSS design tokens — no arbitrary values when a token exists |
-| `drf-best-practices` | Django REST Framework — thin serializers, service layer, queryset optimization, object-level permissions |
-| `fastapi-best-practices` | FastAPI — async correctness, Pydantic validation, dependency injection, service layer, structured error handling |
-| `security-practices` | Web security — OWASP Top 10 prevention, input validation, auth, SQL injection, XSS, CSRF, secure defaults |
-| `alembic-migrations` | Alembic — naming conventions, autogenerate review, data migration safety, downgrades, production deployment |
-| `testing-best-practices` | Testing — Arrange-Act-Assert, factory-based test data, test isolation, mocking boundaries, pyramid-balanced coverage |
-| `docker-best-practices` | Docker — multi-stage builds, layer caching, security hardening, Compose Watch for local dev, health checks |
-| `trpc-react-query` | tRPC v11 — queryOptions/mutationOptions patterns, router organization, middleware, cache invalidation, optimistic updates |
 | `express-best-practices` | Express.js — feature-based structure, 3-layer architecture, Zod validation, centralized error handling, security middleware |
 | `fastify-best-practices` | Fastify — plugin architecture, encapsulation, TypeBox validation/serialization, services as decorators, reply helpers, hooks |
+| `fastapi-best-practices` | FastAPI — async correctness, Pydantic validation, dependency injection, service layer, structured error handling |
+| `drf-best-practices` | Django REST Framework — thin serializers, service layer, queryset optimization, object-level permissions |
 | `drizzle-orm` | Drizzle ORM — schema design, identity columns, relations, relational queries, migrations, drizzle-kit workflow, type inference |
-| `zustand` | Zustand — store design, selectors, persist/immer middleware, slices pattern, devtools, transient updates |
-| `tauri-v2` | Tauri v2 — IPC commands, plugins, window management, system tray, global shortcuts, capabilities/permissions, events |
-| `dnd-kit` | @dnd-kit — sortable lists, sensors, collision detection, drag overlays, multi-container (kanban), accessibility |
-| `framer-motion` | Motion (Framer Motion) — AnimatePresence, layout animations, variants, gestures, useAnimate, performance |
+| `alembic-migrations` | Alembic — naming conventions, autogenerate review, data migration safety, downgrades, production deployment |
+| `docker-best-practices` | Docker — multi-stage builds, layer caching, security hardening, Compose Watch for local dev, health checks |
+
+### Database
+
+| Skill | Description |
+|-------|-------------|
+| `sql-joins` | SQL joins — LEFT JOIN traps, fan-out, NOT IN NULL bug, EXISTS vs IN, FK design, junction tables, CASCADE pitfalls |
+| `sql-indexing` | SQL indexing — composite order, covering/partial/expression indexes, SARGability, EXPLAIN interpretation, keyset pagination |
+| `sql-schema-design` | SQL schema — normalization, data types (TIMESTAMPTZ, NUMERIC), constraints, anti-patterns, safe migrations |
+| `sql-orm-patterns` | SQL ORM — N+1 fixes for Prisma/Django/SQLAlchemy/ActiveRecord/TypeORM, transactions, isolation levels, locking |
+
+### Architecture
+
+| Skill | Description |
+|-------|-------------|
 | `single-responsibility` | Single Responsibility Principle — language-agnostic SRP, file size limits, CQS, separation of concerns, smell tests |
 
-## GitHub Authentication
+### Quality
 
-The CLI fetches skills via the GitHub API. Unauthenticated requests are limited to 60/hour. To avoid rate limits:
+| Skill | Description |
+|-------|-------------|
+| `testing-best-practices` | Testing — Arrange-Act-Assert, factory-based test data, test isolation, mocking boundaries, pyramid-balanced coverage |
+| `security-practices` | Web security — OWASP Top 10 prevention, input validation, auth, SQL injection, XSS, CSRF, secure defaults |
+
+## Commands
+
+Portable slash commands for common git workflows. Installed to `.claude/commands/` in your project.
+
+| Command | Description |
+|---------|-------------|
+| `/commit` | Smart commit — branch safety, atomic staging, conventional commits |
+| `/pr` | Create PR — auto-detect base branch, structured summary and test plan |
+| `/release` | Release flow — dev→main PR with semver, changelog, tag, and GitHub release |
+| `/refactor` | Detect size/complexity/duplication/coupling issues via 4 parallel Haiku subagents, then refactor |
+| `/deep-review` | Multi-agent deep code review — 5 parallel Sonnet subagents catch guard bypasses, lost async state, wrong-table queries, dead references, protocol violations |
 
-- 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
+## Quick Start
 
-## What are Claude Code Skills?
+Run from any project directory:
 
-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.
+```bash
+npx @spardutti/claude-skills
+```
 
-## License
+The CLI will:
 
-MIT
+1. Fetch the latest skills, commands, and agents from GitHub
+2. Let you pick which skills to install → `.claude/skills/`
+3. Let you pick which commands to install → `.claude/commands/`
+4. Auto-install any subagents declared by the selected commands → `.claude/agents/`
+5. **Optionally set up automatic skill evaluation** (recommended — see below)
+
+## Automatic Skill Evaluation
+
+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
+
+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.
+
+### What gets created
+
+**`.claude/settings.json`** — Registers the hook:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/skill-forced-eval-hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**`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.
+```
+
+## Manual Install
+
+If you don't want to use the CLI, copy files directly into your project:
+
+```bash
+# Skills
+cp -r skills/<skill-name> /path/to/project/.claude/skills/
+
+# Commands
+cp commands/<command-name>.md /path/to/project/.claude/commands/
+
+# Subagents (required by some commands — see the command's `requires-agents` frontmatter)
+cp agents/<agent-name>.md /path/to/project/.claude/agents/
+```
+
+## Repository Layout
+
+```
+skills/           Reference playbooks loaded by Claude during coding tasks
+commands/         Slash commands installed to .claude/commands/
+agents/           Subagent definitions — commands declare which ones they need
+cli/              The npm installer (npx @spardutti/claude-skills)
+```

package/bin/cli.mjs

@@ -5,9 +5,9 @@ import chalk from "chalk";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { fetchSkills, fetchCommands } from "../lib/github.mjs";
+import { fetchSkills, fetchCommands, fetchAgents } from "../lib/github.mjs";
 import { promptSkillSelection, promptCommandSelection } from "../lib/prompt.mjs";
-import { installSkills, installCommands } from "../lib/install.mjs";
+import { installSkills, installCommands, installRequiredAgents } from "../lib/install.mjs";
 import { setupHook } from "../lib/setup-hook.mjs";
 import { setupClaudeMd } from "../lib/setup-claude-md.mjs";
 
@@ -17,8 +17,8 @@ const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-
 async function main() {
   console.log(`\n  ${chalk.bold.cyan("Claude Skills Installer")} ${chalk.dim(`v${pkg.version}`)}\n`);
 
-  console.log(chalk.dim("  Fetching available skills and commands...\n"));
-  const [skills, commands] = await Promise.all([fetchSkills(), fetchCommands()]);
+  console.log(chalk.dim("  Fetching available skills, commands, and agents...\n"));
+  const [skills, commands, agents] = await Promise.all([fetchSkills(), fetchCommands(), fetchAgents()]);
 
   // --- Skills ---
   let selectedSkills = [];
@@ -34,12 +34,21 @@ async function main() {
 
   // --- Commands ---
   let selectedCommands = [];
+  let installedAgentCount = 0;
   if (commands.length > 0) {
     console.log();
     selectedCommands = await promptCommandSelection(commands);
     if (selectedCommands.length > 0) {
       console.log();
       await installCommands(selectedCommands);
+
+      const { installed, missing } = await installRequiredAgents(selectedCommands, agents);
+      installedAgentCount = installed.length;
+      if (missing.length > 0) {
+        console.log(
+          `  ${chalk.yellow("!")} Missing agents referenced by commands: ${missing.join(", ")}`
+        );
+      }
     }
   }
 
@@ -66,7 +75,8 @@ async function main() {
   const parts = [];
   if (selectedSkills.length > 0) parts.push(`${selectedSkills.length} skill(s)`);
   if (selectedCommands.length > 0) parts.push(`${selectedCommands.length} command(s)`);
-  console.log(`\n  ${chalk.green("✔")} ${chalk.bold(`${parts.join(" and ")} installed successfully.`)}\n`);
+  if (installedAgentCount > 0) parts.push(`${installedAgentCount} agent(s)`);
+  console.log(`\n  ${chalk.green("✔")} ${chalk.bold(`${parts.join(", ")} installed successfully.`)}\n`);
 }
 
 main().catch((err) => {

package/lib/github.mjs

@@ -4,20 +4,20 @@ const REPO_OWNER = "Spardutti";
 const REPO_NAME = "claude-skills";
 const CONTENTS_API = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/contents/skills`;
 const COMMANDS_API = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/contents/commands`;
+const AGENTS_API = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/contents/agents`;
 const RAW_BASE = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main/skills`;
 const RAW_COMMANDS_BASE = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main/commands`;
+const RAW_AGENTS_BASE = `https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main/agents`;
 
 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",
@@ -34,38 +34,31 @@ function getAuthHeaders() {
   return headers;
 }
 
-export async function fetchSkills() {
+async function fetchListing({ apiUrl, label, entryFilter, buildRawUrl, mapEntry, allow404 = false }) {
   const headers = getAuthHeaders();
-
-  const res = await fetch(CONTENTS_API, { headers });
+  const res = await fetch(apiUrl, { headers });
 
   if (!res.ok) {
+    if (allow404 && res.status === 404) return [];
     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}`);
+    throw new Error(`Failed to list ${label}: ${res.status} ${res.statusText}`);
   }
 
-  const entries = await res.json();
-  const dirs = entries.filter((e) => e.type === "dir");
+  const entries = (await res.json()).filter(entryFilter);
 
   const results = await Promise.all(
-    dirs.map(async (dir) => {
+    entries.map(async (entry) => {
       try {
-        const url = `${RAW_BASE}/${dir.name}/SKILL.md`;
-        const r = await fetch(url, { headers });
-
+        const r = await fetch(buildRawUrl(entry), { headers });
         if (!r.ok) {
-          console.warn(`  Warning: No SKILL.md found in ${dir.name}, skipping`);
+          console.warn(`  Warning: Failed to fetch ${label} ${entry.name}, skipping`);
           return null;
         }
-
-        const content = await r.text();
-        const { name, description, category } = parseFrontmatter(content, dir.name);
-
-        return { dirName: dir.name, name, description, category, content };
+        return mapEntry(entry, await r.text());
       } catch {
-        console.warn(`  Warning: Failed to fetch ${dir.name}, skipping`);
+        console.warn(`  Warning: Failed to fetch ${entry.name}, skipping`);
         return null;
       }
     })
@@ -74,62 +67,76 @@ export async function fetchSkills() {
   return results.filter(Boolean);
 }
 
-export async function fetchCommands() {
-  const headers = getAuthHeaders();
-
-  const res = await fetch(COMMANDS_API, { headers });
-
-  if (!res.ok) {
-    if (res.status === 404) {
-      return [];
-    }
-    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 commands: ${res.status} ${res.statusText}`);
-  }
-
-  const entries = await res.json();
-  const files = entries.filter((e) => e.type === "file" && e.name.endsWith(".md"));
-
-  const results = await Promise.all(
-    files.map(async (file) => {
-      try {
-        const url = `${RAW_COMMANDS_BASE}/${file.name}`;
-        const r = await fetch(url, { headers });
-
-        if (!r.ok) {
-          console.warn(`  Warning: Failed to fetch command ${file.name}, skipping`);
-          return null;
-        }
-
-        const content = await r.text();
-        const { name, description, category } = parseFrontmatter(content, file.name.replace(/\.md$/, ""));
+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 };
+    },
+  });
+}
 
-        return { fileName: file.name, name, description, category, content };
-      } catch {
-        console.warn(`  Warning: Failed to fetch ${file.name}, skipping`);
-        return null;
-      }
-    })
-  );
+export function fetchCommands() {
+  return fetchListing({
+    apiUrl: COMMANDS_API,
+    label: "commands",
+    allow404: true,
+    entryFilter: (e) => e.type === "file" && e.name.endsWith(".md"),
+    buildRawUrl: (file) => `${RAW_COMMANDS_BASE}/${file.name}`,
+    mapEntry: (file, content) => {
+      const { name, description, category, requiresAgents } = parseFrontmatter(content, file.name.replace(/\.md$/, ""));
+      return { fileName: file.name, name, description, category, requiresAgents, content };
+    },
+  });
+}
 
-  return results.filter(Boolean);
+export function fetchAgents() {
+  return fetchListing({
+    apiUrl: AGENTS_API,
+    label: "agents",
+    allow404: true,
+    entryFilter: (e) => e.type === "file" && e.name.endsWith(".md"),
+    buildRawUrl: (file) => `${RAW_AGENTS_BASE}/${file.name}`,
+    mapEntry: (file, content) => {
+      const { name } = parseFrontmatter(content, file.name.replace(/\.md$/, ""));
+      return { fileName: file.name, name, content };
+    },
+  });
 }
 
 function parseFrontmatter(content, fallbackName) {
   const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
   if (!match) {
-    return { name: fallbackName, description: "", category: "General" };
+    return { name: fallbackName, description: "", category: "General", requiresAgents: [] };
   }
 
   const block = match[1];
-  const name =
-    block.match(/^name:\s*(.+)$/m)?.[1]?.trim() || fallbackName;
-  const description =
-    block.match(/^description:\s*(.+)$/m)?.[1]?.trim() || "";
-  const category =
-    block.match(/^category:\s*(.+)$/m)?.[1]?.trim() || "General";
-
-  return { name, description, category };
+  const name = block.match(/^name:\s*(.+)$/m)?.[1]?.trim() || fallbackName;
+  const description = block.match(/^description:\s*(.+)$/m)?.[1]?.trim() || "";
+  const category = block.match(/^category:\s*(.+)$/m)?.[1]?.trim() || "General";
+  const requiresAgents = parseAgentList(block);
+
+  return { name, description, category, requiresAgents };
+}
+
+function parseAgentList(block) {
+  const inline = block.match(/^requires-agents:\s*\[([^\]]*)\]\s*$/m);
+  if (inline) {
+    return inline[1]
+      .split(",")
+      .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+      .filter(Boolean);
+  }
+  const multiline = block.match(/^requires-agents:\s*\n((?:\s{2,}-\s*.+\n?)+)/m);
+  if (multiline) {
+    return multiline[1]
+      .split("\n")
+      .map((l) => l.replace(/^\s*-\s*/, "").trim().replace(/^["']|["']$/g, ""))
+      .filter(Boolean);
+  }
+  return [];
 }

package/lib/install.mjs

@@ -2,12 +2,21 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import chalk from "chalk";
 
-function humanName(skill) {
-  return skill.name
+function humanName(item) {
+  return item.name
     .replace(/-/g, " ")
     .replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
+async function installFlat(items, subdir, targetDir) {
+  const baseDir = join(targetDir, ".claude", subdir);
+  await mkdir(baseDir, { recursive: true });
+  for (const item of items) {
+    await writeFile(join(baseDir, item.fileName), item.content);
+    console.log(`  ${chalk.green("✔")} ${chalk.bold(humanName(item))} ${chalk.dim(`→ .claude/${subdir}/${item.fileName}`)}`);
+  }
+}
+
 export async function installSkills(skills, targetDir = process.cwd()) {
   const baseDir = join(targetDir, ".claude", "skills");
 
@@ -19,12 +28,28 @@ export async function installSkills(skills, targetDir = process.cwd()) {
   }
 }
 
-export async function installCommands(commands, targetDir = process.cwd()) {
-  const baseDir = join(targetDir, ".claude", "commands");
-  await mkdir(baseDir, { recursive: true });
+export function installCommands(commands, targetDir = process.cwd()) {
+  return installFlat(commands, "commands", targetDir);
+}
+
+export function installAgents(agents, targetDir = process.cwd()) {
+  return installFlat(agents, "agents", targetDir);
+}
+
+export async function installRequiredAgents(selectedCommands, availableAgents, targetDir = process.cwd()) {
+  const requiredNames = new Set(
+    selectedCommands.flatMap((c) => c.requiresAgents ?? [])
+  );
+  if (requiredNames.size === 0) return { installed: [], missing: [] };
+
+  const installed = availableAgents.filter((a) => requiredNames.has(a.name));
+  const missing = [...requiredNames].filter(
+    (n) => !availableAgents.some((a) => a.name === n)
+  );
 
-  for (const cmd of commands) {
-    await writeFile(join(baseDir, cmd.fileName), cmd.content);
-    console.log(`  ${chalk.green("✔")} ${chalk.bold(humanName(cmd))} ${chalk.dim(`→ .claude/commands/${cmd.fileName}`)}`);
+  if (installed.length > 0) {
+    console.log();
+    await installAgents(installed, targetDir);
   }
+  return { installed, missing };
 }

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "1.19.1",
+  "version": "1.21.0",
   "description": "CLI to install Claude Code skills from the claude-skills collection",
   "type": "module",
   "bin": {
     "claude-skills": "bin/cli.mjs"
   },
+  "scripts": {
+    "prepack": "cp ../README.md README.md",
+    "postpack": "git checkout -- README.md"
+  },
   "engines": {
     "node": ">=18"
   },