runboard 1.0.1 → 1.1.2

package/AGENTS.md

@@ -25,6 +25,7 @@ runboard pulse                # compare the two latest assessments
 runboard roadmap              # Now/Next/Later from the binding constraint
 runboard report --type board-update|baseline|monthly
 runboard status               # one-screen current state
+runboard skills install [--target <dir>] [--force] [--dry-run]   # copy these skills to an agent
 ```
 
 Dimension keys: `build.team`, `build.tools`, `build.techniques`, `run.team`, `run.tools`,
@@ -49,6 +50,11 @@ their results match the CLI exactly.
 `skills/*/SKILL.md` are written to the open SKILL.md standard and run unmodified across
 agent platforms. They own the conversation; the CLI owns the computation.
 
+To install them into your agent, run `runboard skills install`. With no `--target` it
+auto-detects a supported agent (v1: Claude Code → `.claude/skills/`); for any other agent
+pass `--target <its skills dir>` (e.g. `--target .cursor/skills`). Existing skills are not
+overwritten without `--force`, and `--dry-run` previews without writing.
+
 > Note: in published installs, `CLAUDE.md` is provided as a copy/symlink of this file so
 > Claude Code reads the same guidance. In this source repo, `CLAUDE.md` is the
 > contributor/Spec-Kit guide instead — this AGENTS.md is the end-user agent guide.

package/README.md

@@ -41,6 +41,7 @@ history becomes your trajectory record.
 | `runboard roadmap` | Now/Next/Later plan from your binding constraint. |
 | `runboard report --type <t>` | Render a board-ready report from a template. |
 | `runboard status` | One-screen current state. |
+| `runboard skills install [--target <dir>]` | Copy the bundled SKILL.md skills into an agent's skills directory. |
 
 ## Use it from your AI assistant
 
@@ -61,6 +62,23 @@ account). Add it to your client with one zero-install command:
 
 See [docs/mcp.md](./docs/mcp.md) for Claude Desktop, Cursor, and VS Code setup.
 
+### Installing the skills
+
+SKILL.md is a cross-agent open format, so "installing" a skill just means copying its
+folder to wherever your agent looks for skills. `skills install` does that from the copy
+already bundled in this package — no download, no network:
+
+```bash
+npx runboard@latest skills install                 # auto-detect (Claude Code → .claude/skills/)
+npx runboard@latest skills install --target .cursor/skills   # any other agent
+npx runboard@latest skills install --dry-run       # preview; writes nothing
+npx runboard@latest skills install --force         # overwrite existing copies (e.g. after upgrade)
+```
+
+Without `--target` it auto-detects a supported agent (v1: Claude Code, via a `.claude/`
+directory). For any other agent, point `--target` at its skills directory. Existing skills
+are never overwritten without `--force`. Restart your agent afterward so it discovers them.
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md). This is a public project; work starts from

package/dist/cli.js

@@ -65,6 +65,215 @@ ${created.map((c) => `  ${c}`).join("\n")}
   });
 }
 
+// src/commands/skills.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, statSync as statSync2 } from "fs";
+import path2 from "path";
+
+// src/core/skills.ts
+function selectTarget(options, detected) {
+  if (options.target) {
+    return { kind: "explicit", dir: options.target };
+  }
+  if (detected.length === 0) {
+    return { kind: "none" };
+  }
+  if (detected.length === 1) {
+    const only = detected[0];
+    return { kind: "detected", agent: only.agent, dir: only.dir };
+  }
+  return { kind: "ambiguous", dirs: detected };
+}
+function planInstall(bundled, existingNames, options) {
+  const existing = new Set(existingNames);
+  return bundled.map((skill) => {
+    if (!existing.has(skill.name)) {
+      return { name: skill.name, kind: "create" };
+    }
+    if (options.force) {
+      return { name: skill.name, kind: "overwrite" };
+    }
+    return {
+      name: skill.name,
+      kind: "skip",
+      reason: "already present (use --force to overwrite)"
+    };
+  });
+}
+
+// src/data/skills.ts
+import { cpSync, readdirSync, statSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+function shippedSkillsDir() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [path.resolve(here, "../skills"), path.resolve(here, "../../skills")];
+  for (const candidate of candidates) {
+    try {
+      if (statSync(candidate).isDirectory()) {
+        return candidate;
+      }
+    } catch {
+    }
+  }
+  return candidates[candidates.length - 1];
+}
+function listBundledSkills(dir = shippedSkillsDir()) {
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return names.map((name) => ({ name, sourceDir: path.join(dir, name) })).filter((skill) => isDirectory(skill.sourceDir)).filter((skill) => isFile(path.join(skill.sourceDir, "SKILL.md"))).sort((a, b) => a.name.localeCompare(b.name));
+}
+var AGENT_TABLE = [
+  { agent: "claude-code", marker: ".claude", skillsDir: ".claude/skills" }
+];
+function detectAgentDirs(cwd = process.cwd()) {
+  return AGENT_TABLE.filter((row) => isDirectory(path.join(cwd, row.marker))).map((row) => ({
+    agent: row.agent,
+    dir: path.join(cwd, row.skillsDir)
+  }));
+}
+function existingSkillNames(destination) {
+  try {
+    return readdirSync(destination, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+}
+function copySkill(sourceDir, destDir) {
+  const target = path.join(destDir, path.basename(sourceDir));
+  cpSync(sourceDir, target, { recursive: true, force: true });
+}
+function isDirectory(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function isFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// src/commands/skills.ts
+function runSkillsInstall(opts = {}) {
+  const root = opts.root ?? process.cwd();
+  const force = opts.force ?? false;
+  const dryRun = opts.dryRun ?? false;
+  const bundled = listBundledSkills();
+  if (bundled.length === 0) {
+    throw new UserError(
+      "No bundled skills found in this runboard install. The package may be corrupt; try reinstalling."
+    );
+  }
+  const destination = resolveDestination(root, opts.target);
+  if (existsSync2(destination) && !statSync2(destination).isDirectory()) {
+    throw new UserError(`Target ${destination} is a file, not a directory.`);
+  }
+  const actions = planInstall(bundled, existingSkillNames(destination), { force });
+  const installed = [];
+  const skipped = [];
+  const failed = [];
+  if (dryRun) {
+    return { destination, dryRun, installed, skipped, failed, actions };
+  }
+  mkdirSync2(destination, { recursive: true });
+  for (const action of actions) {
+    if (action.kind === "skip") {
+      skipped.push(action.name);
+      continue;
+    }
+    const skill = bundled.find((b) => b.name === action.name);
+    if (!skill) {
+      throw new Error(`unreachable: planned skill ${action.name} not in bundle`);
+    }
+    try {
+      copySkill(skill.sourceDir, destination);
+      installed.push(action.name);
+    } catch (err) {
+      failed.push({ name: action.name, error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+  return { destination, dryRun, installed, skipped, failed, actions };
+}
+function resolveDestination(root, target) {
+  const resolution = selectTarget(
+    { target: target ? path2.resolve(root, target) : void 0 },
+    detectAgentDirs(root)
+  );
+  switch (resolution.kind) {
+    case "explicit":
+      return resolution.dir;
+    case "detected":
+      return resolution.dir;
+    case "none":
+      throw new UserError(
+        "No agent skills directory detected. Re-run with --target <dir> (e.g. --target .cursor/skills)."
+      );
+    case "ambiguous":
+      throw new UserError(
+        `Multiple agent skills directories detected:
+${resolution.dirs.map((d) => `  ${d.agent}: ${d.dir}`).join("\n")}
+Re-run with --target <dir> to choose one.`
+      );
+  }
+}
+function formatReport(report) {
+  const lines = [];
+  if (report.dryRun) {
+    lines.push("Dry run \u2014 no files will be written.");
+    lines.push(`Destination: ${report.destination}`);
+    for (const action of report.actions) {
+      const label = action.kind === "skip" ? "skip (already present)" : action.kind;
+      lines.push(`  ${action.name.padEnd(14)}${label}`);
+    }
+    return `${lines.join("\n")}
+`;
+  }
+  const failedNames = new Set(report.failed.map((f) => f.name));
+  lines.push(`Installing skills into ${report.destination}`);
+  for (const action of report.actions) {
+    const failure = report.failed.find((f) => f.name === action.name);
+    if (failure) {
+      lines.push(`  \u2717 ${action.name.padEnd(14)}(failed: ${failure.error})`);
+    } else if (action.kind === "skip") {
+      lines.push(
+        `  - ${action.name.padEnd(14)}(skipped: already present, use --force to overwrite)`
+      );
+    } else {
+      const verb = action.kind === "overwrite" ? "overwritten" : "created";
+      lines.push(`  \u2713 ${action.name.padEnd(14)}(${verb})`);
+    }
+  }
+  lines.push("");
+  const tail = failedNames.size > 0 ? `, ${failedNames.size} failed` : "";
+  lines.push(
+    `Installed ${report.installed.length} skill(s), skipped ${report.skipped.length}${tail}. Restart your agent to pick them up.`
+  );
+  return `${lines.join("\n")}
+`;
+}
+function registerSkills(program) {
+  const skills = program.command("skills").description("Manage runboard's portable AI skills.");
+  skills.command("install").description("Copy the bundled SKILL.md skills into an agent's skills directory.").option("--target <dir>", "destination directory (overrides auto-detection)").option("--force", "overwrite skills already present at the destination").option("--dry-run", "show what would be installed without writing anything").action((options) => {
+    const report = runSkillsInstall({
+      target: options.target,
+      force: options.force,
+      dryRun: options.dryRun
+    });
+    process.stdout.write(formatReport(report));
+    if (report.failed.length > 0) {
+      process.exitCode = 1;
+    }
+  });
+}
+
 // src/cli.ts
 function buildProgram() {
   const program = new Command();
@@ -76,6 +285,7 @@ function buildProgram() {
   registerRoadmap(program);
   registerReport(program);
   registerStatus(program);
+  registerSkills(program);
   program.command("mcp").description("Start the MCP server over stdio (for tool-calling AI clients).").action(async () => {
     await startMcpServer();
   });

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "runboard",
-  "version": "1.0.1",
+  "version": "1.1.2",
   "description": "Local-first CLI for the Runboard technical-leadership maturity framework. Deterministic scoring core, portable AI adapters, no phone-home.",
   "type": "module",
   "license": "MIT",
+  "homepage": "https://runboard.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johncarpenter/runboard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/johncarpenter/runboard/issues"
+  },
   "engines": {
     "node": ">=20"
   },