skillfish 1.0.0

package/dist/lib/agents.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Agent configuration and detection logic.
+ * Supports all agents from the Agent Skills specification: https://agentskills.io
+ */
+/**
+ * Agent configuration - data-driven for easier maintenance.
+ * Detection checks home directory (agent installed globally) and cwd (local project).
+ */
+export type AgentConfig = {
+    readonly name: string;
+    readonly dir: string;
+    readonly homePaths: readonly string[];
+    readonly cwdPaths: readonly string[];
+};
+export declare const AGENT_CONFIGS: readonly AgentConfig[];
+/**
+ * Check if an agent is detected on the system.
+ * Checks home directory paths first, then current working directory paths.
+ */
+export declare function detectAgent(config: AgentConfig, baseDir?: string): boolean;
+/**
+ * Runtime agent type with detect function.
+ */
+export type Agent = {
+    readonly name: string;
+    readonly dir: string;
+    readonly detect: () => boolean;
+};
+/**
+ * Build AGENTS array from config (preserves existing API).
+ */
+export declare function buildAgents(baseDir?: string): readonly Agent[];
+/**
+ * Get all detected agents.
+ */
+export declare function getDetectedAgents(baseDir?: string): readonly Agent[];
+/**
+ * Get the skill directory path for an agent.
+ */
+export declare function getAgentSkillDir(agent: Agent | AgentConfig, baseDir: string): string;

package/dist/lib/agents.js

@@ -0,0 +1,146 @@
+/**
+ * Agent configuration and detection logic.
+ * Supports all agents from the Agent Skills specification: https://agentskills.io
+ */
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+export const AGENT_CONFIGS = [
+    // === Primary Agents (widely used) ===
+    {
+        name: 'Claude Code',
+        dir: '.claude/skills',
+        homePaths: ['.claude/settings.json', '.claude/projects.json', '.claude/credentials.json'],
+        cwdPaths: ['.claude'],
+    },
+    {
+        name: 'Cursor',
+        dir: '.cursor/skills',
+        homePaths: ['.cursor/extensions', '.cursor/argv.json'],
+        cwdPaths: ['.cursor'],
+    },
+    {
+        name: 'Windsurf',
+        dir: '.codeium/windsurf/skills',
+        homePaths: ['.codeium/windsurf/config.json', '.codeium/windsurf/argv.json'],
+        cwdPaths: ['.codeium/windsurf'],
+    },
+    {
+        name: 'Codex',
+        dir: '.codex/skills',
+        homePaths: ['.codex/config.json', '.codex/settings.json', '.codex'],
+        cwdPaths: ['.codex'],
+    },
+    {
+        name: 'GitHub Copilot',
+        dir: '.github/skills',
+        homePaths: ['.copilot/config.json', '.copilot'],
+        cwdPaths: ['.github/skills', '.github/copilot-instructions.md'],
+    },
+    {
+        name: 'Gemini CLI',
+        dir: '.gemini/skills',
+        homePaths: ['.gemini'],
+        cwdPaths: ['.gemini'],
+    },
+    {
+        name: 'OpenCode',
+        dir: '.opencode/skills',
+        homePaths: ['.config/opencode', '.opencode'],
+        cwdPaths: ['.opencode'],
+    },
+    {
+        name: 'Goose',
+        dir: '.goose/skills',
+        homePaths: ['.config/goose'],
+        cwdPaths: ['.goose'],
+    },
+    // === Secondary Agents ===
+    {
+        name: 'Amp',
+        dir: '.agents/skills',
+        homePaths: ['.config/amp'],
+        cwdPaths: ['.agents'],
+    },
+    {
+        name: 'Roo Code',
+        dir: '.roo/skills',
+        homePaths: ['.roo'],
+        cwdPaths: ['.roo'],
+    },
+    {
+        name: 'Kiro CLI',
+        dir: '.kiro/skills',
+        homePaths: ['.kiro'],
+        cwdPaths: ['.kiro'],
+    },
+    {
+        name: 'Kilo Code',
+        dir: '.kilocode/skills',
+        homePaths: ['.kilocode'],
+        cwdPaths: ['.kilocode'],
+    },
+    {
+        name: 'Trae',
+        dir: '.trae/skills',
+        homePaths: ['.trae'],
+        cwdPaths: ['.trae'],
+    },
+    {
+        name: 'Cline',
+        dir: '.cline/skills',
+        homePaths: ['.cline/settings.json', '.cline'],
+        cwdPaths: ['.cline'],
+    },
+    // === Additional Agents ===
+    {
+        name: 'Antigravity',
+        dir: '.gemini/antigravity/skills',
+        homePaths: ['.gemini/antigravity'],
+        cwdPaths: ['.agent'],
+    },
+    {
+        name: 'Droid',
+        dir: '.factory/skills',
+        homePaths: ['.factory'],
+        cwdPaths: ['.factory'],
+    },
+    {
+        name: 'Clawdbot',
+        dir: '.clawdbot/skills',
+        homePaths: ['.clawdbot'],
+        cwdPaths: ['.clawdbot'],
+    },
+];
+/**
+ * Check if an agent is detected on the system.
+ * Checks home directory paths first, then current working directory paths.
+ */
+export function detectAgent(config, baseDir) {
+    const home = homedir();
+    const cwd = baseDir ?? process.cwd();
+    return (config.homePaths.some((p) => existsSync(join(home, p))) ||
+        config.cwdPaths.some((p) => existsSync(join(cwd, p))));
+}
+/**
+ * Build AGENTS array from config (preserves existing API).
+ */
+export function buildAgents(baseDir) {
+    return AGENT_CONFIGS.map((config) => ({
+        name: config.name,
+        dir: config.dir,
+        detect: () => detectAgent(config, baseDir),
+    }));
+}
+/**
+ * Get all detected agents.
+ */
+export function getDetectedAgents(baseDir) {
+    return buildAgents(baseDir).filter((a) => a.detect());
+}
+/**
+ * Get the skill directory path for an agent.
+ */
+export function getAgentSkillDir(agent, baseDir) {
+    return join(baseDir, agent.dir);
+}

package/dist/lib/constants.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Shared constants for skillfish CLI.
+ */
+/**
+ * Exit codes for skillfish CLI commands.
+ *
+ * These follow POSIX conventions where 0 is success and non-zero indicates error.
+ * The specific codes help agents and scripts understand failure reasons without
+ * parsing error messages.
+ *
+ * | Code | Constant        | Meaning                                        |
+ * |------|-----------------|------------------------------------------------|
+ * | 0    | SUCCESS         | Command completed successfully                 |
+ * | 1    | GENERAL_ERROR   | Unspecified error (fallback)                   |
+ * | 2    | INVALID_ARGS    | Invalid arguments or options provided          |
+ * | 3    | NETWORK_ERROR   | Network failure (timeout, rate limit, etc.)    |
+ * | 4    | NOT_FOUND       | Requested resource not found (skill, agent)    |
+ */
+export declare const EXIT_CODES: {
+    /** Command completed successfully */
+    readonly SUCCESS: 0;
+    /** Unspecified error (fallback) */
+    readonly GENERAL_ERROR: 1;
+    /** Invalid arguments or options provided */
+    readonly INVALID_ARGS: 2;
+    /** Network failure (timeout, rate limit, etc.) */
+    readonly NETWORK_ERROR: 3;
+    /** Requested resource not found (skill, agent) */
+    readonly NOT_FOUND: 4;
+};
+export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
+/**
+ * Structured error codes for JSON output.
+ * These provide machine-readable error classification for automation.
+ */
+export declare const ERROR_CODES: {
+    /** Invalid arguments or options */
+    readonly INVALID_ARGS: "INVALID_ARGS";
+    /** GitHub API rate limit exceeded */
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    /** Repository not found on GitHub */
+    readonly REPO_NOT_FOUND: "REPO_NOT_FOUND";
+    /** Network timeout or connection error */
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    /** SKILL.md not found in repository */
+    readonly SKILL_NOT_FOUND: "SKILL_NOT_FOUND";
+    /** No agents detected on system */
+    readonly NO_AGENTS: "NO_AGENTS";
+    /** User cancelled the operation */
+    readonly CANCELLED: "CANCELLED";
+    /** File system operation failed */
+    readonly FS_ERROR: "FS_ERROR";
+    /** General/unclassified error */
+    readonly UNKNOWN: "UNKNOWN";
+};
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/**
+ * Pattern for validating safe names (owner, repo, skill, agent names).
+ * Only allows alphanumeric characters, dots, hyphens, and underscores.
+ */
+export declare const SAFE_NAME_PATTERN: RegExp;
+/**
+ * Validates a name against the safe name pattern.
+ */
+export declare function isValidName(name: string): boolean;

package/dist/lib/constants.js

@@ -0,0 +1,68 @@
+/**
+ * Shared constants for skillfish CLI.
+ */
+// === Exit Codes ===
+/**
+ * Exit codes for skillfish CLI commands.
+ *
+ * These follow POSIX conventions where 0 is success and non-zero indicates error.
+ * The specific codes help agents and scripts understand failure reasons without
+ * parsing error messages.
+ *
+ * | Code | Constant        | Meaning                                        |
+ * |------|-----------------|------------------------------------------------|
+ * | 0    | SUCCESS         | Command completed successfully                 |
+ * | 1    | GENERAL_ERROR   | Unspecified error (fallback)                   |
+ * | 2    | INVALID_ARGS    | Invalid arguments or options provided          |
+ * | 3    | NETWORK_ERROR   | Network failure (timeout, rate limit, etc.)    |
+ * | 4    | NOT_FOUND       | Requested resource not found (skill, agent)    |
+ */
+export const EXIT_CODES = {
+    /** Command completed successfully */
+    SUCCESS: 0,
+    /** Unspecified error (fallback) */
+    GENERAL_ERROR: 1,
+    /** Invalid arguments or options provided */
+    INVALID_ARGS: 2,
+    /** Network failure (timeout, rate limit, etc.) */
+    NETWORK_ERROR: 3,
+    /** Requested resource not found (skill, agent) */
+    NOT_FOUND: 4,
+};
+// === Error Codes (for JSON output) ===
+/**
+ * Structured error codes for JSON output.
+ * These provide machine-readable error classification for automation.
+ */
+export const ERROR_CODES = {
+    /** Invalid arguments or options */
+    INVALID_ARGS: 'INVALID_ARGS',
+    /** GitHub API rate limit exceeded */
+    RATE_LIMITED: 'RATE_LIMITED',
+    /** Repository not found on GitHub */
+    REPO_NOT_FOUND: 'REPO_NOT_FOUND',
+    /** Network timeout or connection error */
+    NETWORK_ERROR: 'NETWORK_ERROR',
+    /** SKILL.md not found in repository */
+    SKILL_NOT_FOUND: 'SKILL_NOT_FOUND',
+    /** No agents detected on system */
+    NO_AGENTS: 'NO_AGENTS',
+    /** User cancelled the operation */
+    CANCELLED: 'CANCELLED',
+    /** File system operation failed */
+    FS_ERROR: 'FS_ERROR',
+    /** General/unclassified error */
+    UNKNOWN: 'UNKNOWN',
+};
+// === Name Validation ===
+/**
+ * Pattern for validating safe names (owner, repo, skill, agent names).
+ * Only allows alphanumeric characters, dots, hyphens, and underscores.
+ */
+export const SAFE_NAME_PATTERN = /^[\w.-]+$/;
+/**
+ * Validates a name against the safe name pattern.
+ */
+export function isValidName(name) {
+    return SAFE_NAME_PATTERN.test(name);
+}

package/dist/lib/github.d.ts

@@ -0,0 +1,52 @@
+/**
+ * GitHub API functions for skill discovery and fetching.
+ */
+export declare const SKILL_FILENAME = "SKILL.md";
+/**
+ * Thrown when GitHub API rate limit is exceeded.
+ */
+export declare class RateLimitError extends Error {
+    resetTime?: Date | undefined;
+    constructor(resetTime?: Date | undefined);
+}
+/**
+ * Thrown when the repository is not found.
+ */
+export declare class RepoNotFoundError extends Error {
+    owner: string;
+    repo: string;
+    constructor(owner: string, repo: string);
+}
+/**
+ * Thrown on network errors (timeout, connection refused, etc.).
+ */
+export declare class NetworkError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when GitHub API returns unexpected response format.
+ */
+export declare class GitHubApiError extends Error {
+    constructor(message: string);
+}
+/**
+ * Fetch with retry and exponential backoff.
+ * Retries on network errors and 5xx responses.
+ */
+export declare function fetchWithRetry(url: string, options: RequestInit, maxRetries?: number): Promise<Response>;
+/**
+ * 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>;
+/**
+ * Find all SKILL.md files in a GitHub repository.
+ * Uses sequential branch checking to conserve API rate limit (60/hr unauthenticated).
+ *
+ * @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[]>;

package/dist/lib/github.js

@@ -0,0 +1,185 @@
+/**
+ * GitHub API functions for skill discovery and fetching.
+ */
+import { isGitTreeResponse, extractSkillPaths, sleep } from '../utils.js';
+// === Constants ===
+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 ===
+/**
+ * Thrown when GitHub API rate limit is exceeded.
+ */
+export class RateLimitError extends Error {
+    resetTime;
+    constructor(resetTime) {
+        super(`GitHub API rate limit exceeded${resetTime ? `. Resets at ${resetTime.toISOString()}` : '. Please try again later.'}`);
+        this.resetTime = resetTime;
+        this.name = 'RateLimitError';
+    }
+}
+/**
+ * Thrown when the repository is not found.
+ */
+export class RepoNotFoundError extends Error {
+    owner;
+    repo;
+    constructor(owner, repo) {
+        super(`Repository not found: ${owner}/${repo}. Check the owner/repo name.`);
+        this.owner = owner;
+        this.repo = repo;
+        this.name = 'RepoNotFoundError';
+    }
+}
+/**
+ * Thrown on network errors (timeout, connection refused, etc.).
+ */
+export class NetworkError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NetworkError';
+    }
+}
+/**
+ * Thrown when GitHub API returns unexpected response format.
+ */
+export class GitHubApiError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GitHubApiError';
+    }
+}
+// === Functions ===
+/**
+ * Fetch with retry and exponential backoff.
+ * Retries on network errors and 5xx responses.
+ */
+export async function fetchWithRetry(url, options, maxRetries = MAX_RETRIES) {
+    let lastError = null;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        try {
+            const res = await fetch(url, options);
+            // Success or client error (4xx) - don't retry
+            if (res.ok || (res.status >= 400 && res.status < 500)) {
+                return res;
+            }
+            // Server error (5xx) - retry
+            if (res.status >= 500) {
+                lastError = new Error(`Server error: ${res.status}`);
+                if (attempt < maxRetries - 1) {
+                    await sleep(RETRY_DELAYS_MS[attempt] || 4000);
+                    continue;
+                }
+            }
+            return res;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            // Network error - retry
+            if (attempt < maxRetries - 1) {
+                await sleep(RETRY_DELAYS_MS[attempt] || 4000);
+                continue;
+            }
+        }
+    }
+    throw lastError || new Error('Max retries exceeded');
+}
+/**
+ * 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) {
+    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 res = await fetchWithRetry(url, { headers }, 2);
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        return res.text();
+    }));
+    // Return first successful result
+    for (const result of results) {
+        if (result.status === 'fulfilled') {
+            return result.value;
+        }
+    }
+    return null;
+}
+/**
+ * Find all SKILL.md files in a GitHub repository.
+ * Uses sequential branch checking to conserve API rate limit (60/hr unauthenticated).
+ *
+ * @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 async function findAllSkillMdFiles(owner, repo) {
+    const headers = { 'User-Agent': 'skillfish' };
+    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;
+            }
+        }
+        // No branch found
+        throw new RepoNotFoundError(owner, repo);
+    }
+    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'}`);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}

package/dist/lib/installer.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Skill installation logic.
+ * Handles downloading, validating, and installing skills to agent directories.
+ */
+import type { Agent } from './agents.js';
+export interface InstallResult {
+    installed: Array<{
+        skill: string;
+        agent: string;
+        path: string;
+    }>;
+    skipped: Array<{
+        skill: string;
+        agent: string;
+        reason: string;
+    }>;
+    warnings: string[];
+    failed: boolean;
+    failureReason?: string;
+}
+export interface InstallOptions {
+    force: boolean;
+    baseDir: string;
+}
+export interface CopyResult {
+    warnings: string[];
+}
+/**
+ * Thrown when SKILL.md is not found in downloaded content.
+ */
+export declare class SkillMdNotFoundError extends Error {
+    skillPath: string;
+    constructor(skillPath: string);
+}
+/**
+ * Recursively copies a directory while skipping symlinks for security.
+ * This prevents symlink attacks where malicious repos could link to sensitive files.
+ *
+ * SECURITY: Uses double-check pattern to minimize TOCTOU race window.
+ * The second lstatSync check immediately before cpSync reduces (but doesn't
+ * eliminate) the window for a race condition attack.
+ *
+ * @returns CopyResult with any warnings generated during copy
+ */
+export declare function safeCopyDir(src: string, dest: string): CopyResult;
+/**
+ * Download and install a skill to multiple agent directories.
+ *
+ * @param owner - GitHub repository owner
+ * @param repo - GitHub repository name
+ * @param skillPath - Path to skill within repository (or SKILL.md for root)
+ * @param skillName - Name to use for the installed skill directory
+ * @param agents - List of agents to install to
+ * @param options - Installation options (force, baseDir)
+ * @returns InstallResult with details of what was installed/skipped
+ */
+export declare function installSkill(owner: string, repo: string, skillPath: string, skillName: string, agents: readonly Agent[], options: InstallOptions): Promise<InstallResult>;
+/**
+ * List installed skills for a given agent directory.
+ *
+ * @param skillDir - Path to the agent's skills directory
+ * @returns Array of skill names that have a valid SKILL.md
+ */
+export declare function listInstalledSkillsInDir(skillDir: string): string[];