@aiskillet/cli 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chinmay Murugkar (AISkillet)
+
+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,54 @@
+# 🍳 skillet
+
+The CLI for [AISkillet](https://aiskillet.com) — install AI skills from the marketplace into **whatever tool you already use**. Write a capability once; `skillet` compiles it into each tool's native format.
+
+```bash
+npx @aiskillet/cli search api
+npx @aiskillet/cli add api-design --target cursor
+npx @aiskillet/cli add api-design --target claude-code --global
+```
+
+## Why
+
+A skill written once should run everywhere. `skillet` is the portability layer: it fetches a skill's canonical `SKILL.md` from its source repo and **compiles** it to the target tool's format + install location — no copy-paste, no reformatting.
+
+| Target | Output | Location |
+|---|---|---|
+| `claude-code` | native `SKILL.md` | `.claude/skills/<name>/` (or `~/.claude/skills` with `--global`) |
+| `cursor` | `.mdc` rule with Cursor frontmatter | `.cursor/rules/<name>.mdc` |
+| `agents-md` | portable `AGENTS.md`-style skill | `.agents/skills/<name>.md` |
+
+We never execute the skill — we only read Markdown. The code stays in its source repo.
+
+## Commands
+
+```
+skillet search [query]              Search the marketplace
+skillet add <name> --target <t>     Compile + install a skill for a target
+skillet list                        List skills installed in this directory
+skillet remove <name> [--target t]  Remove an installed skill
+skillet targets                     List supported targets
+```
+
+### Options
+- `-t, --target <name>` — target tool (`claude-code`, `cursor`, `agents-md`)
+- `-g, --global` — install for the user (e.g. `~/.claude`) instead of the project
+- `--registry <url>` — registry `index.json` URL or local path (env: `SKILLET_REGISTRY`)
+- `--cwd <dir>` — project directory to install into
+
+## Install
+
+```bash
+npm install -g @aiskillet/cli
+# or run without installing:
+npx @aiskillet/cli <command>
+```
+
+Requires Node 20+. Zero runtime dependencies.
+
+## Roadmap
+
+- **Now:** portability/compiler — write once, install into any tool.
+- **Next:** `skillet run <agent>` — run marketplace agents locally against any model (bring-your-own-key) with MCP tools.
+
+MIT licensed.

package/bin/skillet.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/index.mjs";
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(`\x1b[31m✗ ${err?.message ?? err}\x1b[0m`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@aiskillet/cli",
+  "version": "0.5.0",
+  "description": "Install AI skills from the AISkillet marketplace into any tool — write once, run anywhere.",
+  "type": "module",
+  "bin": {
+    "skillet": "bin/skillet.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": ["bin", "src", "README.md", "LICENSE"],
+  "keywords": ["ai", "skills", "agents", "claude", "cursor", "mcp", "marketplace", "portability"],
+  "homepage": "https://aiskillet.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aiskillet/cli.git"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  }
+}

package/src/commands.mjs

@@ -0,0 +1,113 @@
+import { writeFile, mkdir, rm } from "node:fs/promises";
+import { dirname, relative } from "node:path";
+import { loadRegistry, searchEntries, findEntry } from "./registry.mjs";
+import { fetchItem, fetchPluginManifest } from "./source.mjs";
+import { compile, TARGETS } from "./compile.mjs";
+import { recordInstall, readLock, removeInstall } from "./store.mjs";
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const ok = (s) => `\x1b[32m${s}\x1b[0m`;
+
+function rel(cwd, p) {
+  const r = relative(cwd, p);
+  return r.startsWith("..") ? p : r;
+}
+
+export async function search(query, opts) {
+  const entries = await loadRegistry(opts.registry);
+  const results = searchEntries(entries, query);
+  if (!results.length) {
+    console.log(`No results${query ? ` for "${query}"` : ""}.`);
+    return;
+  }
+  console.log(`Found ${results.length} listing${results.length === 1 ? "" : "s"}:\n`);
+  for (const e of results) {
+    console.log(`  ${bold(e.name)}  ${dim(`[${e.type}]`)}${e.verified ? "  " + ok("✓") : ""}`);
+    console.log(`    ${e.description}`);
+    console.log(`    ${dim(`skillet add ${e.name} --target <${TARGETS.join("|")}>`)}\n`);
+  }
+}
+
+export async function add(name, opts) {
+  if (!name) throw new Error("Usage:  skillet add <name> --target <target>");
+  const target = opts.target;
+  if (!target) throw new Error(`Specify a target:  --target <${TARGETS.join("|")}>`);
+  const cwd = opts.cwd || process.cwd();
+
+  const entries = await loadRegistry(opts.registry);
+  const entry = findEntry(entries, name);
+
+  // MCP servers run as external processes — not compiled by skillet. Show the command.
+  if (entry.type === "mcp") {
+    console.log(`${bold(name)} is an MCP server. Add it to Claude Code with:\n`);
+    console.log(`  ${entry.install}\n`);
+    console.log(dim(`Source: ${entry.repo}`));
+    return;
+  }
+
+  // Plugin = a bundle: install each member entry.
+  if (entry.type === "plugin") {
+    const manifest = await fetchPluginManifest(entry);
+    console.log(`Installing plugin ${bold(name)} — ${manifest.includes.length} item(s) → ${target}\n`);
+    let count = 0;
+    for (const inc of manifest.includes) {
+      const member = findEntry(entries, inc.name);
+      const item = await fetchItem(member);
+      for (const f of compile(target, item, { global: opts.global, cwd })) {
+        await mkdir(dirname(f.path), { recursive: true });
+        await writeFile(f.path, f.content);
+        await recordInstall(cwd, { name: item.name, target, path: f.path, installedAt: new Date().toISOString() });
+        console.log(`  ${ok("✓")} ${item.name} ${dim(`(${item.type})`)} → ${rel(cwd, f.path)}`);
+      }
+      count++;
+    }
+    console.log(`\n${ok("✓")} Installed plugin ${bold(name)} (${count} items) → ${target}.`);
+    return;
+  }
+
+  process.stdout.write(`Resolving ${bold(name)}@aiskillet … `);
+  const item = await fetchItem(entry);
+  console.log(ok("ok"));
+
+  const files = compile(target, item, { global: opts.global, cwd });
+  for (const f of files) {
+    await mkdir(dirname(f.path), { recursive: true });
+    await writeFile(f.path, f.content);
+    await recordInstall(cwd, {
+      name: item.name,
+      target,
+      path: f.path,
+      installedAt: new Date().toISOString(),
+    });
+    console.log(`  ${ok("✓")} ${rel(cwd, f.path)}`);
+  }
+  console.log(`\n${ok("✓")} Installed ${bold(item.name)} (${item.type}) → ${target}.`);
+}
+
+export async function list(opts) {
+  const cwd = opts.cwd || process.cwd();
+  const lock = await readLock(cwd);
+  if (!lock.installed.length) {
+    console.log("No skills installed in this directory.");
+    return;
+  }
+  console.log(`Installed here ${dim(`(${cwd})`)}:\n`);
+  for (const r of lock.installed) {
+    console.log(`  ${bold(r.name)}  ${dim(`→ ${r.target}`)}  ${dim(rel(cwd, r.path))}`);
+  }
+}
+
+export async function remove(name, opts) {
+  if (!name) throw new Error("Usage:  skillet remove <name> [--target <target>]");
+  const cwd = opts.cwd || process.cwd();
+  const removed = await removeInstall(cwd, name, opts.target);
+  if (!removed.length) {
+    console.log(`Nothing to remove for "${name}"${opts.target ? ` (target ${opts.target})` : ""}.`);
+    return;
+  }
+  for (const r of removed) {
+    await rm(r.path, { force: true });
+    console.log(`  ${ok("✓")} removed ${rel(cwd, r.path)} ${dim(`(${r.target})`)}`);
+  }
+}

package/src/compile.mjs

@@ -0,0 +1,70 @@
+// The portability layer: turn one canonical skill (SKILL.md) into each
+// target tool's native format + install location. Add a target = add a compiler.
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const TARGETS = ["claude-code", "cursor", "agents-md"];
+
+/** Quote a value for single-line YAML only when needed. */
+function yamlScalar(s) {
+  const oneLine = String(s).replace(/\s+/g, " ").trim();
+  return /[:#"'\[\]{}]|^\s|\s$/.test(oneLine) ? JSON.stringify(oneLine) : oneLine;
+}
+
+/**
+ * Claude Code — SKILL.md / AGENT.md are already native formats.
+ * Skills → .claude/skills/<name>/SKILL.md
+ * Agents → .claude/agents/<name>.md
+ * (--global installs under ~/.claude instead of the project.)
+ */
+function claudeCode(item, { global, cwd }) {
+  const root = global ? join(homedir(), ".claude") : join(cwd, ".claude");
+  if (item.type === "agent") {
+    return [{ path: join(root, "agents", `${item.name}.md`), content: item.md }];
+  }
+  return [{ path: join(root, "skills", item.name, "SKILL.md"), content: item.md }];
+}
+
+/**
+ * Cursor — project rules live in .cursor/rules/<name>.mdc with their own
+ * frontmatter (description drives agent-requested activation).
+ */
+function cursor(skill, { cwd }) {
+  const frontmatter =
+    `---\n` +
+    `description: ${yamlScalar(skill.description)}\n` +
+    `alwaysApply: false\n` +
+    `---\n\n`;
+  return [
+    { path: join(cwd, ".cursor", "rules", `${skill.name}.mdc`), content: frontmatter + skill.body + "\n" },
+  ];
+}
+
+/**
+ * AGENTS.md — the emerging cross-tool convention (Codex, Gemini CLI, etc.).
+ * We write a per-skill file under .agents/skills and expect an AGENTS.md include;
+ * for the MVP we emit the standalone skill file so it's portable.
+ */
+function agentsMd(item, { cwd }) {
+  const folder = item.type === "agent" ? "agents" : "skills";
+  const content = `# ${item.name}\n\n> ${item.description}\n\n${item.body}\n`;
+  return [{ path: join(cwd, ".agents", folder, `${item.name}.md`), content }];
+}
+
+const COMPILERS = {
+  "claude-code": claudeCode,
+  cursor,
+  "agents-md": agentsMd,
+};
+
+/** Compile a skill for a target → array of { path, content } to write. */
+export function compile(target, skill, opts) {
+  const fn = COMPILERS[target];
+  if (!fn) {
+    throw new Error(
+      `Unsupported target "${target}". Supported: ${TARGETS.join(", ")}`
+    );
+  }
+  return fn(skill, opts);
+}

package/src/index.mjs

@@ -0,0 +1,99 @@
+import { parseArgs } from "node:util";
+import { search, add, list, remove } from "./commands.mjs";
+import { TARGETS } from "./compile.mjs";
+
+export const VERSION = "0.5.0";
+
+const HELP = `\x1b[1m🍳 skillet\x1b[0m — install AI skills into any tool. Write once, run anywhere.
+
+\x1b[1mUsage\x1b[0m
+  skillet <command> [options]
+
+\x1b[1mCommands\x1b[0m
+  search [query]              Search the AISkillet marketplace
+  add <name> --target <t>     Compile a skill and install it for a target tool
+  list                        List skills installed in this directory
+  remove <name> [--target t]  Remove an installed skill
+  targets                     List supported targets
+  help                        Show this help
+
+\x1b[1mTargets\x1b[0m
+  ${TARGETS.join(", ")}
+
+\x1b[1mOptions\x1b[0m
+  -t, --target <name>   Target tool to compile for
+  -g, --global          Install for the user (e.g. ~/.claude) instead of the project
+      --registry <url>   Registry index.json URL or local path (env: SKILLET_REGISTRY)
+      --cwd <dir>        Project directory to install into (default: current dir)
+  -h, --help             Show help
+  -v, --version          Show version
+
+\x1b[1mExamples\x1b[0m
+  skillet search api
+  skillet add api-design --target cursor
+  skillet add api-design --target claude-code --global
+  skillet list
+`;
+
+export async function main(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        target: { type: "string", short: "t" },
+        registry: { type: "string" },
+        global: { type: "boolean", short: "g" },
+        cwd: { type: "string" },
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+      },
+    });
+  } catch (err) {
+    console.error(`\x1b[31m✗ ${err.message}\x1b[0m\n`);
+    console.log(HELP);
+    process.exitCode = 1;
+    return;
+  }
+
+  const { values, positionals } = parsed;
+  const cmd = positionals[0];
+
+  if (values.version) {
+    console.log(VERSION);
+    return;
+  }
+  if (!cmd || (values.help && cmd == null)) {
+    console.log(HELP);
+    return;
+  }
+
+  switch (cmd) {
+    case "search":
+      await search(positionals[1], values);
+      break;
+    case "add":
+    case "install":
+      await add(positionals[1], values);
+      break;
+    case "list":
+    case "ls":
+      await list(values);
+      break;
+    case "remove":
+    case "rm":
+      await remove(positionals[1], values);
+      break;
+    case "targets":
+      console.log("Supported targets:\n" + TARGETS.map((t) => "  " + t).join("\n"));
+      break;
+    case "help":
+      console.log(HELP);
+      break;
+    default:
+      console.error(`\x1b[31m✗ Unknown command: ${cmd}\x1b[0m\n`);
+      console.log(HELP);
+      process.exitCode = 1;
+  }
+}

package/src/registry.mjs

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+
+const DEFAULT_REGISTRY =
+  process.env.SKILLET_REGISTRY || "https://aiskillet.com/index.json";
+
+/** Load the marketplace catalog from a URL or local file path. */
+export async function loadRegistry(registry) {
+  const src = registry || DEFAULT_REGISTRY;
+  let text;
+  if (/^https?:\/\//.test(src)) {
+    const res = await fetch(src);
+    if (!res.ok) {
+      throw new Error(`Failed to load registry (${res.status}) from ${src}`);
+    }
+    text = await res.text();
+  } else {
+    text = await readFile(src.replace(/^file:\/\//, ""), "utf8");
+  }
+  const data = JSON.parse(text);
+  const entries = Array.isArray(data) ? data : data.entries || [];
+  if (!entries.length) throw new Error(`Registry at ${src} has no entries.`);
+  return entries;
+}
+
+export function searchEntries(entries, query) {
+  if (!query) return entries;
+  const q = query.toLowerCase();
+  return entries.filter((e) =>
+    [e.name, e.title, e.description, ...(e.tags || [])]
+      .join(" ")
+      .toLowerCase()
+      .includes(q)
+  );
+}
+
+export function findEntry(entries, name) {
+  const e = entries.find((x) => x.name === name);
+  if (!e) {
+    throw new Error(`No listing named "${name}". Try:  skillet search ${name}`);
+  }
+  return e;
+}

package/src/source.mjs

@@ -0,0 +1,91 @@
+// Fetches a skill's canonical SKILL.md from its source repo and parses it.
+// We never execute anything — we only read the Markdown + frontmatter.
+
+/** Parse a repo URL like https://github.com/owner/repo into parts. */
+export function parseRepo(repoUrl) {
+  const u = new URL(repoUrl);
+  const [owner, repo] = u.pathname
+    .replace(/^\//, "")
+    .replace(/\.git$/, "")
+    .split("/");
+  if (!owner || !repo) throw new Error(`Not a GitHub repo URL: ${repoUrl}`);
+  return { owner, repo };
+}
+
+/** Minimal YAML-frontmatter parser (flat key: value pairs). */
+export function parseFrontmatter(md) {
+  const m = md.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) return { data: {}, body: md.trim() };
+  const data = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    let val = line.slice(idx + 1).trim().replace(/^["']|["']$/g, "");
+    if (key) data[key] = val;
+  }
+  return { data, body: m[2].trim() };
+}
+
+/** The canonical file name for an entry's type. */
+export function fileNameFor(entry) {
+  return entry.type === "agent" ? "AGENT.md" : "SKILL.md";
+}
+
+/**
+ * Which git ref(s) to fetch. If the entry pins a commit SHA (`rev`), we fetch
+ * exactly that commit — defeating TOCTOU (source can't change under us).
+ * Otherwise fall back to the default branch.
+ */
+export function refsFor(entry) {
+  return entry.rev ? [entry.rev] : ["main", "master"];
+}
+
+function rawUrls(entry) {
+  const { owner, repo } = parseRepo(entry.repo);
+  const base = entry.path ? entry.path.replace(/\/+$/, "") + "/" : "";
+  const file = fileNameFor(entry);
+  return refsFor(entry).map(
+    (ref) =>
+      `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${base}${file}`
+  );
+}
+
+/** Fetch a plugin bundle's manifest (plugin.json) listing its member entries. */
+export async function fetchPluginManifest(entry) {
+  const { owner, repo } = parseRepo(entry.repo);
+  const base = entry.path ? entry.path.replace(/\/+$/, "") + "/" : "";
+  for (const ref of refsFor(entry)) {
+    const res = await fetch(
+      `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${base}plugin.json`
+    );
+    if (res.ok) {
+      const manifest = JSON.parse(await res.text());
+      manifest.includes = Array.isArray(manifest.includes) ? manifest.includes : [];
+      return manifest;
+    }
+  }
+  throw new Error(`Could not fetch plugin.json for "${entry.name}" from ${entry.repo}`);
+}
+
+/** Fetch + parse the canonical doc (SKILL.md or AGENT.md) for a catalog entry. */
+export async function fetchItem(entry) {
+  for (const url of rawUrls(entry)) {
+    const res = await fetch(url);
+    if (res.ok) {
+      const md = await res.text();
+      const { data, body } = parseFrontmatter(md);
+      return {
+        md,
+        body,
+        type: entry.type || "skill",
+        name: data.name || entry.name,
+        description: data.description || entry.description || "",
+      };
+    }
+  }
+  throw new Error(
+    `Could not fetch ${fileNameFor(entry)} for "${entry.name}" from ${entry.repo}` +
+      (entry.path ? ` (path: ${entry.path})` : "")
+  );
+}

package/src/store.mjs

@@ -0,0 +1,44 @@
+// Tracks what's installed where, in a per-project lockfile: .skillet/installed.json
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const dir = (cwd) => join(cwd, ".skillet");
+const lockPath = (cwd) => join(dir(cwd), "installed.json");
+
+export async function readLock(cwd) {
+  const p = lockPath(cwd);
+  if (!existsSync(p)) return { installed: [] };
+  try {
+    const lock = JSON.parse(await readFile(p, "utf8"));
+    return { installed: Array.isArray(lock.installed) ? lock.installed : [] };
+  } catch {
+    return { installed: [] };
+  }
+}
+
+async function writeLock(cwd, lock) {
+  await mkdir(dir(cwd), { recursive: true });
+  await writeFile(lockPath(cwd), JSON.stringify(lock, null, 2) + "\n");
+}
+
+/** Record (or replace) an install for a given name+target. */
+export async function recordInstall(cwd, record) {
+  const lock = await readLock(cwd);
+  lock.installed = lock.installed.filter(
+    (r) => !(r.name === record.name && r.target === record.target)
+  );
+  lock.installed.push(record);
+  await writeLock(cwd, lock);
+}
+
+/** Remove install records matching name (and optional target). Returns them. */
+export async function removeInstall(cwd, name, target) {
+  const lock = await readLock(cwd);
+  const match = (r) => r.name === name && (!target || r.target === target);
+  const removed = lock.installed.filter(match);
+  lock.installed = lock.installed.filter((r) => !match(r));
+  await writeLock(cwd, lock);
+  return removed;
+}