skillbox 0.2.1 → 0.3.0

package/README.md

@@ -1,150 +1,118 @@
-# skillbox
+# Skillbox
 
-> Local-first, agent-agnostic skills manager. Track, update, and sync skills across popular AI coding agents with one CLI.
+> Local-first, agent-agnostic skills manager for AI coding agents.
 
 [![CI](https://github.com/christiananagnostou/skillbox/actions/workflows/ci.yml/badge.svg)](https://github.com/christiananagnostou/skillbox/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/skillbox.svg)](https://www.npmjs.com/package/skillbox)
 
-## Installation
-
-### npm (recommended)
+## Install
 
 ```bash
 npm install -g skillbox
 ```
 
+On first run, Skillbox auto-detects your installed agents and configures itself.
 
-
-## 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.
-
-Tip: run `skillbox list` right after install to see existing skills.
-
-```bash
-skillbox add https://example.com/skills/linting/SKILL.md
-skillbox list
-skillbox status
-skillbox update linting
-```
-
-## Commands
-
-### Core Commands
-
-```bash
-skillbox add <url> [--name <name>] [--global] [--agents ...]
-skillbox convert <url> [--name <name>] [--output <dir>] [--agent]
-skillbox list [--group=category|namespace|source|project] [--json]
-skillbox status [--group=project|source] [--json]
-skillbox update [name] [--system] [--project <path>]
-skillbox import <path>
-skillbox meta set <name> --category foo --tag bar --namespace baz
-skillbox agent
-```
-
-### Project Commands
-
-```bash
-skillbox project add <path> [--agent-path agent=path]
-skillbox project list
-skillbox project inspect <path>
-skillbox project sync <path>
-```
-
-### Config
+**Quick start:** Install the skillbox skill to teach your agent how to manage skills:
 
 ```bash
-skillbox config get
-skillbox config set --default-scope user
-skillbox config set --default-agent claude --default-agent cursor
-skillbox config set --add-agent codex
-skillbox config set --manage-system
+skillbox add christiananagnostou/skillbox
 ```
 
-Config defaults live in `~/.config/skillbox/config.json`:
-
-- `defaultScope`: `project` (default) or `user`
-- `defaultAgents`: empty array means all agents
-- `manageSystem`: `false` by default
-
-## Agent Mode
+## Golden Workflow
 
-Use `--json` for machine-readable output.
+These three commands cover most use cases:
 
 ```bash
-skillbox list --json
-skillbox status --json
-skillbox update linting --json
+skillbox list              # see installed skills
+skillbox status            # check for updates
+skillbox update [name]     # update skills
 ```
 
-### Agent Usage Snippet
+## Adding Skills
 
-```text
-Use skillbox for skill management.
+| Command | Description |
+|---------|-------------|
+| `skillbox add owner/repo` | Install all skills from a GitHub repo |
+| `skillbox add owner/repo --list` | List available skills in a repo |
+| `skillbox add owner/repo --skill name` | Install a specific skill from a repo |
+| `skillbox add <url>` | Install skill from a direct URL |
+| `skillbox add <url> --name my-skill` | Install with custom name |
 
-Common workflow:
-1) skillbox list --json
-2) skillbox status --json
-3) skillbox update <name> --json
+> **Note:** GitHub unauthenticated API limit is 60 requests/hour per IP.
 
-If you need to install a new skill from a URL, run:
-skillbox add <url> [--name <name>]
+## All Commands
 
-If a URL is not a valid skill, run:
-skillbox convert <url> --agent
-```
+### Skills
 
-## Skill Locations
+| Command | Description |
+|---------|-------------|
+| `skillbox list` | List installed skills |
+| `skillbox status` | Check for outdated skills |
+| `skillbox update [name]` | Update all or one skill |
+| `skillbox remove <name>` | Remove a skill |
+| `skillbox import <path>` | Import existing skill directory |
+| `skillbox import --global` | Import all skills from agent folders |
 
-Skillbox maintains a canonical store and syncs into agent-native folders.
+### Config
 
-Canonical store:
+| Command | Description |
+|---------|-------------|
+| `skillbox config get` | Show current config |
+| `skillbox config set --add-agent <name>` | Add an agent |
+| `skillbox config set --default-scope <scope>` | Set default scope (`user` or `project`) |
+| `skillbox config set --install-mode <mode>` | Set install mode (`symlink` or `copy`) |
 
-- `~/.config/skillbox/skills/<name>/`
+### Projects
 
-Index + config:
+| Command | Description |
+|---------|-------------|
+| `skillbox project add <path>` | Register a project |
+| `skillbox project list` | List registered projects |
+| `skillbox project sync <path>` | Re-sync skills to a project |
 
-- `~/.config/skillbox/index.json`
-- `~/.config/skillbox/projects.json`
-- `~/.config/skillbox/config.json`
+## Supported Agents
 
-Agent paths (default):
+| Agent | User Path | Project Path |
+|-------|-----------|--------------|
+| Claude | `~/.claude/skills/` | `.claude/skills/` |
+| Cursor | `~/.cursor/skills/` | `.cursor/skills/` |
+| Codex | `~/.codex/skills/` | `.codex/skills/` |
+| OpenCode | `~/.config/opencode/skills/` | `.opencode/skills/` |
+| Amp | `~/.config/agents/skills/` | `.agents/skills/` |
+| Antigravity | `~/.gemini/antigravity/skills/` | `.agent/skills/` |
 
-- 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)
-- Amp: `.agents/skills/`, `~/.config/agents/skills/` (Claude-compatible `.claude/skills/` also supported)
-- Antigravity: `.agent/skills/`, `~/.gemini/antigravity/skills/`
+## JSON Mode
 
-Note: only Codex defines a system scope path.
+All commands support `--json` for machine-readable output:
 
-## Usage with AI Agents
+```bash
+skillbox list --json
+skillbox status --json
+skillbox update my-skill --json
+```
 
-### Just ask the agent
+## For AI Agents
 
-The simplest approach is to instruct your agent to use Skillbox:
+Install the skillbox skill to teach your agent how to use skillbox:
 
-```
-Use skillbox to manage skills for this repo. Run skillbox --help for all commands.
+```bash
+skillbox add christiananagnostou/skillbox
 ```
 
-### AGENTS.md / CLAUDE.md
-
-Add this to your project instructions for more consistent results:
+Or add this to your `CLAUDE.md` / `AGENTS.md`:
 
 ```markdown
-## Skills
-
-Use `skillbox` to manage skills. Run `skillbox --help` for all commands.
+Use `skillbox` to manage skills. Run `skillbox --help` for commands.
+```
 
-Core workflow:
+## File Locations
 
-1. `skillbox list --json`
-2. `skillbox status --json`
-3. `skillbox update <name> --json`
-```
+| Path | Purpose |
+|------|---------|
+| `~/.config/skillbox/skills/` | Canonical skill store |
+| `~/.config/skillbox/config.json` | Configuration |
+| `~/.config/skillbox/index.json` | Skill index |
 
 ## Development
 
@@ -153,7 +121,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

@@ -1,30 +1,32 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { registerAdd } from "./commands/add.js";
+import { registerAgent } from "./commands/agent.js";
+import { registerConfig } from "./commands/config.js";
 import { registerConvert } from "./commands/convert.js";
-import { registerList } from "./commands/list.js";
-import { registerStatus } from "./commands/status.js";
-import { registerUpdate } from "./commands/update.js";
 import { registerImport } from "./commands/import.js";
+import { registerList } from "./commands/list.js";
 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";
+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.1.0");
+program.name("skillbox").description("Local-first, agent-agnostic skills manager").version("0.3.0");
 registerAdd(program);
+registerAgent(program);
+registerConfig(program);
 registerConvert(program);
-registerList(program);
-registerStatus(program);
-registerUpdate(program);
 registerImport(program);
+registerList(program);
 registerMeta(program);
 registerProject(program);
-registerAgent(program);
-registerConfig(program);
-const run = async () => {
+registerRemove(program);
+registerStatus(program);
+registerUpdate(program);
+async function run() {
     const { runOnboarding } = await import("./lib/onboarding.js");
     await runOnboarding();
     program.parse();
-};
+}
 void run();

package/dist/commands/add-repo.js

@@ -0,0 +1,176 @@
+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 { printInfo, printJson } 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";
+import { buildMetadata, parseSkillMarkdown } from "../lib/skill-parser.js";
+import { writeSkillMetadata } from "../lib/skill-store.js";
+import { buildSymlinkWarning, buildTargets, installSkillToTargets } from "../lib/sync.js";
+function normalizeSkillSelection(skills, selections) {
+    if (selections.length === 0) {
+        return skills;
+    }
+    const selectionSet = new Set(selections);
+    return skills.filter((name) => selectionSet.has(name));
+}
+async function ensureRepoRef(input) {
+    const ref = parseRepoRef(input);
+    if (!ref) {
+        throw new Error("Unsupported repo URL or shorthand.");
+    }
+    return normalizeRepoRef(ref);
+}
+async function installSkillTargets(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);
+        }
+        for (const target of written) {
+            installs.push({
+                scope,
+                agent,
+                path: target,
+                projectRoot: scope === "project" ? projectRoot : undefined,
+            });
+        }
+    }
+}
+export function isRepoUrl(input) {
+    return Boolean(parseRepoRef(input));
+}
+export async function handleRepoInstall(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(`Repo Skills: ${ref.owner}/${ref.repo}`);
+        printInfo("");
+        printInfo(`Found ${skillNames.length} skill(s):`);
+        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: { 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}`);
+        }
+    }
+    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)`);
+        }
+    }
+    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.");
+    }
+}

package/dist/commands/add.js

@@ -1,22 +1,37 @@
-import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
-import { fetchText } from "../lib/fetcher.js";
-import { parseSkillMarkdown, inferNameFromUrl, buildMetadata } from "../lib/skill-parser.js";
 import { handleCommandError } from "../lib/command.js";
-import { ensureSkillsDir, writeSkillFiles } from "../lib/skill-store.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 { buildTargets, copySkillToTargets } from "../lib/sync.js";
+import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
 import { buildProjectAgentPaths } from "../lib/project-paths.js";
-import { resolveRuntime, ensureProjectRegistered } from "../lib/runtime.js";
-export const registerAdd = (program) => {
+import { ensureProjectRegistered, resolveRuntime } from "../lib/runtime.js";
+import { buildMetadata, inferNameFromUrl, parseSkillMarkdown } from "../lib/skill-parser.js";
+import { ensureSkillsDir, writeSkillFiles } from "../lib/skill-store.js";
+import { buildSymlinkWarning, buildTargets, installSkillToTargets } from "../lib/sync.js";
+import { handleRepoInstall, isRepoUrl } from "./add-repo.js";
+export function 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);
@@ -27,10 +42,10 @@ export const registerAdd = (program) => {
             if (!parsed.name && !options.name) {
                 throw new Error("Skill frontmatter missing name. Provide --name to continue.");
             }
-            const metadata = buildMetadata(parsed, { type: "url", url }, skillName);
             if (!parsed.description) {
                 throw new Error("Skill frontmatter missing description. Convert the source into a valid skill.");
             }
+            const metadata = buildMetadata(parsed, { type: "url", url }, skillName);
             await ensureSkillsDir();
             await writeSkillFiles(skillName, skillMarkdown, metadata);
             const index = await loadIndex();
@@ -46,6 +61,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 +70,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, {
@@ -79,27 +104,32 @@ export const registerAdd = (program) => {
                     command: "add",
                     data: {
                         name: skillName,
-                        url,
+                        source: { type: "url", url },
                         scope,
-                        agents: installed,
+                        installs,
                     },
                 });
                 return;
             }
-            printInfo(`Installed skill: ${skillName}`);
-            printInfo(`Source: ${url}`);
-            printInfo(`Scope: ${scope}`);
-            if (installed.length === 0) {
-                printInfo("No agent targets were updated.");
+            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 {
-                for (const entry of installed) {
-                    printInfo(`Updated ${entry.agent}: ${entry.targets.join(", ")}`);
-                }
+                printInfo("");
+                printInfo("No agent targets were updated.");
             }
         }
         catch (error) {
             handleCommandError(options, "add", error);
         }
     });
-};
+}

package/dist/commands/agent.js

@@ -1,5 +1,5 @@
 import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
-const agentSnippet = `Use skillbox for skill management.
+const AGENT_SNIPPET = `Use skillbox for skill management.
 
 Common workflow:
 1) skillbox list --json
@@ -12,22 +12,16 @@ skillbox add <url> [--name <name>]
 If a URL is not a valid skill, run:
 skillbox convert <url> --agent
 `;
-export const registerAgent = (program) => {
+export function registerAgent(program) {
     program
         .command("agent")
         .description("Print agent-friendly usage")
         .option("--json", "JSON output")
         .action((options) => {
         if (isJsonEnabled(options)) {
-            printJson({
-                ok: true,
-                command: "agent",
-                data: {
-                    snippet: agentSnippet,
-                },
-            });
+            printJson({ ok: true, command: "agent", data: { snippet: AGENT_SNIPPET } });
             return;
         }
-        printInfo(agentSnippet);
+        printInfo(AGENT_SNIPPET);
     });
-};
+}