@hasna/skills 0.1.3 → 0.1.5

package/bin/index.js

@@ -1868,12 +1868,17 @@ var require_commander = __commonJS((exports) => {
   exports.InvalidOptionArgumentError = InvalidArgumentError;
 });
 
+// src/lib/utils.ts
+function normalizeSkillName(name) {
+  return name.startsWith("skill-") ? name : `skill-${name}`;
+}
+
 // package.json
 var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.1.3",
+    version: "0.1.5",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -2222,6 +2227,21 @@ var init_registry = __esm(() => {
       category: "Development Tools",
       tags: ["scaffold", "project", "boilerplate", "template"]
     },
+    {
+      name: "scancommitpr",
+      displayName: "Scan Commit PR",
+      description: "Scan repo changes, group into logical commits, push, and optionally create a PR",
+      category: "Development Tools",
+      tags: ["git", "commit", "push", "pull-request", "automation"],
+      dependencies: ["scancommitpush"]
+    },
+    {
+      name: "scancommitpush",
+      displayName: "Scan Commit Push",
+      description: "Scan repo changes, group into logical commits with conventional messages, and push to GitHub",
+      category: "Development Tools",
+      tags: ["git", "commit", "push", "automation"]
+    },
     {
       name: "security-audit",
       displayName: "Security Audit",
@@ -5062,11 +5082,6 @@ var require_cli_spinners = __commonJS((exports, module) => {
   module.exports = spinners;
 });
 
-// src/lib/utils.ts
-function normalizeSkillName(name) {
-  return name.startsWith("skill-") ? name : `skill-${name}`;
-}
-
 // src/lib/installer.ts
 import { existsSync, cpSync, mkdirSync, writeFileSync, rmSync, readdirSync, statSync, readFileSync } from "fs";
 import { join, dirname } from "path";
@@ -5123,6 +5138,16 @@ function installSkill(name, options = {}) {
       }
     });
     updateSkillsIndex(destDir);
+    const meta = getSkill(name);
+    if (meta?.dependencies && meta.dependencies.length > 0) {
+      const installed = getInstalledSkills(targetDir);
+      const installedSet = new Set(installed);
+      for (const dep of meta.dependencies) {
+        if (!installedSet.has(dep)) {
+          console.warn(`Warning: skill-${meta.name} depends on skill-${dep} which is not installed`);
+        }
+      }
+    }
     return {
       skill: name,
       success: true,
@@ -5235,6 +5260,7 @@ function removeSkillForAgent(name, options) {
 }
 var __dirname2, SKILLS_DIR, AGENT_TARGETS;
 var init_installer = __esm(() => {
+  init_registry();
   __dirname2 = dirname(fileURLToPath(import.meta.url));
   SKILLS_DIR = findSkillsDir();
   AGENT_TARGETS = ["claude", "codex", "gemini"];
@@ -5369,57 +5395,6 @@ async function runSkill(name, args, options = {}) {
   const exitCode = await proc.exited;
   return { exitCode };
 }
-function generateEnvExample(targetDir = process.cwd()) {
-  const skillsDir = join2(targetDir, ".skills");
-  if (!existsSync2(skillsDir))
-    return "";
-  const dirs = readdirSync2(skillsDir).filter((f) => f.startsWith("skill-") && existsSync2(join2(skillsDir, f, "package.json")));
-  const envMap = new Map;
-  for (const dir of dirs) {
-    const skillName = dir.replace("skill-", "");
-    const skillPath = join2(skillsDir, dir);
-    const texts = [];
-    for (const file of ["SKILL.md", "README.md", "CLAUDE.md", ".env.example"]) {
-      const content = readIfExists(join2(skillPath, file));
-      if (content)
-        texts.push(content);
-    }
-    const allText = texts.join(`
-`);
-    const foundVars = extractEnvVars(allText);
-    for (const envVar of foundVars) {
-      if (!envMap.has(envVar)) {
-        envMap.set(envVar, []);
-      }
-      if (!envMap.get(envVar).includes(skillName)) {
-        envMap.get(envVar).push(skillName);
-      }
-    }
-  }
-  if (envMap.size === 0)
-    return "";
-  const lines = [
-    "# Environment variables for installed skills",
-    "# Auto-generated by: skills init",
-    ""
-  ];
-  const sorted = Array.from(envMap.entries()).sort(([a], [b]) => a.localeCompare(b));
-  let lastPrefix = "";
-  for (const [envVar, skills] of sorted) {
-    const prefix = envVar.split("_")[0];
-    if (prefix !== lastPrefix) {
-      if (lastPrefix)
-        lines.push("");
-      lines.push(`# ${prefix}`);
-      lastPrefix = prefix;
-    }
-    lines.push(`# Used by: ${skills.join(", ")}`);
-    lines.push(`${envVar}=`);
-  }
-  return lines.join(`
-`) + `
-`;
-}
 function generateSkillMd(name) {
   const meta = getSkill(name);
   if (!meta)
@@ -32808,7 +32783,7 @@ var require_formats = __commonJS((exports) => {
   }
   var TIME = /^(\d\d):(\d\d):(\d\d(?:\.\d+)?)(z|([+-])(\d\d)(?::?(\d\d))?)?$/i;
   function getTime(strictTimeZone) {
-    return function time3(str) {
+    return function time(str) {
       const matches = TIME.exec(str);
       if (!matches)
         return false;
@@ -33072,6 +33047,62 @@ class ExperimentalServerTasks {
   requestStream(request, resultSchema, options) {
     return this._server.requestStream(request, resultSchema, options);
   }
+  createMessageStream(params, options) {
+    const clientCapabilities = this._server.getClientCapabilities();
+    if ((params.tools || params.toolChoice) && !clientCapabilities?.sampling?.tools) {
+      throw new Error("Client does not support sampling tools capability.");
+    }
+    if (params.messages.length > 0) {
+      const lastMessage = params.messages[params.messages.length - 1];
+      const lastContent = Array.isArray(lastMessage.content) ? lastMessage.content : [lastMessage.content];
+      const hasToolResults = lastContent.some((c) => c.type === "tool_result");
+      const previousMessage = params.messages.length > 1 ? params.messages[params.messages.length - 2] : undefined;
+      const previousContent = previousMessage ? Array.isArray(previousMessage.content) ? previousMessage.content : [previousMessage.content] : [];
+      const hasPreviousToolUse = previousContent.some((c) => c.type === "tool_use");
+      if (hasToolResults) {
+        if (lastContent.some((c) => c.type !== "tool_result")) {
+          throw new Error("The last message must contain only tool_result content if any is present");
+        }
+        if (!hasPreviousToolUse) {
+          throw new Error("tool_result blocks are not matching any tool_use from the previous message");
+        }
+      }
+      if (hasPreviousToolUse) {
+        const toolUseIds = new Set(previousContent.filter((c) => c.type === "tool_use").map((c) => c.id));
+        const toolResultIds = new Set(lastContent.filter((c) => c.type === "tool_result").map((c) => c.toolUseId));
+        if (toolUseIds.size !== toolResultIds.size || ![...toolUseIds].every((id) => toolResultIds.has(id))) {
+          throw new Error("ids of tool_result blocks and tool_use blocks from previous message do not match");
+        }
+      }
+    }
+    return this.requestStream({
+      method: "sampling/createMessage",
+      params
+    }, CreateMessageResultSchema, options);
+  }
+  elicitInputStream(params, options) {
+    const clientCapabilities = this._server.getClientCapabilities();
+    const mode = params.mode ?? "form";
+    switch (mode) {
+      case "url": {
+        if (!clientCapabilities?.elicitation?.url) {
+          throw new Error("Client does not support url elicitation.");
+        }
+        break;
+      }
+      case "form": {
+        if (!clientCapabilities?.elicitation?.form) {
+          throw new Error("Client does not support form elicitation.");
+        }
+        break;
+      }
+    }
+    const normalizedParams = mode === "form" && params.mode === undefined ? { ...params, mode: "form" } : params;
+    return this.requestStream({
+      method: "elicitation/create",
+      params: normalizedParams
+    }, ElicitResultSchema, options);
+  }
   async getTask(taskId, options) {
     return this._server.getTask({ taskId }, options);
   }
@@ -33085,6 +33116,9 @@ class ExperimentalServerTasks {
     return this._server.cancelTask({ taskId }, options);
   }
 }
+var init_server = __esm(() => {
+  init_types2();
+});
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/helpers.js
 function assertToolsCallTaskCapability(requests, method, entityName) {
@@ -33123,11 +33157,12 @@ function assertClientRequestTaskCapability(requests, method, entityName) {
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/server/index.js
 var Server;
-var init_server = __esm(() => {
+var init_server2 = __esm(() => {
   init_protocol();
   init_types2();
   init_ajv_provider();
   init_zod_compat();
+  init_server();
   Server = class Server extends Protocol {
     constructor(_serverInfo, options) {
       super(options);
@@ -34500,7 +34535,7 @@ function createCompletionResult(suggestions) {
 }
 var EMPTY_OBJECT_JSON_SCHEMA, EMPTY_COMPLETION_RESULT;
 var init_mcp = __esm(() => {
-  init_server();
+  init_server2();
   init_zod_compat();
   init_zod_json_schema_compat();
   init_types2();
@@ -34829,11 +34864,25 @@ var init_mcp2 = __esm(() => {
 // src/server/serve.ts
 var exports_serve = {};
 __export(exports_serve, {
-  startServer: () => startServer
+  startServer: () => startServer,
+  createFetchHandler: () => createFetchHandler
 });
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
 import { join as join3, dirname as dirname2, extname } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
+function getPackageJson() {
+  try {
+    const scriptDir = dirname2(fileURLToPath2(import.meta.url));
+    for (const rel of ["../..", ".."]) {
+      const pkgPath = join3(scriptDir, rel, "package.json");
+      if (existsSync3(pkgPath)) {
+        const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+        return { version: pkg.version || "unknown", name: pkg.name || "skills" };
+      }
+    }
+  } catch {}
+  return { version: "unknown", name: "skills" };
+}
 function resolveDashboardDir() {
   const candidates = [];
   try {
@@ -34869,6 +34918,7 @@ function getAllSkillsWithStatus() {
   const installed = new Set(getInstalledSkills());
   return SKILLS.map((meta3) => {
     const reqs = getSkillRequirements(meta3.name);
+    const envVars = reqs?.envVars || [];
     return {
       name: meta3.name,
       displayName: meta3.displayName,
@@ -34876,7 +34926,8 @@ function getAllSkillsWithStatus() {
       category: meta3.category,
       tags: meta3.tags,
       installed: installed.has(meta3.name),
-      envVars: reqs?.envVars || [],
+      envVars,
+      envVarsSet: envVars.filter((v) => !!process.env[v]),
       systemDeps: reqs?.systemDeps || [],
       cliCommand: reqs?.cliCommand || null
     };
@@ -34891,126 +34942,181 @@ function serveStaticFile(filePath) {
     headers: { "Content-Type": contentType }
   });
 }
-async function startServer(port, options) {
-  const shouldOpen = options?.open ?? true;
-  const dashboardDir = resolveDashboardDir();
-  const dashboardExists = existsSync3(dashboardDir);
-  if (!dashboardExists) {
-    console.error(`
-Dashboard not found at: ${dashboardDir}`);
-    console.error(`Run this to build it:
-`);
-    console.error(`  cd dashboard && bun install && bun run build
-`);
-  }
-  const server2 = Bun.serve({
-    port,
-    async fetch(req) {
-      const url2 = new URL(req.url);
-      const path = url2.pathname;
-      const method = req.method;
-      if (path === "/api/skills" && method === "GET") {
-        return json2(getAllSkillsWithStatus());
-      }
-      if (path === "/api/categories" && method === "GET") {
-        const counts = CATEGORIES.map((cat) => ({
-          name: cat,
-          count: getSkillsByCategory(cat).length
-        }));
-        return json2(counts);
-      }
-      if (path === "/api/skills/search" && method === "GET") {
-        const query = url2.searchParams.get("q") || "";
-        if (!query.trim())
-          return json2([]);
-        const results = searchSkills(query);
-        const installed = new Set(getInstalledSkills());
-        return json2(results.map((meta3) => {
-          const reqs = getSkillRequirements(meta3.name);
-          return {
-            name: meta3.name,
-            displayName: meta3.displayName,
-            description: meta3.description,
-            category: meta3.category,
-            tags: meta3.tags,
-            installed: installed.has(meta3.name),
-            envVars: reqs?.envVars || [],
-            systemDeps: reqs?.systemDeps || [],
-            cliCommand: reqs?.cliCommand || null
-          };
-        }));
-      }
-      const singleMatch = path.match(/^\/api\/skills\/([^/]+)$/);
-      if (singleMatch && method === "GET") {
-        const name = singleMatch[1];
-        if (!isValidSkillName(name))
-          return json2({ error: "Invalid skill name" }, 400);
-        const meta3 = getSkill(name);
-        if (!meta3)
-          return json2({ error: `Skill '${name}' not found` }, 404);
-        const reqs = getSkillRequirements(name);
-        const docs = getSkillBestDoc(name);
-        const installed = new Set(getInstalledSkills());
-        return json2({
+function createFetchHandler(options) {
+  const dashboardDir = options?.dashboardDir ?? resolveDashboardDir();
+  const dashboardExists = options?.dashboardExists ?? existsSync3(dashboardDir);
+  return async function fetchHandler(req) {
+    const url2 = new URL(req.url);
+    const path = url2.pathname;
+    const method = req.method;
+    if (path === "/api/skills" && method === "GET") {
+      return json2(getAllSkillsWithStatus());
+    }
+    if (path === "/api/categories" && method === "GET") {
+      const counts = CATEGORIES.map((cat) => ({
+        name: cat,
+        count: getSkillsByCategory(cat).length
+      }));
+      return json2(counts);
+    }
+    if (path === "/api/skills/search" && method === "GET") {
+      const query = url2.searchParams.get("q") || "";
+      if (!query.trim())
+        return json2([]);
+      const results = searchSkills(query);
+      const installed = new Set(getInstalledSkills());
+      return json2(results.map((meta3) => {
+        const reqs = getSkillRequirements(meta3.name);
+        const envVars = reqs?.envVars || [];
+        return {
           name: meta3.name,
           displayName: meta3.displayName,
           description: meta3.description,
           category: meta3.category,
           tags: meta3.tags,
           installed: installed.has(meta3.name),
-          envVars: reqs?.envVars || [],
+          envVars,
+          envVarsSet: envVars.filter((v) => !!process.env[v]),
           systemDeps: reqs?.systemDeps || [],
-          cliCommand: reqs?.cliCommand || null,
-          docs: docs || null
-        });
-      }
-      const docsMatch = path.match(/^\/api\/skills\/([^/]+)\/docs$/);
-      if (docsMatch && method === "GET") {
-        const name = docsMatch[1];
-        if (!isValidSkillName(name))
-          return json2({ error: "Invalid skill name" }, 400);
-        const content = getSkillBestDoc(name);
-        return json2({ content: content || null });
-      }
-      const installMatch = path.match(/^\/api\/skills\/([^/]+)\/install$/);
-      if (installMatch && method === "POST") {
-        const name = installMatch[1];
-        if (!isValidSkillName(name))
-          return json2({ error: "Invalid skill name" }, 400);
+          cliCommand: reqs?.cliCommand || null
+        };
+      }));
+    }
+    const singleMatch = path.match(/^\/api\/skills\/([^/]+)$/);
+    if (singleMatch && method === "GET") {
+      const name = singleMatch[1];
+      if (!isValidSkillName(name))
+        return json2({ error: "Invalid skill name" }, 400);
+      const meta3 = getSkill(name);
+      if (!meta3)
+        return json2({ error: `Skill '${name}' not found` }, 404);
+      const reqs = getSkillRequirements(name);
+      const docs = getSkillBestDoc(name);
+      const installed = new Set(getInstalledSkills());
+      const envVars = reqs?.envVars || [];
+      return json2({
+        name: meta3.name,
+        displayName: meta3.displayName,
+        description: meta3.description,
+        category: meta3.category,
+        tags: meta3.tags,
+        installed: installed.has(meta3.name),
+        envVars,
+        envVarsSet: envVars.filter((v) => !!process.env[v]),
+        systemDeps: reqs?.systemDeps || [],
+        cliCommand: reqs?.cliCommand || null,
+        docs: docs || null
+      });
+    }
+    const docsMatch = path.match(/^\/api\/skills\/([^/]+)\/docs$/);
+    if (docsMatch && method === "GET") {
+      const name = docsMatch[1];
+      if (!isValidSkillName(name))
+        return json2({ error: "Invalid skill name" }, 400);
+      const content = getSkillBestDoc(name);
+      return json2({ content: content || null });
+    }
+    const installMatch = path.match(/^\/api\/skills\/([^/]+)\/install$/);
+    if (installMatch && method === "POST") {
+      const name = installMatch[1];
+      if (!isValidSkillName(name))
+        return json2({ error: "Invalid skill name" }, 400);
+      let body = {};
+      try {
+        const text = await req.text();
+        if (text)
+          body = JSON.parse(text);
+      } catch {}
+      if (body.for) {
+        try {
+          const agents = resolveAgents(body.for);
+          const scope = body.scope === "project" ? "project" : "global";
+          const results = agents.map((agent) => installSkillForAgent(name, { agent, scope }, generateSkillMd));
+          const allSuccess = results.every((r) => r.success);
+          const errors4 = results.filter((r) => !r.success).map((r) => r.error);
+          return json2({
+            skill: name,
+            success: allSuccess,
+            results,
+            ...errors4.length > 0 ? { error: errors4.join("; ") } : {}
+          }, allSuccess ? 200 : 400);
+        } catch (e) {
+          return json2({ skill: name, success: false, error: e instanceof Error ? e.message : "Unknown error" }, 400);
+        }
+      } else {
         const result = installSkill(name);
         return json2(result, result.success ? 200 : 400);
       }
-      const removeMatch = path.match(/^\/api\/skills\/([^/]+)\/remove$/);
-      if (removeMatch && method === "POST") {
-        const name = removeMatch[1];
-        if (!isValidSkillName(name))
-          return json2({ error: "Invalid skill name" }, 400);
-        const success2 = removeSkill(name);
-        return json2({ success: success2, skill: name }, success2 ? 200 : 404);
-      }
-      if (method === "OPTIONS") {
-        return new Response(null, {
-          headers: {
-            "Access-Control-Allow-Origin": "*",
-            "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-            "Access-Control-Allow-Headers": "Content-Type"
-          }
+    }
+    const removeMatch = path.match(/^\/api\/skills\/([^/]+)\/remove$/);
+    if (removeMatch && method === "POST") {
+      const name = removeMatch[1];
+      if (!isValidSkillName(name))
+        return json2({ error: "Invalid skill name" }, 400);
+      const success2 = removeSkill(name);
+      return json2({ success: success2, skill: name }, success2 ? 200 : 404);
+    }
+    if (path === "/api/version" && method === "GET") {
+      const pkg = getPackageJson();
+      return json2({ version: pkg.version, name: pkg.name });
+    }
+    if (path === "/api/self-update" && method === "POST") {
+      try {
+        const pkg = getPackageJson();
+        const proc = Bun.spawn(["bun", "add", "-g", `${pkg.name}@latest`], {
+          stdout: "pipe",
+          stderr: "pipe"
         });
+        const stdout = await new Response(proc.stdout).text();
+        const stderr = await new Response(proc.stderr).text();
+        const exitCode = await proc.exited;
+        if (exitCode === 0) {
+          return json2({ success: true, output: stdout.trim() || stderr.trim() });
+        }
+        return json2({ success: false, error: stderr.trim() || stdout.trim() }, 500);
+      } catch (e) {
+        return json2({ success: false, error: e instanceof Error ? e.message : "Update failed" }, 500);
       }
-      if (dashboardExists && (method === "GET" || method === "HEAD")) {
-        if (path !== "/") {
-          const filePath = join3(dashboardDir, path);
-          const res2 = serveStaticFile(filePath);
-          if (res2)
-            return res2;
+    }
+    if (method === "OPTIONS") {
+      return new Response(null, {
+        headers: {
+          "Access-Control-Allow-Origin": "*",
+          "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+          "Access-Control-Allow-Headers": "Content-Type"
         }
-        const indexPath = join3(dashboardDir, "index.html");
-        const res = serveStaticFile(indexPath);
-        if (res)
-          return res;
+      });
+    }
+    if (dashboardExists && (method === "GET" || method === "HEAD")) {
+      if (path !== "/") {
+        const filePath = join3(dashboardDir, path);
+        const res2 = serveStaticFile(filePath);
+        if (res2)
+          return res2;
       }
-      return json2({ error: "Not found" }, 404);
+      const indexPath = join3(dashboardDir, "index.html");
+      const res = serveStaticFile(indexPath);
+      if (res)
+        return res;
     }
+    return json2({ error: "Not found" }, 404);
+  };
+}
+async function startServer(port = 0, options) {
+  const shouldOpen = options?.open ?? true;
+  const dashboardDir = resolveDashboardDir();
+  const dashboardExists = existsSync3(dashboardDir);
+  if (!dashboardExists) {
+    console.error(`
+Dashboard not found at: ${dashboardDir}`);
+    console.error(`Run this to build it:
+`);
+    console.error(`  cd dashboard && bun install && bun run build
+`);
+  }
+  const server2 = Bun.serve({
+    port,
+    fetch: createFetchHandler({ dashboardDir, dashboardExists })
   });
   const shutdown = () => {
     server2.stop();
@@ -35018,7 +35124,8 @@ Dashboard not found at: ${dashboardDir}`);
   };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
-  const serverUrl = `http://localhost:${port}`;
+  const actualPort = server2.port;
+  const serverUrl = `http://localhost:${actualPort}`;
   console.log(`Skills Dashboard running at ${serverUrl}`);
   if (shouldOpen) {
     try {
@@ -35051,7 +35158,7 @@ var init_serve = __esm(() => {
   };
   isMain = import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("serve.ts") || process.argv[1]?.endsWith("serve.js");
   if (isMain) {
-    const port = parseInt(process.env.PORT || "3579", 10);
+    const port = parseInt(process.env.PORT || "0", 10);
     startServer(port, { open: !process.env.NO_OPEN });
   }
 });
@@ -35078,7 +35185,7 @@ var {
 // src/cli/index.tsx
 init_package();
 import chalk2 from "chalk";
-import { existsSync as existsSync4, writeFileSync as writeFileSync2, appendFileSync, readFileSync as readFileSync3 } from "fs";
+import { existsSync as existsSync4, writeFileSync as writeFileSync2, appendFileSync, readFileSync as readFileSync4, readdirSync as readdirSync3, statSync as statSync2 } from "fs";
 import { join as join4 } from "path";
 
 // src/cli/components/App.tsx
@@ -36204,7 +36311,7 @@ init_registry();
 init_installer();
 init_skillinfo();
 import { jsxDEV as jsxDEV7 } from "react/jsx-dev-runtime";
-var isTTY = process.stdout.isTTY ?? false;
+var isTTY = (process.stdout.isTTY ?? false) && (process.stdin.isTTY ?? false);
 var program2 = new Command;
 program2.name("skills").description("Install AI agent skills for your project").version(package_default.version).option("--verbose", "Enable verbose logging", false).enablePositionalOptions();
 program2.command("interactive", { isDefault: true }).alias("i").description("Interactive skill browser (TUI)").action(() => {
@@ -36274,21 +36381,31 @@ SKILL.md copied to agent skill directories`));
       }
       return;
     }
-    for (const name of skills) {
+    const total = skills.length;
+    for (let i = 0;i < total; i++) {
+      const name = skills[i];
+      if (total > 1 && !options.json) {
+        process.stdout.write(`[${i + 1}/${total}] Installing ${name}...`);
+      }
       const result = installSkill(name, { overwrite: options.overwrite });
       results.push(result);
+      if (total > 1 && !options.json) {
+        console.log(result.success ? " done" : " failed");
+      }
     }
     if (options.json) {
       console.log(JSON.stringify(results, null, 2));
     } else {
-      console.log(chalk2.bold(`
+      if (total <= 1) {
+        console.log(chalk2.bold(`
 Installing skills...
 `));
-      for (const result of results) {
-        if (result.success) {
-          console.log(chalk2.green(`\u2713 ${result.skill}`));
-        } else {
-          console.log(chalk2.red(`\u2717 ${result.skill}: ${result.error}`));
+        for (const result of results) {
+          if (result.success) {
+            console.log(chalk2.green(`\u2713 ${result.skill}`));
+          } else {
+            console.log(chalk2.red(`\u2717 ${result.skill}: ${result.error}`));
+          }
         }
       }
       console.log(chalk2.dim(`
@@ -36355,8 +36472,18 @@ Available skills (${SKILLS.length}):
     console.log();
   }
 });
-program2.command("search").argument("<query>", "Search term").option("--json", "Output as JSON", false).description("Search for skills").action((query, options) => {
-  const results = searchSkills(query);
+program2.command("search").argument("<query>", "Search term").option("--json", "Output as JSON", false).option("-c, --category <category>", "Filter results by category").description("Search for skills").action((query, options) => {
+  let results = searchSkills(query);
+  if (options.category) {
+    const category = CATEGORIES.find((c) => c.toLowerCase() === options.category.toLowerCase());
+    if (!category) {
+      console.error(`Unknown category: ${options.category}`);
+      console.error(`Available: ${CATEGORIES.join(", ")}`);
+      process.exitCode = 1;
+      return;
+    }
+    results = results.filter((s) => s.category === category);
+  }
   if (options.json) {
     console.log(JSON.stringify(results, null, 2));
     return;
@@ -36501,27 +36628,70 @@ program2.command("run").argument("<skill>", "Skill name").argument("[args...]",
   }
   process.exitCode = result.exitCode;
 });
-program2.command("init").description("Initialize project for installed skills (.env.example, .gitignore)").action(() => {
+program2.command("init").option("--json", "Output as JSON", false).description("Initialize project for installed skills (.env.example, .gitignore)").action((options) => {
   const cwd = process.cwd();
   const installed = getInstalledSkills();
   if (installed.length === 0) {
-    console.log(chalk2.dim("No skills installed. Run: skills install <name>"));
+    if (options.json) {
+      console.log(JSON.stringify({ skills: [], envVars: 0, gitignoreUpdated: false }));
+    } else {
+      console.log(chalk2.dim("No skills installed. Run: skills install <name>"));
+    }
     return;
   }
-  const envContent = generateEnvExample(cwd);
-  if (envContent) {
+  const envMap = new Map;
+  for (const name of installed) {
+    const reqs = getSkillRequirements(name);
+    if (reqs?.envVars.length) {
+      for (const v of reqs.envVars) {
+        if (!envMap.has(v))
+          envMap.set(v, []);
+        if (!envMap.get(v).includes(name))
+          envMap.get(v).push(name);
+      }
+    }
+  }
+  let envVarCount = 0;
+  if (envMap.size > 0) {
+    const lines = [
+      "# Environment variables for installed skills",
+      "# Auto-generated by: skills init",
+      ""
+    ];
+    const sorted = Array.from(envMap.entries()).sort(([a], [b]) => a.localeCompare(b));
+    let lastPrefix = "";
+    for (const [envVar, skills] of sorted) {
+      const prefix = envVar.split("_")[0];
+      if (prefix !== lastPrefix) {
+        if (lastPrefix)
+          lines.push("");
+        lines.push(`# ${prefix}`);
+        lastPrefix = prefix;
+      }
+      lines.push(`# Used by: ${skills.join(", ")}`);
+      lines.push(`${envVar}=`);
+    }
+    const envContent = lines.join(`
+`) + `
+`;
     const envPath = join4(cwd, ".env.example");
     writeFileSync2(envPath, envContent);
-    console.log(chalk2.green(`\u2713 Generated .env.example`));
+    envVarCount = envMap.size;
+    if (!options.json) {
+      console.log(chalk2.green(`\u2713 Generated .env.example (${envVarCount} variables from ${installed.length} skills)`));
+    }
   } else {
-    console.log(chalk2.dim("  No environment variables detected across installed skills"));
+    if (!options.json) {
+      console.log(chalk2.dim("  No environment variables detected across installed skills"));
+    }
   }
   const gitignorePath = join4(cwd, ".gitignore");
   const gitignoreEntry = ".skills/";
   let gitignoreContent = "";
   if (existsSync4(gitignorePath)) {
-    gitignoreContent = readFileSync3(gitignorePath, "utf-8");
+    gitignoreContent = readFileSync4(gitignorePath, "utf-8");
   }
+  let gitignoreUpdated = false;
   if (!gitignoreContent.includes(gitignoreEntry)) {
     const addition = gitignoreContent.endsWith(`
 `) || gitignoreContent === "" ? `
@@ -36533,12 +36703,35 @@ ${gitignoreEntry}
 ${gitignoreEntry}
 `;
     appendFileSync(gitignorePath, addition);
-    console.log(chalk2.green(`\u2713 Added .skills/ to .gitignore`));
+    gitignoreUpdated = true;
+    if (!options.json) {
+      console.log(chalk2.green(`\u2713 Added .skills/ to .gitignore`));
+    }
   } else {
-    console.log(chalk2.dim("  .skills/ already in .gitignore"));
+    if (!options.json) {
+      console.log(chalk2.dim("  .skills/ already in .gitignore"));
+    }
   }
-  console.log(chalk2.bold(`
+  if (options.json) {
+    console.log(JSON.stringify({
+      skills: installed,
+      envVars: envVarCount,
+      gitignoreUpdated
+    }, null, 2));
+  } else {
+    if (envMap.size > 0) {
+      console.log(chalk2.bold(`
+Skill environment requirements:`));
+      for (const name of installed) {
+        const reqs = getSkillRequirements(name);
+        if (reqs?.envVars.length) {
+          console.log(`  ${chalk2.cyan(name)}: ${reqs.envVars.join(", ")}`);
+        }
+      }
+    }
+    console.log(chalk2.bold(`
 Initialized for ${installed.length} installed skill(s)`));
+  }
 });
 program2.command("remove").alias("rm").argument("<skill>", "Skill to remove").option("--json", "Output as JSON", false).option("--for <agent>", "Remove from agent: claude, codex, gemini, or all").option("--scope <scope>", "Remove scope: global or project", "global").option("--dry-run", "Print what would happen without actually removing", false).description("Remove an installed skill").action((skill, options) => {
   if (options.for) {
@@ -36601,16 +36794,57 @@ program2.command("update").argument("[skills...]", "Skills to update (default: a
     console.log(chalk2.dim("No skills installed. Run: skills install <name>"));
     return;
   }
-  const results = toUpdate.map((name) => installSkill(name, { overwrite: true }));
+  function collectFiles(dir, base = "") {
+    const files = new Set;
+    if (!existsSync4(dir))
+      return files;
+    for (const entry of readdirSync3(dir)) {
+      const full = join4(dir, entry);
+      const rel = base ? `${base}/${entry}` : entry;
+      if (statSync2(full).isDirectory()) {
+        for (const f of collectFiles(full, rel))
+          files.add(f);
+      } else {
+        files.add(rel);
+      }
+    }
+    return files;
+  }
+  const updateResults = [];
+  for (const name of toUpdate) {
+    const skillName = normalizeSkillName(name);
+    const destPath = join4(process.cwd(), ".skills", skillName);
+    const beforeFiles = collectFiles(destPath);
+    const result = installSkill(name, { overwrite: true });
+    const afterFiles = collectFiles(destPath);
+    const newFiles = [...afterFiles].filter((f) => !beforeFiles.has(f));
+    const removedFiles = [...beforeFiles].filter((f) => !afterFiles.has(f));
+    const unchangedCount = [...afterFiles].filter((f) => beforeFiles.has(f)).length;
+    updateResults.push({
+      skill: result.skill,
+      success: result.success,
+      error: result.error,
+      newFiles,
+      removedFiles,
+      unchangedCount
+    });
+  }
   if (options.json) {
-    console.log(JSON.stringify(results, null, 2));
+    console.log(JSON.stringify(updateResults, null, 2));
   } else {
     console.log(chalk2.bold(`
 Updating skills...
 `));
-    for (const result of results) {
+    for (const result of updateResults) {
       if (result.success) {
         console.log(chalk2.green(`\u2713 ${result.skill}`));
+        if (result.newFiles.length > 0) {
+          console.log(chalk2.green(`    + ${result.newFiles.length} new file(s): ${result.newFiles.join(", ")}`));
+        }
+        if (result.removedFiles.length > 0) {
+          console.log(chalk2.red(`    - ${result.removedFiles.length} removed file(s): ${result.removedFiles.join(", ")}`));
+        }
+        console.log(chalk2.dim(`    ${result.unchangedCount} file(s) updated`));
       } else {
         console.log(chalk2.red(`\u2717 ${result.skill}: ${result.error}`));
       }
@@ -36618,7 +36852,7 @@ Updating skills...
     console.log(chalk2.dim(`
 Skills updated in .skills/`));
   }
-  if (results.some((r) => !r.success)) {
+  if (updateResults.some((r) => !r.success)) {
     process.exitCode = 1;
   }
 });
@@ -36681,9 +36915,266 @@ Add to ${configPath} mcpServers:`));
   }
   await Promise.resolve().then(() => (init_mcp2(), exports_mcp));
 });
-program2.command("serve").description("Start the Skills Dashboard web server").option("-p, --port <port>", "Port number", "3579").option("--no-open", "Don't open browser automatically").action(async (options) => {
+program2.command("serve").description("Start the Skills Dashboard web server").option("-p, --port <port>", "Port number (0 = auto-assign free port)", "0").option("--no-open", "Don't open browser automatically").action(async (options) => {
   const { startServer: startServer2 } = await Promise.resolve().then(() => (init_serve(), exports_serve));
   const port = parseInt(options.port, 10);
   await startServer2(port, { open: options.open });
 });
+program2.command("self-update").description(`Update ${package_default.name} to the latest version`).action(async () => {
+  console.log(chalk2.bold(`
+Updating ${package_default.name}...
+`));
+  const proc = Bun.spawn(["bun", "add", "-g", `${package_default.name}@latest`], {
+    stdout: "inherit",
+    stderr: "inherit"
+  });
+  const exitCode = await proc.exited;
+  if (exitCode === 0) {
+    console.log(chalk2.green(`
+\u2713 Updated to latest version`));
+    const vProc = Bun.spawn(["skills", "--version"], { stdout: "pipe" });
+    const ver = (await new Response(vProc.stdout).text()).trim();
+    console.log(chalk2.dim(`  Version: ${ver}`));
+  } else {
+    console.error(chalk2.red(`
+\u2717 Update failed`));
+    process.exitCode = 1;
+  }
+});
+program2.command("completion").argument("<shell>", "Shell type: bash, zsh, or fish").description("Generate shell completions").action((shell) => {
+  const subcommands = [
+    "install",
+    "list",
+    "search",
+    "info",
+    "docs",
+    "requires",
+    "run",
+    "remove",
+    "update",
+    "categories",
+    "mcp",
+    "serve",
+    "init",
+    "self-update",
+    "completion",
+    "outdated"
+  ];
+  const skillNames = SKILLS.map((s) => s.name);
+  const categoryNames = CATEGORIES.map((c) => c);
+  const skillCmds = ["install", "info", "docs", "requires", "run", "remove"];
+  switch (shell) {
+    case "bash": {
+      const script = `# Bash completion for skills CLI
+_skills_completions() {
+  local cur prev subcmds skill_cmds skills categories
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  subcmds="${subcommands.join(" ")}"
+  skill_cmds="${skillCmds.join(" ")}"
+  skills="${skillNames.join(" ")}"
+  categories="${categoryNames.join(" ")}"
+
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "\${subcmds}" -- "\${cur}") )
+    return 0
+  fi
+
+  case "\${prev}" in
+    --category|-c)
+      COMPREPLY=( $(compgen -W "\${categories}" -- "\${cur}") )
+      return 0
+      ;;
+  esac
+
+  for cmd in \${skill_cmds}; do
+    if [[ "\${COMP_WORDS[1]}" == "\${cmd}" && \${COMP_CWORD} -eq 2 ]]; then
+      COMPREPLY=( $(compgen -W "\${skills}" -- "\${cur}") )
+      return 0
+    fi
+  done
+
+  return 0
+}
+complete -F _skills_completions skills
+`;
+      console.log(script);
+      break;
+    }
+    case "zsh": {
+      const script = `#compdef skills
+# Zsh completion for skills CLI
+
+_skills() {
+  local -a subcmds skill_cmds skills categories
+
+  subcmds=(
+${subcommands.map((c) => `    '${c}:${c} command'`).join(`
+`)}
+  )
+
+  skills=(${skillNames.join(" ")})
+  categories=(${categoryNames.map((c) => `'${c.replace(/'/g, "'\\''")}'`).join(" ")})
+
+  skill_cmds=(${skillCmds.join(" ")})
+
+  _arguments -C \\
+    '1:command:->command' \\
+    '*::arg:->args'
+
+  case $state in
+    command)
+      _describe 'skills command' subcmds
+      ;;
+    args)
+      case \${words[1]} in
+        ${skillCmds.join("|")})
+          _describe 'skill' skills
+          ;;
+        list|search)
+          _arguments '--category[Filter by category]:category:($categories)'
+          ;;
+        completion)
+          _describe 'shell' '(bash zsh fish)'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_skills "$@"
+`;
+      console.log(script);
+      break;
+    }
+    case "fish": {
+      const lines = [
+        "# Fish completion for skills CLI",
+        "",
+        "# Disable file completions by default",
+        "complete -c skills -f",
+        "",
+        "# Subcommands"
+      ];
+      for (const cmd of subcommands) {
+        lines.push(`complete -c skills -n '__fish_use_subcommand' -a '${cmd}' -d '${cmd} command'`);
+      }
+      lines.push("");
+      lines.push("# Skill names for relevant subcommands");
+      for (const cmd of skillCmds) {
+        for (const name of skillNames) {
+          lines.push(`complete -c skills -n '__fish_seen_subcommand_from ${cmd}' -a '${name}'`);
+        }
+      }
+      lines.push("");
+      lines.push("# Category completions for --category flag");
+      for (const cat of categoryNames) {
+        lines.push(`complete -c skills -l category -s c -a '${cat}' -d 'Category'`);
+      }
+      console.log(lines.join(`
+`));
+      break;
+    }
+    default:
+      console.error(`Unknown shell: ${shell}. Supported: bash, zsh, fish`);
+      process.exitCode = 1;
+  }
+});
+program2.command("doctor").option("--json", "Output as JSON", false).description("Check environment variables for installed skills").action((options) => {
+  const installed = getInstalledSkills();
+  if (installed.length === 0) {
+    if (options.json) {
+      console.log(JSON.stringify({ skills: [], message: "No skills installed" }));
+    } else {
+      console.log("No skills installed");
+    }
+    return;
+  }
+  const report = [];
+  for (const name of installed) {
+    const reqs = getSkillRequirements(name);
+    const envVars = (reqs?.envVars ?? []).map((v) => ({
+      name: v,
+      set: !!process.env[v]
+    }));
+    report.push({ skill: name, envVars });
+  }
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  console.log(chalk2.bold(`
+Skills Doctor (${installed.length} installed):
+`));
+  for (const entry of report) {
+    console.log(chalk2.bold(`  ${entry.skill}`));
+    if (entry.envVars.length === 0) {
+      console.log(chalk2.dim("    No environment variables required"));
+    } else {
+      for (const v of entry.envVars) {
+        const status = v.set ? chalk2.green("set") : chalk2.red("missing");
+        console.log(`    ${v.name} [${status}]`);
+      }
+    }
+  }
+});
+program2.command("outdated").option("--json", "Output as JSON", false).description("Check for outdated installed skills").action((options) => {
+  const installed = getInstalledSkills();
+  if (installed.length === 0) {
+    if (options.json) {
+      console.log(JSON.stringify([]));
+    } else {
+      console.log(chalk2.dim("No skills installed. Run: skills install <name>"));
+    }
+    return;
+  }
+  const cwd = process.cwd();
+  const outdated = [];
+  const upToDate = [];
+  for (const name of installed) {
+    const skillName = normalizeSkillName(name);
+    const installedPkgPath = join4(cwd, ".skills", skillName, "package.json");
+    let installedVersion = "unknown";
+    if (existsSync4(installedPkgPath)) {
+      try {
+        installedVersion = JSON.parse(readFileSync4(installedPkgPath, "utf-8")).version || "unknown";
+      } catch {}
+    }
+    const registryPath = getSkillPath(name);
+    const registryPkgPath = join4(registryPath, "package.json");
+    let registryVersion = "unknown";
+    if (existsSync4(registryPkgPath)) {
+      try {
+        registryVersion = JSON.parse(readFileSync4(registryPkgPath, "utf-8")).version || "unknown";
+      } catch {}
+    }
+    if (installedVersion !== registryVersion) {
+      outdated.push({ skill: name, installedVersion, registryVersion });
+    } else {
+      upToDate.push(name);
+    }
+  }
+  if (options.json) {
+    console.log(JSON.stringify(outdated, null, 2));
+    return;
+  }
+  if (outdated.length === 0) {
+    console.log(chalk2.green(`
+All ${installed.length} installed skill(s) are up to date`));
+    return;
+  }
+  console.log(chalk2.bold(`
+Outdated skills (${outdated.length}):
+`));
+  for (const entry of outdated) {
+    console.log(`  ${chalk2.cyan(entry.skill)}  ${chalk2.red(entry.installedVersion)} \u2192 ${chalk2.green(entry.registryVersion)}`);
+  }
+  if (upToDate.length > 0) {
+    console.log(chalk2.dim(`
+${upToDate.length} skill(s) up to date`));
+  }
+  console.log(chalk2.dim(`
+Run ${chalk2.bold("skills update")} to update all outdated skills`));
+});
 program2.parse();