skillhub 0.1.12 → 0.1.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SkillHub Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.js

@@ -26,11 +26,13 @@ import https from "https";
 import http from "http";
 var API_BASE_URL = process.env.SKILLHUB_API_URL || "https://skills.palebluedot.live/api";
 var API_TIMEOUT = parseInt(process.env.SKILLHUB_API_TIMEOUT || "10000");
+var API_FILES_TIMEOUT = parseInt(process.env.SKILLHUB_API_FILES_TIMEOUT || "45000");
 function httpsRequest(url, options = {}) {
   return new Promise((resolve, reject) => {
     const parsedUrl = new URL(url);
     const isHttps = parsedUrl.protocol === "https:";
     const lib = isHttps ? https : http;
+    const requestTimeout = options.timeout || API_TIMEOUT;
     const reqOptions = {
       hostname: parsedUrl.hostname,
       port: parsedUrl.port || (isHttps ? 443 : 80),
@@ -41,7 +43,7 @@ function httpsRequest(url, options = {}) {
         "Accept": "application/json",
         ...options.headers
       },
-      timeout: API_TIMEOUT
+      timeout: requestTimeout
     };
     const req = lib.request(reqOptions, (res) => {
       const chunks = [];
@@ -74,10 +76,10 @@ function httpsRequest(url, options = {}) {
           });
         }
       });
-      res.setTimeout(API_TIMEOUT, () => {
+      res.setTimeout(requestTimeout, () => {
         if (!resolved) {
           res.destroy();
-          reject(new Error(`Response timeout after ${API_TIMEOUT / 1e3}s`));
+          reject(new Error(`Response timeout after ${requestTimeout / 1e3}s`));
         }
       });
     });
@@ -87,7 +89,7 @@ function httpsRequest(url, options = {}) {
     });
     req.on("timeout", () => {
       req.destroy();
-      reject(new Error(`Request timeout after ${API_TIMEOUT / 1e3}s`));
+      reject(new Error(`Request timeout after ${requestTimeout / 1e3}s`));
     });
     if (options.body) {
       req.write(options.body);
@@ -99,7 +101,8 @@ async function searchSkills(query, options = {}) {
   const params = new URLSearchParams({
     q: query,
     limit: String(options.limit || 10),
-    page: String(options.page || 1)
+    page: String(options.page || 1),
+    sort: options.sort || "downloads"
   });
   if (options.platform) {
     params.set("platform", options.platform);
@@ -131,6 +134,23 @@ async function trackInstall(skillId, platform, method = "cli") {
   } catch {
   }
 }
+async function getSkillFiles(id) {
+  try {
+    const response = await httpsRequest(
+      `${API_BASE_URL}/skill-files?id=${encodeURIComponent(id)}`,
+      { timeout: API_FILES_TIMEOUT }
+    );
+    if (response.statusCode === 404) {
+      return null;
+    }
+    if (response.statusCode !== 200) {
+      return null;
+    }
+    return JSON.parse(response.data);
+  } catch {
+    return null;
+  }
+}
 
 // src/utils/github.ts
 import { Octokit } from "@octokit/rest";
@@ -343,20 +363,49 @@ async function install(skillId, options) {
       process.exit(1);
     }
     await ensureSkillsDir(options.platform, options.project);
-    spinner.text = `Downloading from ${owner}/${repo}/${skillPath || ""}...`;
+    spinner.text = `Downloading ${skillInfo?.name || skillId}...`;
     let content;
-    try {
-      content = await fetchSkillContent(owner, repo, skillPath, branch);
-      spinner.text = `Downloaded ${content.scripts.length} scripts, ${content.references.length} references`;
-    } catch (error) {
-      spinner.fail("Failed to download skill files");
-      console.error(chalk.red(error.message));
-      console.log();
-      console.log(chalk.yellow("Troubleshooting tips:"));
-      console.log(chalk.dim("  1. Check your internet connection"));
-      console.log(chalk.dim("  2. If behind a proxy, configure HTTP_PROXY/HTTPS_PROXY environment variables"));
-      console.log(chalk.dim("  3. Try again in a few minutes (GitHub API might be rate-limited)"));
-      console.log(chalk.dim("  4. Set GITHUB_TOKEN environment variable for higher rate limits"));
+    let apiWasReachable = false;
+    if (!options.noApi && skillInfo) {
+      apiWasReachable = true;
+      try {
+        spinner.text = "Downloading skill files...";
+        const cachedFiles = await getSkillFiles(skillInfo.id);
+        if (cachedFiles && cachedFiles.files.length > 0) {
+          content = convertCachedFilesToSkillContent(cachedFiles);
+          spinner.text = cachedFiles.fromCache ? `Using cached files (${cachedFiles.files.length} files)` : `Downloaded ${cachedFiles.files.length} files via API`;
+        }
+      } catch {
+        spinner.text = "API file fetch failed, falling back to GitHub...";
+      }
+    }
+    if (!content) {
+      if (apiWasReachable) {
+        spinner.text = `Falling back to GitHub: ${owner}/${repo}/${skillPath || ""}...`;
+      } else {
+        spinner.text = `Downloading from GitHub: ${owner}/${repo}/${skillPath || ""}...`;
+      }
+      try {
+        content = await fetchSkillContent(owner, repo, skillPath, branch);
+        spinner.text = `Downloaded ${content.scripts.length} scripts, ${content.references.length} references`;
+      } catch (error) {
+        spinner.fail("Failed to download skill files");
+        console.error(chalk.red(error.message));
+        console.log();
+        console.log(chalk.yellow("Troubleshooting tips:"));
+        console.log(chalk.dim("  1. Check your internet connection"));
+        if (apiWasReachable) {
+          console.log(chalk.dim("  2. The API server could not fetch files either - try again in a minute"));
+          console.log(chalk.dim("  3. The server may be caching the files now - retry shortly"));
+        } else {
+          console.log(chalk.dim("  2. If behind a proxy, configure HTTP_PROXY/HTTPS_PROXY environment variables"));
+        }
+        console.log(chalk.dim(`  ${apiWasReachable ? "4" : "3"}. Set GITHUB_TOKEN environment variable for higher rate limits`));
+        process.exit(1);
+      }
+    }
+    if (!content) {
+      spinner.fail("Failed to download skill content");
       process.exit(1);
     }
     const parsed = parseSkillMd(content.skillMd);
@@ -453,6 +502,37 @@ function getPlatformName(platform) {
   };
   return names[platform];
 }
+function convertCachedFilesToSkillContent(response) {
+  let skillMd = "";
+  const scripts = [];
+  const references = [];
+  for (const file of response.files) {
+    if (!file.content) continue;
+    if (file.name === "SKILL.md" && (file.path === "SKILL.md" || file.path === file.name)) {
+      skillMd = file.content;
+      continue;
+    }
+    if (file.path.startsWith("scripts/")) {
+      scripts.push({
+        name: file.name,
+        content: file.content
+      });
+      continue;
+    }
+    if (file.path.startsWith("references/")) {
+      references.push({
+        name: file.name,
+        content: file.content
+      });
+    }
+  }
+  return {
+    skillMd,
+    scripts,
+    references,
+    assets: []
+  };
+}
 
 // src/commands/search.ts
 import chalk2 from "chalk";
@@ -461,9 +541,13 @@ async function search(query, options) {
   const spinner = ora2("Searching skills...").start();
   try {
     const limit = parseInt(options.limit || "10");
+    const page = parseInt(options.page || "1");
+    const sort = options.sort || "downloads";
     const result = await searchSkills(query, {
       platform: options.platform,
-      limit
+      limit,
+      page,
+      sort
     });
     spinner.stop();
     if (result.skills.length === 0) {
@@ -471,35 +555,43 @@ async function search(query, options) {
       console.log(chalk2.dim("Try a different search term or check the spelling."));
       return;
     }
-    console.log(chalk2.bold(`Found ${result.pagination.total} skills:
+    const sortLabel = { downloads: "downloads", stars: "GitHub stars", rating: "rating", recent: "recently updated" }[sort] || sort;
+    console.log(chalk2.bold(`Found ${result.pagination.total} skills (sorted by ${sortLabel}):
 `));
     console.log(
       chalk2.dim("\u2500".repeat(80))
     );
-    for (const skill of result.skills) {
+    const startIndex = (page - 1) * limit;
+    for (let i = 0; i < result.skills.length; i++) {
+      const skill = result.skills[i];
+      const num = chalk2.dim(`[${startIndex + i + 1}]`);
       const verified = skill.isVerified ? chalk2.green("\u2713") : " ";
       const security = skill.securityStatus ? getSecurityStatusBadge(skill.securityStatus) : getSecurityBadge(skill.securityScore);
       console.log(
-        `${verified} ${chalk2.cyan(skill.id.padEnd(40))} ${security}  \u2B50 ${formatNumber(skill.githubStars).padStart(6)}  \u2B07 ${formatNumber(skill.downloadCount).padStart(6)}`
+        `${num} ${verified} ${chalk2.cyan(skill.id.padEnd(38))} ${security}`
       );
       console.log(
-        `  ${chalk2.dim(skill.description.slice(0, 70))}${skill.description.length > 70 ? "..." : ""}`
+        `     \u2B07 ${formatNumber(skill.downloadCount).padStart(6)}  \u2B50 ${formatNumber(skill.githubStars).padStart(6)}  ${chalk2.dim(skill.description.slice(0, 55))}${skill.description.length > 55 ? "..." : ""}`
       );
       const showRating = (skill.ratingCount ?? 0) >= 3;
       if (showRating && skill.rating) {
         console.log(
-          `  ${chalk2.yellow("\u2605")} ${skill.rating.toFixed(1)} ${chalk2.dim(`(${skill.ratingCount} ratings)`)}`
+          `     ${chalk2.yellow("\u2605")} ${skill.rating.toFixed(1)} ${chalk2.dim(`(${skill.ratingCount} ratings)`)}`
         );
       }
       console.log(chalk2.dim("\u2500".repeat(80)));
     }
     console.log();
     console.log(chalk2.dim(`Install with: ${chalk2.white("npx skillhub install <skill-id>")}`));
-    if (result.pagination.total > result.skills.length) {
+    const totalPages = result.pagination.totalPages;
+    if (totalPages > 1) {
       console.log(
-        chalk2.dim(`Showing ${result.skills.length} of ${result.pagination.total}. Use --limit to see more.`)
+        chalk2.dim(`Page ${page} of ${totalPages}. Use ${chalk2.white(`--page ${page + 1}`)} for next page.`)
       );
     }
+    if (sort === "downloads") {
+      console.log(chalk2.dim(`Sort options: ${chalk2.white("--sort stars|rating|recent")}`));
+    }
   } catch (error) {
     spinner.fail("Search failed");
     const err = error;
@@ -720,7 +812,7 @@ program.command("install <skill-id>").description("Install a skill from the regi
     // Commander converts --no-api to api: false
   });
 });
-program.command("search <query>").description("Search for skills in the registry").option("-p, --platform <platform>", "Filter by platform").option("-l, --limit <number>", "Number of results", "10").action(async (query, options) => {
+program.command("search <query>").description("Search for skills in the registry").option("-p, --platform <platform>", "Filter by platform").option("-s, --sort <sort>", "Sort by: downloads, stars, rating, recent", "downloads").option("-l, --limit <number>", "Number of results", "10").option("--page <number>", "Page number", "1").action(async (query, options) => {
   await search(query, options);
 });
 program.command("list").description("List installed skills").option("-p, --platform <platform>", "Filter by platform").option("--project", "List skills in the current project").option("--all", "List both global and project skills").action(async (options) => {

package/package.json

@@ -1,59 +1,59 @@
-{
-  "name": "skillhub",
-  "version": "0.1.12",
-  "description": "CLI tool for managing AI Agent skills - search, install, and update skills for Claude, Codex, Copilot, and more",
-  "author": "SkillHub Contributors",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/anthropics/skillhub.git",
-    "directory": "apps/cli"
-  },
-  "homepage": "https://skills.palebluedot.live",
-  "type": "module",
-  "bin": {
-    "skillhub": "./dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --target node20 --clean",
-    "dev": "tsx src/index.ts",
-    "start": "node dist/index.js",
-    "lint": "eslint src/",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest",
-    "test:run": "vitest run"
-  },
-  "dependencies": {
-    "skillhub-core": "^0.1.0",
-    "@octokit/rest": "^20.0.2",
-    "chalk": "^5.3.0",
-    "commander": "^11.1.0",
-    "fs-extra": "^11.2.0",
-    "ora": "^8.0.1",
-    "prompts": "^2.4.2"
-  },
-  "devDependencies": {
-    "@types/fs-extra": "^11.0.4",
-    "@types/node": "^20.10.0",
-    "@types/prompts": "^2.4.9",
-    "tsup": "^8.0.1",
-    "tsx": "^4.7.0",
-    "typescript": "^5.3.0",
-    "vitest": "^1.2.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "keywords": [
-    "ai",
-    "agent",
-    "skills",
-    "cli",
-    "claude",
-    "codex",
-    "copilot"
-  ]
-}
+{
+  "name": "skillhub",
+  "version": "0.1.14",
+  "description": "CLI tool for managing AI Agent skills - search, install, and update skills for Claude, Codex, Copilot, and more",
+  "author": "SkillHub Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/skillhub.git",
+    "directory": "apps/cli"
+  },
+  "homepage": "https://skills.palebluedot.live",
+  "type": "module",
+  "bin": {
+    "skillhub": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "skillhub-core": "^0.1.0",
+    "@octokit/rest": "^20.0.2",
+    "chalk": "^5.3.0",
+    "commander": "^11.1.0",
+    "fs-extra": "^11.2.0",
+    "ora": "^8.0.1",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^20.10.0",
+    "@types/prompts": "^2.4.9",
+    "tsup": "^8.0.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "skills",
+    "cli",
+    "claude",
+    "codex",
+    "copilot"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --target node20 --clean",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run"
+  }
+}