skillbox 0.2.2 → 0.3.0

package/README.md

@@ -1,200 +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
 ```
 
-## Quick Start
-
-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.
+On first run, Skillbox auto-detects your installed agents and configures itself.
 
-Skillbox links agent folders to the canonical store using symlinks on macOS/Linux and file copies on Windows.
+**Quick start:** Install the skillbox skill to teach your agent how to manage skills:
 
 ```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
+skillbox add christiananagnostou/skillbox
 ```
 
-Notes:
-- GitHub unauthenticated API limit: 60 req/hr per IP
-- use `skillbox convert` for non-skill URLs
+## Golden Workflow
 
-## Commands
-
-### Core Commands
+These three commands cover most use cases:
 
 ```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]
-# 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
+skillbox list              # see installed skills
+skillbox status            # check for updates
+skillbox update [name]     # update skills
 ```
 
-### Project Commands
+## Adding Skills
 
-```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>
-```
+| 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 |
 
-### Config
+> **Note:** GitHub unauthenticated API limit is 60 requests/hour per IP.
 
-```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
-# use symlink installs
-skillbox config set --install-mode symlink
-# use file copies
-skillbox config set --install-mode copy
-```
+## All Commands
 
-Config defaults live in `~/.config/skillbox/config.json`:
+### Skills
 
-- `defaultScope`: `user` (default) or `project`
-- `defaultAgents`: empty array means all agents
-- `installMode`: `symlink` (macOS/Linux) or `copy` (Windows)
+| 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 |
 
-## Agent Mode
-
-Use `--json` for machine-readable output.
+### Config
 
-```bash
-# list skills (json)
-skillbox list --json
-# status check (json)
-skillbox status --json
-# update one skill (json)
-skillbox update linting --json
-```
+| 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`) |
 
-### Agent Usage Snippet
+### Projects
 
-```text
-Use skillbox for skill management.
+| 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 |
 
-Common workflow:
-1) skillbox list --json
-2) skillbox status --json
-3) skillbox update <name> --json
+## Supported Agents
 
-If you need to install a new skill from a URL, run:
-# add skill from URL
-skillbox add <url> [--name <name>]
+| 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/` |
 
-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
+## JSON Mode
 
-Note: GitHub unauthenticated API limits are 60 requests per hour per IP, so heavy repo usage may hit rate limits.
+All commands support `--json` for machine-readable output:
 
-If a URL is not a valid skill, run:
-# convert content to skill
-skillbox convert <url> --agent
+```bash
+skillbox list --json
+skillbox status --json
+skillbox update my-skill --json
 ```
 
-## Skill Locations
-
-Skillbox maintains a canonical store and syncs into agent-native folders.
-
-Canonical store:
-
-- `~/.config/skillbox/skills/<name>/`
-
-Index + config:
-
-- `~/.config/skillbox/index.json`
-- `~/.config/skillbox/projects.json`
-- `~/.config/skillbox/config.json`
-
-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/`
-- Amp: `.agents/skills/`, `~/.config/agents/skills/` (Claude-compatible `.claude/skills/` also supported)
-- Antigravity: `.agent/skills/`, `~/.gemini/antigravity/skills/`
+## For AI Agents
 
-## Usage with AI Agents
+Install the skillbox skill to teach your agent how to use skillbox:
 
-### Just ask the agent
-
-The simplest approach is to instruct your agent 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
 

package/dist/cli.js

@@ -1,32 +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);
 registerRemove(program);
-const run = async () => {
+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

@@ -1,29 +1,29 @@
-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 { getErrorMessage } from "../lib/command.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 { parseRepoRef } from "../lib/github.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) => {
+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));
-};
-const ensureRepoRef = async (input) => {
+}
+async function ensureRepoRef(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) => {
+    return normalizeRepoRef(ref);
+}
+async function installSkillTargets(skillName, options, installs) {
     const { projectRoot, scope, agentList } = await resolveRuntime({
         global: options.global,
         agents: options.agents,
@@ -45,22 +45,20 @@ const installSkillTargets = async (skillName, options, installs) => {
         if (warning) {
             printInfo(warning);
         }
-        if (written.length > 0) {
-            for (const target of written) {
-                installs.push({
-                    scope,
-                    agent,
-                    path: target,
-                    projectRoot: scope === "project" ? projectRoot : undefined,
-                });
-            }
+        for (const target of written) {
+            installs.push({
+                scope,
+                agent,
+                path: target,
+                projectRoot: scope === "project" ? projectRoot : undefined,
+            });
         }
     }
-};
-export const isRepoUrl = (input) => {
+}
+export function isRepoUrl(input) {
     return Boolean(parseRepoRef(input));
-};
-export const handleRepoInstall = async (input, options) => {
+}
+export async function handleRepoInstall(input, options) {
     const ref = await ensureRepoRef(input);
     const { skills } = await listRepoSkills(ref);
     const skillNames = skills.map((skill) => skill.name).sort();
@@ -69,9 +67,11 @@ export const handleRepoInstall = async (input, options) => {
             printJson({ ok: true, command: "add", data: { repo: input, skills: skillNames } });
             return;
         }
-        printInfo(`Skills found: ${skillNames.length}`);
+        printInfo(`Repo Skills: ${ref.owner}/${ref.repo}`);
+        printInfo("");
+        printInfo(`Found ${skillNames.length} skill(s):`);
         for (const name of skillNames) {
-            printInfo(`- ${name}`);
+            printInfo(`  - ${name}`);
         }
         return;
     }
@@ -133,25 +133,44 @@ export const handleRepoInstall = async (input, options) => {
     }
     await saveIndex(sortIndex(index));
     if (options.json) {
-        printJson({ ok: true, command: "add", data: summary });
+        printJson({ ok: true, command: "add", data: { repo: `${ref.owner}/${ref.repo}`, ...summary } });
         return;
     }
-    if (summary.failed.length > 0) {
-        printInfo("Some skills failed to install:");
-        for (const failure of summary.failed) {
-            printInfo(`- ${failure.name}: ${failure.reason}`);
-        }
-    }
+    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(`Installed ${summary.installed.length} skill(s): ${summary.installed.join(", ")}`);
+        printInfo("");
+        printInfo(`Installed (${summary.installed.length}):`);
+        for (const name of summary.installed) {
+            printInfo(`  ✓ ${name}`);
+        }
     }
     if (summary.updated.length > 0) {
-        printInfo(`Updated ${summary.updated.length} skill(s): ${summary.updated.join(", ")}`);
+        printInfo("");
+        printInfo(`Updated (${summary.updated.length}):`);
+        for (const name of summary.updated) {
+            printInfo(`  ✓ ${name}`);
+        }
     }
     if (summary.skipped.length > 0) {
-        printInfo(`Skipped ${summary.skipped.length} skill(s): ${summary.skipped.join(", ")}`);
+        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})`);
+        }
     }
-    if (summary.installed.length === 0 && summary.updated.length === 0) {
-        printInfo("No agent targets were updated (canonical store only).");
+    const total = summary.installed.length + summary.updated.length;
+    if (total === 0) {
+        printInfo("");
+        printInfo("No skills were added.");
     }
-};
+}

package/dist/commands/add.js

@@ -1,15 +1,16 @@
-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 { buildSymlinkWarning, buildTargets, installSkillToTargets } 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";
-import { loadConfig } from "../lib/config.js";
+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 const registerAdd = (program) => {
+export function registerAdd(program) {
     program
         .command("add")
         .argument("<url>", "Skill URL or repo")
@@ -41,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();
@@ -103,30 +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 (canonical store only).");
+            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);
         }
     });
-};
-const collect = (value, previous = []) => {
-    return [...previous, value];
-};
+}

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);
     });
-};
+}

package/dist/commands/config.js

@@ -1,10 +1,8 @@
-import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
-import { loadConfig, saveConfig } from "../lib/config.js";
 import { handleCommandError } from "../lib/command.js";
-const collect = (value, previous = []) => {
-    return [...previous, value];
-};
-export const registerConfig = (program) => {
+import { loadConfig, saveConfig } from "../lib/config.js";
+import { collect } from "../lib/fs-utils.js";
+import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
+export function registerConfig(program) {
     const config = program.command("config").description("View or edit skillbox config");
     config
         .command("get")
@@ -36,13 +34,13 @@ export const registerConfig = (program) => {
             if (nextScope !== "project" && nextScope !== "user") {
                 throw new Error("defaultScope must be 'project' or 'user'.");
             }
-            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 addedAgents = options.addAgent ?? [];
+            const nextAgents = options.defaultAgent ?? current.defaultAgents;
+            const mergedAgents = Array.from(new Set([...(nextAgents ?? []), ...addedAgents].filter((agent) => agent.length > 0)));
             const next = {
                 ...current,
                 defaultAgents: mergedAgents,
@@ -60,4 +58,4 @@ export const registerConfig = (program) => {
             handleCommandError(options, "config set", error);
         }
     });
-};
+}