skillbox 0.1.2 → 0.2.0

package/README.md

@@ -13,26 +13,13 @@
 npm install -g skillbox
 ```
 
-### From Source
 
-```bash
-git clone https://github.com/christiananagnostou/skillbox
-cd skillbox
-npm install
-npm run build
-npm link --global
-```
-
-## CI
 
-```bash
-npm run lint:ci
-npm run format:check
-npm run build
-```
+## 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.
 
-## Quick Start
+Tip: run `skillbox list` right after install to see existing skills.
 
 ```bash
 skillbox add https://example.com/skills/linting/SKILL.md
@@ -71,10 +58,15 @@ skillbox project sync <path>
 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
 ```
 
-TODO: Config option reference (defaults, values, validation)
+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
 
@@ -126,7 +118,7 @@ Agent paths (default):
 - Amp: `.agents/skills/`, `~/.config/agents/skills/` (Claude-compatible `.claude/skills/` also supported)
 - Antigravity: `.agent/skills/`, `~/.gemini/antigravity/skills/`
 
-TODO: Validate agent path list against upstream docs before release
+Note: only Codex defines a system scope path.
 
 ## Usage with AI Agents
 
@@ -154,9 +146,15 @@ Core workflow:
 3. `skillbox update <name> --json`
 ```
 
-### Claude Code Skill
+## Development
 
-TODO: Provide a Skillbox skill for Claude Code (SKILL.md)
+```bash
+git clone https://github.com/christiananagnostou/skillbox
+cd skillbox
+npm install
+npm run build
+npm link --global
+```
 
 ## License
 

package/dist/cli.js

@@ -22,4 +22,9 @@ registerMeta(program);
 registerProject(program);
 registerAgent(program);
 registerConfig(program);
-program.parse();
+const run = async () => {
+    const { runOnboarding } = await import("./lib/onboarding.js");
+    await runOnboarding();
+    program.parse();
+};
+void run();

package/dist/commands/config.js

@@ -25,6 +25,7 @@ export const registerConfig = (program) => {
     config
         .command("set")
         .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("--json", "JSON output")
@@ -35,9 +36,12 @@ 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 next = {
                 ...current,
-                defaultAgents: options.defaultAgent ?? current.defaultAgents,
+                defaultAgents: mergedAgents,
                 defaultScope: nextScope,
                 manageSystem: options.manageSystem ?? current.manageSystem,
             };

package/dist/commands/import.js

@@ -5,13 +5,36 @@ import { parseSkillMarkdown, buildMetadata } from "../lib/skill-parser.js";
 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";
 export const registerImport = (program) => {
     program
         .command("import")
-        .argument("<path>", "Path to skill directory")
+        .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 (options.global || options.system) {
+                const summary = await importGlobalSkills({
+                    includeUser: Boolean(options.global),
+                    includeSystem: Boolean(options.system),
+                });
+                if (isJsonEnabled(options)) {
+                    printJson({
+                        ok: true,
+                        command: "import",
+                        data: summary,
+                    });
+                    return;
+                }
+                printInfo(`Imported ${summary.imported.length} skill(s).`);
+                return;
+            }
             const resolved = path.resolve(inputPath);
             const skillPath = path.join(resolved, "SKILL.md");
             const markdown = await fs.readFile(skillPath, "utf8");
@@ -48,3 +71,50 @@ export const registerImport = (program) => {
         }
     });
 };
+const importGlobalSkills = async (options) => {
+    const projectRoot = process.cwd();
+    const paths = [
+        ...(options.includeUser ? getUserAgentPaths(projectRoot) : []),
+        ...(options.includeSystem ? getSystemAgentPaths(projectRoot) : []),
+    ];
+    const discovered = await discoverSkills(paths);
+    const index = await loadIndex();
+    const seen = new Set(index.skills.map((skill) => skill.name));
+    const imported = [];
+    const skipped = [];
+    for (const skill of discovered) {
+        if (seen.has(skill.name)) {
+            skipped.push(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);
+            continue;
+        }
+        await ensureSkillsDir();
+        await writeSkillFiles(metadata.name, markdown, metadata);
+        const next = upsertSkill(index, {
+            name: metadata.name,
+            source: { type: "local" },
+            checksum: parsed.checksum,
+            updatedAt: metadata.updatedAt,
+            installs: [
+                {
+                    scope: options.includeSystem ? "system" : "user",
+                    agent: "unknown",
+                    path: skill.skillDir,
+                },
+            ],
+        });
+        index.skills = next.skills;
+        imported.push(metadata.name);
+    }
+    await saveIndex(sortIndex(index));
+    return {
+        imported: imported.sort(),
+        skipped: skipped.sort(),
+    };
+};

package/dist/commands/list.js

@@ -1,14 +1,17 @@
 import { isJsonEnabled, printInfo, printJson, printGroupList } from "../lib/output.js";
 import { loadIndex } from "../lib/index.js";
 import { groupNamesByKey } from "../lib/grouping.js";
+import { discoverGlobalSkills } from "../lib/global-skills.js";
 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 skills = index.skills;
+        const globalSkills = options.projectOnly ? [] : await listGlobalSkills(index.skills);
+        const skills = [...index.skills, ...globalSkills];
         const groupedProjects = groupByProject(skills);
         const groupedSources = groupBySource(skills);
         const groupedNamespaces = groupByNamespace(skills);
@@ -61,6 +64,21 @@ const groupByProject = (skills) => {
         .map((install) => install.projectRoot));
     return grouped.map((group) => ({ root: group.key, skills: group.skills }));
 };
+const listGlobalSkills = async (existing) => {
+    const projectRoot = process.cwd();
+    const seen = new Set(existing.map((skill) => skill.name));
+    const discovered = await discoverGlobalSkills(projectRoot);
+    return discovered
+        .filter((skill) => !seen.has(skill.name))
+        .map((skill) => ({
+        name: skill.name,
+        source: { type: "local" },
+        installs: skill.installs,
+        namespace: undefined,
+        categories: undefined,
+        tags: undefined,
+    }));
+};
 const groupBySource = (skills) => {
     const grouped = groupNamesByKey(skills, (skill) => skill.name, (skill) => [skill.source.type]);
     return grouped.map((group) => ({ source: group.key, skills: group.skills }));

package/dist/commands/status.js

@@ -16,9 +16,9 @@ export const registerStatus = (program) => {
             const config = await loadConfig();
             const results = [];
             for (const skill of index.skills) {
-                const projects = (skill.installs ?? [])
+                const projects = Array.from(new Set((skill.installs ?? [])
                     .filter((install) => install.scope === "project" && install.projectRoot)
-                    .map((install) => install.projectRoot);
+                    .map((install) => install.projectRoot)));
                 const allowSystem = config.manageSystem;
                 const isSystem = (skill.installs ?? []).some((install) => install.scope === "system");
                 if (isSystem && !allowSystem) {

package/dist/lib/agent-detect.js

@@ -0,0 +1,31 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+const home = os.homedir();
+const agentRoots = {
+    opencode: [path.join(home, ".config", "opencode")],
+    claude: [path.join(home, ".claude")],
+    cursor: [path.join(home, ".cursor")],
+    codex: [path.join(home, ".codex")],
+    amp: [path.join(home, ".config", "agents")],
+    antigravity: [path.join(home, ".gemini", "antigravity")],
+};
+const exists = async (target) => {
+    try {
+        await fs.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const detectAgents = async () => {
+    const detected = [];
+    for (const [agent, roots] of Object.entries(agentRoots)) {
+        const matches = await Promise.all(roots.map((root) => exists(root)));
+        if (matches.some(Boolean)) {
+            detected.push(agent);
+        }
+    }
+    return detected;
+};

package/dist/lib/agents.js

@@ -38,6 +38,14 @@ export const agentPaths = (projectRoot) => ({
     },
 });
 export const allAgents = ["opencode", "claude", "cursor", "codex", "amp", "antigravity"];
+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/discovery.js

@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const exists = async (target) => {
+    try {
+        await fs.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const discoverSkills = async (paths) => {
+    const results = [];
+    for (const root of paths) {
+        if (!(await exists(root))) {
+            continue;
+        }
+        const entries = await fs.readdir(root, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const skillDir = path.join(root, entry.name);
+            const skillFile = path.join(skillDir, "SKILL.md");
+            if (!(await exists(skillFile))) {
+                continue;
+            }
+            results.push({ name: entry.name, skillDir, skillFile });
+        }
+    }
+    return results;
+};

package/dist/lib/global-skills.js

@@ -0,0 +1,36 @@
+import { getUserAgentPaths, getSystemAgentPaths } 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;
+};

package/dist/lib/onboarding.js

@@ -0,0 +1,39 @@
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { allAgents, isAgentId } from "./agents.js";
+import { loadConfig, saveConfig } from "./config.js";
+import { detectAgents } from "./agent-detect.js";
+const formatPrompt = (detected) => {
+    if (detected.length === 0) {
+        return `Which agents do you use? (comma-separated) [${allAgents.join(", ")}]: `;
+    }
+    return `Detected agents: ${detected.join(", ")}. Press enter to accept or edit: `;
+};
+const promptAgents = async () => {
+    const detected = await detectAgents();
+    const rl = readline.createInterface({ input, output });
+    const answer = await rl.question(formatPrompt(detected));
+    rl.close();
+    const raw = answer.trim().length > 0 ? answer : detected.join(",");
+    const selected = raw
+        .split(",")
+        .map((agent) => agent.trim())
+        .filter((agent) => agent.length > 0)
+        .filter(isAgentId);
+    if (selected.length > 0) {
+        return selected;
+    }
+    return detected.length > 0 ? detected : allAgents;
+};
+export const runOnboarding = async () => {
+    const config = await loadConfig();
+    if (config.defaultAgents.length > 0) {
+        return;
+    }
+    const selected = await promptAgents();
+    const next = {
+        ...config,
+        defaultAgents: selected,
+    };
+    await saveConfig(next);
+};

package/package.json

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