skillbox 0.2.0 → 0.2.2

package/README.md

@@ -13,68 +13,108 @@
 npm install -g skillbox
 ```
 
-
-
 ## Quick Start
 
-Skillbox will detect installed agents on your machine. If detection succeeds, `enter` accepts the detected list; if nothing is found, `enter` defaults to all agents or you can type a comma-separated list.
+Skillbox will detect installed agents on your machine. Repo and URL installs track their origin so updates stay one command away.
 
-Tip: run `skillbox list` right after install to see existing skills.
+> Tip: run `skillbox list` right after install to see existing skills.
+
+Skillbox links agent folders to the canonical store using symlinks on macOS/Linux and file copies on Windows.
 
 ```bash
+# install all repo skills
+skillbox add owner/repo
+# list skills in repo
+skillbox add owner/repo --list
+# install single repo skill
+skillbox add owner/repo --skill linting
+# add skill from URL
 skillbox add https://example.com/skills/linting/SKILL.md
+# list installed skills
 skillbox list
+# check for updates
 skillbox status
+# update one skill
 skillbox update linting
 ```
 
+Notes:
+- GitHub unauthenticated API limit: 60 req/hr per IP
+- use `skillbox convert` for non-skill URLs
+
 ## Commands
 
 ### Core Commands
 
 ```bash
+# add skill from URL
 skillbox add <url> [--name <name>] [--global] [--agents ...]
+# add skill(s) from repo
+skillbox add <repo> [--list] [--skill <name>] [--global] [--agents ...]
+# convert content to skill
 skillbox convert <url> [--name <name>] [--output <dir>] [--agent]
+# list skills
 skillbox list [--group=category|namespace|source|project] [--json]
+# check for updates
 skillbox status [--group=project|source] [--json]
-skillbox update [name] [--system] [--project <path>]
+# update skills
+skillbox update [name] [--project <path>]
+# remove skills
+skillbox remove <name> [--project <path>]
+# import existing skills
 skillbox import <path>
+# update metadata
 skillbox meta set <name> --category foo --tag bar --namespace baz
+# open agent REPL
 skillbox agent
 ```
 
 ### Project Commands
 
 ```bash
+# register project
 skillbox project add <path> [--agent-path agent=path]
+# list projects
 skillbox project list
+# show project details
 skillbox project inspect <path>
+# resync project skills
 skillbox project sync <path>
 ```
 
 ### Config
 
 ```bash
+# show config
 skillbox config get
+# set default scope
 skillbox config set --default-scope user
+# replace default agents
 skillbox config set --default-agent claude --default-agent cursor
+# add default agent
 skillbox config set --add-agent codex
-skillbox config set --manage-system
+# use symlink installs
+skillbox config set --install-mode symlink
+# use file copies
+skillbox config set --install-mode copy
 ```
 
 Config defaults live in `~/.config/skillbox/config.json`:
 
-- `defaultScope`: `project` (default) or `user`
+- `defaultScope`: `user` (default) or `project`
 - `defaultAgents`: empty array means all agents
-- `manageSystem`: `false` by default
+- `installMode`: `symlink` (macOS/Linux) or `copy` (Windows)
 
 ## Agent Mode
 
 Use `--json` for machine-readable output.
 
 ```bash
+# list skills (json)
 skillbox list --json
+# status check (json)
 skillbox status --json
+# update one skill (json)
 skillbox update linting --json
 ```
 
@@ -89,9 +129,21 @@ Common workflow:
 3) skillbox update <name> --json
 
 If you need to install a new skill from a URL, run:
+# add skill from URL
 skillbox add <url> [--name <name>]
 
+If you need a skill from a repo, run:
+# list skills in repo
+skillbox add owner/repo --list
+# install single repo skill
+skillbox add owner/repo --skill <name>
+# install all repo skills
+skillbox add owner/repo
+
+Note: GitHub unauthenticated API limits are 60 requests per hour per IP, so heavy repo usage may hit rate limits.
+
 If a URL is not a valid skill, run:
+# convert content to skill
 skillbox convert <url> --agent
 ```
 
@@ -114,12 +166,10 @@ Agent paths (default):
 - OpenCode: `.opencode/skills/`, `~/.config/opencode/skills/` (Claude-compatible `.claude/skills/` also supported)
 - Claude: `.claude/skills/`, `~/.claude/skills/`
 - Cursor: `.cursor/skills/`, `.claude/skills/`, `~/.cursor/skills/`, `~/.claude/skills/`
-- Codex: `$REPO_ROOT/.codex/skills/`, `~/.codex/skills/`, `/etc/codex/skills` (system)
+- Codex: `$REPO_ROOT/.codex/skills/`, `~/.codex/skills/`
 - Amp: `.agents/skills/`, `~/.config/agents/skills/` (Claude-compatible `.claude/skills/` also supported)
 - Antigravity: `.agent/skills/`, `~/.gemini/antigravity/skills/`
 
-Note: only Codex defines a system scope path.
-
 ## Usage with AI Agents
 
 ### Just ask the agent
@@ -153,7 +203,7 @@ git clone https://github.com/christiananagnostou/skillbox
 cd skillbox
 npm install
 npm run build
-npm link --global
+npm link
 ```
 
 ## License

package/dist/cli.js

@@ -10,6 +10,7 @@ import { registerMeta } from "./commands/meta.js";
 import { registerProject } from "./commands/project.js";
 import { registerAgent } from "./commands/agent.js";
 import { registerConfig } from "./commands/config.js";
+import { registerRemove } from "./commands/remove.js";
 const program = new Command();
 program.name("skillbox").description("Local-first, agent-agnostic skills manager").version("0.1.0");
 registerAdd(program);
@@ -22,6 +23,7 @@ registerMeta(program);
 registerProject(program);
 registerAgent(program);
 registerConfig(program);
+registerRemove(program);
 const run = async () => {
     const { runOnboarding } = await import("./lib/onboarding.js");
     await runOnboarding();

package/dist/commands/add-repo.js

@@ -0,0 +1,157 @@
+import { listRepoSkills, normalizeRepoRef, fetchRepoFile, writeRepoSkillDirectory, } from "../lib/repo-skills.js";
+import { parseSkillMarkdown, buildMetadata } from "../lib/skill-parser.js";
+import { writeSkillMetadata } from "../lib/skill-store.js";
+import { loadConfig } from "../lib/config.js";
+import { buildProjectAgentPaths } from "../lib/project-paths.js";
+import { resolveRuntime, ensureProjectRegistered } from "../lib/runtime.js";
+import { buildSymlinkWarning, buildTargets, installSkillToTargets } from "../lib/sync.js";
+import { loadIndex, saveIndex, sortIndex, upsertSkill } from "../lib/index.js";
+import { printInfo, printJson } from "../lib/output.js";
+import { parseRepoRef } from "../lib/github.js";
+import { getErrorMessage } from "../lib/command.js";
+const normalizeSkillSelection = (skills, selections) => {
+    if (selections.length === 0) {
+        return skills;
+    }
+    const selectionSet = new Set(selections);
+    return skills.filter((name) => selectionSet.has(name));
+};
+const ensureRepoRef = async (input) => {
+    const ref = parseRepoRef(input);
+    if (!ref) {
+        throw new Error("Unsupported repo URL or shorthand.");
+    }
+    return await normalizeRepoRef(ref);
+};
+const installSkillTargets = async (skillName, options, installs) => {
+    const { projectRoot, scope, agentList } = await resolveRuntime({
+        global: options.global,
+        agents: options.agents,
+    });
+    const projectEntry = await ensureProjectRegistered(projectRoot, scope);
+    const paths = buildProjectAgentPaths(projectRoot, projectEntry);
+    const config = await loadConfig();
+    for (const agent of agentList) {
+        const map = paths[agent];
+        if (!map) {
+            continue;
+        }
+        const targets = buildTargets(agent, map, scope).map((target) => target.path);
+        const results = await installSkillToTargets(skillName, targets, config);
+        const written = results
+            .filter((result) => result.mode !== "skipped")
+            .map((result) => result.path);
+        const warning = buildSymlinkWarning(agent, results);
+        if (warning) {
+            printInfo(warning);
+        }
+        if (written.length > 0) {
+            for (const target of written) {
+                installs.push({
+                    scope,
+                    agent,
+                    path: target,
+                    projectRoot: scope === "project" ? projectRoot : undefined,
+                });
+            }
+        }
+    }
+};
+export const isRepoUrl = (input) => {
+    return Boolean(parseRepoRef(input));
+};
+export const handleRepoInstall = async (input, options) => {
+    const ref = await ensureRepoRef(input);
+    const { skills } = await listRepoSkills(ref);
+    const skillNames = skills.map((skill) => skill.name).sort();
+    if (options.list) {
+        if (options.json) {
+            printJson({ ok: true, command: "add", data: { repo: input, skills: skillNames } });
+            return;
+        }
+        printInfo(`Skills found: ${skillNames.length}`);
+        for (const name of skillNames) {
+            printInfo(`- ${name}`);
+        }
+        return;
+    }
+    const selected = normalizeSkillSelection(skillNames, options.skill ?? []);
+    if (selected.length === 0) {
+        throw new Error("No matching skills found. Use --list to see available skills.");
+    }
+    const summary = { installed: [], updated: [], skipped: [], failed: [] };
+    const index = await loadIndex();
+    for (const skill of skills) {
+        if (!selected.includes(skill.name)) {
+            continue;
+        }
+        const alreadyInstalled = index.skills.some((entry) => entry.name === skill.name);
+        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);
+                continue;
+            }
+            await writeRepoSkillDirectory(ref, skill.path, skill.name);
+            const sourcePath = [ref.path, skill.path].filter(Boolean).join("/");
+            const source = {
+                type: "git",
+                repo: `${ref.owner}/${ref.repo}`,
+                path: sourcePath || undefined,
+                ref: ref.ref,
+            };
+            const metadata = buildMetadata(parsed, source, skill.name);
+            await writeSkillMetadata(skill.name, metadata);
+            const updated = upsertSkill(index, {
+                name: skill.name,
+                source,
+                checksum: parsed.checksum,
+                updatedAt: metadata.updatedAt,
+            });
+            const installs = [];
+            await installSkillTargets(skill.name, options, installs);
+            const nextIndex = upsertSkill(updated, {
+                name: skill.name,
+                source,
+                checksum: parsed.checksum,
+                updatedAt: metadata.updatedAt,
+                installs,
+            });
+            index.skills = nextIndex.skills;
+            if (alreadyInstalled) {
+                summary.updated.push(skill.name);
+            }
+            else {
+                summary.installed.push(skill.name);
+            }
+        }
+        catch (error) {
+            const message = getErrorMessage(error, "unknown");
+            summary.failed.push({ name: skill.name, reason: message });
+        }
+    }
+    await saveIndex(sortIndex(index));
+    if (options.json) {
+        printJson({ ok: true, command: "add", data: summary });
+        return;
+    }
+    if (summary.failed.length > 0) {
+        printInfo("Some skills failed to install:");
+        for (const failure of summary.failed) {
+            printInfo(`- ${failure.name}: ${failure.reason}`);
+        }
+    }
+    if (summary.installed.length > 0) {
+        printInfo(`Installed ${summary.installed.length} skill(s): ${summary.installed.join(", ")}`);
+    }
+    if (summary.updated.length > 0) {
+        printInfo(`Updated ${summary.updated.length} skill(s): ${summary.updated.join(", ")}`);
+    }
+    if (summary.skipped.length > 0) {
+        printInfo(`Skipped ${summary.skipped.length} skill(s): ${summary.skipped.join(", ")}`);
+    }
+    if (summary.installed.length === 0 && summary.updated.length === 0) {
+        printInfo("No agent targets were updated (canonical store only).");
+    }
+};

package/dist/commands/add.js

@@ -4,19 +4,33 @@ import { parseSkillMarkdown, inferNameFromUrl, buildMetadata } from "../lib/skil
 import { handleCommandError } from "../lib/command.js";
 import { ensureSkillsDir, writeSkillFiles } from "../lib/skill-store.js";
 import { loadIndex, saveIndex, sortIndex, upsertSkill } from "../lib/index.js";
-import { buildTargets, copySkillToTargets } from "../lib/sync.js";
+import { buildSymlinkWarning, buildTargets, installSkillToTargets } from "../lib/sync.js";
 import { buildProjectAgentPaths } from "../lib/project-paths.js";
 import { resolveRuntime, ensureProjectRegistered } from "../lib/runtime.js";
+import { loadConfig } from "../lib/config.js";
+import { handleRepoInstall, isRepoUrl } from "./add-repo.js";
 export const registerAdd = (program) => {
     program
         .command("add")
-        .argument("<url>", "Skill URL")
+        .argument("<url>", "Skill URL or repo")
         .option("--name <name>", "Override skill name")
         .option("--global", "Install to user scope")
         .option("--agents <list>", "Comma-separated agent list")
+        .option("--skill <skill>", "Skill name to install", collect)
+        .option("--list", "List skills in repo without installing")
         .option("--json", "JSON output")
         .action(async (url, options) => {
         try {
+            if (options.list || options.skill || isRepoUrl(url)) {
+                await handleRepoInstall(url, {
+                    global: options.global,
+                    agents: options.agents,
+                    json: options.json,
+                    list: options.list,
+                    skill: options.skill,
+                });
+                return;
+            }
             const skillMarkdown = await fetchText(url);
             const parsed = parseSkillMarkdown(skillMarkdown);
             const inferred = inferNameFromUrl(url);
@@ -46,6 +60,7 @@ export const registerAdd = (program) => {
             });
             const projectEntry = await ensureProjectRegistered(projectRoot, scope);
             const paths = buildProjectAgentPaths(projectRoot, projectEntry);
+            const config = await loadConfig();
             const installed = [];
             const installs = [];
             for (const agent of agentList) {
@@ -54,15 +69,24 @@ export const registerAdd = (program) => {
                     continue;
                 }
                 const targets = buildTargets(agent, map, scope).map((target) => target.path);
-                const written = await copySkillToTargets(skillName, targets);
-                installed.push({ agent, scope, targets: written });
-                for (const target of written) {
-                    installs.push({
-                        scope,
-                        agent,
-                        path: target,
-                        projectRoot: scope === "project" ? projectRoot : undefined,
-                    });
+                const results = await installSkillToTargets(skillName, targets, config);
+                const written = results
+                    .filter((result) => result.mode !== "skipped")
+                    .map((result) => result.path);
+                const warning = buildSymlinkWarning(agent, results);
+                if (warning) {
+                    printInfo(warning);
+                }
+                if (written.length > 0) {
+                    installed.push({ agent, scope, targets: written });
+                    for (const target of written) {
+                        installs.push({
+                            scope,
+                            agent,
+                            path: target,
+                            projectRoot: scope === "project" ? projectRoot : undefined,
+                        });
+                    }
                 }
             }
             const nextIndex = upsertSkill(updated, {
@@ -90,7 +114,7 @@ export const registerAdd = (program) => {
             printInfo(`Source: ${url}`);
             printInfo(`Scope: ${scope}`);
             if (installed.length === 0) {
-                printInfo("No agent targets were updated.");
+                printInfo("No agent targets were updated (canonical store only).");
             }
             else {
                 for (const entry of installed) {
@@ -103,3 +127,6 @@ export const registerAdd = (program) => {
         }
     });
 };
+const collect = (value, previous = []) => {
+    return [...previous, value];
+};

package/dist/commands/config.js

@@ -27,7 +27,7 @@ export const registerConfig = (program) => {
         .option("--default-agent <agent>", "Default agent", collect)
         .option("--add-agent <agent>", "Add to default agents", collect)
         .option("--default-scope <scope>", "Default scope: project or user")
-        .option("--manage-system", "Enable system scope operations")
+        .option("--install-mode <mode>", "Install mode: symlink or copy")
         .option("--json", "JSON output")
         .action(async (options) => {
         try {
@@ -39,11 +39,15 @@ export const registerConfig = (program) => {
             const addedAgents = options.addAgent ?? [];
             const nextAgents = options.defaultAgent ?? current.defaultAgents;
             const mergedAgents = Array.from(new Set([...(nextAgents ?? []), ...addedAgents].filter((agent) => agent.length > 0)));
+            const nextMode = options.installMode ?? current.installMode;
+            if (nextMode !== "symlink" && nextMode !== "copy") {
+                throw new Error("installMode must be 'symlink' or 'copy'.");
+            }
             const next = {
                 ...current,
                 defaultAgents: mergedAgents,
                 defaultScope: nextScope,
-                manageSystem: options.manageSystem ?? current.manageSystem,
+                installMode: nextMode,
             };
             await saveConfig(next);
             if (isJsonEnabled(options)) {

package/dist/commands/import.js

@@ -6,24 +6,20 @@ import { ensureSkillsDir, writeSkillFiles } from "../lib/skill-store.js";
 import { loadIndex, saveIndex, sortIndex, upsertSkill } from "../lib/index.js";
 import { handleCommandError } from "../lib/command.js";
 import { discoverSkills } from "../lib/discovery.js";
-import { getSystemAgentPaths, getUserAgentPaths } from "../lib/agents.js";
+import { getUserAgentPaths } from "../lib/agents.js";
 export const registerImport = (program) => {
     program
         .command("import")
         .argument("[path]", "Path to skill directory")
         .option("--global", "Import skills from user agent folders")
-        .option("--system", "Import skills from system agent folders")
         .option("--json", "JSON output")
         .action(async (inputPath, options) => {
         try {
-            if (!inputPath && !options.global && !options.system) {
-                throw new Error("Provide a path or use --global/--system.");
+            if (!inputPath && !options.global) {
+                throw new Error("Provide a path or use --global.");
             }
-            if (options.global || options.system) {
-                const summary = await importGlobalSkills({
-                    includeUser: Boolean(options.global),
-                    includeSystem: Boolean(options.system),
-                });
+            if (options.global) {
+                const summary = await importGlobalSkills();
                 if (isJsonEnabled(options)) {
                     printJson({
                         ok: true,
@@ -71,27 +67,24 @@ export const registerImport = (program) => {
         }
     });
 };
-const importGlobalSkills = async (options) => {
+const importGlobalSkills = async () => {
     const projectRoot = process.cwd();
-    const paths = [
-        ...(options.includeUser ? getUserAgentPaths(projectRoot) : []),
-        ...(options.includeSystem ? getSystemAgentPaths(projectRoot) : []),
-    ];
+    const paths = getUserAgentPaths(projectRoot);
     const discovered = await discoverSkills(paths);
     const index = await loadIndex();
     const seen = new Set(index.skills.map((skill) => skill.name));
-    const imported = [];
-    const skipped = [];
+    const imported = new Set();
+    const skipped = new Set();
     for (const skill of discovered) {
         if (seen.has(skill.name)) {
-            skipped.push(skill.name);
+            skipped.add(skill.name);
             continue;
         }
         const markdown = await fs.readFile(skill.skillFile, "utf8");
         const parsed = parseSkillMarkdown(markdown);
         const metadata = buildMetadata(parsed, { type: "local" });
         if (!parsed.description) {
-            skipped.push(skill.name);
+            skipped.add(skill.name);
             continue;
         }
         await ensureSkillsDir();
@@ -103,18 +96,18 @@ const importGlobalSkills = async (options) => {
             updatedAt: metadata.updatedAt,
             installs: [
                 {
-                    scope: options.includeSystem ? "system" : "user",
+                    scope: "user",
                     agent: "unknown",
                     path: skill.skillDir,
                 },
             ],
         });
         index.skills = next.skills;
-        imported.push(metadata.name);
+        imported.add(metadata.name);
     }
     await saveIndex(sortIndex(index));
     return {
-        imported: imported.sort(),
-        skipped: skipped.sort(),
+        imported: Array.from(imported).sort(),
+        skipped: Array.from(skipped).sort(),
     };
 };

package/dist/commands/list.js

@@ -6,11 +6,10 @@ export const registerList = (program) => {
     program
         .command("list")
         .option("--group <group>", "Group by category, namespace, source, project")
-        .option("--project-only", "Only show project-indexed skills")
         .option("--json", "JSON output")
         .action(async (options) => {
         const index = await loadIndex();
-        const globalSkills = options.projectOnly ? [] : await listGlobalSkills(index.skills);
+        const globalSkills = await listGlobalSkills(index.skills);
         const skills = [...index.skills, ...globalSkills];
         const groupedProjects = groupByProject(skills);
         const groupedSources = groupBySource(skills);

package/dist/commands/remove.js

@@ -0,0 +1,76 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
+import { loadIndex, saveIndex, sortIndex } from "../lib/index.js";
+import { skillDir } from "../lib/skill-store.js";
+import { handleCommandError } from "../lib/command.js";
+const removePaths = async (paths) => {
+    for (const target of paths) {
+        await fs.rm(target, { recursive: true, force: true });
+    }
+};
+export const registerRemove = (program) => {
+    program
+        .command("remove")
+        .argument("<name>", "Skill name")
+        .option("--project <path>", "Only remove installs for a project")
+        .option("--json", "JSON output")
+        .action(async (name, options) => {
+        try {
+            const index = await loadIndex();
+            const skill = index.skills.find((entry) => entry.name === name);
+            if (!skill) {
+                throw new Error(`Skill not found: ${name}`);
+            }
+            const projectRoot = options.project ? path.resolve(options.project) : null;
+            const installs = skill.installs ?? [];
+            const toRemove = projectRoot
+                ? installs.filter((install) => install.scope === "project" &&
+                    install.projectRoot &&
+                    install.projectRoot === projectRoot)
+                : installs;
+            if (projectRoot && toRemove.length === 0) {
+                throw new Error(`No installs found for ${name} in ${projectRoot}.`);
+            }
+            const removedPaths = toRemove.map((install) => install.path);
+            await removePaths(removedPaths);
+            let removedCanonical = false;
+            if (projectRoot) {
+                const remaining = installs.filter((install) => !(install.scope === "project" &&
+                    install.projectRoot &&
+                    install.projectRoot === projectRoot));
+                index.skills = index.skills.map((entry) => entry.name === name
+                    ? { ...entry, installs: remaining.length > 0 ? remaining : undefined }
+                    : entry);
+            }
+            else {
+                index.skills = index.skills.filter((entry) => entry.name !== name);
+                await fs.rm(skillDir(name), { recursive: true, force: true });
+                removedCanonical = true;
+            }
+            await saveIndex(sortIndex(index));
+            if (isJsonEnabled(options)) {
+                printJson({
+                    ok: true,
+                    command: "remove",
+                    data: {
+                        name,
+                        project: projectRoot,
+                        removed: removedPaths,
+                        removedCanonical,
+                    },
+                });
+                return;
+            }
+            if (projectRoot) {
+                printInfo(`Removed ${removedPaths.length} install(s) for ${name} in ${projectRoot}.`);
+            }
+            else {
+                printInfo(`Removed ${name} and ${removedPaths.length} install(s).`);
+            }
+        }
+        catch (error) {
+            handleCommandError(options, "remove", error);
+        }
+    });
+};

package/dist/commands/status.js

@@ -3,7 +3,6 @@ import { loadIndex, saveIndex } from "../lib/index.js";
 import { fetchText } from "../lib/fetcher.js";
 import { hashContent } from "../lib/skill-store.js";
 import { groupStatusByKey } from "../lib/grouping.js";
-import { loadConfig } from "../lib/config.js";
 import { handleCommandError } from "../lib/command.js";
 export const registerStatus = (program) => {
     program
@@ -13,25 +12,11 @@ export const registerStatus = (program) => {
         .action(async (options) => {
         try {
             const index = await loadIndex();
-            const config = await loadConfig();
             const results = [];
             for (const skill of index.skills) {
                 const projects = Array.from(new Set((skill.installs ?? [])
                     .filter((install) => install.scope === "project" && install.projectRoot)
                     .map((install) => install.projectRoot)));
-                const allowSystem = config.manageSystem;
-                const isSystem = (skill.installs ?? []).some((install) => install.scope === "system");
-                if (isSystem && !allowSystem) {
-                    results.push({
-                        name: skill.name,
-                        source: skill.source.type,
-                        outdated: false,
-                        localChecksum: skill.checksum,
-                        projects,
-                        system: true,
-                    });
-                    continue;
-                }
                 if (skill.source.type !== "url" || !skill.source.url) {
                     results.push({
                         name: skill.name,
@@ -39,7 +24,6 @@ export const registerStatus = (program) => {
                         outdated: false,
                         localChecksum: skill.checksum,
                         projects,
-                        system: isSystem,
                     });
                     continue;
                 }
@@ -54,7 +38,6 @@ export const registerStatus = (program) => {
                     localChecksum: skill.checksum,
                     remoteChecksum,
                     projects,
-                    system: false,
                 });
             }
             await saveIndex(index);

package/dist/commands/update.js

@@ -2,51 +2,89 @@ import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
 import { loadIndex, saveIndex, sortIndex, upsertSkill } from "../lib/index.js";
 import { fetchText } from "../lib/fetcher.js";
 import { parseSkillMarkdown, buildMetadata } from "../lib/skill-parser.js";
-import { ensureSkillsDir, writeSkillFiles } from "../lib/skill-store.js";
-import { copySkillToInstallPaths } from "../lib/sync.js";
+import { ensureSkillsDir, writeSkillFiles, writeSkillMetadata } from "../lib/skill-store.js";
 import path from "node:path";
-import { loadConfig } from "../lib/config.js";
+import { installSkillToTargets } from "../lib/sync.js";
 import { handleCommandError } from "../lib/command.js";
+import { loadConfig } from "../lib/config.js";
+import { fetchRepoFile, normalizeRepoRef, writeRepoSkillDirectory } from "../lib/repo-skills.js";
+import { getInstallPaths } from "../lib/installs.js";
 export const registerUpdate = (program) => {
     program
         .command("update")
         .argument("[name]", "Skill name")
-        .option("--system", "Allow system-scope updates")
         .option("--project <path>", "Only update installs for a project")
         .option("--json", "JSON output")
         .action(async (name, options) => {
         try {
             const index = await loadIndex();
-            const config = await loadConfig();
             const targets = name ? index.skills.filter((skill) => skill.name === name) : index.skills;
             if (name && targets.length === 0) {
                 throw new Error(`Skill not found: ${name}`);
             }
             const updated = [];
             await ensureSkillsDir();
+            const config = await loadConfig();
             const projectRoot = options.project ? path.resolve(options.project) : null;
             for (const skill of targets) {
-                if (skill.source.type !== "url" || !skill.source.url) {
+                if (skill.source.type === "url" && skill.source.url) {
+                    const markdown = await fetchText(skill.source.url);
+                    const parsed = parseSkillMarkdown(markdown);
+                    if (!parsed.description) {
+                        throw new Error(`Skill ${skill.name} is missing a description after update.`);
+                    }
+                    const metadata = buildMetadata(parsed, { type: "url", url: skill.source.url }, skill.name);
+                    await writeSkillFiles(skill.name, markdown, metadata);
+                    const installPaths = getInstallPaths(skill, projectRoot);
+                    if (installPaths.length > 0) {
+                        await installSkillToTargets(skill.name, installPaths, config);
+                    }
+                    const nextIndex = upsertSkill(index, {
+                        name: skill.name,
+                        source: { type: "url", url: skill.source.url },
+                        checksum: parsed.checksum,
+                        updatedAt: metadata.updatedAt,
+                        lastSync: new Date().toISOString(),
+                    });
+                    index.skills = nextIndex.skills;
+                    updated.push(skill.name);
                     continue;
                 }
-                const markdown = await fetchText(skill.source.url);
+                if (skill.source.type !== "git" || !skill.source.repo) {
+                    continue;
+                }
+                const [owner, repo] = skill.source.repo.split("/");
+                if (!owner || !repo) {
+                    continue;
+                }
+                const skillPath = skill.source.path?.replace(/\/$/, "") ?? "";
+                const ref = await normalizeRepoRef({
+                    owner,
+                    repo,
+                    ref: skill.source.ref ?? "main",
+                });
+                const skillFilePath = skillPath ? `${skillPath}/SKILL.md` : "SKILL.md";
+                const markdown = await fetchRepoFile(ref, skillFilePath);
                 const parsed = parseSkillMarkdown(markdown);
                 if (!parsed.description) {
                     throw new Error(`Skill ${skill.name} is missing a description after update.`);
                 }
-                const metadata = buildMetadata(parsed, { type: "url", url: skill.source.url }, skill.name);
-                await writeSkillFiles(skill.name, markdown, metadata);
-                const allowSystem = options.system || config.manageSystem;
-                const installPaths = (skill.installs ?? [])
-                    .filter((install) => allowSystem || install.scope !== "system")
-                    .filter((install) => !projectRoot || install.projectRoot === projectRoot)
-                    .map((install) => install.path);
+                await writeRepoSkillDirectory(ref, skillPath, skill.name);
+                const source = {
+                    type: "git",
+                    repo: skill.source.repo,
+                    path: skillPath || undefined,
+                    ref: ref.ref,
+                };
+                const metadata = buildMetadata(parsed, source, skill.name);
+                await writeSkillMetadata(skill.name, metadata);
+                const installPaths = getInstallPaths(skill, projectRoot);
                 if (installPaths.length > 0) {
-                    await copySkillToInstallPaths(skill.name, installPaths);
+                    await installSkillToTargets(skill.name, installPaths, config);
                 }
                 const nextIndex = upsertSkill(index, {
                     name: skill.name,
-                    source: { type: "url", url: skill.source.url },
+                    source,
                     checksum: parsed.checksum,
                     updatedAt: metadata.updatedAt,
                     lastSync: new Date().toISOString(),
@@ -61,7 +99,6 @@ export const registerUpdate = (program) => {
                     command: "update",
                     data: {
                         name: name ?? null,
-                        system: Boolean(options.system),
                         project: projectRoot,
                         updated,
                     },

package/dist/lib/agents.js

@@ -23,7 +23,6 @@ export const agentPaths = (projectRoot) => ({
     codex: {
         project: [path.join(projectRoot, ".codex", "skills")],
         user: [path.join(home, ".codex", "skills")],
-        system: [path.join(path.sep, "etc", "codex", "skills")],
     },
     amp: {
         project: [
@@ -42,10 +41,6 @@ export const getUserAgentPaths = (projectRoot) => {
     const paths = agentPaths(projectRoot);
     return Object.values(paths).flatMap((entry) => entry.user);
 };
-export const getSystemAgentPaths = (projectRoot) => {
-    const paths = agentPaths(projectRoot);
-    return Object.values(paths).flatMap((entry) => entry.system ?? []);
-};
 const agentSet = new Set(allAgents);
 export const isAgentId = (value) => {
     return agentSet.has(value);

package/dist/lib/command.js

@@ -1,6 +1,9 @@
 import { isJsonEnabled, printError, printJson } from "./output.js";
+export const getErrorMessage = (error, fallback = "Unexpected error") => {
+    return error instanceof Error ? error.message : fallback;
+};
 export const handleCommandError = (options, command, error) => {
-    const message = error instanceof Error ? error.message : "Unexpected error";
+    const message = getErrorMessage(error);
     if (isJsonEnabled(options)) {
         printJson({ ok: false, command, error: { message } });
         return;

package/dist/lib/config.js

@@ -1,11 +1,14 @@
 import fs from "node:fs/promises";
 import { skillboxRoot } from "./paths.js";
 import path from "node:path";
+const defaultInstallMode = () => {
+    return process.platform === "win32" ? "copy" : "symlink";
+};
 const defaultConfig = () => ({
     version: 1,
     defaultAgents: [],
-    defaultScope: "project",
-    manageSystem: false,
+    defaultScope: "user",
+    installMode: defaultInstallMode(),
 });
 export const configPath = () => path.join(skillboxRoot(), "config.json");
 export const loadConfig = async () => {

package/dist/lib/github.js

@@ -0,0 +1,43 @@
+import { fetchText } from "./fetcher.js";
+const repoUrlRegex = /^https?:\/\/github\.com\/(.+?)\/(.+?)(?:\.git)?(?:\/)?$/i;
+const treeUrlRegex = /^https?:\/\/github\.com\/(.+?)\/(.+?)\/tree\/([^/]+)\/(.+)$/i;
+export const parseRepoRef = (input) => {
+    if (input.includes("github.com") && input.includes("/tree/")) {
+        const match = input.match(treeUrlRegex);
+        if (!match) {
+            return null;
+        }
+        return {
+            owner: match[1],
+            repo: match[2],
+            ref: match[3],
+            path: match[4],
+        };
+    }
+    if (!input.includes("github.com") && input.includes("/")) {
+        const [owner, repo] = input.split("/");
+        if (!owner || !repo) {
+            return null;
+        }
+        return { owner, repo, ref: "main" };
+    }
+    if (input.includes("github.com")) {
+        const match = input.match(repoUrlRegex);
+        if (!match) {
+            return null;
+        }
+        return {
+            owner: match[1],
+            repo: match[2].replace(/\.git$/, ""),
+            ref: "main",
+        };
+    }
+    return null;
+};
+export const buildRawUrl = (ref, filePath) => {
+    return `https://raw.githubusercontent.com/${ref.owner}/${ref.repo}/${ref.ref}/${filePath}`;
+};
+export const fetchJson = async (url) => {
+    const response = await fetchText(url);
+    return JSON.parse(response);
+};

package/dist/lib/global-skills.js

@@ -1,36 +1,16 @@
-import { getUserAgentPaths, getSystemAgentPaths } from "./agents.js";
+import { getUserAgentPaths } from "./agents.js";
 import { discoverSkills } from "./discovery.js";
 export const discoverGlobalSkills = async (projectRoot) => {
     const userPaths = getUserAgentPaths(projectRoot);
-    const systemPaths = getSystemAgentPaths(projectRoot);
-    const [userSkills, systemSkills] = await Promise.all([
-        discoverSkills(userPaths),
-        discoverSkills(systemPaths),
-    ]);
-    const entries = [];
-    for (const skill of userSkills) {
-        entries.push({
-            name: skill.name,
-            installs: [
-                {
-                    scope: "user",
-                    agent: "unknown",
-                    path: skill.skillDir,
-                },
-            ],
-        });
-    }
-    for (const skill of systemSkills) {
-        entries.push({
-            name: skill.name,
-            installs: [
-                {
-                    scope: "system",
-                    agent: "unknown",
-                    path: skill.skillDir,
-                },
-            ],
-        });
-    }
-    return entries;
+    const userSkills = await discoverSkills(userPaths);
+    return userSkills.map((skill) => ({
+        name: skill.name,
+        installs: [
+            {
+                scope: "user",
+                agent: "unknown",
+                path: skill.skillDir,
+            },
+        ],
+    }));
 };

package/dist/lib/installs.js

@@ -21,13 +21,19 @@ export const getProjectSkills = (skills, projectRoot) => {
     const map = collectProjectSkills(skills);
     return (map.get(projectRoot) ?? []).sort();
 };
+export const getInstallPaths = (skill, projectRoot) => {
+    if (!projectRoot) {
+        return (skill.installs ?? []).map((install) => install.path);
+    }
+    return (skill.installs ?? [])
+        .filter(projectInstalls)
+        .filter((install) => install.projectRoot === projectRoot)
+        .map((install) => install.path);
+};
 export const getProjectInstallPaths = (skills, projectRoot) => {
     const map = new Map();
     for (const skill of skills) {
-        const paths = (skill.installs ?? [])
-            .filter(projectInstalls)
-            .filter((install) => install.projectRoot === projectRoot)
-            .map((install) => install.path);
+        const paths = getInstallPaths(skill, projectRoot);
         if (paths.length > 0) {
             map.set(skill.name, paths);
         }

package/dist/lib/repo-skills.js

@@ -0,0 +1,136 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fetchJson, buildRawUrl, parseRepoRef } from "./github.js";
+import { fetchText } from "./fetcher.js";
+import { ensureSkillsDir, skillDir } from "./skill-store.js";
+const skillRoots = [
+    "skills",
+    "skill",
+    ".skills",
+    ".skill",
+    "agents/skills",
+    ".claude/skills",
+    ".codex/skills",
+    ".cursor/skills",
+    ".opencode/skills",
+];
+const buildTreeUrl = (ref) => {
+    return `https://api.github.com/repos/${ref.owner}/${ref.repo}/git/trees/${ref.ref}?recursive=1`;
+};
+const normalizeSkillPath = (filePath, basePath) => {
+    if (!filePath.endsWith("/SKILL.md") && filePath !== "SKILL.md") {
+        return null;
+    }
+    const normalized = basePath ? filePath.replace(`${basePath}/`, "") : filePath;
+    const segments = normalized.split("/");
+    if (segments.length === 1) {
+        const name = basePath ? (basePath.split("/").filter(Boolean).pop() ?? "root") : "root";
+        return {
+            name,
+            path: "",
+            skillFile: normalized,
+        };
+    }
+    return {
+        name: segments[segments.length - 2],
+        path: segments.slice(0, -1).join("/"),
+        skillFile: normalized,
+    };
+};
+const normalizeSkillFile = (skillPath) => {
+    return skillPath ? `${skillPath}/SKILL.md` : "SKILL.md";
+};
+const filterSkills = (entries, basePath, includeAll = false) => {
+    const skills = [];
+    for (const entry of entries) {
+        if (entry.type !== "blob") {
+            continue;
+        }
+        if (basePath &&
+            !entry.path.startsWith(`${basePath}/`) &&
+            entry.path !== `${basePath}/SKILL.md`) {
+            continue;
+        }
+        const skill = normalizeSkillPath(entry.path, basePath);
+        if (!skill) {
+            continue;
+        }
+        skills.push(skill);
+    }
+    if (basePath) {
+        return skills;
+    }
+    if (includeAll) {
+        return skills;
+    }
+    return skills.filter((skill) => {
+        const isRoot = skill.skillFile === "SKILL.md";
+        if (isRoot) {
+            return true;
+        }
+        return skillRoots.some((root) => skill.path.startsWith(root));
+    });
+};
+export const listRepoSkills = async (input) => {
+    const ref = typeof input === "string" ? parseRepoRef(input) : input;
+    if (!ref) {
+        throw new Error("Unsupported repo URL or shorthand.");
+    }
+    const normalized = await normalizeRepoRef(ref);
+    const tree = await fetchJson(buildTreeUrl(normalized));
+    const includeAll = normalized.repo.toLowerCase() === "skills" && !normalized.path;
+    const skills = filterSkills(tree.tree, normalized.path, includeAll);
+    if (skills.length === 0) {
+        throw new Error("No skills found in repository.");
+    }
+    return { ref: normalized, skills };
+};
+export const listRepoFiles = async (ref, skill, basePath) => {
+    const tree = await fetchJson(buildTreeUrl(ref));
+    const prefix = basePath ? [basePath, skill.path].filter(Boolean).join("/") : skill.path;
+    const files = tree.tree
+        .filter((entry) => entry.type === "blob")
+        .map((entry) => entry.path)
+        .filter((filePath) => (prefix ? filePath.startsWith(`${prefix}/`) : true))
+        .map((filePath) => (basePath ? filePath.replace(`${basePath}/`, "") : filePath));
+    if (files.length === 0) {
+        return [skill.skillFile];
+    }
+    return files;
+};
+export const fetchRepoFile = async (ref, filePath) => {
+    return await fetchText(buildRawUrl(ref, filePath));
+};
+export const writeRepoSkillDirectory = async (ref, skillPath, skillName) => {
+    const normalizedSkillPath = skillPath.replace(/\/$/, "");
+    const files = await listRepoFiles(ref, {
+        name: skillName,
+        path: normalizedSkillPath,
+        skillFile: normalizeSkillFile(normalizedSkillPath),
+    }, ref.path);
+    const targetDir = skillDir(skillName);
+    await ensureSkillsDir();
+    await fs.mkdir(targetDir, { recursive: true });
+    for (const file of files) {
+        const filePath = ref.path ? `${ref.path}/${file}` : file;
+        const content = await fetchRepoFile(ref, filePath);
+        const relative = normalizedSkillPath ? file.replace(`${normalizedSkillPath}/`, "") : file;
+        const targetPath = path.join(targetDir, relative);
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        await fs.writeFile(targetPath, content, "utf8");
+    }
+};
+export const normalizeRepoRef = async (ref) => {
+    try {
+        await fetchJson(buildTreeUrl(ref));
+        return ref;
+    }
+    catch {
+        if (ref.ref === "main") {
+            const fallback = { ...ref, ref: "master" };
+            await fetchJson(buildTreeUrl(fallback));
+            return fallback;
+        }
+        throw new Error("Unable to resolve repository ref.");
+    }
+};

package/dist/lib/sync.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { skillDir } from "./skill-store.js";
+import { getErrorMessage } from "./command.js";
 export const ensureDir = async (dir) => {
     await fs.mkdir(dir, { recursive: true });
 };
@@ -16,16 +17,42 @@ const copyFiles = async (sourceDir, targetDir) => {
         await fs.copyFile(sourcePath, destPath);
     }
 };
-export const copySkillToTargets = async (skillName, targets) => {
+const createSymlink = async (sourceDir, targetDir) => {
+    await fs.symlink(sourceDir, targetDir, "dir");
+};
+export const buildSymlinkWarning = (agent, results) => {
+    const skipped = results.filter((result) => result.mode === "skipped");
+    if (skipped.length === 0) {
+        return null;
+    }
+    const details = skipped
+        .map((result) => `${result.path}: ${result.error ?? "unknown error"}`)
+        .join("; ");
+    return `Warning: symlink failed for ${agent}. ${details}. Remove the existing target or run "skillbox config set --install-mode copy" to use file copies.`;
+};
+export const installSkillToTargets = async (skillName, targets, config) => {
     const sourceDir = skillDir(skillName);
-    const writtenPaths = [];
+    const results = [];
     for (const targetRoot of targets) {
         const targetDir = path.join(targetRoot, skillName);
+        await ensureDir(targetRoot);
+        if (config.installMode === "symlink") {
+            try {
+                await createSymlink(sourceDir, targetDir);
+                results.push({ path: targetDir, mode: "symlink" });
+                continue;
+            }
+            catch (error) {
+                const message = getErrorMessage(error, "unknown error");
+                results.push({ path: targetDir, mode: "skipped", error: message });
+                continue;
+            }
+        }
         await ensureDir(targetDir);
         await copyFiles(sourceDir, targetDir);
-        writtenPaths.push(targetDir);
+        results.push({ path: targetDir, mode: "copy" });
     }
-    return writtenPaths;
+    return results;
 };
 export const copySkillToInstallPaths = async (skillName, installPaths) => {
     const sourceDir = skillDir(skillName);
@@ -35,9 +62,6 @@ export const copySkillToInstallPaths = async (skillName, installPaths) => {
     }
 };
 export const buildTargets = (agent, paths, scope) => {
-    if (scope === "system") {
-        return (paths.system ?? []).map((pathValue) => ({ agent, scope, path: pathValue }));
-    }
     const list = scope === "user" ? paths.user : paths.project;
     return list.map((pathValue) => ({ agent, scope, path: pathValue }));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillbox",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Local-first, agent-agnostic skills manager",
   "license": "MIT",
   "author": "Christian Anagnostou",