skillbox 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Anagnostou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# skillbox
+
+Local-first, agent-agnostic skills manager. Track, update, and sync skills across popular AI coding agents with one CLI.
+
+## Installation
+
+### npm (recommended)
+
+```bash
+npm install -g skillbox
+```
+
+TODO: Publish initial npm release
+
+### From Source
+
+```bash
+git clone https://github.com/christiananagnostou/skillbox
+cd skillbox
+npm install
+npm run build
+npm link --global
+```
+
+### Homebrew
+
+```bash
+brew tap christiananagnostou/skillbox
+brew install skillbox
+```
+
+TODO: Homebrew formula publishing
+
+## CI
+
+```bash
+npm run lint:ci
+npm run format:check
+npm run build
+```
+
+TODO: Publish GitHub Actions badge
+
+## Quick Start
+
+```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
+
+```bash
+skillbox config get
+skillbox config set --default-scope user
+skillbox config set --default-agent claude --default-agent cursor
+skillbox config set --manage-system
+```
+
+TODO: Config option reference (defaults, values, validation)
+
+## Agent Mode
+
+Use `--json` for machine-readable output.
+
+```bash
+skillbox list --json
+skillbox status --json
+skillbox update linting --json
+```
+
+### Agent Usage Snippet
+
+```text
+Use skillbox for skill management.
+
+Common workflow:
+1) skillbox list --json
+2) skillbox status --json
+3) skillbox update <name> --json
+
+If you need to install a new skill from a URL, run:
+skillbox add <url> [--name <name>]
+
+If a URL is not a valid skill, run:
+skillbox convert <url> --agent
+```
+
+## 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/`, `/etc/codex/skills` (system)
+- 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
+
+## Usage with AI Agents
+
+### 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.
+```
+
+### AGENTS.md / CLAUDE.md
+
+Add this to your project instructions for more consistent results:
+
+```markdown
+## Skills
+
+Use `skillbox` to manage skills. Run `skillbox --help` for all commands.
+
+Core workflow:
+
+1. `skillbox list --json`
+2. `skillbox status --json`
+3. `skillbox update <name> --json`
+```
+
+### Claude Code Skill
+
+TODO: Provide a Skillbox skill for Claude Code (SKILL.md)
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { registerAdd } from "./commands/add.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 { registerMeta } from "./commands/meta.js";
+import { registerProject } from "./commands/project.js";
+import { registerAgent } from "./commands/agent.js";
+import { registerConfig } from "./commands/config.js";
+const program = new Command();
+program.name("skillbox").description("Local-first, agent-agnostic skills manager").version("0.1.0");
+registerAdd(program);
+registerConvert(program);
+registerList(program);
+registerStatus(program);
+registerUpdate(program);
+registerImport(program);
+registerMeta(program);
+registerProject(program);
+registerAgent(program);
+registerConfig(program);
+program.parse();

package/dist/commands/add.js

@@ -0,0 +1,105 @@
+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 { loadIndex, saveIndex, sortIndex, upsertSkill } from "../lib/index.js";
+import { buildTargets, copySkillToTargets } from "../lib/sync.js";
+import { buildProjectAgentPaths } from "../lib/project-paths.js";
+import { resolveRuntime, ensureProjectRegistered } from "../lib/runtime.js";
+export const registerAdd = (program) => {
+    program
+        .command("add")
+        .argument("<url>", "Skill URL")
+        .option("--name <name>", "Override skill name")
+        .option("--global", "Install to user scope")
+        .option("--agents <list>", "Comma-separated agent list")
+        .option("--json", "JSON output")
+        .action(async (url, options) => {
+        try {
+            const skillMarkdown = await fetchText(url);
+            const parsed = parseSkillMarkdown(skillMarkdown);
+            const inferred = inferNameFromUrl(url);
+            const skillName = options.name ?? inferred ?? parsed.name;
+            if (!skillName) {
+                throw new Error("Unable to infer skill name. Use --name to specify it.");
+            }
+            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.");
+            }
+            await ensureSkillsDir();
+            await writeSkillFiles(skillName, skillMarkdown, metadata);
+            const index = await loadIndex();
+            const updated = upsertSkill(index, {
+                name: skillName,
+                source: { type: "url", url },
+                checksum: parsed.checksum,
+                updatedAt: metadata.updatedAt,
+            });
+            const { projectRoot, scope, agentList } = await resolveRuntime({
+                global: options.global,
+                agents: options.agents,
+            });
+            const projectEntry = await ensureProjectRegistered(projectRoot, scope);
+            const paths = buildProjectAgentPaths(projectRoot, projectEntry);
+            const installed = [];
+            const installs = [];
+            for (const agent of agentList) {
+                const map = paths[agent];
+                if (!map) {
+                    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 nextIndex = upsertSkill(updated, {
+                name: skillName,
+                source: { type: "url", url },
+                checksum: parsed.checksum,
+                updatedAt: metadata.updatedAt,
+                installs,
+            });
+            await saveIndex(sortIndex(nextIndex));
+            if (isJsonEnabled(options)) {
+                printJson({
+                    ok: true,
+                    command: "add",
+                    data: {
+                        name: skillName,
+                        url,
+                        scope,
+                        agents: installed,
+                    },
+                });
+                return;
+            }
+            printInfo(`Installed skill: ${skillName}`);
+            printInfo(`Source: ${url}`);
+            printInfo(`Scope: ${scope}`);
+            if (installed.length === 0) {
+                printInfo("No agent targets were updated.");
+            }
+            else {
+                for (const entry of installed) {
+                    printInfo(`Updated ${entry.agent}: ${entry.targets.join(", ")}`);
+                }
+            }
+        }
+        catch (error) {
+            handleCommandError(options, "add", error);
+        }
+    });
+};

package/dist/commands/agent.js

@@ -0,0 +1,33 @@
+import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
+const agentSnippet = `Use skillbox for skill management.
+
+Common workflow:
+1) skillbox list --json
+2) skillbox status --json
+3) skillbox update <name> --json
+
+If you need to install a new skill from a URL, run:
+skillbox add <url> [--name <name>]
+
+If a URL is not a valid skill, run:
+skillbox convert <url> --agent
+`;
+export const 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,
+                },
+            });
+            return;
+        }
+        printInfo(agentSnippet);
+    });
+};

package/dist/commands/config.js

@@ -0,0 +1,55 @@
+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) => {
+    const config = program.command("config").description("View or edit skillbox config");
+    config
+        .command("get")
+        .option("--json", "JSON output")
+        .action(async (options) => {
+        try {
+            const current = await loadConfig();
+            if (isJsonEnabled(options)) {
+                printJson({ ok: true, command: "config get", data: current });
+                return;
+            }
+            printInfo(JSON.stringify(current, null, 2));
+        }
+        catch (error) {
+            handleCommandError(options, "config get", error);
+        }
+    });
+    config
+        .command("set")
+        .option("--default-agent <agent>", "Default agent", collect)
+        .option("--default-scope <scope>", "Default scope: project or user")
+        .option("--manage-system", "Enable system scope operations")
+        .option("--json", "JSON output")
+        .action(async (options) => {
+        try {
+            const current = await loadConfig();
+            const nextScope = options.defaultScope ?? current.defaultScope;
+            if (nextScope !== "project" && nextScope !== "user") {
+                throw new Error("defaultScope must be 'project' or 'user'.");
+            }
+            const next = {
+                ...current,
+                defaultAgents: options.defaultAgent ?? current.defaultAgents,
+                defaultScope: nextScope,
+                manageSystem: options.manageSystem ?? current.manageSystem,
+            };
+            await saveConfig(next);
+            if (isJsonEnabled(options)) {
+                printJson({ ok: true, command: "config set", data: next });
+                return;
+            }
+            printInfo("Config updated.");
+        }
+        catch (error) {
+            handleCommandError(options, "config set", error);
+        }
+    });
+};

package/dist/commands/convert.js

@@ -0,0 +1,64 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
+import { fetchText } from "../lib/fetcher.js";
+import { inferNameFromUrl } from "../lib/skill-parser.js";
+import { handleCommandError } from "../lib/command.js";
+export const registerConvert = (program) => {
+    program
+        .command("convert")
+        .argument("<url>", "Source URL to convert")
+        .option("--name <name>", "Override skill name")
+        .option("--output <dir>", "Output directory")
+        .option("--agent", "Delegate conversion to agent")
+        .option("--json", "JSON output")
+        .action(async (url, options) => {
+        try {
+            const sourceText = await fetchText(url);
+            const inferred = inferNameFromUrl(url);
+            const skillName = options.name ?? inferred;
+            if (!skillName) {
+                throw new Error("Unable to infer skill name. Use --name to specify it.");
+            }
+            const outputDir = options.output
+                ? path.resolve(options.output)
+                : path.join(process.cwd(), "skillbox-convert", skillName);
+            const description = "Draft skill generated from source content.";
+            const draftMarkdown = `---\nname: ${skillName}\ndescription: ${description}\n---\n\n# ${skillName}\n\n## Source\n- See source.txt for the raw content.\n\n## When to use\n- TODO\n\n## Instructions\n- TODO\n`;
+            const metadata = {
+                name: skillName,
+                version: "0.1.0",
+                description,
+                entry: "SKILL.md",
+                source: { type: "url", url },
+                checksum: "draft",
+                updatedAt: new Date().toISOString(),
+            };
+            await fs.mkdir(outputDir, { recursive: true });
+            await fs.writeFile(path.join(outputDir, "source.txt"), sourceText, "utf8");
+            await fs.writeFile(path.join(outputDir, "SKILL.md"), draftMarkdown, "utf8");
+            await fs.writeFile(path.join(outputDir, "skill.json"), `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+            if (isJsonEnabled(options)) {
+                printJson({
+                    ok: true,
+                    command: "convert",
+                    data: {
+                        url,
+                        name: skillName,
+                        outputDir,
+                        agent: Boolean(options.agent),
+                        sourceLength: sourceText.length,
+                    },
+                });
+                return;
+            }
+            printInfo(`Draft created: ${outputDir}`);
+            if (options.agent) {
+                printInfo("Agent mode enabled. Use the source.txt content to refine SKILL.md.");
+            }
+        }
+        catch (error) {
+            handleCommandError(options, "convert", error);
+        }
+    });
+};

package/dist/commands/import.js

@@ -0,0 +1,50 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
+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";
+export const registerImport = (program) => {
+    program
+        .command("import")
+        .argument("<path>", "Path to skill directory")
+        .option("--json", "JSON output")
+        .action(async (inputPath, options) => {
+        try {
+            const resolved = path.resolve(inputPath);
+            const skillPath = path.join(resolved, "SKILL.md");
+            const markdown = await fs.readFile(skillPath, "utf8");
+            const parsed = parseSkillMarkdown(markdown);
+            const metadata = buildMetadata(parsed, { type: "local" });
+            if (!parsed.description) {
+                throw new Error("Skill frontmatter missing description.");
+            }
+            await ensureSkillsDir();
+            await writeSkillFiles(metadata.name, markdown, metadata);
+            const index = await loadIndex();
+            const updated = upsertSkill(index, {
+                name: metadata.name,
+                source: { type: "local" },
+                checksum: parsed.checksum,
+                updatedAt: metadata.updatedAt,
+            });
+            await saveIndex(sortIndex(updated));
+            if (isJsonEnabled(options)) {
+                printJson({
+                    ok: true,
+                    command: "import",
+                    data: {
+                        name: metadata.name,
+                        path: resolved,
+                    },
+                });
+                return;
+            }
+            printInfo(`Imported skill: ${metadata.name}`);
+        }
+        catch (error) {
+            handleCommandError(options, "import", error);
+        }
+    });
+};

package/dist/commands/list.js

@@ -0,0 +1,95 @@
+import { isJsonEnabled, printInfo, printJson, printGroupList } from "../lib/output.js";
+import { loadIndex } from "../lib/index.js";
+import { groupNamesByKey } from "../lib/grouping.js";
+export const registerList = (program) => {
+    program
+        .command("list")
+        .option("--group <group>", "Group by category, namespace, source, project")
+        .option("--json", "JSON output")
+        .action(async (options) => {
+        const index = await loadIndex();
+        const skills = index.skills;
+        const groupedProjects = groupByProject(skills);
+        const groupedSources = groupBySource(skills);
+        const groupedNamespaces = groupByNamespace(skills);
+        const groupedCategories = groupByCategory(skills);
+        if (isJsonEnabled(options)) {
+            printJson({
+                ok: true,
+                command: "list",
+                data: {
+                    group: options.group ?? null,
+                    skills,
+                    projects: options.group === "project" ? groupedProjects : undefined,
+                    sources: options.group === "source" ? groupedSources : undefined,
+                    namespaces: options.group === "namespace" ? groupedNamespaces : undefined,
+                    categories: options.group === "category" ? groupedCategories : undefined,
+                },
+            });
+            return;
+        }
+        if (options.group === "project") {
+            printGroupList("Projects", groupedProjects.map((project) => ({ key: project.root, items: project.skills })));
+            return;
+        }
+        if (options.group === "source") {
+            printGroupList("Sources", groupedSources.map((source) => ({ key: source.source, items: source.skills })));
+            return;
+        }
+        if (options.group === "namespace") {
+            printGroupList("Namespaces", groupedNamespaces.map((namespace) => ({
+                key: namespace.namespace,
+                items: namespace.skills,
+            })));
+            return;
+        }
+        if (options.group === "category") {
+            printGroupList("Categories", groupedCategories.map((category) => ({ key: category.category, items: category.skills })));
+            return;
+        }
+        printInfo(`Skills: ${skills.length}`);
+        for (const skill of skills) {
+            const source = skill.source.type;
+            const namespace = skill.namespace ? ` (${skill.namespace})` : "";
+            printInfo(`- ${skill.name}${namespace} [${source}]`);
+        }
+    });
+};
+const groupByProject = (skills) => {
+    const grouped = groupNamesByKey(skills, (skill) => skill.name, (skill) => (skill.installs ?? [])
+        .filter((install) => install.scope === "project" && install.projectRoot)
+        .map((install) => install.projectRoot));
+    return grouped.map((group) => ({ root: group.key, skills: group.skills }));
+};
+const groupBySource = (skills) => {
+    const grouped = groupNamesByKey(skills, (skill) => skill.name, (skill) => [skill.source.type]);
+    return grouped.map((group) => ({ source: group.key, skills: group.skills }));
+};
+const groupByNamespace = (skills) => {
+    const grouped = groupNamesByKey(skills, (skill) => skill.name, (skill) => [skill.namespace ?? "(none)"]);
+    return grouped
+        .map((group) => ({ namespace: group.key, skills: group.skills }))
+        .sort((a, b) => {
+        if (a.namespace === "(none)") {
+            return 1;
+        }
+        if (b.namespace === "(none)") {
+            return -1;
+        }
+        return a.namespace.localeCompare(b.namespace);
+    });
+};
+const groupByCategory = (skills) => {
+    const grouped = groupNamesByKey(skills, (skill) => skill.name, (skill) => skill.categories ?? ["(uncategorized)"]);
+    return grouped
+        .map((group) => ({ category: group.key, skills: group.skills }))
+        .sort((a, b) => {
+        if (a.category === "(uncategorized)") {
+            return 1;
+        }
+        if (b.category === "(uncategorized)") {
+            return -1;
+        }
+        return a.category.localeCompare(b.category);
+    });
+};

package/dist/commands/meta.js

@@ -0,0 +1,60 @@
+import { isJsonEnabled, printInfo, printJson } from "../lib/output.js";
+import { readSkillMetadata, writeSkillMetadata } from "../lib/skill-store.js";
+import { loadIndex, saveIndex, sortIndex, upsertSkill } from "../lib/index.js";
+import { handleCommandError } from "../lib/command.js";
+export const registerMeta = (program) => {
+    const meta = program.command("meta").description("Manage skill metadata");
+    meta
+        .command("set")
+        .argument("<name>", "Skill name")
+        .option("--category <category>", "Category", collect)
+        .option("--tag <tag>", "Tag", collect)
+        .option("--namespace <namespace>", "Namespace")
+        .option("--json", "JSON output")
+        .action(async (name, options) => {
+        try {
+            const metadata = await readSkillMetadata(name);
+            const categories = options.category ?? metadata.categories ?? [];
+            const tags = options.tag ?? metadata.tags ?? [];
+            const namespace = options.namespace ?? metadata.namespace;
+            const nextMetadata = {
+                ...metadata,
+                categories: categories.length > 0 ? categories : undefined,
+                tags: tags.length > 0 ? tags : undefined,
+                namespace,
+            };
+            await writeSkillMetadata(name, nextMetadata);
+            const index = await loadIndex();
+            const updated = upsertSkill(index, {
+                name,
+                source: metadata.source,
+                checksum: metadata.checksum,
+                updatedAt: metadata.updatedAt,
+                categories: nextMetadata.categories,
+                tags: nextMetadata.tags,
+                namespace: nextMetadata.namespace,
+            });
+            await saveIndex(sortIndex(updated));
+            if (isJsonEnabled(options)) {
+                printJson({
+                    ok: true,
+                    command: "meta set",
+                    data: {
+                        name,
+                        categories: nextMetadata.categories ?? [],
+                        tags: nextMetadata.tags ?? [],
+                        namespace: nextMetadata.namespace ?? null,
+                    },
+                });
+                return;
+            }
+            printInfo(`Updated metadata for ${name}`);
+        }
+        catch (error) {
+            handleCommandError(options, "meta set", error);
+        }
+    });
+};
+const collect = (value, previous = []) => {
+    return [...previous, value];
+};