skillbox 0.3.2 → 0.3.4

package/README.md

@@ -67,8 +67,9 @@ skillbox update [name]     # update skills
 
 | Command | Description |
 |---------|-------------|
-| `skillbox project add <path>` | Register a project |
+| `skillbox project add <path>` | Register a project and auto-import skills from `skills/` and agent directories |
 | `skillbox project list` | List registered projects |
+| `skillbox project inspect <path>` | Show project details and skills |
 | `skillbox project sync <path>` | Re-sync skills to a project |
 
 ## Supported Agents

package/dist/cli.js

@@ -12,7 +12,7 @@ import { registerRemove } from "./commands/remove.js";
 import { registerStatus } from "./commands/status.js";
 import { registerUpdate } from "./commands/update.js";
 const program = new Command();
-program.name("skillbox").description("Local-first, agent-agnostic skills manager").version("0.3.2");
+program.name("skillbox").description("Local-first, agent-agnostic skills manager").version("0.3.4");
 registerAdd(program);
 registerAgent(program);
 registerConfig(program);

package/dist/commands/add-repo.js

@@ -1,9 +1,10 @@
+import path from "node:path";
 import { getErrorMessage } from "../lib/command.js";
 import { loadConfig } from "../lib/config.js";
 import { parseRepoRef } from "../lib/github.js";
 import { loadIndex, saveIndex, sortIndex, upsertSkill } from "../lib/index.js";
 import { recordInstallPaths } from "../lib/installs.js";
-import { printInfo, printJson } from "../lib/output.js";
+import { printFailure, printInfo, printJson, printSkipped, printSuccess, startSpinner, stopSpinner, } from "../lib/output.js";
 import { buildProjectAgentPaths } from "../lib/project-paths.js";
 import { fetchRepoFile, listRepoSkills, normalizeRepoRef, writeRepoSkillDirectory, } from "../lib/repo-skills.js";
 import { ensureProjectRegistered, resolveRuntime } from "../lib/runtime.js";
@@ -38,25 +39,22 @@ async function installSkillTargets(skillName, options, installs) {
         if (!map) {
             continue;
         }
-        const targets = buildTargets(agent, map, scope).map((target) => target.path);
+        const targets = buildTargets(agent, map, scope).map((target) => path.join(target.path, skillName));
         const results = await installSkillToTargets(skillName, targets, config);
-        const written = results
-            .filter((result) => result.mode !== "skipped")
-            .map((result) => result.path);
         const warnings = buildSymlinkWarning(agent, results);
         for (const warning of warnings) {
             printInfo(warning);
         }
-        const deduped = recordInstallPaths(written, recordedPaths);
-        if (deduped.length > 0) {
-            for (const target of deduped) {
-                installs.push({
-                    scope,
-                    agent,
-                    path: target,
-                    projectRoot: scope === "project" ? projectRoot : undefined,
-                });
-            }
+        // Record all targets, not just successfully written ones
+        // The warning tells users about symlink issues, but we still track the install intent
+        const deduped = recordInstallPaths(targets, recordedPaths);
+        for (const target of deduped) {
+            installs.push({
+                scope,
+                agent,
+                path: target,
+                projectRoot: scope === "project" ? projectRoot : undefined,
+            });
         }
     }
 }
@@ -86,16 +84,27 @@ export async function handleRepoInstall(input, options) {
     }
     const summary = { installed: [], updated: [], skipped: [], failed: [] };
     const index = await loadIndex();
-    for (const skill of skills) {
-        if (!selected.includes(skill.name)) {
-            continue;
-        }
+    const showProgress = !options.json;
+    const selectedSkills = skills.filter((s) => selected.includes(s.name));
+    const total = selectedSkills.length;
+    if (showProgress && total > 0) {
+        printInfo(`Adding ${total} skill${total === 1 ? "" : "s"} from ${ref.owner}/${ref.repo}...\n`);
+    }
+    for (let i = 0; i < selectedSkills.length; i++) {
+        const skill = selectedSkills[i];
+        const progress = `(${i + 1}/${total})`;
         const alreadyInstalled = index.skills.some((entry) => entry.name === skill.name);
+        if (showProgress) {
+            startSpinner(`${skill.name} ${progress}`);
+        }
         try {
             const skillMarkdown = await fetchRepoFile(ref, ref.path ? `${ref.path}/${skill.skillFile}` : skill.skillFile);
             const parsed = parseSkillMarkdown(skillMarkdown);
             if (!parsed.description) {
                 summary.skipped.push(skill.name);
+                if (showProgress) {
+                    printSkipped(skill.name, "missing description");
+                }
                 continue;
             }
             await writeRepoSkillDirectory(ref, skill.path, skill.name);
@@ -126,56 +135,49 @@ export async function handleRepoInstall(input, options) {
             index.skills = nextIndex.skills;
             if (alreadyInstalled) {
                 summary.updated.push(skill.name);
+                if (showProgress) {
+                    printSuccess(skill.name, "updated");
+                }
             }
             else {
                 summary.installed.push(skill.name);
+                if (showProgress) {
+                    printSuccess(skill.name);
+                }
             }
         }
         catch (error) {
             const message = getErrorMessage(error, "unknown");
             summary.failed.push({ name: skill.name, reason: message });
+            if (showProgress) {
+                printFailure(skill.name, message);
+            }
         }
     }
+    if (showProgress) {
+        stopSpinner();
+    }
     await saveIndex(sortIndex(index));
     if (options.json) {
         printJson({ ok: true, command: "add", data: { repo: `${ref.owner}/${ref.repo}`, ...summary } });
         return;
     }
-    printInfo(`Skills Added from: ${ref.owner}/${ref.repo}`);
-    printInfo("");
-    printInfo("Source: git");
-    printInfo(`  ${ref.owner}/${ref.repo}${ref.path ? `/${ref.path}` : ""} (${ref.ref})`);
-    if (summary.installed.length > 0) {
-        printInfo("");
-        printInfo(`Installed (${summary.installed.length}):`);
-        for (const name of summary.installed) {
-            printInfo(`  ✓ ${name}`);
-        }
+    // Summary line
+    const added = summary.installed.length + summary.updated.length;
+    const failed = summary.failed.length;
+    const skipped = summary.skipped.length;
+    if (added > 0 && failed === 0 && skipped === 0) {
+        printInfo(`\nAdded ${added} skill${added === 1 ? "" : "s"} from ${ref.owner}/${ref.repo}.`);
     }
-    if (summary.updated.length > 0) {
-        printInfo("");
-        printInfo(`Updated (${summary.updated.length}):`);
-        for (const name of summary.updated) {
-            printInfo(`  ✓ ${name}`);
-        }
-    }
-    if (summary.skipped.length > 0) {
-        printInfo("");
-        printInfo(`Skipped (${summary.skipped.length}):`);
-        for (const name of summary.skipped) {
-            printInfo(`  - ${name} (missing description)`);
-        }
+    else if (added > 0) {
+        const parts = [];
+        if (failed > 0)
+            parts.push(`${failed} failed`);
+        if (skipped > 0)
+            parts.push(`${skipped} skipped`);
+        printInfo(`\nAdded ${added} skill${added === 1 ? "" : "s"} (${parts.join(", ")}).`);
     }
-    if (summary.failed.length > 0) {
-        printInfo("");
-        printInfo(`Failed (${summary.failed.length}):`);
-        for (const failure of summary.failed) {
-            printInfo(`  ✗ ${failure.name} (${failure.reason})`);
-        }
-    }
-    const total = summary.installed.length + summary.updated.length;
-    if (total === 0) {
-        printInfo("");
-        printInfo("No skills were added.");
+    else {
+        printInfo("\nNo skills were added.");
     }
 }

package/dist/commands/add.js

@@ -1,10 +1,11 @@
+import path from "node:path";
 import { handleCommandError } from "../lib/command.js";
 import { loadConfig } from "../lib/config.js";
 import { fetchText } from "../lib/fetcher.js";
 import { collect } from "../lib/fs-utils.js";
 import { loadIndex, saveIndex, sortIndex, upsertSkill } from "../lib/index.js";
 import { recordInstallPaths } from "../lib/installs.js";
-import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
+import { isJsonEnabled, printInfo, printJson, printSuccess, startSpinner, stopSpinner, } from "../lib/output.js";
 import { buildProjectAgentPaths } from "../lib/project-paths.js";
 import { ensureProjectRegistered, resolveRuntime } from "../lib/runtime.js";
 import { buildMetadata, inferNameFromUrl, parseSkillMarkdown } from "../lib/skill-parser.js";
@@ -33,17 +34,28 @@ export function registerAdd(program) {
                 });
                 return;
             }
+            const showProgress = !isJsonEnabled(options);
+            const inferred = inferNameFromUrl(url);
+            const displayName = options.name ?? inferred ?? "skill";
+            if (showProgress) {
+                startSpinner(`Adding ${displayName}`);
+            }
             const skillMarkdown = await fetchText(url);
             const parsed = parseSkillMarkdown(skillMarkdown);
-            const inferred = inferNameFromUrl(url);
             const skillName = options.name ?? inferred ?? parsed.name;
             if (!skillName) {
+                if (showProgress)
+                    stopSpinner();
                 throw new Error("Unable to infer skill name. Use --name to specify it.");
             }
             if (!parsed.name && !options.name) {
+                if (showProgress)
+                    stopSpinner();
                 throw new Error("Skill frontmatter missing name. Provide --name to continue.");
             }
             if (!parsed.description) {
+                if (showProgress)
+                    stopSpinner();
                 throw new Error("Skill frontmatter missing description. Convert the source into a valid skill.");
             }
             const metadata = buildMetadata(parsed, { type: "url", url }, skillName);
@@ -71,16 +83,15 @@ export function registerAdd(program) {
                 if (!map) {
                     continue;
                 }
-                const targets = buildTargets(agent, map, scope).map((target) => target.path);
+                const targets = buildTargets(agent, map, scope).map((target) => path.join(target.path, skillName));
                 const results = await installSkillToTargets(skillName, targets, config);
-                const written = results
-                    .filter((result) => result.mode !== "skipped")
-                    .map((result) => result.path);
                 const warnings = buildSymlinkWarning(agent, results);
                 for (const warning of warnings) {
                     printInfo(warning);
                 }
-                const deduped = recordInstallPaths(written, recordedPaths);
+                // Record all targets, not just successfully written ones
+                // The warning tells users about symlink issues, but we still track the install intent
+                const deduped = recordInstallPaths(targets, recordedPaths);
                 if (deduped.length > 0) {
                     installed.push({ agent, scope, targets: deduped });
                     for (const target of deduped) {
@@ -102,6 +113,7 @@ export function registerAdd(program) {
             });
             await saveIndex(sortIndex(nextIndex));
             if (isJsonEnabled(options)) {
+                stopSpinner();
                 printJson({
                     ok: true,
                     command: "add",
@@ -114,22 +126,8 @@ export function registerAdd(program) {
                 });
                 return;
             }
-            printInfo(`Skill Added: ${skillName}`);
-            printInfo("");
-            printInfo("Source: url");
-            printInfo(`  ${url}`);
-            if (installs.length > 0) {
-                printInfo("");
-                printInfo("Installed to:");
-                for (const install of installs) {
-                    const scopeLabel = install.scope === "project" ? `project:${install.projectRoot}` : "user";
-                    printInfo(`  ✓ ${scopeLabel}/${install.agent}`);
-                }
-            }
-            else {
-                printInfo("");
-                printInfo("No agent targets were updated.");
-            }
+            printSuccess(skillName);
+            printInfo(`\nAdded skill from ${url}.`);
         }
         catch (error) {
             handleCommandError(options, "add", error);

package/dist/commands/import.js

@@ -1,4 +1,3 @@
-import fs from "node:fs/promises";
 import path from "node:path";
 import { getUserPathsForAgents } from "../lib/agents.js";
 import { handleCommandError } from "../lib/command.js";
@@ -6,8 +5,7 @@ import { discoverSkills } from "../lib/discovery.js";
 import { loadIndex, saveIndex, sortIndex, upsertSkill } from "../lib/index.js";
 import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
 import { resolveRuntime } from "../lib/runtime.js";
-import { buildMetadata, parseSkillMarkdown } from "../lib/skill-parser.js";
-import { ensureSkillsDir, writeSkillFiles } from "../lib/skill-store.js";
+import { importSkillFromDir } from "../lib/skill-store.js";
 async function importGlobalSkills(agents) {
     const projectRoot = process.cwd();
     const agentPaths = getUserPathsForAgents(projectRoot, agents);
@@ -32,24 +30,20 @@ async function importGlobalSkills(agents) {
             skipped.add(skill.name);
             continue;
         }
-        const markdown = await fs.readFile(skill.skillFile, "utf8");
-        const parsed = parseSkillMarkdown(markdown);
-        if (!parsed.description) {
+        const data = await importSkillFromDir(skill.skillFile);
+        if (!data) {
             skipped.add(skill.name);
             continue;
         }
-        const metadata = buildMetadata(parsed, { type: "local" });
-        await ensureSkillsDir();
-        await writeSkillFiles(metadata.name, markdown, metadata);
         const next = upsertSkill(index, {
-            name: metadata.name,
+            name: data.name,
             source: { type: "local" },
-            checksum: parsed.checksum,
-            updatedAt: metadata.updatedAt,
+            checksum: data.checksum,
+            updatedAt: data.updatedAt,
             installs: [{ scope: "user", agent: skill.agent, path: skill.skillDir }],
         });
         index.skills = next.skills;
-        imported.add(metadata.name);
+        imported.add(data.name);
     }
     await saveIndex(sortIndex(index));
     return {
@@ -81,27 +75,23 @@ export function registerImport(program) {
             }
             const resolved = path.resolve(inputPath);
             const skillPath = path.join(resolved, "SKILL.md");
-            const markdown = await fs.readFile(skillPath, "utf8");
-            const parsed = parseSkillMarkdown(markdown);
-            if (!parsed.description) {
+            const data = await importSkillFromDir(skillPath);
+            if (!data) {
                 throw new Error("Skill frontmatter missing description.");
             }
-            const metadata = buildMetadata(parsed, { type: "local" });
-            await ensureSkillsDir();
-            await writeSkillFiles(metadata.name, markdown, metadata);
             const index = await loadIndex();
             const updated = upsertSkill(index, {
-                name: metadata.name,
+                name: data.name,
                 source: { type: "local" },
-                checksum: parsed.checksum,
-                updatedAt: metadata.updatedAt,
+                checksum: data.checksum,
+                updatedAt: data.updatedAt,
             });
             await saveIndex(sortIndex(updated));
             if (isJsonEnabled(options)) {
-                printJson({ ok: true, command: "import", data: { name: metadata.name, path: resolved } });
+                printJson({ ok: true, command: "import", data: { name: data.name, path: resolved } });
                 return;
             }
-            printInfo(`Imported skill: ${metadata.name}`);
+            printInfo(`Imported skill: ${data.name}`);
         }
         catch (error) {
             handleCommandError(options, "import", error);

package/dist/commands/list.js

@@ -1,9 +1,34 @@
+import chalk from "chalk";
 import fs from "node:fs/promises";
+import terminalLink from "terminal-link";
 import { discoverGlobalSkills } from "../lib/global-skills.js";
 import { loadIndex } from "../lib/index.js";
 import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
 import { resolveRuntime } from "../lib/runtime.js";
 import { groupAndSort, sortByName } from "../lib/source-grouping.js";
+function getSkillUrl(skill) {
+    if (skill.source.type === "url" && skill.source.url) {
+        return skill.source.url;
+    }
+    if (skill.source.type === "git" && skill.source.repo) {
+        const repo = skill.source.repo;
+        // If already a full URL, use it directly
+        if (repo.startsWith("http://") || repo.startsWith("https://")) {
+            return repo;
+        }
+        // Convert shorthand (user/repo) to full GitHub URL
+        return `https://github.com/${repo}`;
+    }
+    return undefined;
+}
+function linkSkillName(skill) {
+    const url = getSkillUrl(skill);
+    if (url && terminalLink.isSupported) {
+        const linkIcon = terminalLink("‹↗›", url);
+        return `${skill.name} ${chalk.dim(linkIcon)}`;
+    }
+    return skill.name;
+}
 async function detectSubcommands(skillPath) {
     try {
         const entries = await fs.readdir(skillPath);
@@ -108,7 +133,7 @@ function printScopeGroup(group) {
             for (const sourceGroup of projectGroup.sourceGroups) {
                 printInfo(`  ${sourceGroup.source}`);
                 for (const skill of sourceGroup.skills) {
-                    printInfo(`    ${skill.name}`);
+                    printInfo(`    ${linkSkillName(skill)}`);
                     if (skill.subcommands.length > 0) {
                         printInfo(`      → ${skill.subcommands.join(", ")}`);
                     }
@@ -121,7 +146,7 @@ function printScopeGroup(group) {
         printInfo("");
         printInfo(`${sourceGroup.source}`);
         for (const skill of sourceGroup.skills) {
-            printInfo(`  ${skill.name}`);
+            printInfo(`  ${linkSkillName(skill)}`);
             if (skill.subcommands.length > 0) {
                 printInfo(`    → ${skill.subcommands.join(", ")}`);
             }
@@ -147,6 +172,14 @@ function filterByAgents(skills, agents) {
     const agentSet = new Set(agents);
     return skills.filter((skill) => skill.installs?.some((install) => install.agent && agentSet.has(install.agent)));
 }
+function filterUserScope(skills) {
+    return skills
+        .filter((skill) => skill.installs?.some((install) => install.scope === "user") ?? !skill.installs?.length)
+        .map((skill) => ({
+        ...skill,
+        installs: skill.installs?.filter((install) => install.scope === "user"),
+    }));
+}
 export function registerList(program) {
     program
         .command("list")
@@ -161,8 +194,9 @@ export function registerList(program) {
         const indexedSkills = options.agents
             ? filterByAgents(index.skills, runtime.agentList)
             : index.skills;
-        const allSkills = [...indexedSkills, ...globalSkills];
-        const enrichedSkills = await enrichWithSubcommands(allSkills);
+        const scopedSkills = options.global ? filterUserScope(indexedSkills) : indexedSkills;
+        const mergedSkills = [...scopedSkills, ...globalSkills];
+        const enrichedSkills = await enrichWithSubcommands(mergedSkills);
         if (isJsonEnabled(options)) {
             printJson({
                 ok: true,

package/dist/commands/project.js

@@ -1,11 +1,53 @@
 import path from "node:path";
+import { allAgents, getProjectPathsForAgents } from "../lib/agents.js";
 import { handleCommandError } from "../lib/command.js";
+import { discoverSkills } from "../lib/discovery.js";
 import { collect } from "../lib/fs-utils.js";
-import { loadIndex } from "../lib/index.js";
+import { loadIndex, saveIndex, sortIndex, upsertSkill } from "../lib/index.js";
 import { collectProjectSkills, getProjectInstallPaths, getProjectSkills } from "../lib/installs.js";
 import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
 import { loadProjects, saveProjects, upsertProject } from "../lib/projects.js";
+import { importSkillFromDir } from "../lib/skill-store.js";
 import { copySkillToInstallPaths } from "../lib/sync.js";
+function getProjectSkillPaths(projectRoot) {
+    const agentPaths = getProjectPathsForAgents(projectRoot, allAgents);
+    const seen = new Set();
+    // Add generic skills/ directory
+    seen.add(path.join(projectRoot, "skills"));
+    // Add all agent-specific project paths
+    for (const { path: agentPath } of agentPaths) {
+        seen.add(agentPath);
+    }
+    return Array.from(seen);
+}
+async function discoverProjectSkills(projectRoot) {
+    const skillPaths = getProjectSkillPaths(projectRoot);
+    const discovered = await discoverSkills(skillPaths);
+    if (discovered.length === 0) {
+        return [];
+    }
+    const index = await loadIndex();
+    const imported = [];
+    for (const skill of discovered) {
+        const data = await importSkillFromDir(skill.skillFile);
+        if (!data) {
+            continue;
+        }
+        const updated = upsertSkill(index, {
+            name: data.name,
+            source: { type: "local" },
+            checksum: data.checksum,
+            updatedAt: data.updatedAt,
+            installs: [{ scope: "project", agent: "claude", path: skill.skillDir, projectRoot }],
+        });
+        index.skills = updated.skills;
+        imported.push(data.name);
+    }
+    if (imported.length > 0) {
+        await saveIndex(sortIndex(index));
+    }
+    return imported;
+}
 function parseAgentPaths(entries) {
     const overrides = {};
     for (const entry of entries) {
@@ -22,6 +64,7 @@ export function registerProject(program) {
     const project = program.command("project").description("Manage projects");
     project
         .command("add")
+        .description("Register a project and import skills from its skills/ directory")
         .argument("<path>", "Project path")
         .option("--agent-path <agentPath>", "Agent path override (agent=path)", collect)
         .option("--json", "JSON output")
@@ -45,6 +88,7 @@ export function registerProject(program) {
                 }),
             };
             await saveProjects(merged);
+            const importedSkills = await discoverProjectSkills(resolved);
             if (isJsonEnabled(options)) {
                 printJson({
                     ok: true,
@@ -52,11 +96,15 @@ export function registerProject(program) {
                     data: {
                         path: resolved,
                         agentPaths: merged.projects.find((p) => p.root === resolved)?.agentPaths ?? {},
+                        skills: importedSkills,
                     },
                 });
                 return;
             }
             printInfo(`Project registered: ${resolved}`);
+            if (importedSkills.length > 0) {
+                printInfo(`Discovered ${importedSkills.length} skill(s): ${importedSkills.join(", ")}`);
+            }
         }
         catch (error) {
             handleCommandError(options, "project add", error);

package/dist/commands/update.js

@@ -4,7 +4,7 @@ import { loadConfig } from "../lib/config.js";
 import { fetchText } from "../lib/fetcher.js";
 import { loadIndex, saveIndex, sortIndex, upsertSkill } from "../lib/index.js";
 import { getInstallPaths } from "../lib/installs.js";
-import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
+import { isJsonEnabled, printFailure, printInfo, printJson, printSkipped, printSuccess, startSpinner, stopSpinner, } from "../lib/output.js";
 import { fetchRepoFile, normalizeRepoRef, writeRepoSkillDirectory } from "../lib/repo-skills.js";
 import { buildMetadata, parseSkillMarkdown } from "../lib/skill-parser.js";
 import { ensureSkillsDir, writeSkillFiles, writeSkillMetadata } from "../lib/skill-store.js";
@@ -21,31 +21,6 @@ function groupBySource(results) {
         failedCount: items.filter((r) => r.status === "failed").length,
     }));
 }
-function formatSourceHeader(group) {
-    const count = group.results.length;
-    const skillWord = count === 1 ? "skill" : "skills";
-    if (group.source === "local") {
-        return `${group.source} (${count} ${skillWord} - skipped)`;
-    }
-    if (group.failedCount > 0) {
-        return `${group.source} (${count} ${skillWord}, ${group.failedCount} failed)`;
-    }
-    return `${group.source} (${count} ${skillWord})`;
-}
-function printSourceGroup(group) {
-    printInfo(formatSourceHeader(group));
-    for (const result of group.results) {
-        if (result.status === "skipped") {
-            printInfo(`  - ${result.name}`);
-        }
-        else if (result.status === "failed") {
-            printInfo(`  ✗ ${result.name} (${result.error ?? "failed"})`);
-        }
-        else {
-            printInfo(`  ✓ ${result.name}`);
-        }
-    }
-}
 async function updateUrlSkill(skill, index, projectRoot, config) {
     if (!skill.source.url) {
         return;
@@ -129,39 +104,72 @@ export function registerUpdate(program) {
             const config = await loadConfig();
             const projectRoot = options.project ? path.resolve(options.project) : null;
             const results = [];
-            for (const skill of targets) {
+            const showProgress = !isJsonEnabled(options);
+            if (showProgress && targets.length > 0) {
+                printInfo(`Updating ${targets.length} skill${targets.length === 1 ? "" : "s"}...\n`);
+            }
+            const total = targets.length;
+            for (let i = 0; i < targets.length; i++) {
+                const skill = targets[i];
+                const progress = `(${i + 1}/${total})`;
                 if (skill.source.type === "url") {
+                    if (showProgress) {
+                        startSpinner(`${skill.name} ${progress}`);
+                    }
                     try {
                         await updateUrlSkill(skill, index, projectRoot, config);
                         results.push({ name: skill.name, source: "url", status: "updated" });
+                        if (showProgress) {
+                            printSuccess(skill.name);
+                        }
                     }
                     catch (err) {
+                        const errorMsg = err instanceof Error ? err.message : "unknown error";
                         results.push({
                             name: skill.name,
                             source: "url",
                             status: "failed",
-                            error: err instanceof Error ? err.message : "unknown error",
+                            error: errorMsg,
                         });
+                        if (showProgress) {
+                            printFailure(skill.name, errorMsg);
+                        }
                     }
                 }
                 else if (skill.source.type === "git") {
+                    if (showProgress) {
+                        startSpinner(`${skill.name} ${progress}`);
+                    }
                     try {
                         await updateGitSkill(skill, index, projectRoot, config);
                         results.push({ name: skill.name, source: "git", status: "updated" });
+                        if (showProgress) {
+                            printSuccess(skill.name);
+                        }
                     }
                     catch (err) {
+                        const errorMsg = err instanceof Error ? err.message : "unknown error";
                         results.push({
                             name: skill.name,
                             source: "git",
                             status: "failed",
-                            error: err instanceof Error ? err.message : "unknown error",
+                            error: errorMsg,
                         });
+                        if (showProgress) {
+                            printFailure(skill.name, errorMsg);
+                        }
                     }
                 }
                 else {
                     results.push({ name: skill.name, source: skill.source.type, status: "skipped" });
+                    if (showProgress) {
+                        printSkipped(skill.name, "skipped");
+                    }
                 }
             }
+            if (showProgress) {
+                stopSpinner();
+            }
             await saveIndex(sortIndex(index));
             const sourceGroups = groupBySource(results);
             const totalUpdated = results.filter((r) => r.status === "updated").length;
@@ -189,21 +197,15 @@ export function registerUpdate(program) {
                 printInfo("No skills to update.");
                 return;
             }
-            printInfo("Skill Update");
-            for (const group of sourceGroups) {
-                printInfo("");
-                printSourceGroup(group);
-            }
             // Summary line
-            printInfo("");
             if (totalFailed > 0) {
-                printInfo(`Updated ${totalUpdated} of ${totalTrackable} trackable skills (${totalFailed} failed).`);
+                printInfo(`\nUpdated ${totalUpdated} of ${totalTrackable} trackable skill${totalTrackable === 1 ? "" : "s"} (${totalFailed} failed).`);
             }
             else if (totalUpdated > 0) {
-                printInfo(`Updated ${totalUpdated} of ${totalTrackable} trackable skills.`);
+                printInfo(`\nUpdated ${totalUpdated} of ${totalTrackable} trackable skill${totalTrackable === 1 ? "" : "s"}.`);
             }
             else if (totalSkipped > 0 && totalTrackable === 0) {
-                printInfo("No trackable skills to update.");
+                printInfo("\nNo trackable skills to update.");
             }
         }
         catch (error) {

package/dist/lib/agents.js

@@ -48,6 +48,12 @@ export function getUserAgentPaths(projectRoot) {
     return Object.values(paths).flatMap((entry) => entry.user);
 }
 export function getUserPathsForAgents(projectRoot, agents) {
+    return getPathsForAgents(projectRoot, agents, "user");
+}
+export function getProjectPathsForAgents(projectRoot, agents) {
+    return getPathsForAgents(projectRoot, agents, "project");
+}
+function getPathsForAgents(projectRoot, agents, scope) {
     const paths = agentPaths(projectRoot);
     const seen = new Set();
     const results = [];
@@ -56,12 +62,12 @@ export function getUserPathsForAgents(projectRoot, agents) {
         if (!agentEntry) {
             continue;
         }
-        for (const userPath of agentEntry.user) {
-            if (seen.has(userPath)) {
+        for (const pathValue of agentEntry[scope]) {
+            if (seen.has(pathValue)) {
                 continue;
             }
-            seen.add(userPath);
-            results.push({ agent, path: userPath });
+            seen.add(pathValue);
+            results.push({ agent, path: pathValue });
         }
     }
     return results;

package/dist/lib/fetcher.js

@@ -1,5 +1,44 @@
+import { execSync } from "node:child_process";
+const GITHUB_HOSTS = ["api.github.com", "raw.githubusercontent.com"];
+let cachedToken;
+function getGitHubToken() {
+    if (cachedToken !== undefined)
+        return cachedToken;
+    // Check environment variables first, then fall back to gh CLI
+    const envToken = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+    if (envToken) {
+        cachedToken = envToken;
+    }
+    else {
+        try {
+            cachedToken =
+                execSync("gh auth token", { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim() ||
+                    null;
+        }
+        catch {
+            cachedToken = null;
+        }
+    }
+    return cachedToken;
+}
+function isGitHubUrl(url) {
+    try {
+        const { host } = new URL(url);
+        return GITHUB_HOSTS.includes(host);
+    }
+    catch {
+        return false;
+    }
+}
 export async function fetchText(url) {
-    const response = await fetch(url);
+    const headers = {};
+    if (isGitHubUrl(url)) {
+        const token = getGitHubToken();
+        if (token) {
+            headers.Authorization = `Bearer ${token}`;
+        }
+    }
+    const response = await fetch(url, { headers });
     if (!response.ok) {
         throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
     }

package/dist/lib/index.js

@@ -29,9 +29,30 @@ export function upsertSkill(index, skill) {
         next.skills.push(skill);
         return next;
     }
-    next.skills[existingIndex] = { ...next.skills[existingIndex], ...skill };
+    const existing = next.skills[existingIndex];
+    const mergedInstalls = mergeInstalls(existing.installs, skill.installs);
+    next.skills[existingIndex] = { ...existing, ...skill, installs: mergedInstalls };
     return next;
 }
+function mergeInstalls(existing, incoming) {
+    if (!existing && !incoming)
+        return undefined;
+    if (!existing)
+        return incoming;
+    if (!incoming)
+        return existing;
+    // Dedupe by scope + agent + projectRoot combination
+    const seen = new Set();
+    const merged = [];
+    for (const install of [...existing, ...incoming]) {
+        const key = `${install.scope}:${install.agent}:${install.projectRoot ?? ""}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push(install);
+    }
+    return merged;
+}
 export function sortIndex(index) {
     const skills = [...index.skills].sort((a, b) => a.name.localeCompare(b.name));
     return { ...index, skills };

package/dist/lib/output.js

@@ -2,6 +2,48 @@ import chalk from "chalk";
 export function isJsonEnabled(options) {
     return Boolean(options.json);
 }
+// Progress indicator support
+const isTTY = process.stdout.isTTY ?? false;
+// Braille spinner frames (single character, smooth animation)
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+let spinnerInterval = null;
+let spinnerFrame = 0;
+export function startSpinner(message) {
+    if (!isTTY)
+        return;
+    spinnerFrame = 0;
+    const render = () => {
+        const frame = SPINNER_FRAMES[spinnerFrame % SPINNER_FRAMES.length];
+        process.stdout.write(`\r\x1b[K  ${frame} ${message}`);
+        spinnerFrame++;
+    };
+    render();
+    spinnerInterval = setInterval(render, 80);
+}
+export function stopSpinner() {
+    if (spinnerInterval) {
+        clearInterval(spinnerInterval);
+        spinnerInterval = null;
+    }
+    if (isTTY) {
+        process.stdout.write(`\r\x1b[K`);
+    }
+}
+export function printProgressResult(message) {
+    stopSpinner();
+    process.stdout.write(`${message}\n`);
+}
+// Common result formatters for progress output
+export function printSuccess(name, suffix) {
+    const msg = suffix ? `  ✓ ${name} (${suffix})` : `  ✓ ${name}`;
+    printProgressResult(msg);
+}
+export function printFailure(name, error) {
+    printProgressResult(`  ✗ ${name} (${error})`);
+}
+export function printSkipped(name, reason) {
+    printProgressResult(`  - ${name} (${reason})`);
+}
 export function printJson(result) {
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }

package/dist/lib/skill-store.js

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { skillboxSkillsDir } from "./paths.js";
+import { buildMetadata, parseSkillMarkdown } from "./skill-parser.js";
 export async function ensureSkillsDir() {
     await fs.mkdir(skillboxSkillsDir(), { recursive: true });
 }
@@ -26,3 +27,23 @@ export async function writeSkillMetadata(name, metadata) {
 export function hashContent(content) {
     return crypto.createHash("sha256").update(content).digest("hex");
 }
+/**
+ * Import a skill from a local directory. Reads the markdown, parses it,
+ * and writes to the skill store. Returns the data needed for index updates,
+ * or null if the skill is invalid (missing description).
+ */
+export async function importSkillFromDir(skillFile) {
+    const markdown = await fs.readFile(skillFile, "utf8");
+    const parsed = parseSkillMarkdown(markdown);
+    if (!parsed.description) {
+        return null;
+    }
+    const metadata = buildMetadata(parsed, { type: "local" });
+    await ensureSkillsDir();
+    await writeSkillFiles(metadata.name, markdown, metadata);
+    return {
+        name: metadata.name,
+        checksum: parsed.checksum,
+        updatedAt: metadata.updatedAt,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillbox",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Local-first, agent-agnostic skills manager",
   "license": "MIT",
   "author": "Christian Anagnostou",
@@ -33,18 +33,24 @@
     "lint:ci": "oxlint --deny-warnings",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ci": "vitest run --reporter=verbose --reporter=junit --outputFile=test-results.xml",
     "prepublishOnly": "npm run lint:ci && npm run format:check && npm run build"
   },
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
+    "terminal-link": "^3.0.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/node": "^20.11.19",
+    "execa": "^9.6.1",
     "oxfmt": "^0.16.0",
     "oxlint": "^0.16.0",
     "ts-node": "^10.9.2",
-    "typescript": "^5.4.2"
+    "typescript": "^5.4.2",
+    "vitest": "^4.0.18"
   }
 }