@its-thepoe/skills 1.0.0

package/bin/cli.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "../lib/cli-main.mjs";
+
+process.exitCode = run(process.argv.slice(2));

package/lib/cli-main.mjs

@@ -0,0 +1,249 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import {
+  AGENT_TARGETS,
+  agentBaseDir,
+  linkSkillToAgents,
+  readSkillVersion,
+  removeSkillFromAgents,
+  resolveSkillRoot,
+} from "./link-engine.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_DIR = path.resolve(__dirname, "..");
+const MANIFEST_PATH = path.join(PKG_DIR, "skills.manifest.json");
+
+function logLine(msg) {
+  process.stdout.write(msg + "\n");
+}
+
+function loadManifest() {
+  const raw = fs.readFileSync(MANIFEST_PATH, "utf8");
+  return JSON.parse(raw);
+}
+
+function parseGlobalFlags(argv) {
+  const flags = {
+    dryRun: false,
+    only: [],
+    strategy: "symlink",
+    online: false,
+  };
+  const rest = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--dry-run") flags.dryRun = true;
+    else if (a === "--online") flags.online = true;
+    else if (a === "--strategy" && argv[i + 1]) {
+      flags.strategy = String(argv[++i]);
+      if (flags.strategy !== "symlink" && flags.strategy !== "copy") {
+        throw new Error('--strategy must be "symlink" or "copy"');
+      }
+    }     else if (a.startsWith("--only=")) {
+      flags.only.push(
+        ...a
+          .slice("--only=".length)
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      );
+    } else if (a === "--only" && argv[i + 1]) {
+      flags.only.push(
+        ...String(argv[++i])
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      );
+    } else rest.push(a);
+  }
+  return { flags, rest };
+}
+
+function printHelp() {
+  logLine(`@its-thepoe/skills — install Agent Skills into local agent directories
+
+Usage:
+  npx @its-thepoe/skills@latest <command> [options]
+
+Commands:
+  install --all                 Link or copy every skill from the manifest
+  install <skill-name> [...]     Install specific skills (folder names)
+  sync --all                    Idempotent re-install (same as install --all)
+  sync <skill-name> [...]      Re-install specific skills
+  check                         Verify installs under agent dirs
+  remove --all                 Remove managed installs for all manifest skills
+  remove <skill-name> [...]     Remove specific skills
+
+Options:
+  --dry-run                     Print actions without writing
+  --only=<a>[,<b>...]          Limit targets: cursor, claude, opencode, windsurf, all
+  --strategy symlink|copy       Default symlink; use copy if symlinks fail (e.g. Windows)
+  --online                      With check: compare to npm registry (requires network)
+
+Agents (default: all):
+${Object.keys(AGENT_TARGETS)
+  .map((k) => `  - ${k}`)
+  .join("\n")}
+`);
+}
+
+function getManifestEntries(manifest, names) {
+  const byName = new Map(manifest.skills.map((s) => [s.name, s]));
+  const out = [];
+  for (const n of names) {
+    const row = byName.get(n);
+    if (!row) throw new Error(`Unknown skill "${n}" (not in skills.manifest.json)`);
+    out.push(row);
+  }
+  return out;
+}
+
+function npmViewVersion(pkg) {
+  const r = spawnSync("npm", ["view", pkg, "version"], {
+    encoding: "utf8",
+    shell: process.platform === "win32",
+  });
+  if (r.status !== 0) return null;
+  return String(r.stdout || "").trim() || null;
+}
+
+/**
+ * @param {{ online: boolean }} opts
+ */
+function runCheck(opts) {
+  const manifest = loadManifest();
+  const { online } = opts;
+  let exit = 0;
+  for (const row of manifest.skills) {
+    let root = null;
+    try {
+      root = resolveSkillRoot(row.package, import.meta.url);
+    } catch {
+      logLine(`BUNDLE ${row.package}: not resolvable via node_modules (install orchestrator deps)`);
+      exit = 1;
+      continue;
+    }
+    const bundledVer = readSkillVersion(root);
+    let latest = null;
+    if (online) {
+      latest = npmViewVersion(row.package);
+    }
+    logLine(`\n${row.name} (${row.package}) bundled@${bundledVer}${latest ? ` registry_latest@${latest}` : ""}`);
+
+    for (const agent of Object.keys(AGENT_TARGETS)) {
+      const dest = path.join(agentBaseDir(agent), row.name);
+      if (!fs.existsSync(dest)) {
+        logLine(`  [${agent}] MISSING ${dest}`);
+        exit = 1;
+        continue;
+      }
+      const st = fs.lstatSync(dest);
+      if (st.isSymbolicLink()) {
+        const t = fs.readlinkSync(dest);
+        logLine(`  [${agent}] OK symlink -> ${t}`);
+      } else if (st.isDirectory()) {
+        const skillMd = path.join(dest, "SKILL.md");
+        if (!fs.existsSync(skillMd)) {
+          logLine(`  [${agent}] BAD copy dir (no SKILL.md) ${dest}`);
+          exit = 1;
+        } else {
+          logLine(`  [${agent}] OK directory copy ${dest}`);
+        }
+      } else {
+        logLine(`  [${agent}] UNEXPECTED ${dest}`);
+        exit = 1;
+      }
+    }
+  }
+  return exit;
+}
+
+/**
+ * @param {string[]} argv
+ */
+export function run(argv) {
+  if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
+    printHelp();
+    return 0;
+  }
+
+  const { flags, rest } = parseGlobalFlags(argv);
+  const cmd = rest[0];
+  const args = rest.slice(1);
+
+  if (!cmd || cmd === "help") {
+    printHelp();
+    return 0;
+  }
+
+  const log = logLine;
+  const only = flags.only.length ? flags.only.join(",").split(",").map((s) => s.trim()).filter(Boolean) : ["all"];
+
+  try {
+    if (cmd === "check") {
+      return runCheck({ online: flags.online });
+    }
+
+    if (cmd === "install" || cmd === "sync") {
+      const all = args.includes("--all");
+      const names = args.filter((a) => a !== "--all");
+      const manifest = loadManifest();
+      let entries = manifest.skills;
+      if (!all) {
+        if (names.length === 0) {
+          logLine("Error: specify skill names or --all");
+          printHelp();
+          return 1;
+        }
+        entries = getManifestEntries(manifest, names);
+      }
+
+      for (const row of entries) {
+        const root = resolveSkillRoot(row.package, import.meta.url);
+        const version = readSkillVersion(root);
+        logLine(`\n${cmd} ${row.name} @ ${root}`);
+        linkSkillToAgents({
+          skillRoot: root,
+          skillName: row.name,
+          skillPackage: row.package,
+          version,
+          only,
+          strategy: flags.strategy,
+          dryRun: flags.dryRun,
+          log,
+        });
+      }
+      logLine(`\nDone. Reload your agents (Cursor, Claude Code, OpenCode, Windsurf).`);
+      return 0;
+    }
+
+    if (cmd === "remove") {
+      const all = args.includes("--all");
+      const names = args.filter((a) => a !== "--all");
+      const manifest = loadManifest();
+      let targets = manifest.skills.map((s) => s.name);
+      if (!all) {
+        if (names.length === 0) {
+          logLine("Error: specify skill names or --all");
+          return 1;
+        }
+        targets = names;
+        for (const n of targets) getManifestEntries(manifest, [n]);
+      }
+      for (const name of targets) {
+        logLine(`\nremove ${name}`);
+        removeSkillFromAgents({ skillName: name, only, dryRun: flags.dryRun, log });
+      }
+      return 0;
+    }
+
+    logLine(`Unknown command: ${cmd}`);
+    printHelp();
+    return 1;
+  } catch (e) {
+    logLine(`Error: ${e instanceof Error ? e.message : e}`);
+    return 1;
+  }
+}

package/lib/link-engine.mjs

@@ -0,0 +1,218 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+const INSTALL_MARKER = ".its-thepoe-skills-install.json";
+
+/** @type {Record<string, { env?: string, segments: string[] }>} */
+export const AGENT_TARGETS = {
+  cursor: { segments: [".cursor", "skills"] },
+  claude: { segments: [".claude", "skills"] },
+  opencode: { segments: [".config", "opencode", "skills"] },
+  windsurf: { segments: [".codeium", "windsurf", "skills"] },
+};
+
+/**
+ * @param {string} key
+ * @returns {string}
+ */
+export function agentBaseDir(key) {
+  const home = os.homedir();
+  const spec = AGENT_TARGETS[key];
+  if (!spec) throw new Error(`Unknown agent target: ${key}`);
+  return path.join(home, ...spec.segments);
+}
+
+/**
+ * @param {string[]} onlyKeys
+ */
+export function normalizeOnly(onlyKeys) {
+  const allowed = new Set(["cursor", "claude", "opencode", "windsurf"]);
+  if (onlyKeys.length === 0 || onlyKeys.includes("all")) {
+    return [...allowed];
+  }
+  for (const k of onlyKeys) {
+    if (!allowed.has(k)) throw new Error(`Invalid --only value: ${k}`);
+  }
+  return onlyKeys;
+}
+
+function exists(p) {
+  try {
+    fs.accessSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} skillPackage
+ * @param {string} fromFile - use import.meta.url of caller for resolution context
+ * @returns {string} absolute path to package root
+ */
+export function resolveSkillRoot(skillPackage, fromFile) {
+  const require = createRequire(fromFile);
+  // Do not use `${pkg}/package.json` — many packages omit it from "exports".
+  // Resolve the package main (e.g. SKILL.md); its directory is the package root.
+  const entry = require.resolve(skillPackage);
+  return path.dirname(entry);
+}
+
+function readJson(p) {
+  return JSON.parse(fs.readFileSync(p, "utf8"));
+}
+
+function writeMarker(destDir, meta) {
+  const p = path.join(destDir, INSTALL_MARKER);
+  fs.writeFileSync(p, JSON.stringify(meta, null, 2) + "\n", "utf8");
+}
+
+/**
+ * @param {{ dest: string, source: string, dryRun: boolean, strategy: 'symlink'|'copy', skillName: string, skillPackage: string, version: string, log: (m:string)=>void }} opts
+ */
+function linkOneDest(opts) {
+  const { dest, source, dryRun, strategy, skillName, skillPackage, version, log } = opts;
+  const absSource = path.resolve(source);
+
+  if (strategy === "symlink") {
+    if (exists(dest)) {
+      const st = fs.lstatSync(dest);
+      if (st.isSymbolicLink()) {
+        let target = fs.readlinkSync(dest);
+        if (!path.isAbsolute(target)) {
+          target = path.resolve(path.dirname(dest), target);
+        }
+        if (path.resolve(target) === absSource) {
+          log(`SKIP   ${dest} -> ${absSource}`);
+          return;
+        }
+        log(`${dryRun ? "DRY-RUN " : ""}REPLACE ${dest} (symlink -> new target)`);
+        if (!dryRun) fs.unlinkSync(dest);
+      } else if (st.isDirectory()) {
+        // copy-mode directory or manual folder — don't destroy
+        const marker = path.join(dest, INSTALL_MARKER);
+        if (exists(marker)) {
+          log(`${dryRun ? "DRY-RUN " : ""}REPLACE ${dest} (prior copy install)`);
+          if (!dryRun) fs.rmSync(dest, { recursive: true, force: true });
+        } else {
+          throw new Error(
+            `Refusing to replace ${dest}: exists and is not a symlink managed by this tool`
+          );
+        }
+      } else {
+        throw new Error(`Refusing to replace ${dest}: not a directory or symlink`);
+      }
+    } else {
+      log(`${dryRun ? "DRY-RUN " : ""}CREATE  ${dest} -> ${absSource}`);
+    }
+
+    if (dryRun) return;
+
+    try {
+      fs.symlinkSync(absSource, dest, "dir");
+    } catch (err) {
+      if (err && err.code === "EPERM" && process.platform === "win32") {
+        throw new Error(
+          `Symlink failed (EPERM). Re-run with --strategy copy, or enable Developer Mode / run as admin for symlinks.`
+        );
+      }
+      throw err;
+    }
+    return;
+  }
+
+  // copy
+  if (exists(dest)) {
+    log(`${dryRun ? "DRY-RUN " : ""}REPLACE ${dest} (copy)`);
+    if (!dryRun) fs.rmSync(dest, { recursive: true, force: true });
+  } else {
+    log(`${dryRun ? "DRY-RUN " : ""}CREATE  ${dest} (copy)`);
+  }
+  if (dryRun) return;
+  fs.cpSync(absSource, dest, { recursive: true });
+  writeMarker(dest, {
+    managedBy: "@its-thepoe/skills",
+    skillName,
+    package: skillPackage,
+    version,
+    strategy: "copy",
+    installedAt: new Date().toISOString(),
+  });
+}
+
+/**
+ * @param {{ skillRoot: string, skillName: string, skillPackage: string, version: string, only: string[], strategy: 'symlink'|'copy', dryRun: boolean, log: (m:string)=>void }} p
+ */
+export function linkSkillToAgents(p) {
+  const { skillRoot, skillName, skillPackage, version, only, strategy, dryRun, log } = p;
+  if (!exists(path.join(skillRoot, "SKILL.md"))) {
+    throw new Error(`Missing SKILL.md under ${skillRoot}`);
+  }
+
+  for (const key of normalizeOnly(only)) {
+    const base = agentBaseDir(key);
+    const dest = path.join(base, skillName);
+    if (!dryRun) fs.mkdirSync(base, { recursive: true });
+    linkOneDest({
+      dest,
+      source: skillRoot,
+      dryRun,
+      strategy,
+      skillName,
+      skillPackage,
+      version,
+      log,
+    });
+  }
+}
+
+/**
+ * @param {{ skillName: string, only: string[], dryRun: boolean, log: (m:string)=>void }} p
+ */
+export function removeSkillFromAgents(p) {
+  const { skillName, only, dryRun, log } = p;
+  for (const key of normalizeOnly(only)) {
+    const dest = path.join(agentBaseDir(key), skillName);
+    if (!exists(dest)) {
+      log(`SKIP   (missing) ${dest}`);
+      continue;
+    }
+    const st = fs.lstatSync(dest);
+    if (st.isSymbolicLink()) {
+      log(`REMOVE ${dest}`);
+      if (!dryRun) fs.unlinkSync(dest);
+      continue;
+    }
+    if (st.isDirectory()) {
+      const marker = path.join(dest, INSTALL_MARKER);
+      if (exists(marker)) {
+        try {
+          const meta = readJson(marker);
+          if (meta.managedBy === "@its-thepoe/skills") {
+            log(`REMOVE ${dest} (copy install)`);
+            if (!dryRun) fs.rmSync(dest, { recursive: true, force: true });
+            continue;
+          }
+        } catch {
+          /* fall through */
+        }
+      }
+      log(`SKIP   ${dest} (directory not managed; no marker)`);
+    }
+  }
+}
+
+/**
+ * @param {string} skillRoot
+ */
+export function readSkillVersion(skillRoot) {
+  const pj = path.join(skillRoot, "package.json");
+  if (!exists(pj)) return "0.0.0";
+  try {
+    return readJson(String(pj)).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@its-thepoe/skills",
+  "version": "1.0.0",
+  "description": "Orchestrator CLI to install, check, sync, and remove @its-thepoe Agent Skills (Cursor, Claude Code, OpenCode, Windsurf).",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "agent-skills",
+    "cursor",
+    "claude-code",
+    "skills",
+    "its-thepoe"
+  ],
+  "bin": {
+    "skills": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "skills.manifest.json",
+    "package.json"
+  ],
+  "dependencies": {
+    "@its-thepoe/alt-text": "1.0.0",
+    "@its-thepoe/design-and-refine": "1.0.0",
+    "@its-thepoe/design-engineering": "1.0.0",
+    "@its-thepoe/design-motion-principles": "1.0.0",
+    "@its-thepoe/family-taste": "1.0.0",
+    "@its-thepoe/write-a-skill": "1.0.0"
+  }
+}

package/skills.manifest.json

@@ -0,0 +1,10 @@
+{
+  "skills": [
+    { "name": "alt-text", "package": "@its-thepoe/alt-text" },
+    { "name": "design-and-refine", "package": "@its-thepoe/design-and-refine" },
+    { "name": "design-engineering", "package": "@its-thepoe/design-engineering" },
+    { "name": "design-motion-principles", "package": "@its-thepoe/design-motion-principles" },
+    { "name": "family-taste", "package": "@its-thepoe/family-taste" },
+    { "name": "write-a-skill", "package": "@its-thepoe/write-a-skill" }
+  ]
+}