skillship 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skillship contributors
+
+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,156 @@
+# skillship
+
+Make any [Agent Skill](https://agentskills.io/specification) (a `SKILL.md`
+directory) portable across **Cursor**, **Claude Code**, **Claude Web**, and
+**Claude Cowork**.
+
+`skillship` is a thin orchestration layer. It does **not** reimplement the
+multi-agent install matrix (that's [`npx skills`](https://skills.sh)) or host a
+registry. It adds the three things the ecosystem is missing:
+
+1. Strict, per-surface **validation profiles** (notably Claude's 200-char upload
+   cap, which the official validator doesn't enforce).
+2. **`.skill` packaging** for Claude Web / Cowork uploads.
+3. **`init` scaffolding** with reusable release-please CI and commit
+   conventions.
+
+## Install / usage
+
+```bash
+npx skillship <command>
+```
+
+Requires Node.js >= 18.
+
+## Commands
+
+```
+skillship validate <dir> [--profile <p>] [--json]
+skillship package  <dir> [--out <dir>]
+skillship install  <dir> [--agent <a,b>] [--global] [--copy]
+skillship init     [name] [--ci] [--snippets]
+skillship doctor
+```
+
+`<dir>` defaults to `.` and must contain a `SKILL.md`. Validation exits non-zero
+on failure.
+
+### validate
+
+Parses the `SKILL.md` YAML frontmatter (`name`, `description`, optional
+`license`, `metadata`, `allowed-tools`) and body, then applies checks per
+profile:
+
+| Check | spec | cursor | claude-web | claude-cowork |
+| --- | --- | --- | --- | --- |
+| `name` present, lowercase/numbers/hyphens | yes | yes | yes | yes |
+| `name` matches parent folder | yes | yes | yes | yes |
+| `description` non-empty, no `<`/`>` | yes | yes | yes | yes |
+| `description` length | <= 1024 | <= 1024 | **<= 200** | **<= 200** |
+| Body recommended <= 500 lines | warn | warn | warn | warn |
+
+`--profile` is one of `spec | cursor | claude-web | claude-cowork | all`
+(default `all`, the strictest combination — description must be <= 200 chars).
+`--json` emits machine-readable output for CI.
+
+The frontmatter parser handles YAML block scalars (`>`, `>-`, `>+`, `|`, `|-`,
+`|+`) and nested maps (e.g. `metadata:` with indented children) without
+mis-joining keys. If `agentskills` (the Python spec validator) is on `PATH`, its
+findings are merged in; it is never a hard dependency.
+
+### package
+
+```bash
+skillship package ./my-skill            # -> dist/my-skill.skill
+skillship package ./my-skill --out out  # -> out/my-skill.skill
+```
+
+Runs `validate --profile all` first (aborts on failure), then produces a
+`<name>.skill` zip whose **archive root is the skill folder** (entries are
+`<name>/SKILL.md`, ...) — Claude rejects archives with files at the zip root.
+Excludes `__pycache__/`, `.DS_Store`, `node_modules/`, `dist/`, `.git/`.
+
+### install
+
+```bash
+skillship install ./my-skill -a cursor,claude-code
+```
+
+For filesystem agents, shells out to `npx skills add <dir> [--global] [--copy]
+-a <agents>`. Default agents are `cursor,claude-code`. For upload-only surfaces
+(`claude-web`, `claude-cowork`) it prints upload instructions instead.
+
+### init
+
+```bash
+skillship init demo --ci --snippets
+```
+
+Scaffolds a skill repo (see layout below) that auto-releases via
+[release-please](https://github.com/googleapis/release-please-action) +
+[Conventional Commits](https://www.conventionalcommits.org/). `--ci` adds the
+GitHub Actions workflows; `--snippets` adds `cursor-rule.mdc` and
+`claude-md.md`.
+
+Scaffolded layout:
+
+```
+my-skill/
+  my-skill/SKILL.md
+  snippets/                 # if --snippets
+    cursor-rule.mdc
+    claude-md.md
+  release-please-config.json
+  .release-please-manifest.json
+  version.txt
+  .github/workflows/{validate,release}.yml
+  AGENTS.md
+  README.md
+```
+
+> After pushing the scaffolded repo, enable **Settings -> Actions -> Workflow
+> permissions**: "Read and write" and "Allow GitHub Actions to create and
+> approve pull requests" so release-please can open release PRs and upload the
+> `.skill` asset.
+
+The `SKILL.md` version line uses an inline marker so release-please updates it
+in
+place and the validator ignores it:
+
+```yaml
+metadata:
+  version: "1.0.0" # x-release-please-version
+```
+
+### doctor
+
+Checks the local environment: Node >= 18 and `npx` (required), plus `gh` and
+`agentskills` (optional).
+
+## Development
+
+```bash
+npm install
+npm run build   # tsup -> dist/cli.js
+npm run lint    # tsc --noEmit
+npm test        # vitest
+```
+
+Project layout:
+
+```
+src/
+  cli.ts                  # arg parsing, command dispatch (commander)
+  commands/{validate,package,install,init,doctor}.ts
+  lib/frontmatter.ts      # YAML frontmatter parser (block scalars + maps)
+  lib/profiles.ts         # profile definitions and checks
+  lib/zip.ts              # .skill packaging (archiver)
+  lib/exec.ts             # spawn wrappers for npx skills / gh / agentskills
+  lib/load.ts             # SKILL.md loader
+templates/                # CI + snippet + AGENTS/README/SKILL templates for init
+test/                     # vitest specs + fixtures
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,722 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/lib/load.ts
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+
+// src/lib/frontmatter.ts
+var FENCE = /^---\s*$/;
+function splitFrontmatter(content) {
+  const normalized = content.replace(/\r\n/g, "\n");
+  const lines = normalized.split("\n");
+  if (lines.length === 0 || !FENCE.test(lines[0])) {
+    return { raw: "", body: normalized };
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (FENCE.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  if (end === -1) {
+    return { raw: "", body: normalized };
+  }
+  const raw = lines.slice(1, end).join("\n");
+  const body = lines.slice(end + 1).join("\n");
+  return { raw, body };
+}
+function tokenize(raw) {
+  return raw.split("\n").map((raw2) => {
+    const match = raw2.match(/^(\s*)(.*)$/);
+    const indent = match ? match[1].length : 0;
+    const text = match ? match[2] : raw2;
+    return { indent, text, raw: raw2 };
+  });
+}
+function stripComment(value) {
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i];
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    else if (ch === '"' && !inSingle) inDouble = !inDouble;
+    else if (ch === "#" && !inSingle && !inDouble) {
+      if (i === 0 || /\s/.test(value[i - 1])) {
+        return value.slice(0, i).trimEnd();
+      }
+    }
+  }
+  return value;
+}
+function unquote(value) {
+  const v = value.trim();
+  if (v.length >= 2) {
+    if (v.startsWith('"') && v.endsWith('"')) {
+      return v.slice(1, -1).replace(/\\"/g, '"').replace(/\\n/g, "\n");
+    }
+    if (v.startsWith("'") && v.endsWith("'")) {
+      return v.slice(1, -1).replace(/''/g, "'");
+    }
+  }
+  return v;
+}
+var BLOCK_SCALAR = /^([|>])([+-]?)\s*$/;
+function collectBlockScalar(lines, start, parentIndent, style, chomp) {
+  const collected = [];
+  let i = start;
+  let blockIndent = -1;
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    const isBlank = line.text === "";
+    if (isBlank) {
+      collected.push("");
+      continue;
+    }
+    if (line.indent <= parentIndent) break;
+    if (blockIndent === -1) blockIndent = line.indent;
+    collected.push(line.raw.slice(blockIndent));
+  }
+  let value;
+  if (style === ">") {
+    const parts = [];
+    let buffer = [];
+    const flush = () => {
+      if (buffer.length) {
+        parts.push(buffer.join(" "));
+        buffer = [];
+      }
+    };
+    for (const l of collected) {
+      if (l === "") {
+        flush();
+        parts.push("");
+      } else {
+        buffer.push(l);
+      }
+    }
+    flush();
+    value = parts.join("\n").replace(/\n{2,}/g, "\n");
+  } else {
+    value = collected.join("\n");
+  }
+  if (chomp === "-") {
+    value = value.replace(/\n+$/, "");
+  } else if (chomp === "+") {
+  } else {
+    value = value.replace(/\n+$/, "\n");
+    value = value.replace(/\n$/, "");
+  }
+  value = value.trim();
+  return { value, next: i };
+}
+function parseFrontmatter(raw) {
+  const fm = {};
+  if (!raw.trim()) return fm;
+  const lines = tokenize(raw);
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.text === "" || line.text.startsWith("#")) {
+      i++;
+      continue;
+    }
+    if (line.indent !== 0) {
+      i++;
+      continue;
+    }
+    const colon = line.text.indexOf(":");
+    if (colon === -1) {
+      i++;
+      continue;
+    }
+    const key = line.text.slice(0, colon).trim();
+    let rest = line.text.slice(colon + 1).trim();
+    const blockMatch = rest.match(BLOCK_SCALAR);
+    if (blockMatch) {
+      const style = blockMatch[1];
+      const chomp = blockMatch[2] || "";
+      const { value, next } = collectBlockScalar(
+        lines,
+        i + 1,
+        line.indent,
+        style,
+        chomp
+      );
+      fm[key] = value;
+      i = next;
+      continue;
+    }
+    if (rest === "") {
+      const childIndent = line.indent;
+      const children = {};
+      let j = i + 1;
+      let sawChild = false;
+      for (; j < lines.length; j++) {
+        const child = lines[j];
+        if (child.text === "" || child.text.startsWith("#")) continue;
+        if (child.indent <= childIndent) break;
+        const cColon = child.text.indexOf(":");
+        if (cColon === -1) continue;
+        const cKey = child.text.slice(0, cColon).trim();
+        const cVal = unquote(stripComment(child.text.slice(cColon + 1).trim()));
+        children[cKey] = cVal;
+        sawChild = true;
+      }
+      if (sawChild) {
+        fm[key] = children;
+      } else {
+        fm[key] = "";
+      }
+      i = j;
+      continue;
+    }
+    if (rest.startsWith("[") && rest.endsWith("]")) {
+      const inner = rest.slice(1, -1).trim();
+      fm[key] = inner ? inner.split(",").map((s) => unquote(s.trim())) : [];
+      i++;
+      continue;
+    }
+    rest = unquote(stripComment(rest));
+    fm[key] = rest;
+    i++;
+  }
+  return fm;
+}
+function parseSkill(content) {
+  const { raw, body } = splitFrontmatter(content);
+  return {
+    frontmatter: parseFrontmatter(raw),
+    body
+  };
+}
+
+// src/lib/load.ts
+async function loadSkill(dir) {
+  const abs = resolve(dir);
+  const skillMdPath = join(abs, "SKILL.md");
+  if (!existsSync(skillMdPath)) {
+    throw new Error(`No SKILL.md found in ${abs}`);
+  }
+  const content = await readFile(skillMdPath, "utf8");
+  return { dir: abs, skillMdPath, parsed: parseSkill(content) };
+}
+
+// src/lib/profiles.ts
+import { basename } from "path";
+var PROFILE_NAMES = [
+  "spec",
+  "cursor",
+  "claude-web",
+  "claude-cowork",
+  "all"
+];
+var DESCRIPTION_MAX = {
+  spec: 1024,
+  cursor: 1024,
+  "claude-web": 200,
+  "claude-cowork": 200
+};
+var BODY_RECOMMENDED_MAX_LINES = 500;
+var NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function descriptionMax(profile) {
+  if (profile === "all") {
+    return Math.min(...Object.values(DESCRIPTION_MAX));
+  }
+  return DESCRIPTION_MAX[profile];
+}
+function checkName(fm, folderName, findings) {
+  const name = typeof fm.name === "string" ? fm.name : void 0;
+  if (!name) {
+    findings.push({
+      severity: "error",
+      check: "name-present",
+      message: "`name` is missing from frontmatter."
+    });
+    return;
+  }
+  if (!NAME_RE.test(name)) {
+    findings.push({
+      severity: "error",
+      check: "name-format",
+      message: `\`name\` "${name}" must be lowercase letters, numbers, and single hyphens (no leading/trailing/double hyphens).`
+    });
+  }
+  if (name !== folderName) {
+    findings.push({
+      severity: "error",
+      check: "name-matches-folder",
+      message: `\`name\` "${name}" must match the parent folder "${folderName}".`
+    });
+  }
+}
+function checkDescription(fm, max, findings) {
+  const desc = typeof fm.description === "string" ? fm.description : void 0;
+  if (!desc || desc.trim() === "") {
+    findings.push({
+      severity: "error",
+      check: "description-present",
+      message: "`description` is missing or empty."
+    });
+    return;
+  }
+  if (/[<>]/.test(desc)) {
+    findings.push({
+      severity: "error",
+      check: "description-xml",
+      message: "`description` must not contain `<` or `>` characters."
+    });
+  }
+  if (desc.length > max) {
+    findings.push({
+      severity: "error",
+      check: "description-length",
+      message: `\`description\` is ${desc.length} chars; limit is ${max}.`
+    });
+  }
+}
+function checkBody(body, findings) {
+  const lineCount = body.split("\n").length;
+  if (lineCount > BODY_RECOMMENDED_MAX_LINES) {
+    findings.push({
+      severity: "warning",
+      check: "body-length",
+      message: `Body is ${lineCount} lines; recommended <= ${BODY_RECOMMENDED_MAX_LINES}.`
+    });
+  }
+}
+function validateProfile(skill, skillDir, profile) {
+  const findings = [];
+  const folderName = basename(skillDir);
+  checkName(skill.frontmatter, folderName, findings);
+  checkDescription(skill.frontmatter, descriptionMax(profile), findings);
+  checkBody(skill.body, findings);
+  const ok = !findings.some((f) => f.severity === "error");
+  return { profile, ok, findings };
+}
+
+// src/lib/exec.ts
+import { spawn, spawnSync } from "child_process";
+function buildSkillsAddArgv(opts) {
+  const argv = ["skills", "add", opts.dir];
+  if (opts.global) argv.push("--global");
+  if (opts.copy) argv.push("--copy");
+  if (opts.agents.length > 0) argv.push("-a", opts.agents.join(","));
+  return argv;
+}
+function run(command, args, opts = {}) {
+  return new Promise((resolve3, reject) => {
+    const child = spawn(command, args, {
+      cwd: opts.cwd,
+      stdio: "inherit",
+      shell: false
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve3(code ?? 1));
+  });
+}
+function isAvailable(command) {
+  const probe = process.platform === "win32" ? "where" : "which";
+  const res = spawnSync(probe, [command], { stdio: "ignore" });
+  return res.status === 0;
+}
+function runCapture(command, args, opts = {}) {
+  const res = spawnSync(command, args, {
+    cwd: opts.cwd,
+    encoding: "utf8"
+  });
+  return {
+    code: res.status ?? 1,
+    stdout: res.stdout ?? "",
+    stderr: res.stderr ?? ""
+  };
+}
+
+// src/commands/validate.ts
+function profilesToRun(profile) {
+  if (profile === "all") return ["all"];
+  return [profile];
+}
+function mergeAgentskills(dir, results) {
+  if (!isAvailable("agentskills")) return;
+  const res = runCapture("agentskills", ["validate", dir]);
+  if (res.code !== 0) {
+    const message = (res.stderr || res.stdout || "agentskills reported errors").trim();
+    for (const r of results) {
+      r.findings.push({
+        severity: "error",
+        check: "agentskills",
+        message
+      });
+      r.ok = false;
+    }
+  }
+}
+async function validateCommand(dir, options) {
+  const profileArg = options.profile ?? "all";
+  if (!PROFILE_NAMES.includes(profileArg)) {
+    process.stderr.write(
+      `Unknown profile "${profileArg}". Valid: ${PROFILE_NAMES.join(", ")}
+`
+    );
+    return 2;
+  }
+  let loaded;
+  try {
+    loaded = await loadSkill(dir);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      process.stdout.write(
+        JSON.stringify({ ok: false, error: msg }, null, 2) + "\n"
+      );
+    } else {
+      process.stderr.write(`Error: ${msg}
+`);
+    }
+    return 1;
+  }
+  const results = profilesToRun(profileArg).map(
+    (p) => validateProfile(loaded.parsed, loaded.dir, p)
+  );
+  mergeAgentskills(loaded.dir, results);
+  const ok = results.every((r) => r.ok);
+  if (options.json) {
+    process.stdout.write(JSON.stringify({ ok, results }, null, 2) + "\n");
+  } else {
+    printHuman(results, ok);
+  }
+  return ok ? 0 : 1;
+}
+function printHuman(results, ok) {
+  for (const result of results) {
+    const errors = result.findings.filter((f) => f.severity === "error");
+    const warnings = result.findings.filter((f) => f.severity === "warning");
+    const status = result.ok ? "PASS" : "FAIL";
+    process.stdout.write(`[${status}] profile: ${result.profile}
+`);
+    for (const f of [...errors, ...warnings]) printFinding(f);
+  }
+  process.stdout.write(ok ? "\nAll checks passed.\n" : "\nValidation failed.\n");
+}
+function printFinding(f) {
+  const tag = f.severity === "error" ? "  \u2717" : "  \u26A0";
+  process.stdout.write(`${tag} ${f.check}: ${f.message}
+`);
+}
+
+// src/commands/package.ts
+import { join as join3 } from "path";
+
+// src/lib/zip.ts
+import { createWriteStream } from "fs";
+import { mkdir, readdir } from "fs/promises";
+import { join as join2, relative } from "path";
+import archiver from "archiver";
+var EXCLUDED_DIRS = /* @__PURE__ */ new Set([
+  "__pycache__",
+  "node_modules",
+  "dist",
+  ".git"
+]);
+var EXCLUDED_FILES = /* @__PURE__ */ new Set([".DS_Store"]);
+async function collectFiles(root) {
+  const out = [];
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = join2(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (EXCLUDED_DIRS.has(entry.name)) continue;
+        await walk(full);
+      } else if (entry.isFile()) {
+        if (EXCLUDED_FILES.has(entry.name)) continue;
+        out.push(full);
+      }
+    }
+  }
+  await walk(root);
+  return out.sort();
+}
+async function packSkill(opts) {
+  const { skillDir, name, outDir } = opts;
+  await mkdir(outDir, { recursive: true });
+  const outPath = join2(outDir, `${name}.skill`);
+  const files = await collectFiles(skillDir);
+  await new Promise((resolve3, reject) => {
+    const output = createWriteStream(outPath);
+    const archive = archiver("zip", { zlib: { level: 9 } });
+    output.on("close", () => resolve3());
+    output.on("error", reject);
+    archive.on("error", reject);
+    archive.pipe(output);
+    for (const file of files) {
+      const rel = relative(skillDir, file);
+      archive.file(file, { name: `${name}/${rel}` });
+    }
+    void archive.finalize();
+  });
+  return outPath;
+}
+
+// src/commands/package.ts
+async function packageCommand(dir, options) {
+  let loaded;
+  try {
+    loaded = await loadSkill(dir);
+  } catch (err) {
+    process.stderr.write(
+      `Error: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return 1;
+  }
+  const result = validateProfile(loaded.parsed, loaded.dir, "all");
+  if (!result.ok) {
+    process.stderr.write("Cannot package: validation failed (--profile all).\n");
+    for (const f of result.findings.filter((x) => x.severity === "error")) {
+      process.stderr.write(`  \u2717 ${f.check}: ${f.message}
+`);
+    }
+    process.stderr.write("\nRun `skillship validate` for details.\n");
+    return 1;
+  }
+  const name = String(loaded.parsed.frontmatter.name);
+  const outDir = options.out ?? join3(process.cwd(), "dist");
+  const outPath = await packSkill({ skillDir: loaded.dir, name, outDir });
+  process.stdout.write(`Packaged ${name} -> ${outPath}
+`);
+  return 0;
+}
+
+// src/commands/install.ts
+var DEFAULT_AGENTS = ["cursor", "claude-code"];
+var UPLOAD_ONLY = /* @__PURE__ */ new Set(["claude-web", "claude-cowork"]);
+async function installCommand(dir, options) {
+  let loaded;
+  try {
+    loaded = await loadSkill(dir);
+  } catch (err) {
+    process.stderr.write(
+      `Error: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return 1;
+  }
+  const requested = options.agent ? options.agent.split(",").map((a) => a.trim()).filter(Boolean) : DEFAULT_AGENTS;
+  const uploadOnly = requested.filter((a) => UPLOAD_ONLY.has(a));
+  const filesystem = requested.filter((a) => !UPLOAD_ONLY.has(a));
+  if (uploadOnly.length > 0) {
+    printUploadInstructions(uploadOnly, String(loaded.parsed.frontmatter.name));
+  }
+  if (filesystem.length === 0) return 0;
+  if (!isAvailable("npx")) {
+    process.stderr.write(
+      "Error: `npx` not found. Install Node.js (>=18). Run `skillship doctor`.\n"
+    );
+    return 1;
+  }
+  const argv = buildSkillsAddArgv({
+    dir: loaded.dir,
+    agents: filesystem,
+    global: options.global,
+    copy: options.copy
+  });
+  process.stdout.write(`Running: npx ${argv.join(" ")}
+`);
+  const code = await run("npx", argv);
+  return code;
+}
+function printUploadInstructions(agents, name) {
+  process.stdout.write(
+    `
+The following surfaces are upload-only (no filesystem install): ${agents.join(", ")}
+`
+  );
+  process.stdout.write(
+    `Run \`skillship package .\` then upload \`dist/${name}.skill\`.
+`
+  );
+  if (agents.includes("claude-web")) {
+    process.stdout.write(
+      "  Claude Web: Settings -> Capabilities -> Upload skill -> enable toggle.\n"
+    );
+  }
+  if (agents.includes("claude-cowork")) {
+    process.stdout.write(
+      "  Claude Cowork: Customize -> Skills -> Upload (desktop app only).\n"
+    );
+  }
+  process.stdout.write("\n");
+}
+
+// src/commands/init.ts
+import { fileURLToPath } from "url";
+import { dirname, join as join4, resolve as resolve2 } from "path";
+import { mkdir as mkdir2, readFile as readFile2, writeFile } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+function templatesDir() {
+  const candidates = [
+    join4(__dirname2, "..", "templates"),
+    // dist/cli.js -> repo/templates
+    join4(__dirname2, "..", "..", "templates"),
+    // src/commands -> repo/templates
+    join4(__dirname2, "templates")
+  ];
+  for (const c of candidates) {
+    if (existsSync2(c)) return c;
+  }
+  return candidates[0];
+}
+async function renderTemplate(file, name) {
+  const raw = await readFile2(join4(templatesDir(), file), "utf8");
+  return raw.replaceAll("{{name}}", name);
+}
+async function emit(target, content) {
+  await mkdir2(dirname(target), { recursive: true });
+  await writeFile(target, content);
+}
+async function initCommand(name, options) {
+  const skillName = name ?? "my-skill";
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(skillName)) {
+    process.stderr.write(
+      `Invalid skill name "${skillName}". Use lowercase letters, numbers, and single hyphens.
+`
+    );
+    return 1;
+  }
+  const root = resolve2(process.cwd(), skillName);
+  if (existsSync2(root)) {
+    process.stderr.write(`Error: directory "${skillName}" already exists.
+`);
+    return 1;
+  }
+  const writes = [];
+  writes.push([
+    join4(root, skillName, "SKILL.md"),
+    await renderTemplate("SKILL.md", skillName)
+  ]);
+  writes.push([join4(root, "README.md"), await renderTemplate("README.md", skillName)]);
+  writes.push([join4(root, "AGENTS.md"), await renderTemplate("AGENTS.md", skillName)]);
+  writes.push([
+    join4(root, "release-please-config.json"),
+    await renderTemplate("release-please-config.json", skillName)
+  ]);
+  writes.push([
+    join4(root, ".release-please-manifest.json"),
+    JSON.stringify({ ".": "1.0.0" }, null, 2) + "\n"
+  ]);
+  writes.push([join4(root, "version.txt"), "1.0.0\n"]);
+  if (options.ci) {
+    writes.push([
+      join4(root, ".github", "workflows", "validate.yml"),
+      await renderTemplate("validate.yml", skillName)
+    ]);
+    writes.push([
+      join4(root, ".github", "workflows", "release.yml"),
+      await renderTemplate("release.yml", skillName)
+    ]);
+  }
+  if (options.snippets) {
+    writes.push([
+      join4(root, "snippets", "cursor-rule.mdc"),
+      await renderTemplate("cursor-rule.mdc", skillName)
+    ]);
+    writes.push([
+      join4(root, "snippets", "claude-md.md"),
+      await renderTemplate("claude-md.md", skillName)
+    ]);
+  }
+  for (const [target, content] of writes) {
+    await emit(target, content);
+  }
+  process.stdout.write(`Scaffolded ${skillName}/ (${writes.length} files)
+`);
+  process.stdout.write(`  cd ${skillName}
+`);
+  process.stdout.write(`  npx skillship validate ${skillName} --profile all
+`);
+  return 0;
+}
+
+// src/commands/doctor.ts
+async function doctorCommand() {
+  const checks = [];
+  const nodeOk = nodeVersionOk();
+  checks.push({
+    name: "node >= 18",
+    required: true,
+    ok: nodeOk,
+    detail: process.version
+  });
+  const npx = isAvailable("npx");
+  checks.push({
+    name: "npx (for `skills add`)",
+    required: true,
+    ok: npx,
+    detail: npx ? "found" : "missing \u2014 install Node.js"
+  });
+  const gh = isAvailable("gh");
+  checks.push({
+    name: "gh (GitHub CLI, for releases)",
+    required: false,
+    ok: gh,
+    detail: gh ? "found" : "optional \u2014 needed for release uploads"
+  });
+  const agentskills = isAvailable("agentskills");
+  checks.push({
+    name: "agentskills (optional spec validator)",
+    required: false,
+    ok: agentskills,
+    detail: agentskills ? versionOf("agentskills") : "optional"
+  });
+  for (const c of checks) {
+    const mark = c.ok ? "\u2713" : c.required ? "\u2717" : "\u2013";
+    process.stdout.write(`  ${mark} ${c.name}: ${c.detail}
+`);
+  }
+  const failedRequired = checks.some((c) => c.required && !c.ok);
+  process.stdout.write(
+    failedRequired ? "\nMissing required dependencies.\n" : "\nEnvironment looks good.\n"
+  );
+  return failedRequired ? 1 : 0;
+}
+function nodeVersionOk() {
+  const major = Number(process.versions.node.split(".")[0]);
+  return major >= 18;
+}
+function versionOf(cmd) {
+  const res = runCapture(cmd, ["--version"]);
+  return (res.stdout || res.stderr).trim() || "found";
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("skillship").description(
+  "Make any Agent Skill (SKILL.md) portable across Cursor, Claude Code, Claude Web, and Claude Cowork."
+).version("1.0.0");
+program.command("validate").description("Validate a SKILL.md against per-surface profiles").argument("[dir]", "skill directory", ".").option("--profile <p>", "spec | cursor | claude-web | claude-cowork | all", "all").option("--json", "machine-readable output").action(async (dir, opts) => {
+  process.exit(await validateCommand(dir, opts));
+});
+program.command("package").description("Validate then build a .skill zip for Claude upload").argument("[dir]", "skill directory", ".").option("--out <dir>", "output directory", "dist").action(async (dir, opts) => {
+  process.exit(await packageCommand(dir, opts));
+});
+program.command("install").description("Install a skill via `npx skills`, or print upload instructions").argument("[dir]", "skill directory", ".").option("--agent <a,b>", "comma-separated agents").option("--global", "install globally").option("--copy", "copy instead of symlink").action(async (dir, opts) => {
+  process.exit(await installCommand(dir, opts));
+});
+program.command("init").description("Scaffold a new skill repo with release-please CI").argument("[name]", "skill name").option("--ci", "include GitHub Actions workflows").option("--snippets", "include cursor-rule.mdc and claude-md.md snippets").action(async (name, opts) => {
+  process.exit(await initCommand(name, opts));
+});
+program.command("doctor").description("Check the local environment for required/optional tools").action(async () => {
+  process.exit(await doctorCommand());
+});
+program.parseAsync(process.argv).catch((err) => {
+  process.stderr.write(`${err instanceof Error ? err.stack : String(err)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "skillship",
+  "version": "1.0.0",
+  "description": "Make any Agent Skill (SKILL.md) portable across Cursor, Claude Code, Claude Web, and Claude Cowork.",
+  "type": "module",
+  "bin": {
+    "skillship": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "agent-skills",
+    "skill",
+    "cursor",
+    "claude",
+    "cli"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "archiver": "^7.0.1",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/archiver": "^6.0.3",
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "yauzl": "^3.2.0",
+    "@types/yauzl": "^2.10.3"
+  }
+}

package/templates/AGENTS.md

@@ -0,0 +1,29 @@
+# Repository guide for agents
+
+This repo packages the `{{name}}` Agent Skill for distribution across Cursor,
+Claude Code, Claude Web, and Claude Cowork.
+
+## Layout
+
+- `{{name}}/SKILL.md` — the skill itself (source of truth).
+- `release-please-config.json`, `.release-please-manifest.json`, `version.txt` —
+  release automation via release-please + Conventional Commits.
+- `.github/workflows/validate.yml` — validates the skill on PRs/pushes.
+- `.github/workflows/release.yml` — cuts releases and uploads `{{name}}.skill`.
+
+## Conventions
+
+- Use Conventional Commits (`feat:`, `fix:`, `docs:`, ...). `feat`/`fix` bump
+  the
+  version; merging the release PR publishes `{{name}}.skill` to a GitHub
+  Release.
+- Keep the `description` in `{{name}}/SKILL.md` <= 200 chars so it uploads to
+  Claude Web/Cowork.
+- The version line in `SKILL.md` carries `# x-release-please-version` so
+  release-please updates it in place.
+
+## Commands
+
+- `npx skillship validate {{name}} --profile all`
+- `npx skillship package {{name}}`
+- `npx skillship install {{name}} -a cursor,claude-code`

package/templates/README.md

@@ -0,0 +1,27 @@
+# {{name}}
+
+An [Agent Skill](https://agentskills.io/specification) packaged for Cursor,
+Claude Code, Claude Web, and Claude Cowork.
+
+## Develop
+
+- Validate: `npx skillship validate {{name}} --profile all`
+- Package: `npx skillship package {{name}}` (produces `dist/{{name}}.skill`)
+- Install locally: `npx skillship install {{name}} -a cursor,claude-code`
+
+## Upload to Claude
+
+1. `npx skillship package {{name}}`
+2. Upload `dist/{{name}}.skill`:
+   - Claude Web: Settings -> Capabilities -> Upload skill -> enable toggle.
+   - Claude Cowork: Customize -> Skills -> Upload (desktop app only).
+
+## Releasing
+
+This repo auto-releases with
+[release-please](https://github.com/googleapis/release-please-action) using
+[Conventional Commits](https://www.conventionalcommits.org/). Merging the
+generated release PR publishes `{{name}}.skill` to a GitHub Release.
+
+> Enable **Settings -> Actions -> Workflow permissions**: "Read and write" and
+> "Allow GitHub Actions to create and approve pull requests".

package/templates/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: {{name}}
+description: Describe when an agent should use {{name}} and what it does. Keep this under 200 characters so it uploads cleanly to Claude Web and Cowork.
+license: MIT
+metadata:
+  version: "1.0.0" # x-release-please-version
+---
+
+# {{name}}
+
+Explain what this skill does and when an agent should use it.
+
+## Instructions
+
+1. Step one.
+2. Step two.

package/templates/claude-md.md

@@ -0,0 +1,5 @@
+# {{name}}
+
+This project ships the `{{name}}` Agent Skill.
+
+When a task matches the skill's purpose, read `{{name}}/SKILL.md` and follow it.

package/templates/cursor-rule.mdc

@@ -0,0 +1,11 @@
+---
+description: {{name}} skill guidance
+alwaysApply: false
+---
+
+# {{name}}
+
+This rule points the agent at the `{{name}}` Agent Skill.
+
+Read `{{name}}/SKILL.md` and follow its instructions when the task matches the
+skill's description.

package/templates/release-please-config.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "simple",
+      "changelog-sections": [
+        { "type": "feat", "section": "Features" },
+        { "type": "fix", "section": "Bug Fixes" },
+        { "type": "perf", "section": "Performance" },
+        { "type": "docs", "section": "Documentation" },
+        { "type": "refactor", "section": "Refactors" },
+        { "type": "ci", "section": "CI", "hidden": true },
+        { "type": "chore", "section": "Chores", "hidden": true }
+      ],
+      "extra-files": [
+        {
+          "type": "generic",
+          "path": "{{name}}/SKILL.md"
+        }
+      ]
+    }
+  }
+}

package/templates/release.yml

@@ -0,0 +1,30 @@
+name: release
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: write
+  pull-requests: write
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+      - uses: actions/checkout@v4
+        if: ${{ steps.release.outputs.release_created }}
+      - uses: actions/setup-node@v4
+        if: ${{ steps.release.outputs.release_created }}
+        with:
+          node-version: "20"
+      - name: Package skill
+        if: ${{ steps.release.outputs.release_created }}
+        run: npx skillship package {{name}}
+      - name: Upload to release
+        if: ${{ steps.release.outputs.release_created }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release upload "${{ steps.release.outputs.tag_name }}" dist/{{name}}.skill --clobber

package/templates/validate.yml

@@ -0,0 +1,14 @@
+name: validate
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npx skillship validate {{name}} --profile all