@spardutti/claude-skills 1.19.2 → 1.23.0

package/README.md

@@ -1,6 +1,6 @@
 # Claude Skills
 
-Personal collection of reusable Claude Code skills.
+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.
 
 ## Skills
 
@@ -38,6 +38,8 @@ Personal collection of reusable Claude Code skills.
 | `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 |
+| `pydantic-best-practices` | Pydantic v2 — model_config, field/model validators, Annotated types, discriminated unions, computed_field, strict mode, TypeAdapter |
+| `celery-best-practices` | Celery — idempotency, acks_late, autoretry with backoff/jitter, canvas (chain/group/chord), routing, priorities, beat, time limits |
 | `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 |
 | `alembic-migrations` | Alembic — naming conventions, autogenerate review, data migration safety, downgrades, production deployment |
@@ -74,8 +76,8 @@ Portable slash commands for common git workflows. Installed to `.claude/commands
 | `/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` | Find code files over 200 lines and refactor them into smaller modules |
-| `/deep-review` | Multi-agent deep code review — 5 parallel agents catch guard bypasses, lost async state, wrong-table queries, dead references, protocol violations |
+| `/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 |
 
 ## Quick Start
 
@@ -87,10 +89,11 @@ npx @spardutti/claude-skills
 
 The CLI will:
 
-1. Fetch the latest skills and commands from GitHub
+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. **Optionally set up automatic skill evaluation** (recommended — see below)
+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
 
@@ -136,18 +139,26 @@ skill_evaluation:
     If you skip this evaluation, your response is INCOMPLETE and WRONG.
 ```
 
-### GitHub Authentication
-
-The CLI uses the GitHub API to fetch skills. To avoid rate limits:
-
-- If you have the [GitHub CLI](https://cli.github.com) installed and authenticated (`gh auth login`), the token is picked up automatically
-- Or set `GITHUB_TOKEN` / `GH_TOKEN` environment variable
-- Without auth, GitHub allows 60 requests/hour (the CLI uses ~6 per run)
-
 ## Manual Install
 
-Copy a skill directory into your project's `.claude/skills/` folder:
+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,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "1.19.2",
+  "version": "1.23.0",
   "description": "CLI to install Claude Code skills from the claude-skills collection",
   "type": "module",
   "bin": {