skillfish 1.0.5 → 1.0.6

package/dist/commands/add.js

@@ -113,15 +113,16 @@ Examples:
         exitWithError('Invalid repository format. Use: owner/repo', EXIT_CODES.INVALID_ARGS);
     }
     // 1. Discover or select skills
-    const skillPaths = explicitPath
-        ? [explicitPath]
+    const discoveryResult = explicitPath
+        ? { paths: [explicitPath], branch: undefined }
         : await discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput, skillNameArg);
-    if (!skillPaths || skillPaths.length === 0) {
+    if (!discoveryResult || discoveryResult.paths.length === 0) {
         if (jsonMode) {
             outputJsonAndExit(EXIT_CODES.NOT_FOUND);
         }
         process.exit(EXIT_CODES.NOT_FOUND);
     }
+    const { paths: skillPaths, branch: discoveredBranch } = discoveryResult;
     // 2. Determine install location (global vs project)
     const baseDir = await selectInstallLocation(projectFlag, globalFlag, jsonMode);
     // 3. Select agents to install to
@@ -179,6 +180,7 @@ Examples:
         const result = await installSkill(owner, repo, skillPath, skillName, targetAgents, {
             force,
             baseDir,
+            branch: discoveredBranch,
         });
         if (spinner) {
             if (result.failed) {
@@ -324,9 +326,9 @@ async function selectAgents(agents, isLocal, jsonMode) {
     return agents.filter((a) => selected.includes(a.name));
 }
 async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput, targetSkillName) {
-    let skillPaths;
+    let skillDiscovery;
     try {
-        skillPaths = await findAllSkillMdFiles(owner, repo);
+        skillDiscovery = await findAllSkillMdFiles(owner, repo);
     }
     catch (err) {
         let errorMsg;
@@ -359,6 +361,7 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
         }
         process.exit(exitCode);
     }
+    const { paths: skillPaths, branch } = skillDiscovery;
     if (skillPaths.length === 0) {
         const errorMsg = `No ${SKILL_FILENAME} found in repository`;
         if (jsonMode) {
@@ -380,8 +383,8 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
     const skills = await batchMap(skillPaths, async (sp) => {
         const skillDir = sp === SKILL_FILENAME ? '.' : dirname(sp);
         const folderName = sp === SKILL_FILENAME ? repo : basename(skillDir);
-        // Fetch raw content to parse frontmatter
-        const content = await fetchSkillMdContent(owner, repo, sp);
+        // Fetch raw content to parse frontmatter (use discovered branch)
+        const content = await fetchSkillMdContent(owner, repo, sp, branch);
         const frontmatter = content ? parseFrontmatter(content) : {};
         return {
             path: sp,
@@ -397,15 +400,27 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
     jsonOutput.skills_found = skills.map((s) => s.name);
     // If a specific skill name was requested, find and return it
     if (targetSkillName) {
-        const normalizedTarget = targetSkillName.toLowerCase();
-        const matchedSkill = skills.find((s) => s.name.toLowerCase() === normalizedTarget);
+        // Normalize for flexible matching: lowercase, replace spaces/underscores with hyphens
+        const normalize = (s) => s.toLowerCase().replace(/[\s_]+/g, '-');
+        const normalizedTarget = normalize(targetSkillName);
+        // Try multiple matching strategies
+        const matchedSkill = skills.find((s) => {
+            const normalizedName = normalize(s.name);
+            const normalizedDir = normalize(s.dir);
+            const dirBasename = normalize(s.dir.split('/').pop() || '');
+            return (normalizedName === normalizedTarget || // Exact name match (normalized)
+                normalizedDir === normalizedTarget || // Exact dir match
+                dirBasename === normalizedTarget || // Directory basename match
+                s.name.toLowerCase() === targetSkillName.toLowerCase() // Original case-insensitive
+            );
+        });
         if (matchedSkill) {
             const displayName = toTitleCase(matchedSkill.name);
             const desc = matchedSkill.description ? truncate(matchedSkill.description, 60) : '';
             if (!jsonMode) {
                 p.log.info(`${pc.bold(displayName)}${desc ? pc.dim(` - ${desc}`) : ''}`);
             }
-            return [matchedSkill.dir];
+            return { paths: [matchedSkill.dir], branch };
         }
         // Skill not found - show available skills
         const errorMsg = `Skill "${targetSkillName}" not found in repository`;
@@ -431,7 +446,7 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
         if (!jsonMode) {
             p.log.info(`${pc.bold(displayName)}${desc ? pc.dim(` - ${desc}`) : ''}`);
         }
-        return [skill.dir];
+        return { paths: [skill.dir], branch };
     }
     // Build options for selection with frontmatter metadata
     // Title in label, description in hint (shows on focus)
@@ -447,7 +462,7 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
             if (!jsonMode) {
                 console.log(`Installing all ${skills.length} skills`);
             }
-            return skills.map((s) => s.dir);
+            return { paths: skills.map((s) => s.dir), branch };
         }
         // Otherwise, list skills and exit with guidance
         if (jsonMode) {
@@ -475,7 +490,7 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
         p.cancel('Cancelled');
         process.exit(EXIT_CODES.SUCCESS);
     }
-    return selected;
+    return { paths: selected, branch };
 }
 /**
  * SECURITY: Show warning and ask for user confirmation before installing.

package/dist/lib/github.d.ts

@@ -2,6 +2,13 @@
  * GitHub API functions for skill discovery and fetching.
  */
 export declare const SKILL_FILENAME = "SKILL.md";
+/**
+ * Result of skill discovery including branch information.
+ */
+export interface SkillDiscoveryResult {
+    paths: string[];
+    branch: string;
+}
 /**
  * Thrown when GitHub API rate limit is exceeded.
  */
@@ -29,6 +36,15 @@ export declare class NetworkError extends Error {
 export declare class GitHubApiError extends Error {
     constructor(message: string);
 }
+/**
+ * Fetch the default branch name for a repository.
+ * Uses the GitHub repos API which returns repository metadata including default_branch.
+ *
+ * @throws {RepoNotFoundError} When the repository is not found
+ * @throws {RateLimitError} When GitHub API rate limit is exceeded
+ * @throws {NetworkError} On network errors
+ */
+export declare function fetchDefaultBranch(owner: string, repo: string): Promise<string>;
 /**
  * Fetch with retry and exponential backoff.
  * Retries on network errors and 5xx responses.
@@ -37,16 +53,16 @@ export declare function fetchWithRetry(url: string, options: RequestInit, maxRet
 /**
  * Fetch raw SKILL.md content from GitHub.
  * Uses raw.githubusercontent.com which is not rate-limited like the API.
- * Tries both main and master branches in parallel for better performance.
  */
-export declare function fetchSkillMdContent(owner: string, repo: string, path: string): Promise<string | null>;
+export declare function fetchSkillMdContent(owner: string, repo: string, path: string, branch: string): Promise<string | null>;
 /**
  * Find all SKILL.md files in a GitHub repository.
- * Uses sequential branch checking to conserve API rate limit (60/hr unauthenticated).
+ * Fetches the default branch, then searches for skills on that branch.
  *
+ * @returns SkillDiscoveryResult with paths and the branch they were found on
  * @throws {RateLimitError} When GitHub API rate limit is exceeded
  * @throws {RepoNotFoundError} When the repository is not found
  * @throws {NetworkError} On network errors (timeout, connection refused)
  * @throws {GitHubApiError} When the API response format is unexpected
  */
-export declare function findAllSkillMdFiles(owner: string, repo: string): Promise<string[]>;
+export declare function findAllSkillMdFiles(owner: string, repo: string): Promise<SkillDiscoveryResult>;

package/dist/lib/github.js

@@ -6,7 +6,6 @@ import { isGitTreeResponse, extractSkillPaths, sleep } from '../utils.js';
 const API_TIMEOUT_MS = 10000;
 const MAX_RETRIES = 3;
 const RETRY_DELAYS_MS = [1000, 2000, 4000]; // Exponential backoff
-const DEFAULT_BRANCHES = ['main', 'master'];
 export const SKILL_FILENAME = 'SKILL.md';
 // === Error Types ===
 /**
@@ -51,7 +50,76 @@ export class GitHubApiError extends Error {
         this.name = 'GitHubApiError';
     }
 }
+// === Helper Functions ===
+/**
+ * Check if a response indicates rate limiting and throw RateLimitError if so.
+ * @throws {RateLimitError} When rate limit is exceeded
+ */
+function checkRateLimit(res) {
+    if (res.status === 403) {
+        const remaining = res.headers.get('X-RateLimit-Remaining');
+        if (remaining === '0') {
+            const resetHeader = res.headers.get('X-RateLimit-Reset');
+            const resetTime = resetHeader ? new Date(parseInt(resetHeader) * 1000) : undefined;
+            throw new RateLimitError(resetTime);
+        }
+    }
+}
+/**
+ * Wrap unknown errors in appropriate typed errors.
+ * Re-throws known error types, wraps others in NetworkError.
+ * @throws {RateLimitError | RepoNotFoundError | GitHubApiError | NetworkError}
+ */
+function wrapApiError(err) {
+    // Re-throw known error types
+    if (err instanceof RateLimitError ||
+        err instanceof RepoNotFoundError ||
+        err instanceof GitHubApiError) {
+        throw err;
+    }
+    // Handle timeout errors
+    if (err instanceof Error && err.name === 'AbortError') {
+        throw new NetworkError('Request timed out. Check your network connection.');
+    }
+    // Wrap unknown errors as NetworkError
+    throw new NetworkError(`Network error: ${err instanceof Error ? err.message : 'unknown error'}`);
+}
 // === Functions ===
+/**
+ * Fetch the default branch name for a repository.
+ * Uses the GitHub repos API which returns repository metadata including default_branch.
+ *
+ * @throws {RepoNotFoundError} When the repository is not found
+ * @throws {RateLimitError} When GitHub API rate limit is exceeded
+ * @throws {NetworkError} On network errors
+ */
+export async function fetchDefaultBranch(owner, repo) {
+    const headers = { 'User-Agent': 'skillfish' };
+    const url = `https://api.github.com/repos/${owner}/${repo}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), API_TIMEOUT_MS);
+    try {
+        const res = await fetchWithRetry(url, { headers, signal: controller.signal });
+        checkRateLimit(res);
+        if (res.status === 404) {
+            throw new RepoNotFoundError(owner, repo);
+        }
+        if (!res.ok) {
+            throw new GitHubApiError(`GitHub API returned status ${res.status}`);
+        }
+        const data = await res.json();
+        if (typeof data.default_branch !== 'string' || !data.default_branch) {
+            throw new GitHubApiError('Repository metadata missing or invalid default_branch field');
+        }
+        return data.default_branch;
+    }
+    catch (err) {
+        wrapApiError(err);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
 /**
  * Fetch with retry and exponential backoff.
  * Retries on network errors and 5xx responses.
@@ -89,30 +157,25 @@ export async function fetchWithRetry(url, options, maxRetries = MAX_RETRIES) {
 /**
  * Fetch raw SKILL.md content from GitHub.
  * Uses raw.githubusercontent.com which is not rate-limited like the API.
- * Tries both main and master branches in parallel for better performance.
  */
-export async function fetchSkillMdContent(owner, repo, path) {
+export async function fetchSkillMdContent(owner, repo, path, branch) {
     const headers = { 'User-Agent': 'skillfish' };
-    // Try both branches in parallel
-    const results = await Promise.allSettled(DEFAULT_BRANCHES.map(async (branch) => {
-        const url = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${path}`;
+    const url = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${path}`;
+    try {
         const res = await fetchWithRetry(url, { headers }, 2);
         if (!res.ok)
-            throw new Error(`HTTP ${res.status}`);
+            return null;
         return res.text();
-    }));
-    // Return first successful result
-    for (const result of results) {
-        if (result.status === 'fulfilled') {
-            return result.value;
-        }
     }
-    return null;
+    catch {
+        return null;
+    }
 }
 /**
  * Find all SKILL.md files in a GitHub repository.
- * Uses sequential branch checking to conserve API rate limit (60/hr unauthenticated).
+ * Fetches the default branch, then searches for skills on that branch.
  *
+ * @returns SkillDiscoveryResult with paths and the branch they were found on
  * @throws {RateLimitError} When GitHub API rate limit is exceeded
  * @throws {RepoNotFoundError} When the repository is not found
  * @throws {NetworkError} On network errors (timeout, connection refused)
@@ -120,64 +183,26 @@ export async function fetchSkillMdContent(owner, repo, path) {
  */
 export async function findAllSkillMdFiles(owner, repo) {
     const headers = { 'User-Agent': 'skillfish' };
+    // Get the default branch
+    const branch = await fetchDefaultBranch(owner, repo);
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), API_TIMEOUT_MS);
     try {
-        // Try each branch sequentially to conserve rate limit
-        for (const branch of DEFAULT_BRANCHES) {
-            const url = `https://api.github.com/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`;
-            try {
-                const res = await fetchWithRetry(url, { headers, signal: controller.signal });
-                // Check for rate limiting
-                if (res.status === 403) {
-                    const remaining = res.headers.get('X-RateLimit-Remaining');
-                    if (remaining === '0') {
-                        const resetHeader = res.headers.get('X-RateLimit-Reset');
-                        const resetTime = resetHeader ? new Date(parseInt(resetHeader) * 1000) : undefined;
-                        throw new RateLimitError(resetTime);
-                    }
-                }
-                // 404 means branch doesn't exist, try next
-                if (res.status === 404) {
-                    continue;
-                }
-                if (!res.ok) {
-                    continue;
-                }
-                const rawData = await res.json();
-                if (!isGitTreeResponse(rawData)) {
-                    throw new GitHubApiError('Unexpected response format from GitHub API.');
-                }
-                return extractSkillPaths(rawData, SKILL_FILENAME);
-            }
-            catch (err) {
-                // Re-throw typed errors
-                if (err instanceof RateLimitError ||
-                    err instanceof GitHubApiError) {
-                    throw err;
-                }
-                // If this is the last branch, let the error propagate
-                if (branch === DEFAULT_BRANCHES[DEFAULT_BRANCHES.length - 1]) {
-                    throw err;
-                }
-                // Otherwise try next branch
-                continue;
-            }
+        const url = `https://api.github.com/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`;
+        const res = await fetchWithRetry(url, { headers, signal: controller.signal });
+        checkRateLimit(res);
+        if (!res.ok) {
+            throw new GitHubApiError(`GitHub API returned status ${res.status}`);
+        }
+        const rawData = await res.json();
+        if (!isGitTreeResponse(rawData)) {
+            throw new GitHubApiError('Unexpected response format from GitHub API.');
         }
-        // No branch found
-        throw new RepoNotFoundError(owner, repo);
+        const paths = extractSkillPaths(rawData, SKILL_FILENAME);
+        return { paths, branch };
     }
     catch (err) {
-        // Re-throw typed errors
-        if (err instanceof RateLimitError ||
-            err instanceof RepoNotFoundError ||
-            err instanceof GitHubApiError) {
-            throw err;
-        }
-        if (err instanceof Error && err.name === 'AbortError') {
-            throw new NetworkError('Request timed out. Check your network connection.');
-        }
-        throw new NetworkError(`Network error: ${err instanceof Error ? err.message : 'unknown error'}`);
+        wrapApiError(err);
     }
     finally {
         clearTimeout(timeoutId);

package/dist/lib/installer.d.ts

@@ -21,6 +21,8 @@ export interface InstallResult {
 export interface InstallOptions {
     force: boolean;
     baseDir: string;
+    /** Branch to clone from. If not specified, degit will use default branch detection. */
+    branch?: string;
 }
 export interface CopyResult {
     warnings: string[];

package/dist/lib/installer.js

@@ -8,6 +8,18 @@ import { join } from 'path';
 import { randomUUID } from 'crypto';
 import degit from 'degit';
 import { SKILL_FILENAME } from './github.js';
+/**
+ * Validates a branch name for safe use in degit paths.
+ * Git branch names can contain alphanumerics, dots, hyphens, underscores, and slashes.
+ * We explicitly reject '#' which is used as a delimiter in degit syntax.
+ */
+function isValidBranchName(branch) {
+    if (!branch || branch.length > 255)
+        return false;
+    // Allow alphanumerics, dots, hyphens, underscores, and slashes (for feature branches)
+    // Reject anything else, especially '#' which would break degit parsing
+    return /^[\w./-]+$/.test(branch) && !branch.includes('#');
+}
 // === Error Types ===
 /**
  * Thrown when SKILL.md is not found in downloaded content.
@@ -86,13 +98,22 @@ export async function installSkill(owner, repo, skillPath, skillName, agents, op
         warnings: [],
         failed: false,
     };
-    const { force, baseDir } = options;
+    const { force, baseDir, branch } = options;
     const tmpDir = join(homedir(), '.cache', 'skillfish', `${owner}-${repo}-${randomUUID()}`);
     mkdirSync(tmpDir, { recursive: true, mode: 0o700 });
     try {
         // Download skill
+        // Build degit path: owner/repo[/subpath][#branch]
         const downloadPath = skillPath === SKILL_FILENAME ? '' : skillPath;
-        const degitPath = downloadPath ? `${owner}/${repo}/${downloadPath}` : `${owner}/${repo}`;
+        let degitPath = downloadPath ? `${owner}/${repo}/${downloadPath}` : `${owner}/${repo}`;
+        // Append branch if specified (critical for repos with non-standard default branches like 'canary')
+        // Validate branch name to prevent injection attacks via malformed branch names
+        if (branch) {
+            if (!isValidBranchName(branch)) {
+                throw new Error(`Invalid branch name: ${branch}`);
+            }
+            degitPath = `${degitPath}#${branch}`;
+        }
         const emitter = degit(degitPath, { cache: false, force: true });
         await emitter.clone(tmpDir);
         // Validate download
@@ -132,7 +153,17 @@ export async function installSkill(owner, repo, skillPath, skillName, agents, op
             result.failureReason = err.message;
         }
         else {
-            result.failureReason = err instanceof Error ? err.message : String(err);
+            const errMsg = err instanceof Error ? err.message : String(err);
+            // Provide more helpful error messages for common degit failures
+            if (errMsg.includes('could not find commit hash for HEAD')) {
+                result.failureReason = `Could not clone repository. The branch or path may not exist, or there may be a network issue. Tried: ${owner}/${repo}${skillPath !== SKILL_FILENAME ? `/${skillPath}` : ''}`;
+            }
+            else if (errMsg.includes('404')) {
+                result.failureReason = `Repository or path not found: ${owner}/${repo}${skillPath !== SKILL_FILENAME ? `/${skillPath}` : ''}`;
+            }
+            else {
+                result.failureReason = errMsg;
+            }
         }
     }
     finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillfish",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Install AI agent skills from GitHub with a single command",
   "type": "module",
   "bin": {