@getskillmd/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tekcify
+
+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,62 @@
+# @getskillmd/cli
+
+Install `skill.md` files into Claude Code, Cursor, and Windsurf with one command.
+
+## Install
+
+No install needed — use `npx`:
+
+```bash
+npx @getskillmd/cli add stripe
+```
+
+Or install globally:
+
+```bash
+npm i -g @getskillmd/cli
+getskillmd add stripe
+```
+
+## Usage
+
+### Add a skill by slug
+
+```bash
+npx @getskillmd/cli add stripe
+npx @getskillmd/cli add tailwind --ide cursor
+npx @getskillmd/cli add nextjs --ide all
+```
+
+### Generate from a URL
+
+```bash
+npx @getskillmd/cli add https://stripe.com/docs/api
+npx @getskillmd/cli add https://nextjs.org/docs --mode library
+```
+
+Modes: `design` (default), `api`, `library`, `generic`.
+
+### List installed skills
+
+```bash
+npx @getskillmd/cli list
+```
+
+## IDE behavior
+
+| IDE          | Path written                          | Notes                              |
+| ------------ | ------------------------------------- | ---------------------------------- |
+| Claude Code  | `.claude/skills/<slug>/SKILL.md`      | Directory created if missing       |
+| Cursor       | `.cursor/rules/<slug>.mdc`            | Wrapped with Cursor frontmatter    |
+| Windsurf     | `.windsurfrules`                      | Appended in a labelled section     |
+
+If `--ide` is not provided, the CLI detects which config dirs already exist
+in your project. If multiple are found (or none), you are prompted.
+
+## Environment
+
+- `GETSKILLMD_API_URL` — override the API base URL. Defaults to `https://getskillmd.com`.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+import kleur from "kleur";
+import prompts from "prompts";
+
+// src/constants.ts
+var DEFAULT_API_URL = "https://getskillmd.com";
+var POLL_INTERVAL_MS = 2e3;
+var POLL_TIMEOUT_MS = 24e4;
+var REQUEST_TIMEOUT_MS = 3e4;
+var IDE_LABELS = {
+  claude: "Claude Code",
+  cursor: "Cursor",
+  windsurf: "Windsurf"
+};
+var IDE_PATHS = {
+  claude: ".claude/skills",
+  cursor: ".cursor/rules",
+  windsurf: ".windsurfrules"
+};
+var WINDSURF_SECTION_HEADER_PREFIX = "# getskillmd:";
+var WINDSURF_SECTION_FOOTER_PREFIX = "# end getskillmd:";
+var VALID_MODES = ["design", "api", "library", "generic"];
+var VALID_IDES = ["claude", "cursor", "windsurf", "all"];
+
+// src/api.ts
+function getBaseUrl() {
+  const fromEnv = process.env.GETSKILLMD_API_URL;
+  if (fromEnv && fromEnv.trim().length > 0) {
+    return fromEnv.replace(/\/$/, "");
+  }
+  return DEFAULT_API_URL;
+}
+async function request(path, init = {}, timeoutMs = REQUEST_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(`${getBaseUrl()}${path}`, {
+      ...init,
+      signal: controller.signal,
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "User-Agent": "getskillmd-cli",
+        ...init.headers ?? {}
+      }
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      let message = `Request failed (${response.status})`;
+      try {
+        const parsed = JSON.parse(text);
+        message = parsed.error ?? parsed.message ?? message;
+      } catch {
+        if (text) message = text.slice(0, 200);
+      }
+      throw new ApiError(message, response.status);
+    }
+    return await response.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var ApiError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+  }
+};
+async function fetchSkillBySlug(slug) {
+  return request(
+    `/api/cli/skills/${encodeURIComponent(slug)}`,
+    { method: "GET" }
+  );
+}
+async function startGenerationFromUrl(url, mode) {
+  return request("/api/cli/generate", {
+    method: "POST",
+    body: JSON.stringify({ url, mode })
+  });
+}
+async function pollGeneration(id) {
+  return request(`/api/cli/poll/${encodeURIComponent(id)}`, {
+    method: "GET"
+  });
+}
+async function waitForGeneration(id, onTick) {
+  const start = Date.now();
+  while (Date.now() - start < POLL_TIMEOUT_MS) {
+    const result = await pollGeneration(id);
+    onTick(result.status);
+    if (result.status === "done" || result.status === "failed") {
+      return result;
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new Error("Timed out waiting for generation");
+}
+function sleep(ms) {
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
+}
+function isUrlInput(input) {
+  if (input.startsWith("http://") || input.startsWith("https://")) return true;
+  if (input.includes("://")) return true;
+  return false;
+}
+
+// src/install.ts
+import { existsSync } from "fs";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join, resolve } from "path";
+async function installSkill(input) {
+  const results = [];
+  for (const ide of input.ides) {
+    if (ide === "claude") {
+      results.push(await writeClaudeSkill(input.cwd, input.slug, input.skillMd));
+    } else if (ide === "cursor") {
+      results.push(await writeCursorRule(input.cwd, input.slug, input.skillMd));
+    } else if (ide === "windsurf") {
+      results.push(await writeWindsurfSection(input.cwd, input.slug, input.skillMd));
+    }
+  }
+  return results;
+}
+async function writeClaudeSkill(cwd, slug, skillMd) {
+  const dir = resolve(cwd, IDE_PATHS.claude, slug);
+  const path = join(dir, "SKILL.md");
+  await mkdir(dir, { recursive: true });
+  await writeFile(path, skillMd, "utf8");
+  return { ide: "claude", path, written: true };
+}
+async function writeCursorRule(cwd, slug, skillMd) {
+  const dir = resolve(cwd, IDE_PATHS.cursor);
+  const path = join(dir, `${slug}.mdc`);
+  await mkdir(dir, { recursive: true });
+  const body = stripFrontmatter(skillMd);
+  const description = extractDescription(skillMd) ?? slug;
+  const content = [
+    "---",
+    `description: ${escapeYaml(description)}`,
+    "globs:",
+    '  - "**/*"',
+    "alwaysApply: false",
+    "---",
+    "",
+    body.trimStart()
+  ].join("\n");
+  await writeFile(path, content, "utf8");
+  return { ide: "cursor", path, written: true };
+}
+async function writeWindsurfSection(cwd, slug, skillMd) {
+  const path = resolve(cwd, IDE_PATHS.windsurf);
+  await mkdir(dirname(path), { recursive: true });
+  let existing = "";
+  if (existsSync(path)) {
+    existing = await readFile(path, "utf8");
+  }
+  const header = `${WINDSURF_SECTION_HEADER_PREFIX}${slug}`;
+  const footer = `${WINDSURF_SECTION_FOOTER_PREFIX}${slug}`;
+  const block = [header, "", skillMd.trimEnd(), "", footer, ""].join("\n");
+  const sectionRegex = new RegExp(
+    `(^|\\n)${escapeRegex(header)}[\\s\\S]*?${escapeRegex(footer)}\\n?`,
+    "g"
+  );
+  const stripped = existing.replace(sectionRegex, "$1");
+  const next = (stripped.trimEnd() + "\n\n" + block).trimStart();
+  await writeFile(path, next, "utf8");
+  return { ide: "windsurf", path, written: true };
+}
+function detectIdes(cwd) {
+  const detected = [];
+  if (existsSync(resolve(cwd, ".claude"))) detected.push("claude");
+  if (existsSync(resolve(cwd, ".cursor"))) detected.push("cursor");
+  if (existsSync(resolve(cwd, ".windsurfrules"))) detected.push("windsurf");
+  return detected;
+}
+function expandIdeSelection(selection) {
+  if (selection === "all") return ["claude", "cursor", "windsurf"];
+  return [selection];
+}
+function stripFrontmatter(raw) {
+  return raw.replace(/^---\n[\s\S]*?\n---\n*/, "");
+}
+function extractDescription(raw) {
+  const match = raw.match(/^description:\s*(.+)$/m);
+  if (!match) return null;
+  return match[1].trim().replace(/^"(.*)"$/, "$1");
+}
+function escapeYaml(value) {
+  if (/[":\n]/.test(value)) {
+    return `"${value.replace(/"/g, '\\"').replace(/\n/g, " ")}"`;
+  }
+  return value;
+}
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/list.ts
+import { existsSync as existsSync2 } from "fs";
+import { readdir, readFile as readFile2, stat } from "fs/promises";
+import { join as join2, resolve as resolve2 } from "path";
+async function listInstalledSkills(cwd) {
+  const skills = [];
+  skills.push(...await listClaudeSkills(cwd));
+  skills.push(...await listCursorSkills(cwd));
+  skills.push(...await listWindsurfSkills(cwd));
+  return skills;
+}
+async function listClaudeSkills(cwd) {
+  const root = resolve2(cwd, IDE_PATHS.claude);
+  if (!existsSync2(root)) return [];
+  const entries = await readdir(root);
+  const out = [];
+  for (const entry of entries) {
+    const dir = join2(root, entry);
+    const info = await stat(dir).catch(() => null);
+    if (!info?.isDirectory()) continue;
+    const path = join2(dir, "SKILL.md");
+    if (existsSync2(path)) {
+      out.push({ ide: "claude", slug: entry, path });
+    }
+  }
+  return out;
+}
+async function listCursorSkills(cwd) {
+  const root = resolve2(cwd, IDE_PATHS.cursor);
+  if (!existsSync2(root)) return [];
+  const entries = await readdir(root);
+  return entries.filter((entry) => entry.endsWith(".mdc")).map((entry) => ({
+    ide: "cursor",
+    slug: entry.replace(/\.mdc$/, ""),
+    path: join2(root, entry)
+  }));
+}
+async function listWindsurfSkills(cwd) {
+  const path = resolve2(cwd, IDE_PATHS.windsurf);
+  if (!existsSync2(path)) return [];
+  const content = await readFile2(path, "utf8");
+  const matches = content.matchAll(
+    new RegExp(`^${escapeRegex2(WINDSURF_SECTION_HEADER_PREFIX)}(.+)$`, "gm")
+  );
+  const out = [];
+  for (const match of matches) {
+    out.push({ ide: "windsurf", slug: match[1].trim(), path });
+  }
+  return out;
+}
+function escapeRegex2(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/cli.ts
+var VERSION = "0.1.0";
+var program = new Command();
+program.name("getskillmd").description("Install skill.md files into Claude Code, Cursor, and Windsurf").version(VERSION, "-v, --version", "Print the version");
+program.command("add").argument("<slug-or-url>", "skill slug or source URL").option(
+  "--ide <ide>",
+  `target IDE: ${VALID_IDES.join(" | ")}`
+).option(
+  "--mode <mode>",
+  `generation mode (URL only): ${VALID_MODES.join(" | ")}`,
+  "design"
+).option("--cwd <path>", "working directory", process.cwd()).description("Install a skill into your IDE").action(async (input, options) => {
+  try {
+    await runAdd(input, options);
+  } catch (error) {
+    handleError(error);
+  }
+});
+program.command("list").option("--cwd <path>", "working directory", process.cwd()).description("List skills installed in this project").action(async (options) => {
+  try {
+    await runList(options);
+  } catch (error) {
+    handleError(error);
+  }
+});
+program.parseAsync(process.argv).catch(handleError);
+async function runAdd(input, options) {
+  const cwd = options.cwd;
+  const ideSelection = await resolveIdeSelection(options.ide, cwd);
+  const ides = expandIdeSelection(ideSelection);
+  const mode = parseMode(options.mode);
+  const skill = isUrlInput(input) ? await generateFromUrl(input, mode) : await loadFromSlug(input);
+  console.log(
+    kleur.dim("Installing"),
+    kleur.cyan(skill.slug),
+    kleur.dim("into"),
+    kleur.bold(ides.map((i) => IDE_LABELS[i]).join(", "))
+  );
+  const results = await installSkill({
+    cwd,
+    slug: skill.slug,
+    skillMd: skill.skillMd,
+    ides
+  });
+  for (const result of results) {
+    console.log(
+      kleur.green("  +"),
+      kleur.bold(IDE_LABELS[result.ide]),
+      kleur.dim(`(${result.path.replace(cwd, ".")})`)
+    );
+  }
+  console.log();
+  console.log(kleur.green("Done."), kleur.dim(`${skill.slug} ready to use.`));
+}
+async function runList(options) {
+  const skills = await listInstalledSkills(options.cwd);
+  if (skills.length === 0) {
+    console.log(kleur.dim("No skills installed in this directory."));
+    console.log(
+      kleur.dim("Looked in:"),
+      Object.values(IDE_PATHS).join(", ")
+    );
+    return;
+  }
+  const grouped = /* @__PURE__ */ new Map();
+  for (const skill of skills) {
+    const list = grouped.get(skill.ide) ?? [];
+    list.push(skill);
+    grouped.set(skill.ide, list);
+  }
+  for (const [ide, list] of grouped) {
+    console.log(kleur.bold(IDE_LABELS[ide]));
+    for (const skill of list) {
+      console.log("  ", kleur.cyan(skill.slug), kleur.dim(skill.path));
+    }
+  }
+}
+async function loadFromSlug(slug) {
+  console.log(kleur.dim("Fetching"), kleur.cyan(slug), kleur.dim("..."));
+  const response = await fetchSkillBySlug(slug);
+  return { slug: response.slug, skillMd: response.skill_md };
+}
+async function generateFromUrl(url, mode) {
+  console.log(
+    kleur.dim("Generating skill from"),
+    kleur.cyan(url),
+    kleur.dim(`(${mode})`)
+  );
+  const start = await startGenerationFromUrl(url, mode);
+  let lastStatus = null;
+  const result = await waitForGeneration(start.id, (status) => {
+    if (status !== lastStatus) {
+      lastStatus = status;
+      console.log(kleur.dim("  status:"), status);
+    }
+  });
+  if (result.status === "failed") {
+    throw new Error(result.error ?? "Generation failed");
+  }
+  if (!result.skill_md || !result.slug) {
+    throw new Error("Generation completed without a skill payload");
+  }
+  return { slug: result.slug, skillMd: result.skill_md };
+}
+async function resolveIdeSelection(raw, cwd) {
+  if (raw) {
+    if (!isValidIde(raw)) {
+      throw new Error(
+        `Invalid --ide value "${raw}". Use one of: ${VALID_IDES.join(", ")}`
+      );
+    }
+    return raw;
+  }
+  const detected = detectIdes(cwd);
+  if (detected.length === 1) return detected[0];
+  if (detected.length === 0) {
+    const response2 = await prompts({
+      type: "select",
+      name: "ide",
+      message: "Which IDE?",
+      choices: [
+        { title: IDE_LABELS.claude, value: "claude" },
+        { title: IDE_LABELS.cursor, value: "cursor" },
+        { title: IDE_LABELS.windsurf, value: "windsurf" },
+        { title: "All of them", value: "all" }
+      ],
+      initial: 0
+    });
+    if (!response2.ide) throw new Error("Aborted");
+    return response2.ide;
+  }
+  const response = await prompts({
+    type: "select",
+    name: "ide",
+    message: "Multiple IDE configs detected. Which one?",
+    choices: [
+      ...detected.map((ide) => ({ title: IDE_LABELS[ide], value: ide })),
+      { title: "All detected", value: "all" }
+    ],
+    initial: 0
+  });
+  if (!response.ide) throw new Error("Aborted");
+  return response.ide;
+}
+function parseMode(raw) {
+  if (!raw) return "design";
+  if (!isValidMode(raw)) {
+    throw new Error(
+      `Invalid --mode value "${raw}". Use one of: ${VALID_MODES.join(", ")}`
+    );
+  }
+  return raw;
+}
+function isValidIde(value) {
+  return VALID_IDES.includes(value);
+}
+function isValidMode(value) {
+  return VALID_MODES.includes(value);
+}
+function handleError(error) {
+  if (error instanceof ApiError) {
+    console.error(kleur.red("Error:"), error.message);
+    if (error.status === 404) {
+      console.error(
+        kleur.dim("Hint: pass a full URL to generate a new skill from scratch.")
+      );
+    }
+  } else if (error instanceof Error) {
+    console.error(kleur.red("Error:"), error.message);
+  } else {
+    console.error(kleur.red("Error:"), String(error));
+  }
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@getskillmd/cli",
+  "version": "0.1.0",
+  "description": "CLI to install skill.md files into Claude Code, Cursor, and Windsurf",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "tekcify",
+    "url": "https://tekcify.com"
+  },
+  "homepage": "https://getskillmd.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tekcify/getskillmd.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/tekcify/getskillmd/issues"
+  },
+  "keywords": [
+    "ai",
+    "claude",
+    "cursor",
+    "windsurf",
+    "skills",
+    "skill.md",
+    "agent"
+  ],
+  "bin": {
+    "getskillmd": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "kleur": "^4.1.5",
+    "nanoid": "^5.1.11",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/prompts": "^2.4.9",
+    "tsup": "^8.3.5",
+    "typescript": "^5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit"
+  }
+}