skill-forger 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Marc Mansour
+
+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,143 @@
+# 🤹 skill-forger
+
+Manage project Agent [skills](https://skills.sh/) from `skills.json`. Uses [`skills`](https://github.com/vercel-labs/skills) CLI under the hood.
+
+## Usage
+
+**Install all skills from `skills.json`:**
+
+```bash
+npx skill-forger
+```
+
+<p align="center">
+  <img src="./assets/install.svg" alt="Install preview">
+</p>
+
+**Add new skills to project:**
+
+```bash
+npx skill-forger add skills.sh/vercel-labs/skills/find-skills
+
+npx skill-forger add anthropics/skills:skill-creator
+```
+
+<p align="center">
+  <img src="./assets/add.svg" alt="Install preview">
+</p>
+
+This creates a `skills.json` file:
+
+```json
+{
+  "$schema": "https://unpkg.com/skill-forger/skills_schema.json",
+  "skills": [
+    { "source": "vercel-labs/skills", "skills": ["find-skills"] },
+    { "source": "anthropics/skills", "skills": ["skill-creator"] }
+  ]
+}
+```
+
+## CLI Usage
+
+```sh
+npx skill-forger                    # Install skills from skills.json (default)
+npx skill-forger install, i         # Same as above
+npx skill-forger add <source>...    # Add skill source(s) to skills.json
+```
+
+### Commands
+
+#### `install` (default)
+
+Installs all skills defined in `skills.json`.
+
+```sh
+npx skill-forger install [options]
+```
+
+| Option           | Description                                       |
+| ---------------- | ------------------------------------------------- |
+| `--agent <name>` | Target agent (default: `claude-code`, repeatable) |
+| `-g, --global`   | Install skills globally                           |
+| `-h, --help`     | Show help                                         |
+
+#### `add`
+
+Adds skill source(s) to `skills.json` and installs them.
+
+```sh
+npx skill-forger add <source>... [options]
+```
+
+| Option           | Description                                       |
+| ---------------- | ------------------------------------------------- |
+| `--agent <name>` | Target agent (default: `claude-code`, repeatable) |
+| `-h, --help`     | Show help                                         |
+
+### Source Formats
+
+Sources can be specified in multiple formats:
+
+```sh
+# GitHub owner/repo format
+npx skill-forger add vercel-labs/skills
+
+# skills.sh URL
+npx skill-forger add https://skills.sh/vercel-labs/skills/find-skills
+npx skill-forger add skills.sh/vercel-labs/skills/find-skills
+
+
+# Multiple sources
+npx skill-forger add org/repo-a:skill1 org/repo-b:skill2
+
+# Specify skills (comma separated)
+npx skill-forger add vercel-labs/agent-skills:vercel-deploy,vercel-react-native-skills
+```
+
+### Examples
+
+```sh
+# Install all skills from skills.json
+npx skill-forger
+
+# Add a skill source (all skills)
+npx skill-forger add vercel-labs/skills
+
+# Add specific skills from a source
+npx skill-forger add vercel-labs/agent-skills:vercel-deploy,vercel-react-native-skills
+
+# Add from skills.sh URL
+npx skill-forger add https://skills.sh/vercel-labs/skills/find-skills
+
+# Install skills globally
+npx skill-forger install --global
+
+# Install for multiple agents
+npx skill-forger install --agent claude-code --agent cursor
+```
+
+## Development
+
+🤖 Are you a robot? Read [AGENTS.md](./AGENTS.md).
+
+<details>
+
+<summary>local development</summary>
+
+- Clone this repository
+- Install [Bun](https://bun.sh)
+- Install dependencies using `bun install`
+- Run interactive tests using `bun run dev`
+
+</details>
+
+## Alternatives
+
+- Proposal PR for adding `skill-lock.json` ([vercel-labs/skills#234](https://github.com/vercel-labs/skills/pull/234))
+- Proposal PR for adding `.skills` ([vercel-labs/skills#134](https://github.com/vercel-labs/skills/pull/134))
+- [hairyf/skills-manifest](https://github.com/hairyf/skills-manifest)
+
+## License
+
+Published under the [MIT](https://github.com/unjs/skill-forger/blob/main/LICENSE) license 💛.

package/dist/cli.d.mts

@@ -0,0 +1,8 @@
+//#region src/cli.d.ts
+declare function parseSource(input: string): {
+  source: string;
+  skills: string[];
+};
+declare function main(argv?: string[]): Promise<void>;
+//#endregion
+export { main, parseSource };

package/dist/cli.mjs

@@ -0,0 +1,403 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { parseArgs } from "node:util";
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+//#region src/config.ts
+function findSkillsConfig(cwd = process.cwd()) {
+	let dir = resolve(cwd);
+	const root = dirname(dir);
+	while (dir !== root) {
+		const candidate = join(dir, "skills.json");
+		if (existsSync(candidate)) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	const rootCandidate = join(dir, "skills.json");
+	if (existsSync(rootCandidate)) return rootCandidate;
+}
+function defaultConfig() {
+	return { skills: [] };
+}
+async function readSkillsConfig(options = {}) {
+	const { cwd, createIfNotExists = false } = options;
+	const skillsPath = findSkillsConfig(cwd);
+	if (!skillsPath) {
+		if (createIfNotExists) {
+			const newPath = join(resolve(cwd ?? process.cwd()), "skills.json");
+			const config = defaultConfig();
+			await writeFile(newPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+			return {
+				config,
+				path: newPath
+			};
+		}
+		throw new Error("skills.json not found in current directory or any parent directory.");
+	}
+	const raw = await readFile(skillsPath, "utf8");
+	return {
+		config: assertSkillsConfig(JSON.parse(raw)),
+		path: skillsPath
+	};
+}
+async function updateSkillsConfig(updater, options = {}) {
+	const { cwd, createIfNotExists = true } = options;
+	const { config, path } = await readSkillsConfig({
+		cwd,
+		createIfNotExists
+	});
+	const validated = assertSkillsConfig(await updater(config) ?? config);
+	await writeFile(path, `${JSON.stringify(validated, null, 2)}\n`, "utf8");
+	return {
+		config: validated,
+		path
+	};
+}
+function addSkill(source, skills = [], options = {}) {
+	return updateSkillsConfig((config) => {
+		const entry = config.skills.find((item) => item.source === source);
+		if (!entry) {
+			config.skills.push({
+				source,
+				skills: [...skills]
+			});
+			return config;
+		}
+		if (skills.length === 0 || !entry.skills?.length) {
+			entry.skills = [];
+			return config;
+		}
+		const merged = new Set(entry.skills);
+		for (const skill of skills) merged.add(skill);
+		entry.skills = [...merged];
+		return config;
+	}, options);
+}
+function assertSkillsConfig(value) {
+	if (!value || typeof value !== "object" || !("skills" in value)) throw new Error("Invalid skills.json: missing 'skills' key.");
+	if (!("$schema" in value)) return {
+		$schema: "https://unpkg.com/skill-forger/skills_schema.json",
+		...value
+	};
+	return value;
+}
+//#endregion
+//#region src/utils/colors.ts
+const enabled = process.stdout.isTTY !== false;
+function code(n) {
+	return enabled ? `\x1B[${n}m` : "";
+}
+const c = {
+	reset: code(0),
+	bold: code(1),
+	dim: code(2),
+	red: code(31),
+	green: code(32),
+	yellow: code(33),
+	blue: code(34),
+	magenta: code(35),
+	cyan: code(36)
+};
+//#endregion
+//#region src/utils/gitignore.ts
+function findGitignore(cwd = process.cwd()) {
+	let dir = resolve(cwd);
+	const root = dirname(dir);
+	while (dir !== root) {
+		const candidate = join(dir, ".gitignore");
+		if (existsSync(candidate)) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	const rootCandidate = join(dir, ".gitignore");
+	if (existsSync(rootCandidate)) return rootCandidate;
+}
+async function addGitignoreEntry(entries, options = {}) {
+	const { cwd, createIfNotExists = true } = options;
+	const resolvedCwd = resolve(cwd ?? process.cwd());
+	const uniqueEntries = [...new Set((Array.isArray(entries) ? entries : [entries]).map((e) => e.trim()).filter(Boolean))];
+	if (uniqueEntries.length === 0) return;
+	let gitignorePath = findGitignore(resolvedCwd);
+	if (!gitignorePath) {
+		if (!createIfNotExists) return;
+		gitignorePath = join(resolvedCwd, ".gitignore");
+		await writeFile(gitignorePath, `${uniqueEntries.join("\n")}\n`, "utf8");
+		return gitignorePath;
+	}
+	const content = await readFile(gitignorePath, "utf8");
+	const existingLines = new Set(content.split("\n").map((line) => line.trim()));
+	const newEntries = uniqueEntries.filter((entry) => !existingLines.has(entry));
+	if (newEntries.length === 0) return gitignorePath;
+	const newContent = `${content}${content.endsWith("\n") ? "" : "\n"}${newEntries.join("\n")}\n`;
+	await writeFile(gitignorePath, newContent, "utf8");
+	return gitignorePath;
+}
+//#endregion
+//#region src/skills.ts
+let _skillsBinaryCache = null;
+function findSkillsBinary(options) {
+	if (options?.cache !== false && _skillsBinaryCache !== null) return _skillsBinaryCache;
+	let dir = dirname(fileURLToPath(import.meta.url));
+	while (true) {
+		const candidate = join(dir, "node_modules", ".bin", "skills");
+		if (existsSync(candidate)) {
+			_skillsBinaryCache = candidate;
+			return candidate;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	_skillsBinaryCache = void 0;
+}
+async function installSkills(options = {}) {
+	const { config, path: configPath } = await readSkillsConfig({ cwd: options.cwd });
+	await addGitignoreEntry(".agents", { cwd: dirname(configPath) });
+	const total = config.skills.length;
+	const totalStart = performance.now();
+	const globalPrefix = options.global ? `${c.magenta}[ global ]${c.reset} ` : "";
+	console.log(`${globalPrefix}🤹 Installing ${total} skill${total === 1 ? "" : "s"}...\n`);
+	let i = 0;
+	for (const entry of config.skills) {
+		i++;
+		await installSkillSource(entry, {
+			...options,
+			prefix: `[${i}/${total}] `
+		});
+	}
+	const totalDuration = formatDuration(performance.now() - totalStart);
+	console.log(`${globalPrefix}🎉 Done! ${total} skill${total === 1 ? "" : "s"} installed in ${c.green}${totalDuration}${c.reset}.`);
+}
+async function installSkillSource(entry, options) {
+	const skillsBinary = findSkillsBinary();
+	const globalPrefix = options.global ? `${c.magenta}[ global ]${c.reset} ` : "";
+	const skillList = (entry.skills?.length || 0) > 0 ? entry.skills?.join(", ") : "all skills";
+	console.log(`${globalPrefix}${c.cyan}◐${c.reset} ${options.prefix || ""}Installing ${c.cyan}${entry.source}${c.reset} ${c.dim}(${skillList})${c.reset}`);
+	const [command, args] = skillsBinary ? [skillsBinary, ["add", entry.source]] : ["npx", [
+		"skills",
+		"add",
+		entry.source
+	]];
+	if (entry.skills && entry.skills.length > 0) args.push("--skill", ...entry.skills);
+	else args.push("--skill", "*");
+	if (options.agents && options.agents.length > 0) args.push("--agent", ...options.agents);
+	if (options.global) args.push("--global");
+	if (options.yes) args.push("--yes");
+	if (process.env.DEBUG) console.log(`${c.dim}$ ${[command.replace(process.cwd(), "."), ...args].join(" ")}${c.reset}\n`);
+	const skillStart = performance.now();
+	await runCommand(command, args);
+	const skillDuration = formatDuration(performance.now() - skillStart);
+	console.log(`${globalPrefix}${c.green}✔${c.reset} Installed ${entry.source} ${c.dim}(${skillDuration})${c.reset}\n`);
+}
+function formatDuration(ms) {
+	const rounded = Math.round(ms);
+	if (rounded < 1e3) return `${rounded}ms`;
+	const seconds = Math.round(rounded / 1e3);
+	return seconds < 60 ? `${seconds}s` : `${Math.round(seconds / 60)}m`;
+}
+function runCommand(command, args) {
+	return new Promise((resolve, reject) => {
+		const stdout = [];
+		const stderr = [];
+		const child = spawn(command, args, { stdio: "pipe" });
+		child.stdout.on("data", (data) => stdout.push(data));
+		child.stderr.on("data", (data) => stderr.push(data));
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			const output = [Buffer.concat(stdout).toString(), Buffer.concat(stderr).toString()].filter(Boolean).join("\n");
+			if (output) console.error(output);
+			reject(/* @__PURE__ */ new Error(`${command} exited with code ${code ?? "unknown"}.`));
+		});
+	});
+}
+//#endregion
+//#region src/cli.ts
+const { version } = createRequire(import.meta.url)("../package.json");
+const name = "skill-forger";
+const SKILLS_SH_RE = /^(?:https?:\/\/)?skills\.sh\/(.+)/;
+function parseSource(input) {
+	const skillsShMatch = input.match(SKILLS_SH_RE)?.[1];
+	if (skillsShMatch) {
+		const [namespace, repo, ...skills] = skillsShMatch.split("/");
+		if (!(namespace && repo)) return {
+			source: input,
+			skills: []
+		};
+		const filtered = skills.flatMap((s) => s.split(",")).map((s) => s.trim()).filter(Boolean);
+		return {
+			source: `${namespace}/${repo}`,
+			skills: filtered.includes("*") ? [] : filtered
+		};
+	}
+	const [source = "", ...parts] = input.split(":");
+	const skills = parts.flatMap((p) => p.split(",")).map((s) => s.trim()).filter(Boolean);
+	return {
+		source,
+		skills: skills.includes("*") ? [] : skills
+	};
+}
+async function handleInstall(values) {
+	if (!findSkillsConfig()) {
+		console.log(`${c.yellow}No skills.json found.${c.reset}
+
+Get started by adding a skill source:
+
+${c.dim}$${c.reset} npx ${name} add ${c.cyan}vercel-labs/skills${c.reset}
+`);
+		return;
+	}
+	await installSkills({
+		yes: true,
+		agents: values.agent || ["claude-code"],
+		global: values.global
+	});
+}
+async function handleAdd(positionals, values) {
+	const sources = positionals.slice(1);
+	if (sources.length === 0) {
+		showUsage("add");
+		throw new Error("Missing skill source.");
+	}
+	const parsedSources = [];
+	for (const rawSource of sources) {
+		const { source, skills } = parseSource(rawSource);
+		const existing = parsedSources.find((p) => p.source === source);
+		if (existing) if (skills.length === 0 || existing.skills.length === 0) existing.skills = [];
+		else existing.skills = [...new Set([...existing.skills, ...skills])];
+		else parsedSources.push({
+			source,
+			skills: [...skills]
+		});
+	}
+	const agents = values.agent || ["claude-code"];
+	const globalPrefix = values.global ? `${c.magenta}[ global ]${c.reset} ` : "";
+	for (const { source, skills } of parsedSources) {
+		await installSkillSource({
+			source,
+			skills
+		}, {
+			agents,
+			yes: true,
+			global: values.global
+		});
+		await addSkill(source, skills);
+		console.log(`${globalPrefix}${c.green}✔${c.reset} Added ${c.cyan}${source}${c.reset} to skills.json`);
+	}
+}
+async function main(argv = process.argv.slice(2)) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		options: {
+			agent: {
+				type: "string",
+				multiple: true
+			},
+			global: {
+				type: "boolean",
+				short: "g"
+			},
+			help: {
+				type: "boolean",
+				short: "h"
+			},
+			version: {
+				type: "boolean",
+				short: "v"
+			}
+		}
+	});
+	if (values.version) {
+		console.log(`${name} ${version}`);
+		return;
+	}
+	const command = positionals[0];
+	if (values.help) {
+		showUsage(command);
+		return;
+	}
+	if (!command || command === "install" || command === "i") {
+		await handleInstall(values);
+		return;
+	}
+	if (command === "add") {
+		await handleAdd(positionals, values);
+		return;
+	}
+	throw new Error(`Unknown command: ${command}`);
+}
+function showUsage(command) {
+	if (command === "add") {
+		console.log(`
+${c.bold}Usage:${c.reset} ${c.cyan}${name} add${c.reset} <source>... [options]
+
+${c.bold}Arguments:${c.reset}
+  ${c.cyan}<source>${c.reset}          Skill source ${c.dim}(e.g., vercel-labs/skills:pdf,commit)${c.reset}
+
+${c.bold}Options:${c.reset}
+  ${c.cyan}--agent${c.reset} <name>    Target agent ${c.dim}(default: claude-code, can be repeated)${c.reset}
+  ${c.cyan}-h, --help${c.reset}        Show this help message
+
+${c.bold}Examples:${c.reset}
+  ${c.dim}$${c.reset} ${name} add vercel-labs/skills
+  ${c.dim}$${c.reset} ${name} add vercel-labs/skills:pdf,commit
+  ${c.dim}$${c.reset} ${name} add vercel-labs/skills:find-skills anthropics/skills:skill-creator
+  ${c.dim}$${c.reset} ${name} add https://skills.sh/vercel-labs/skills/pdf
+`);
+		return;
+	}
+	if (command === "install" || command === "i") {
+		console.log(`
+${c.bold}Usage:${c.reset} ${c.cyan}${name} install${c.reset} [options]
+
+${c.bold}Options:${c.reset}
+  ${c.cyan}--agent${c.reset} <name>    Target agent ${c.dim}(default: claude-code, can be repeated)${c.reset}
+  ${c.cyan}-g, --global${c.reset}      Install skills globally
+  ${c.cyan}-h, --help${c.reset}        Show this help message
+
+${c.bold}Examples:${c.reset}
+  ${c.dim}$${c.reset} npx ${name} install
+  ${c.dim}$${c.reset} npx ${name} install --global
+  ${c.dim}$${c.reset} npx ${name} install --agent claude-code --agent cursor
+`);
+		return;
+	}
+	console.log(`
+${c.bold}${name}${c.reset} ${c.dim}v${version}${c.reset}
+
+Manage project skills declaratively with ${c.cyan}skills.json${c.reset}
+
+${c.bold}Usage:${c.reset} ${c.cyan}${name}${c.reset} <command> [options]
+
+${c.bold}Commands:${c.reset}
+  ${c.cyan}install, i${c.reset}        Install skills from skills.json ${c.dim}(default)${c.reset}
+  ${c.cyan}add${c.reset}               Add a skill source to skills.json
+
+${c.bold}Options:${c.reset}
+  ${c.cyan}-h, --help${c.reset}        Show help for a command
+  ${c.cyan}-v, --version${c.reset}     Show version number
+
+${c.bold}Examples:${c.reset}
+  ${c.dim}$${c.reset} ${name}                              ${c.dim}# Install all skills${c.reset}
+  ${c.dim}$${c.reset} ${name} add vercel-labs/skills       ${c.dim}# Add a skill source${c.reset}
+  ${c.dim}$${c.reset} ${name} add owner/repo:pdf,commit    ${c.dim}# Add specific skills${c.reset}
+  ${c.dim}$${c.reset} ${name} add org/a:skill1 org/b:skill2 ${c.dim}# Add multiple sources${c.reset}
+
+Run ${c.cyan}${name} <command> --help${c.reset} for command-specific help.
+`);
+}
+main().catch((error) => {
+	console.error(`${c.red}error:${c.reset} ${error instanceof Error ? error.message : error}`);
+	process.exitCode = 1;
+});
+//#endregion
+export { main, parseSource };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "skill-forger",
+  "version": "0.1.0",
+  "description": "Manage project Agent skills declaratively with skills.json",
+  "license": "MIT",
+  "author": "Marc Mansour",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marcm8793/skillforge.git"
+  },
+  "type": "module",
+  "bin": {
+    "skill-forger": "./dist/cli.mjs",
+    "sf": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "skills_schema.json"
+  ],
+  "keywords": [
+    "skills",
+    "cli",
+    "agent-skills",
+    "ai-agents",
+    "claude-code"
+  ],
+  "scripts": {
+    "build": "obuild",
+    "dev": "vitest --watch",
+    "test": "vitest run",
+    "check": "ultracite check",
+    "fix": "ultracite fix",
+    "typecheck": "tsc --noEmit",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "skills": "^1.4.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.7",
+    "@types/bun": "latest",
+    "jiti": "^2.6.1",
+    "obuild": "^0.4.32",
+    "typescript": "^5",
+    "ultracite": "7.3.2",
+    "vitest": "^4.1.2"
+  }
+}

package/skills_schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/skill-forger/skills_schema.json",
+  "title": "Skills Config",
+  "description": "Configuration file for skill-forger - manages project skills",
+  "type": "object",
+  "required": ["skills"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "skills": {
+      "type": "array",
+      "description": "List of skill sources to install",
+      "items": {
+        "type": "object",
+        "required": ["source"],
+        "properties": {
+          "source": {
+            "type": "string",
+            "description": "Skill source identifier (e.g., 'vercel-labs/skills')"
+          },
+          "skills": {
+            "type": "array",
+            "description": "Specific skills to install from this source (empty array or omitted = all)",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}