skillfish 1.0.4 → 1.0.6

package/dist/commands/add.js

@@ -16,6 +16,7 @@ import { EXIT_CODES, isValidName } from '../lib/constants.js';
 export const addCommand = new Command('add')
     .description('Install a skill from a GitHub repository')
     .argument('<repo>', 'GitHub repository (owner/repo or owner/repo/plugin/skill)')
+    .argument('[skill-name]', 'Install a specific skill by name (from SKILL.md frontmatter)')
     .option('--force', 'Overwrite existing skills without prompting')
     .option('-y, --yes', 'Skip all confirmation prompts')
     .option('--all', 'Install all skills found in the repository')
@@ -26,11 +27,12 @@ export const addCommand = new Command('add')
     .addHelpText('after', `
 Examples:
   $ skillfish add owner/repo                  Install from a repository
+  $ skillfish add owner/repo my-skill         Install skill by name
   $ skillfish add owner/repo --all            Install all skills in repo
-  $ skillfish add owner/repo/plugin/skill     Install a specific skill
+  $ skillfish add owner/repo/plugin/skill     Install a specific skill by path
   $ skillfish add owner/repo --path path/to   Install skill at specific path
   $ skillfish add owner/repo --project        Install to current project only`)
-    .action(async (repoArg, options, command) => {
+    .action(async (repoArg, skillNameArg, options, command) => {
     const jsonMode = command.parent?.opts().json ?? false;
     const jsonOutput = createJsonOutput();
     const version = command.parent?.opts().version ?? '0.0.0';
@@ -84,43 +86,43 @@ Examples:
             exitWithError('Invalid --path value. Path must be relative and contain only safe characters.', EXIT_CODES.INVALID_ARGS);
         }
     }
-    // Parse repo format - supports both owner/repo and owner/repo/plugin/skill
+    // Parse repo format - supports owner/repo and owner/repo/path/to/skill
     const parts = repoArg.split('/');
     let owner;
     let repo;
-    if (parts.length === 2) {
-        [owner, repo] = parts;
-    }
-    else if (parts.length === 4) {
-        const [o, r, plugin, skill] = parts;
-        owner = o;
-        repo = r;
-        // Security: validate plugin and skill names
-        if (!isValidName(plugin) || !isValidName(skill)) {
-            exitWithError('Invalid plugin or skill name. Use only alphanumeric characters, dots, hyphens, and underscores.', EXIT_CODES.INVALID_ARGS);
-        }
-        explicitPath = explicitPath || `plugins/${plugin}/skills/${skill}`;
+    if (parts.length < 2) {
+        exitWithError('Invalid format. Use: owner/repo or owner/repo/path/to/skill', EXIT_CODES.INVALID_ARGS);
+    }
+    [owner, repo] = parts;
+    // If path components exist after owner/repo, use them as the skill path
+    if (parts.length > 2) {
+        const pathParts = parts.slice(2);
+        // Security: validate each path component
+        for (const part of pathParts) {
+            if (!isValidName(part)) {
+                exitWithError('Invalid path component. Use only alphanumeric characters, dots, hyphens, and underscores.', EXIT_CODES.INVALID_ARGS);
+            }
+        }
+        explicitPath = explicitPath || pathParts.join('/');
         if (!jsonMode) {
-            console.log(`Installing skill from: ${plugin}/${skill}`);
+            console.log(`Installing skill from: ${explicitPath}`);
         }
     }
-    else {
-        exitWithError('Invalid format. Use: owner/repo or owner/repo/plugin/skill', EXIT_CODES.INVALID_ARGS);
-    }
     // Validate owner/repo (security: prevent injection)
     if (!owner || !repo || !isValidName(owner) || !isValidName(repo)) {
         exitWithError('Invalid repository format. Use: owner/repo', EXIT_CODES.INVALID_ARGS);
     }
     // 1. Discover or select skills
-    const skillPaths = explicitPath
-        ? [explicitPath]
-        : await discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput);
-    if (!skillPaths || skillPaths.length === 0) {
+    const discoveryResult = explicitPath
+        ? { paths: [explicitPath], branch: undefined }
+        : await discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput, skillNameArg);
+    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
@@ -178,6 +180,7 @@ Examples:
         const result = await installSkill(owner, repo, skillPath, skillName, targetAgents, {
             force,
             baseDir,
+            branch: discoveredBranch,
         });
         if (spinner) {
             if (result.failed) {
@@ -224,10 +227,7 @@ Examples:
         totalSkipped += result.skipped.length;
         // Track successful installs (telemetry with timeout)
         if (result.installed.length > 0) {
-            // Construct github value to match skills.github column format: owner/repo/path/to/skill
-            const skillDir = skillPath.replace(/\/?SKILL\.md$/i, '').replace(/^\.?\/?/, '');
-            const github = skillDir ? `${owner}/${repo}/${skillDir}` : `${owner}/${repo}`;
-            telemetryPromises.push(trackInstall(github));
+            telemetryPromises.push(trackInstall(owner, repo, skillName));
         }
     }
     // Wait for telemetry to complete (with timeout built into trackInstall)
@@ -325,10 +325,10 @@ async function selectAgents(agents, isLocal, jsonMode) {
     }
     return agents.filter((a) => selected.includes(a.name));
 }
-async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput) {
-    let skillPaths;
+async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput, targetSkillName) {
+    let skillDiscovery;
     try {
-        skillPaths = await findAllSkillMdFiles(owner, repo);
+        skillDiscovery = await findAllSkillMdFiles(owner, repo);
     }
     catch (err) {
         let errorMsg;
@@ -361,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) {
@@ -382,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,6 +398,47 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput)
     }
     // Store found skills in JSON output
     jsonOutput.skills_found = skills.map((s) => s.name);
+    // If a specific skill name was requested, find and return it
+    if (targetSkillName) {
+        // 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 { paths: [matchedSkill.dir], branch };
+        }
+        // Skill not found - show available skills
+        const errorMsg = `Skill "${targetSkillName}" not found in repository`;
+        if (jsonMode) {
+            jsonOutput.errors.push(errorMsg);
+            jsonOutput.success = false;
+        }
+        else {
+            p.log.error(errorMsg);
+            console.log(`\nAvailable skills in ${owner}/${repo}:`);
+            for (const skill of skills) {
+                const displayName = toTitleCase(skill.name);
+                const desc = skill.description ? pc.dim(` - ${truncate(skill.description, 80)}`) : '';
+                console.log(`  - ${pc.cyan(skill.name)} ${displayName}${desc}`);
+            }
+        }
+        return null;
+    }
     if (skills.length === 1) {
         const skill = skills[0];
         const displayName = toTitleCase(skill.name);
@@ -404,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)
@@ -420,11 +462,11 @@ 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) {
-            jsonOutput.errors.push('Multiple skills found. Use --path or --all to specify which one(s).');
+            jsonOutput.errors.push('Multiple skills found. Specify skill name, use --path, or --all.');
             jsonOutput.success = false;
         }
         else {
@@ -432,9 +474,9 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput)
             for (const skill of skills) {
                 const displayName = toTitleCase(skill.name);
                 const desc = skill.description ? pc.dim(` - ${truncate(skill.description, 80)}`) : '';
-                console.log(`  - ${displayName}${desc}`);
+                console.log(`  - ${pc.cyan(skill.name)} ${displayName}${desc}`);
             }
-            console.error('\nMultiple skills found. Use --path or --all to specify which one(s) (non-interactive mode).');
+            console.error('\nMultiple skills found. Specify skill name, use --path, or --all (non-interactive mode).');
         }
         return null;
     }
@@ -448,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/dist/telemetry.d.ts

@@ -2,7 +2,9 @@
  * Track a skill install. Returns a promise that resolves when the request
  * completes (or times out). Never rejects.
  *
- * @param github Full GitHub path (e.g., owner/repo/path/to/skill)
+ * @param owner GitHub repository owner
+ * @param repo GitHub repository name
+ * @param skillName Name of the skill being installed
  * @returns Promise that resolves when telemetry is sent (or times out)
  */
-export declare function trackInstall(github: string): Promise<void>;
+export declare function trackInstall(owner: string, repo: string, skillName: string): Promise<void>;

package/dist/telemetry.js

@@ -1,34 +1,39 @@
 const TELEMETRY_URL = 'https://mcpmarket.com/api/telemetry';
 /** Timeout for telemetry requests (ms) */
-const TELEMETRY_TIMEOUT = 2000;
+const TELEMETRY_TIMEOUT = 5000;
 /**
  * Track a skill install. Returns a promise that resolves when the request
  * completes (or times out). Never rejects.
  *
- * @param github Full GitHub path (e.g., owner/repo/path/to/skill)
+ * @param owner GitHub repository owner
+ * @param repo GitHub repository name
+ * @param skillName Name of the skill being installed
  * @returns Promise that resolves when telemetry is sent (or times out)
  */
-export function trackInstall(github) {
+export function trackInstall(owner, repo, skillName) {
     try {
         if (process.env.DO_NOT_TRACK === '1' || process.env.CI === 'true') {
             return Promise.resolve();
         }
-        if (!github || github.length > 500) {
+        if (!owner || !repo || !skillName) {
             return Promise.resolve();
         }
-        // Race between the fetch and a timeout to ensure we don't block the CLI
-        const fetchPromise = fetch(TELEMETRY_URL, {
+        // Use AbortController to properly timeout the request
+        // This ensures the fetch actually completes (or aborts) before we return
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT);
+        const body = JSON.stringify({ owner, repo, skillName });
+        return fetch(TELEMETRY_URL, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ github }),
-        }).then(() => { }).catch(() => { });
-        const timeoutPromise = new Promise((resolve) => {
-            setTimeout(resolve, TELEMETRY_TIMEOUT);
-        });
-        return Promise.race([fetchPromise, timeoutPromise]);
+            body,
+            signal: controller.signal,
+        })
+            .then(() => { })
+            .catch(() => { })
+            .finally(() => clearTimeout(timeoutId));
     }
     catch {
-        // Telemetry should never throw
         return Promise.resolve();
     }
 }

package/package.json

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