skillbox 0.3.1 → 0.3.3

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.1");
+program.name("skillbox").description("Local-first, agent-agnostic skills manager").version("0.3.3");
 registerAdd(program);
 registerAgent(program);
 registerConfig(program);

package/dist/commands/add-repo.js

@@ -1,7 +1,9 @@
+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 { buildProjectAgentPaths } from "../lib/project-paths.js";
 import { fetchRepoFile, listRepoSkills, normalizeRepoRef, writeRepoSkillDirectory, } from "../lib/repo-skills.js";
@@ -31,21 +33,22 @@ async function installSkillTargets(skillName, options, installs) {
     const projectEntry = await ensureProjectRegistered(projectRoot, scope);
     const paths = buildProjectAgentPaths(projectRoot, projectEntry);
     const config = await loadConfig();
+    const recordedPaths = new Set();
     for (const agent of agentList) {
         const map = paths[agent];
         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);
         }
-        for (const target of written) {
+        // 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,

package/dist/commands/add.js

@@ -1,8 +1,10 @@
+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 { buildProjectAgentPaths } from "../lib/project-paths.js";
 import { ensureProjectRegistered, resolveRuntime } from "../lib/runtime.js";
@@ -64,23 +66,24 @@ export function registerAdd(program) {
             const config = await loadConfig();
             const installed = [];
             const installs = [];
+            const recordedPaths = new Set();
             for (const agent of agentList) {
                 const map = paths[agent];
                 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);
                 }
-                if (written.length > 0) {
-                    installed.push({ agent, scope, targets: written });
-                    for (const target of written) {
+                // 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) {
                         installs.push({
                             scope,
                             agent,

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);
@@ -58,9 +83,28 @@ function groupByScope(skills) {
         });
     }
     if (projectSkills.length > 0) {
+        const projectRoots = new Map();
+        for (const skill of projectSkills) {
+            const roots = getProjectRoots(skill);
+            if (roots.length === 0) {
+                continue;
+            }
+            for (const root of roots) {
+                const existing = projectRoots.get(root) ?? [];
+                existing.push(skill);
+                projectRoots.set(root, existing);
+            }
+        }
+        const projectGroups = Array.from(projectRoots.entries())
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([projectRoot, skillsForProject]) => ({
+            projectRoot,
+            sourceGroups: groupBySourceType(skillsForProject),
+        }));
         result.push({
             scope: "project",
             sourceGroups: groupBySourceType(projectSkills),
+            projectGroups,
         });
     }
     return result;
@@ -71,15 +115,38 @@ function groupBySourceType(skills) {
     const grouped = groupAndSort(skills, (skill) => skill.source.type, LIST_SOURCE_ORDER, sortByName);
     return grouped.map(({ key, items }) => ({ source: key, skills: items }));
 }
+function getProjectRoots(skill) {
+    const roots = (skill.installs ?? [])
+        .filter((install) => install.scope === "project")
+        .map((install) => install.projectRoot)
+        .filter((root) => Boolean(root));
+    return Array.from(new Set(roots));
+}
 function printScopeGroup(group) {
     const label = group.scope === "global" ? "Global Skills" : "Project Skills";
     const totalCount = group.sourceGroups.reduce((sum, g) => sum + g.skills.length, 0);
     printInfo(`${label} (${totalCount})`);
+    if (group.scope === "project" && group.projectGroups) {
+        for (const projectGroup of group.projectGroups) {
+            printInfo("");
+            printInfo(projectGroup.projectRoot);
+            for (const sourceGroup of projectGroup.sourceGroups) {
+                printInfo(`  ${sourceGroup.source}`);
+                for (const skill of sourceGroup.skills) {
+                    printInfo(`    ${linkSkillName(skill)}`);
+                    if (skill.subcommands.length > 0) {
+                        printInfo(`      → ${skill.subcommands.join(", ")}`);
+                    }
+                }
+            }
+        }
+        return;
+    }
     for (const sourceGroup of group.sourceGroups) {
         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(", ")}`);
             }

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/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/installs.js

@@ -31,6 +31,17 @@ export function getInstallPaths(skill, projectRoot) {
         .filter((install) => install.projectRoot === projectRoot)
         .map((install) => install.path);
 }
+export function recordInstallPaths(paths, recorded) {
+    const deduped = [];
+    for (const path of paths) {
+        if (recorded.has(path)) {
+            continue;
+        }
+        recorded.add(path);
+        deduped.push(path);
+    }
+    return deduped;
+}
 export function getProjectInstallPaths(skills, projectRoot) {
     const map = new Map();
     for (const skill of skills) {

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/dist/lib/sync.js

@@ -58,9 +58,8 @@ export function buildSymlinkWarning(agent, results) {
 export async function installSkillToTargets(skillName, targets, config) {
     const sourceDir = skillDir(skillName);
     const results = [];
-    for (const targetRoot of targets) {
-        const targetDir = path.join(targetRoot, skillName);
-        await ensureDir(targetRoot);
+    for (const targetDir of targets) {
+        await ensureDir(path.dirname(targetDir));
         if (config.installMode === "symlink") {
             try {
                 const status = await createSymlink(sourceDir, targetDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillbox",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Local-first, agent-agnostic skills manager",
   "license": "MIT",
   "author": "Christian Anagnostou",
@@ -38,6 +38,7 @@
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
+    "terminal-link": "^3.0.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {