skillfish 1.0.8 → 1.0.10

package/README.md

@@ -1,4 +1,14 @@
-# skillfish
+<p align="center">
+  <img src="https://raw.githubusercontent.com/knoxgraeme/skillfish/main/assets/logo.png" alt="skillfish" width="600">
+</p>
+
+<p align="center">
+  <a href="https://npmjs.com/package/skillfish"><img src="https://img.shields.io/npm/v/skillfish" alt="npm"></a>
+  <a href="https://npmjs.com/package/skillfish"><img src="https://img.shields.io/npm/dm/skillfish" alt="downloads"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/skillfish" alt="license"></a>
+  <a href="package.json"><img src="https://img.shields.io/node/v/skillfish" alt="node"></a>
+  <a href="https://github.com/knoxgraeme/skillfish/actions"><img src="https://github.com/knoxgraeme/skillfish/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+</p>
 
 Install AI agent skills from GitHub with a single command.
 
@@ -101,9 +111,9 @@ When a repo contains multiple skills, you'll get an interactive multi-select men
 
 ```
 ◆  Select skills to install
-│  ◻ Frontend Design - Create distinctive, production-grade frontend interfaces
-│  ◻ Agent Browser - Browser automation using Vercel's agent-browser CLI
-│  ◻ Git Worktree - Manage Git worktrees for isolated parallel development
+│  ◻ my-skill - A helpful skill for your AI agent
+│  ◻ another-skill - Another useful capability
+│  ◻ third-skill - Yet another skill option
 │  ...
 └
 ```
@@ -117,7 +127,7 @@ Use `--all` to install all skills non-interactively (useful for automation).
 npx skillfish add user/my-skill
 
 # Install using full path from GitHub
-npx skillfish add EveryInc/compound-engineering-plugin/compound-engineering/frontend-design
+npx skillfish add owner/repo/path/to/skill
 
 # Install from a plugin repo with explicit path
 npx skillfish add org/plugin-repo --path plugins/my-plugin/skills/skill-name
@@ -183,10 +193,22 @@ skillfish add owner/repo --json
 # Output includes: "exit_code": 0 (or error code)
 ```
 
+## Security
+
+**Security Note:** Skills are markdown files that provide instructions to AI agents. Always review skills before installing. skillfish does not vet third-party skills.
+
+To report security vulnerabilities, please email security@skill.fish. See [SECURITY.md](SECURITY.md) for details.
+
 ## Contributing
 
-Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
 
 ## License
 
-AGPL-3.0
+[AGPL-3.0](LICENSE) - Graeme Knox

package/dist/commands/add.js

@@ -9,7 +9,7 @@ import pc from 'picocolors';
 import { trackInstall } from '../telemetry.js';
 import { isValidPath, parseFrontmatter, deriveSkillName, toTitleCase, truncate, batchMap, createJsonOutput, isInputTTY, isTTY, } from '../utils.js';
 import { getDetectedAgents, AGENT_CONFIGS } from '../lib/agents.js';
-import { findAllSkillMdFiles, fetchSkillMdContent, fetchDefaultBranch, SKILL_FILENAME, RateLimitError, RepoNotFoundError, NetworkError, GitHubApiError, } from '../lib/github.js';
+import { findAllSkillMdFiles, fetchSkillMdContent, fetchDefaultBranch, fetchTreeSha, SKILL_FILENAME, RateLimitError, RepoNotFoundError, NetworkError, GitHubApiError, } from '../lib/github.js';
 import { installSkill } from '../lib/installer.js';
 import { EXIT_CODES, isValidName } from '../lib/constants.js';
 // === Command Definition ===
@@ -115,14 +115,23 @@ Examples:
     // 1. Discover or select skills
     let discoveryResult;
     if (explicitPath) {
-        // For explicit paths, we still need to fetch the default branch for degit
+        // For explicit paths, we still need to fetch the default branch and SHA for tracking
         try {
             const branch = await fetchDefaultBranch(owner, repo);
-            discoveryResult = { paths: [explicitPath], branch };
+            // Fetch tree SHA for manifest tracking
+            let sha;
+            try {
+                sha = await fetchTreeSha(owner, repo, branch);
+            }
+            catch {
+                // If we can't fetch SHA, install without manifest tracking
+                sha = undefined;
+            }
+            discoveryResult = { paths: [explicitPath], branch, sha };
         }
-        catch (err) {
+        catch {
             // If we can't fetch the branch, let degit try its own detection
-            discoveryResult = { paths: [explicitPath], branch: undefined };
+            discoveryResult = { paths: [explicitPath], branch: undefined, sha: undefined };
         }
     }
     else {
@@ -134,7 +143,7 @@ Examples:
         }
         process.exit(EXIT_CODES.NOT_FOUND);
     }
-    const { paths: skillPaths, branch: discoveredBranch } = discoveryResult;
+    const { paths: skillPaths, branch: discoveredBranch, sha: discoveredSha } = discoveryResult;
     // 2. Determine install location (global vs project)
     const baseDir = await selectInstallLocation(projectFlag, globalFlag, jsonMode);
     // 3. Select agents to install to
@@ -193,6 +202,7 @@ Examples:
             force,
             baseDir,
             branch: discoveredBranch,
+            sha: discoveredSha,
         });
         if (spinner) {
             if (result.failed) {
@@ -373,7 +383,7 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
         }
         process.exit(exitCode);
     }
-    const { paths: skillPaths, branch } = skillDiscovery;
+    const { paths: skillPaths, branch, sha } = skillDiscovery;
     if (skillPaths.length === 0) {
         const errorMsg = `No ${SKILL_FILENAME} found in repository`;
         if (jsonMode) {
@@ -432,7 +442,7 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
             if (!jsonMode) {
                 p.log.info(`${pc.bold(displayName)}${desc ? pc.dim(` - ${desc}`) : ''}`);
             }
-            return { paths: [matchedSkill.dir], branch };
+            return { paths: [matchedSkill.dir], branch, sha };
         }
         // Skill not found - show available skills
         const errorMsg = `Skill "${targetSkillName}" not found in repository`;
@@ -458,7 +468,7 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
         if (!jsonMode) {
             p.log.info(`${pc.bold(displayName)}${desc ? pc.dim(` - ${desc}`) : ''}`);
         }
-        return { paths: [skill.dir], branch };
+        return { paths: [skill.dir], branch, sha };
     }
     // Build options for selection with frontmatter metadata
     // Title in label, description in hint (shows on focus)
@@ -474,7 +484,7 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
             if (!jsonMode) {
                 console.log(`Installing all ${skills.length} skills`);
             }
-            return { paths: skills.map((s) => s.dir), branch };
+            return { paths: skills.map((s) => s.dir), branch, sha };
         }
         // Otherwise, list skills and exit with guidance
         if (jsonMode) {
@@ -502,7 +512,7 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
         p.cancel('Cancelled');
         process.exit(EXIT_CODES.SUCCESS);
     }
-    return { paths: selected, branch };
+    return { paths: selected, branch, sha };
 }
 /**
  * SECURITY: Show warning and ask for user confirmation before installing.

package/dist/commands/list.js

@@ -78,7 +78,12 @@ Examples:
                     const skillPath = join(globalDir, skill);
                     if (!seenPaths.has(skillPath)) {
                         seenPaths.add(skillPath);
-                        const item = { agent: agent.name, skill, path: skillPath, location: 'global' };
+                        const item = {
+                            agent: agent.name,
+                            skill,
+                            path: skillPath,
+                            location: 'global',
+                        };
                         installed.push(item);
                         globalSkills.push(item);
                     }
@@ -92,7 +97,12 @@ Examples:
                     // Skip if already seen (avoids duplicates when cwd is under home)
                     if (!seenPaths.has(skillPath)) {
                         seenPaths.add(skillPath);
-                        const item = { agent: agent.name, skill, path: skillPath, location: 'project' };
+                        const item = {
+                            agent: agent.name,
+                            skill,
+                            path: skillPath,
+                            location: 'project',
+                        };
                         installed.push(item);
                         projectSkills.push(item);
                     }
@@ -136,7 +146,10 @@ Examples:
         if (hasBothLocations && isInputTTY()) {
             const locationOptions = [
                 { value: 'global', label: `Global (~/) ${pc.dim(`(${globalSkills.length})`)}` },
-                { value: 'project', label: `Project (./) ${pc.dim(`(${projectSkills.length})`)}` },
+                {
+                    value: 'project',
+                    label: `Project (./) ${pc.dim(`(${projectSkills.length})`)}`,
+                },
             ];
             const selectedLocation = await p.select({
                 message: 'Select location',
@@ -208,7 +221,10 @@ Examples:
         if (hasBothLocations) {
             const locationOptions = [
                 { value: 'global', label: `Global (~/) ${pc.dim(`(${globalSkills.length})`)}` },
-                { value: 'project', label: `Project (./) ${pc.dim(`(${projectSkills.length})`)}` },
+                {
+                    value: 'project',
+                    label: `Project (./) ${pc.dim(`(${projectSkills.length})`)}`,
+                },
             ];
             const selectedLocation = await p.select({
                 message: 'Select location',

package/dist/commands/remove.js

@@ -82,16 +82,14 @@ Examples:
     // Detect agents
     const detected = getDetectedAgents();
     if (detected.length === 0) {
-        exitWithError('No agents detected. Install Claude Code, Cursor, or another supported agent first.', EXIT_CODES.GENERAL_ERROR, true // useClackLog
-        );
+        exitWithError('No agents detected. Install Claude Code, Cursor, or another supported agent first.', EXIT_CODES.GENERAL_ERROR, true);
     }
     // Filter to target agent if specified
     let targetAgents = detected;
     if (targetAgentName) {
         const found = detected.filter((a) => a.name.toLowerCase() === targetAgentName.toLowerCase());
         if (found.length === 0) {
-            exitWithError(`Agent "${targetAgentName}" not found. Detected agents: ${detected.map((a) => a.name).join(', ')}`, EXIT_CODES.NOT_FOUND, true // useClackLog
-            );
+            exitWithError(`Agent "${targetAgentName}" not found. Detected agents: ${detected.map((a) => a.name).join(', ')}`, EXIT_CODES.NOT_FOUND, true);
         }
         targetAgents = found;
     }
@@ -220,7 +218,10 @@ Examples:
         if (hasBothLocations) {
             const locationOptions = [
                 { value: 'global', label: `Global (~/) ${pc.dim(`(${globalSkills.length})`)}` },
-                { value: 'project', label: `Project (./) ${pc.dim(`(${projectSkills.length})`)}` },
+                {
+                    value: 'project',
+                    label: `Project (./) ${pc.dim(`(${projectSkills.length})`)}`,
+                },
             ];
             const selectedLocation = await p.select({
                 message: 'Select location',

package/dist/commands/update.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `skillfish update` command - Check for and apply updates to installed skills.
+ */
+import { Command } from 'commander';
+export declare const updateCommand: Command;

package/dist/commands/update.js

@@ -0,0 +1,327 @@
+/**
+ * `skillfish update` command - Check for and apply updates to installed skills.
+ */
+import { Command } from 'commander';
+import { homedir } from 'os';
+import { join } from 'path';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { getDetectedAgents, getAgentSkillDir } from '../lib/agents.js';
+import { listInstalledSkillsInDir, installSkill } from '../lib/installer.js';
+import { readManifest } from '../lib/manifest.js';
+import { fetchTreeSha, RateLimitError, RepoNotFoundError, NetworkError, GitHubApiError, } from '../lib/github.js';
+import { EXIT_CODES } from '../lib/constants.js';
+import { isInputTTY, isTTY } from '../utils.js';
+// === Command Definition ===
+export const updateCommand = new Command('update')
+    .description('Check for and apply updates to installed skills')
+    .option('-y, --yes', 'Update all outdated skills without prompting')
+    .helpOption('-h, --help', 'Display help for command')
+    .addHelpText('after', `
+Examples:
+  $ skillfish update                  Check for updates interactively
+  $ skillfish update --yes            Update all outdated skills
+  $ skillfish update --json           Check for updates (JSON output)
+  $ skillfish update --yes --json     Update all outdated skills (JSON output)`)
+    .action(async (options, command) => {
+    const jsonMode = command.parent?.opts().json ?? false;
+    const autoUpdate = options.yes ?? false;
+    const version = command.parent?.opts().version ?? '0.0.0';
+    // JSON output state
+    const jsonOutput = {
+        success: true,
+        exit_code: EXIT_CODES.SUCCESS,
+        errors: [],
+        outdated: [],
+        updated: [],
+    };
+    function addError(message) {
+        jsonOutput.errors.push(message);
+        jsonOutput.success = false;
+    }
+    function outputJsonAndExit(exitCode) {
+        jsonOutput.exit_code = exitCode;
+        console.log(JSON.stringify(jsonOutput, null, 2));
+        process.exit(exitCode);
+    }
+    function exitWithError(message, exitCode) {
+        if (jsonMode) {
+            addError(message);
+            outputJsonAndExit(exitCode);
+        }
+        p.log.error(message);
+        process.exit(exitCode);
+    }
+    // Show banner (TTY only, not in JSON mode)
+    if (isTTY() && !jsonMode) {
+        console.log();
+        console.log(pc.cyan('     ≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋'));
+        console.log(`       ${pc.cyan('><>')}  ${pc.bold('SKILL FISH')}  ${pc.cyan('><>')}`);
+        console.log(pc.cyan('     ≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋'));
+        console.log();
+        p.intro(`${pc.bgCyan(pc.black(' skillfish '))} ${pc.dim(`v${version}`)}`);
+    }
+    // Detect agents
+    const detected = getDetectedAgents();
+    if (detected.length === 0) {
+        exitWithError('No agents detected. Install Claude Code, Cursor, or another supported agent first.', EXIT_CODES.GENERAL_ERROR);
+    }
+    // Show checking spinner
+    let checkSpinner = null;
+    if (!jsonMode) {
+        checkSpinner = p.spinner();
+        checkSpinner.start('Checking for updates...');
+    }
+    // Collect all tracked skills (skills with manifests)
+    const trackedSkills = collectTrackedSkills(detected);
+    if (trackedSkills.length === 0) {
+        if (checkSpinner) {
+            checkSpinner.stop(pc.yellow('No tracked skills found'));
+        }
+        if (jsonMode) {
+            outputJsonAndExit(EXIT_CODES.SUCCESS);
+        }
+        console.log();
+        p.log.info(pc.dim("Skills installed before this version don't have tracking info."));
+        p.log.info(pc.dim('Reinstall skills with `skillfish add` to enable updates.'));
+        p.outro(pc.dim('Done'));
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    // Check for updates
+    const { outdated, errors, rateLimitHit } = await checkForUpdates(trackedSkills);
+    if (checkSpinner) {
+        if (rateLimitHit) {
+            checkSpinner.stop(pc.yellow('Rate limit reached'));
+        }
+        else if (outdated.length > 0) {
+            checkSpinner.stop(`Found ${pc.cyan(outdated.length.toString())} outdated skill${outdated.length === 1 ? '' : 's'}`);
+        }
+        else {
+            checkSpinner.stop(pc.green('All skills are up to date'));
+        }
+    }
+    // Add any errors to output
+    for (const error of errors) {
+        addError(error);
+    }
+    // Build outdated skills for JSON output
+    jsonOutput.outdated = outdated.map((s) => ({
+        skill: s.skill,
+        agent: s.agent.name,
+        path: s.path,
+        location: s.location,
+        localSha: s.manifest.sha,
+        remoteSha: s.remoteSha,
+        source: `${s.manifest.owner}/${s.manifest.repo}`,
+    }));
+    // If rate limit hit, report and exit
+    if (rateLimitHit) {
+        if (jsonMode) {
+            outputJsonAndExit(EXIT_CODES.NETWORK_ERROR);
+        }
+        p.log.warn('GitHub API rate limit exceeded. Try again later.');
+        process.exit(EXIT_CODES.NETWORK_ERROR);
+    }
+    // No updates available
+    if (outdated.length === 0) {
+        if (jsonMode) {
+            outputJsonAndExit(EXIT_CODES.SUCCESS);
+        }
+        p.outro(pc.green('All skills are up to date'));
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    // Display outdated skills (TTY mode)
+    if (!jsonMode) {
+        console.log();
+        for (const skill of outdated) {
+            const locationLabel = skill.location === 'global' ? pc.dim('global') : pc.dim('project');
+            const shortLocal = skill.manifest.sha.substring(0, 7);
+            const shortRemote = skill.remoteSha.substring(0, 7);
+            console.log(`  ${pc.yellow('•')} ${pc.bold(skill.skill)} (${skill.agent.name}, ${locationLabel})`);
+            console.log(`    ${pc.dim(shortLocal)} → ${pc.cyan(shortRemote)}`);
+        }
+        console.log();
+    }
+    // If --json without --yes: check mode only - don't apply updates
+    if (jsonMode && !autoUpdate) {
+        outputJsonAndExit(EXIT_CODES.SUCCESS);
+    }
+    // Prompt for confirmation (unless --yes)
+    if (!autoUpdate && isInputTTY() && !jsonMode) {
+        const proceed = await p.confirm({
+            message: `Update all ${outdated.length} skill${outdated.length === 1 ? '' : 's'}?`,
+            initialValue: true,
+        });
+        if (p.isCancel(proceed) || !proceed) {
+            p.cancel('Cancelled');
+            process.exit(EXIT_CODES.SUCCESS);
+        }
+    }
+    // Apply updates
+    let updatedCount = 0;
+    let failedCount = 0;
+    for (let i = 0; i < outdated.length; i++) {
+        const skill = outdated[i];
+        const progress = `[${i + 1}/${outdated.length}]`;
+        let updateSpinner = null;
+        if (!jsonMode) {
+            updateSpinner = p.spinner();
+            updateSpinner.start(`${progress} Updating ${skill.skill}...`);
+        }
+        const result = await installSkill(skill.manifest.owner, skill.manifest.repo, skill.manifest.path, skill.skill, [skill.agent], {
+            force: true,
+            baseDir: skill.location === 'global' ? homedir() : process.cwd(),
+            branch: skill.manifest.branch,
+            sha: skill.remoteSha,
+        });
+        if (result.failed) {
+            failedCount++;
+            if (updateSpinner) {
+                updateSpinner.stop(pc.red(`${progress} ${skill.skill} failed`));
+            }
+            addError(`Failed to update ${skill.skill}: ${result.failureReason}`);
+        }
+        else {
+            updatedCount++;
+            if (updateSpinner) {
+                updateSpinner.stop(pc.green(`${progress} ${skill.skill} updated`));
+            }
+            jsonOutput.updated.push({
+                skill: skill.skill,
+                agent: skill.agent.name,
+                path: skill.path,
+                location: skill.location,
+            });
+        }
+    }
+    // Summary
+    if (jsonMode) {
+        const exitCode = failedCount > 0 ? EXIT_CODES.GENERAL_ERROR : EXIT_CODES.SUCCESS;
+        outputJsonAndExit(exitCode);
+    }
+    console.log();
+    if (failedCount > 0) {
+        p.outro(pc.yellow(`Updated ${updatedCount} of ${outdated.length} skill${outdated.length === 1 ? '' : 's'}`));
+        process.exit(EXIT_CODES.GENERAL_ERROR);
+    }
+    else {
+        p.outro(pc.green(`Updated ${updatedCount} skill${updatedCount === 1 ? '' : 's'} successfully`));
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+});
+// === Helper Functions ===
+/**
+ * Collect all installed skills that have manifests (tracked skills).
+ */
+function collectTrackedSkills(agents) {
+    const tracked = [];
+    const seenPaths = new Set();
+    for (const agent of agents) {
+        // Check global skills
+        const globalDir = getAgentSkillDir(agent, homedir());
+        const globalSkills = listInstalledSkillsInDir(globalDir);
+        for (const skill of globalSkills) {
+            const skillPath = join(globalDir, skill);
+            if (seenPaths.has(skillPath))
+                continue;
+            seenPaths.add(skillPath);
+            const manifest = readManifest(skillPath);
+            if (manifest) {
+                tracked.push({
+                    skill,
+                    agent,
+                    path: skillPath,
+                    location: 'global',
+                    manifest,
+                });
+            }
+        }
+        // Check project skills
+        const projectDir = getAgentSkillDir(agent, process.cwd());
+        const projectSkills = listInstalledSkillsInDir(projectDir);
+        for (const skill of projectSkills) {
+            const skillPath = join(projectDir, skill);
+            if (seenPaths.has(skillPath))
+                continue;
+            seenPaths.add(skillPath);
+            const manifest = readManifest(skillPath);
+            if (manifest) {
+                tracked.push({
+                    skill,
+                    agent,
+                    path: skillPath,
+                    location: 'project',
+                    manifest,
+                });
+            }
+        }
+    }
+    return tracked;
+}
+/**
+ * Check which tracked skills have updates available.
+ * Caches tree SHA lookups to avoid duplicate API calls for skills from the same repo.
+ */
+async function checkForUpdates(skills) {
+    const outdated = [];
+    const errors = [];
+    let rateLimitHit = false;
+    // Cache tree SHA lookups by owner/repo/branch to avoid duplicate API calls
+    const shaCache = new Map();
+    const errorCache = new Map();
+    for (const skill of skills) {
+        const cacheKey = `${skill.manifest.owner}/${skill.manifest.repo}/${skill.manifest.branch}`;
+        // Check if we already have a cached error for this repo
+        const cachedError = errorCache.get(cacheKey);
+        if (cachedError) {
+            if (cachedError instanceof RepoNotFoundError) {
+                errors.push(`${skill.skill}: Repository not found (${skill.manifest.owner}/${skill.manifest.repo})`);
+            }
+            else if (cachedError instanceof NetworkError) {
+                errors.push(`${skill.skill}: ${cachedError.message}`);
+            }
+            else if (cachedError instanceof GitHubApiError) {
+                errors.push(`${skill.skill}: ${cachedError.message}`);
+            }
+            else {
+                errors.push(`${skill.skill}: ${cachedError.message}`);
+            }
+            continue;
+        }
+        // Check if we already have a cached SHA for this repo
+        let remoteSha = shaCache.get(cacheKey);
+        if (!remoteSha) {
+            try {
+                remoteSha = await fetchTreeSha(skill.manifest.owner, skill.manifest.repo, skill.manifest.branch);
+                shaCache.set(cacheKey, remoteSha);
+            }
+            catch (err) {
+                if (err instanceof RateLimitError) {
+                    rateLimitHit = true;
+                    break; // Stop checking on rate limit
+                }
+                // Cache the error for other skills from the same repo
+                if (err instanceof Error) {
+                    errorCache.set(cacheKey, err);
+                }
+                if (err instanceof RepoNotFoundError) {
+                    errors.push(`${skill.skill}: Repository not found (${skill.manifest.owner}/${skill.manifest.repo})`);
+                }
+                else if (err instanceof NetworkError) {
+                    errors.push(`${skill.skill}: ${err.message}`);
+                }
+                else if (err instanceof GitHubApiError) {
+                    errors.push(`${skill.skill}: ${err.message}`);
+                }
+                else {
+                    errors.push(`${skill.skill}: ${err instanceof Error ? err.message : 'Unknown error'}`);
+                }
+                continue;
+            }
+        }
+        if (skill.manifest.sha !== remoteSha) {
+            outdated.push({ ...skill, remoteSha });
+        }
+    }
+    return { outdated, errors, rateLimitHit };
+}

package/dist/index.js

@@ -11,6 +11,7 @@ import { dirname, join } from 'path';
 import { addCommand } from './commands/add.js';
 import { listCommand } from './commands/list.js';
 import { removeCommand } from './commands/remove.js';
+import { updateCommand } from './commands/update.js';
 // Read version from package.json (single source of truth)
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -45,6 +46,7 @@ program.hook('preAction', (thisCommand) => {
 program.addCommand(addCommand);
 program.addCommand(listCommand);
 program.addCommand(removeCommand);
+program.addCommand(updateCommand);
 // Handle --json flag for help output
 program.on('option:json', () => {
     // JSON mode is handled by commands

package/dist/lib/agents.d.ts

@@ -6,12 +6,12 @@
  * Agent configuration - data-driven for easier maintenance.
  * Detection checks home directory (agent installed globally) and cwd (local project).
  */
-export type AgentConfig = {
+export interface 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.
@@ -21,11 +21,11 @@ export declare function detectAgent(config: AgentConfig, baseDir?: string): bool
 /**
  * Runtime agent type with detect function.
  */
-export type Agent = {
+export interface Agent {
     readonly name: string;
     readonly dir: string;
     readonly detect: () => boolean;
-};
+}
 /**
  * Build AGENTS array from config (preserves existing API).
  */

package/dist/lib/github.d.ts

@@ -3,11 +3,13 @@
  */
 export declare const SKILL_FILENAME = "SKILL.md";
 /**
- * Result of skill discovery including branch information.
+ * Result of skill discovery including branch and SHA information.
  */
 export interface SkillDiscoveryResult {
     paths: string[];
     branch: string;
+    /** Tree SHA from git/trees response - changes when any file in repo changes */
+    sha: string;
 }
 /**
  * Thrown when GitHub API rate limit is exceeded.
@@ -55,6 +57,16 @@ export declare function fetchWithRetry(url: string, options: RequestInit, maxRet
  * Uses raw.githubusercontent.com which is not rate-limited like the API.
  */
 export declare function fetchSkillMdContent(owner: string, repo: string, path: string, branch: string): Promise<string | null>;
+/**
+ * Fetch the tree SHA for a repository branch.
+ * Used for update checks - compares stored SHA with current SHA.
+ *
+ * @throws {RepoNotFoundError} When the repository is not found
+ * @throws {RateLimitError} When GitHub API rate limit is exceeded
+ * @throws {NetworkError} On network errors
+ * @throws {GitHubApiError} When the API response format is unexpected
+ */
+export declare function fetchTreeSha(owner: string, repo: string, branch: string): Promise<string>;
 /**
  * Find all SKILL.md files in a GitHub repository.
  * Fetches the default branch, then searches for skills on that branch.