agent-skillboard 0.2.7 → 0.2.8

package/src/agent-skill-import.mjs

@@ -0,0 +1,291 @@
+import { createHash } from "node:crypto";
+import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import YAML from "yaml";
+import { detectedAgentSkillRoots, preferredAgentSkillRoot, supportedAgentNames } from "./agent-skill-roots.mjs";
+
+const AGENT_MARKERS = Object.freeze({
+  codex: [/CODEX_HOME/i, /(^|[/\\])\.codex([/\\]|$)/i, /~\/\.codex\b/i, /\bCodex\b/i],
+  claude: [/CLAUDE_HOME/i, /(^|[/\\])\.claude([/\\]|$)/i, /~\/\.claude\b/i, /\bClaude\b/i, /\bCLAUDE\.md\b/],
+  opencode: [/OPENCODE_HOME/i, /(^|[/\\])opencode([/\\]|$)/i, /~\/\.config\/opencode\b/i, /\bOpenCode\b/i],
+  hermes: [/HERMES_HOME/i, /(^|[/\\])\.hermes([/\\]|$)/i, /~\/\.hermes\b/i, /\bHermes\b/i]
+});
+
+export async function importAgentSkill(options = {}) {
+  const env = options.env ?? process.env;
+  const home = env.HOME ?? env.USERPROFILE ?? homedir();
+  const sourceAgent = requireAgent(options.from, "--from");
+  const targetAgent = requireAgent(options.to, "--to");
+  const sourceSkill = requireNonEmpty(options.skill, "--skill");
+  const sourceRoots = (await detectedAgentSkillRoots(sourceAgent, home, env, { includeFallback: true }))
+    .map((root) => root.skillRoot);
+  const targetRoot = await agentSkillRoot(targetAgent, home, env);
+  const source = await findSourceSkillInRoots({ roots: sourceRoots, skill: sourceSkill });
+  const sourceContent = await readFile(source.skillFile, "utf8");
+  const targetSkill = options.targetSkill ?? sourceSkill;
+  const targetDir = resolveRelativeTarget(targetRoot, targetSkill);
+  const targetSkillFile = join(targetDir, "SKILL.md");
+  const provenanceFile = join(targetDir, ".skillboard-import.json");
+  const compatibility = analyzeAgentCompatibility(sourceContent, { sourceAgent, targetAgent });
+  const adaptedFile = options.adaptedFile;
+  const dryRun = options.dryRun === true;
+  const yes = options.yes === true;
+  const replace = options.replace === true;
+  const mode = adaptedFile === undefined ? "copy" : "adapted";
+  const next = nextSteps({ sourceAgent, targetAgent, sourceSkill, targetSkill });
+
+  if (!compatibility.compatible && adaptedFile === undefined) {
+    return {
+      status: "needs-adaptation",
+      mode: "adaptation-required",
+      changed: false,
+      source: sourceSummary(sourceAgent, sourceSkill, source),
+      target: targetSummary(targetAgent, targetSkill, targetSkillFile),
+      compatibility,
+      next
+    };
+  }
+
+  const content = adaptedFile === undefined ? sourceContent : await readFile(adaptedFile, "utf8");
+  const targetExists = await exists(targetSkillFile);
+  const writeRequired = !dryRun && yes;
+  const status = dryRun || !yes ? "ready" : "installed";
+
+  if (targetExists && !replace) {
+    throw new Error(`Target skill already exists: ${targetSkillFile}; pass --replace to overwrite`);
+  }
+  if (writeRequired) {
+    await mkdir(targetDir, { recursive: true });
+    await writeFile(targetSkillFile, content, "utf8");
+    await writeFile(provenanceFile, `${JSON.stringify(provenance({
+      sourceAgent,
+      sourceSkill,
+      source,
+      sourceContent,
+      targetAgent,
+      targetSkill,
+      targetSkillFile,
+      targetContent: content,
+      mode,
+      compatibility
+    }), null, 2)}\n`, "utf8");
+  }
+
+  return {
+    status,
+    mode,
+    changed: writeRequired,
+    source: sourceSummary(sourceAgent, sourceSkill, source),
+    target: targetSummary(targetAgent, targetSkill, targetSkillFile),
+    compatibility,
+    next: status === "ready" ? { ...next, apply: `${next.apply} --yes` } : null
+  };
+}
+
+export function renderImportAgentSkill(result) {
+  if (result.status === "needs-adaptation") {
+    return [
+      "Skill requires adaptation before import.",
+      `Source: ${result.source.agent}:${result.source.skill} (${result.source.path})`,
+      `Target: ${result.target.agent}:${result.target.skill} (${result.target.path})`,
+      `Reasons: ${result.compatibility.reasons.join("; ")}`,
+      `Next: ${result.next.adaptedFileOption}`,
+      ""
+    ].join("\n");
+  }
+  return [
+    `${result.status === "installed" ? "Imported" : "Ready to import"} skill: ${result.source.agent}:${result.source.skill} -> ${result.target.agent}:${result.target.skill}`,
+    `Mode: ${result.mode}`,
+    `Target: ${result.target.path}`,
+    result.status === "ready" ? "Re-run with --yes to write the target skill." : "Provenance: .skillboard-import.json",
+    ""
+  ].join("\n");
+}
+
+export async function agentSkillRoot(agent, home = homedir(), env = process.env) {
+  requireKnownAgent(agent);
+  return await preferredAgentSkillRoot(agent, home, env);
+}
+
+export function supportedImportAgents() {
+  return supportedAgentNames();
+}
+
+function requireAgent(value, optionName) {
+  const agent = requireNonEmpty(value, optionName);
+  if (!supportedAgentNames().includes(agent)) {
+    throw new Error(`Unsupported ${optionName} agent: ${agent}`);
+  }
+  return agent;
+}
+
+function requireKnownAgent(agent) {
+  if (!supportedAgentNames().includes(agent)) {
+    throw new Error(`Unsupported agent: ${agent}`);
+  }
+}
+
+function requireNonEmpty(value, optionName) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${optionName} is required`);
+  }
+  return value.trim();
+}
+
+async function findSourceSkill(options) {
+  const root = resolve(options.root);
+  const directDir = resolveRelativeTarget(root, options.skill);
+  const directFile = join(directDir, "SKILL.md");
+  if (await exists(directFile)) {
+    return { skillDir: directDir, skillFile: directFile, matchedBy: "path" };
+  }
+  const matches = [];
+  for (const file of await findSkillFiles(root)) {
+    const text = await readFile(file, "utf8").catch(() => "");
+    const frontmatter = parseSkillFrontmatter(text);
+    if (frontmatter.name === options.skill) {
+      matches.push({ skillDir: dirname(file), skillFile: file, matchedBy: "frontmatter" });
+    }
+  }
+  if (matches.length === 1) {
+    return matches[0];
+  }
+  if (matches.length > 1) {
+    throw new Error(`Multiple source skills matched ${options.skill}; pass a directory name instead`);
+  }
+  throw new Error(`Source skill not found: ${options.skill} under ${root}`);
+}
+
+async function findSourceSkillInRoots(options) {
+  const misses = [];
+  for (const root of options.roots) {
+    try {
+      return await findSourceSkill({ root, skill: options.skill });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!message.startsWith(`Source skill not found: ${options.skill} under `)) {
+        throw error;
+      }
+      misses.push(root);
+    }
+  }
+  throw new Error(`Source skill not found: ${options.skill} under ${misses.join(", ")}`);
+}
+
+async function findSkillFiles(root) {
+  const files = [];
+  const pending = [resolve(root)];
+  while (pending.length > 0) {
+    const current = pending.shift();
+    const entries = await readdir(current, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) {
+        pending.push(path);
+      } else if (entry.isFile() && entry.name === "SKILL.md") {
+        files.push(path);
+      }
+    }
+  }
+  return files;
+}
+
+function parseSkillFrontmatter(text) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (match === null) {
+    return {};
+  }
+  const parsed = YAML.parse(match[1]);
+  return parsed !== null && typeof parsed === "object" ? parsed : {};
+}
+
+function analyzeAgentCompatibility(content, options) {
+  const reasons = [];
+  for (const [agent, markers] of Object.entries(AGENT_MARKERS)) {
+    if (agent === options.targetAgent) {
+      continue;
+    }
+    const matched = markers.filter((marker) => marker.test(content)).map((marker) => marker.source);
+    if (matched.length > 0) {
+      reasons.push(`source mentions ${agent}-specific runtime markers: ${matched.join(", ")}`);
+    }
+  }
+  return {
+    compatible: reasons.length === 0,
+    sourceAgent: options.sourceAgent,
+    targetAgent: options.targetAgent,
+    reasons
+  };
+}
+
+function nextSteps(options) {
+  const base = `skillboard import-skill --from ${options.sourceAgent} --to ${options.targetAgent} --skill ${options.sourceSkill} --target-skill ${options.targetSkill}`;
+  return {
+    askUser: "Ask whether to adapt the skill for the target agent before changing the skill body.",
+    adaptedFileOption: `${base} --adapted-file <adapted-skill.md> --yes`,
+    apply: base
+  };
+}
+
+function provenance(options) {
+  return {
+    version: 1,
+    mode: options.mode,
+    source: {
+      agent: options.sourceAgent,
+      skill: options.sourceSkill,
+      path: options.source.skillFile,
+      digest: digest(options.sourceContent)
+    },
+    target: {
+      agent: options.targetAgent,
+      skill: options.targetSkill,
+      path: options.targetSkillFile,
+      digest: digest(options.targetContent)
+    },
+    compatibility: options.compatibility
+  };
+}
+
+function sourceSummary(agent, skill, source) {
+  return {
+    agent,
+    skill,
+    path: source.skillFile,
+    matchedBy: source.matchedBy
+  };
+}
+
+function targetSummary(agent, skill, path) {
+  return { agent, skill, path };
+}
+
+function digest(content) {
+  return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+
+function resolveRelativeTarget(root, value) {
+  const relativePath = String(value).replaceAll("\\", "/");
+  if (relativePath.trim() === "" || relativePath.includes("\0")) {
+    throw new Error("skill path must be a non-empty relative path");
+  }
+  if (relativePath.startsWith("/") || /^[A-Za-z]:\//.test(relativePath)) {
+    throw new Error("skill path must be relative");
+  }
+  const absolute = resolve(root, relativePath);
+  assertInside(resolve(root), absolute, "skill path");
+  return absolute;
+}
+
+function assertInside(root, candidate, label) {
+  const rel = relative(root, candidate);
+  if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel))) {
+    return;
+  }
+  throw new Error(`${label} must stay under ${root}`);
+}
+
+async function exists(path) {
+  return access(path).then(() => true, () => false);
+}

package/src/agent-skill-roots.mjs

@@ -0,0 +1,114 @@
+import { access, readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+const SUPPORTED_AGENTS = Object.freeze(["codex", "claude", "opencode", "hermes"]);
+
+export function supportedAgentNames() {
+  return [...SUPPORTED_AGENTS];
+}
+
+export async function detectedAgentSkillRoots(agent, home = homedir(), env = process.env, options = {}) {
+  const candidates = await agentSkillRootCandidates(agent, home, env);
+  const detected = [];
+  for (const candidate of candidates) {
+    if (candidate.explicit || await exists(candidate.skillRoot)) {
+      detected.push(candidate);
+    }
+  }
+  if (detected.length === 0 && options.includeFallback === true) {
+    detected.push(fallbackCandidate(candidates));
+  }
+  return uniqueCandidates(detected);
+}
+
+export async function setupAgentSkillTargets(agent, home = homedir(), env = process.env, options = {}) {
+  const roots = await detectedAgentSkillRoots(agent, home, env, { includeFallback: options.includeFallback === true });
+  return roots.map((root) => ({
+    agent,
+    skillPath: join(root.skillRoot, "skillboard", "SKILL.md"),
+    root: root.skillRoot,
+    source: root.source
+  }));
+}
+
+export async function preferredAgentSkillRoot(agent, home = homedir(), env = process.env) {
+  const [root] = await detectedAgentSkillRoots(agent, home, env, { includeFallback: true });
+  return root.skillRoot;
+}
+
+export async function agentSkillRootCandidates(agent, home = homedir(), env = process.env) {
+  const normalized = normalizeAgent(agent);
+  const xdgConfig = env.XDG_CONFIG_HOME ?? join(home, ".config");
+  if (normalized === "codex") {
+    return uniqueCandidates([
+      env.CODEX_HOME === undefined ? null : candidate(join(env.CODEX_HOME, "skills"), "CODEX_HOME/skills", true, false),
+      env.AGENTS_HOME === undefined ? null : candidate(join(env.AGENTS_HOME, "skills"), "AGENTS_HOME/skills", true, false),
+      candidate(join(home, ".agents", "skills"), "~/.agents/skills", false, false),
+      candidate(join(home, ".codex", "skills"), "~/.codex/skills", false, true)
+    ]);
+  }
+  if (normalized === "claude") {
+    return uniqueCandidates([
+      env.CLAUDE_HOME === undefined ? null : candidate(join(env.CLAUDE_HOME, "skills"), "CLAUDE_HOME/skills", true, false),
+      candidate(join(home, ".claude", "skills"), "~/.claude/skills", false, true),
+      candidate(join(xdgConfig, "claude", "skills"), "XDG claude skills", false, false),
+      candidate(join(home, ".config", "claude", "skills"), "~/.config/claude/skills", false, false)
+    ]);
+  }
+  if (normalized === "opencode") {
+    return uniqueCandidates([
+      env.OPENCODE_HOME === undefined ? null : candidate(join(env.OPENCODE_HOME, "skills"), "OPENCODE_HOME/skills", true, false),
+      candidate(join(xdgConfig, "opencode", "skills"), "XDG opencode skills", false, xdgConfig !== join(home, ".config")),
+      candidate(join(home, ".config", "opencode", "skills"), "~/.config/opencode/skills", false, true),
+      candidate(join(home, ".opencode", "skills"), "~/.opencode/skills", false, false)
+    ]);
+  }
+  const hermesHome = env.HERMES_HOME ?? join(home, ".hermes");
+  return uniqueCandidates([
+    env.HERMES_HOME === undefined ? null : candidate(join(env.HERMES_HOME, "skills"), "HERMES_HOME/skills", true, false),
+    candidate(join(home, ".hermes", "skills"), "~/.hermes/skills", false, true),
+    ...(await hermesProfileCandidates(hermesHome))
+  ]);
+}
+
+function normalizeAgent(agent) {
+  if (!SUPPORTED_AGENTS.includes(agent)) {
+    throw new Error(`Unsupported agent: ${agent}`);
+  }
+  return agent;
+}
+
+function candidate(skillRoot, source, explicit, fallback) {
+  return { skillRoot, source, explicit, fallback };
+}
+
+function fallbackCandidate(candidates) {
+  return candidates.find((candidate) => candidate.fallback) ?? candidates[0];
+}
+
+function uniqueCandidates(candidates) {
+  const seen = new Set();
+  const unique = [];
+  for (const candidate of candidates.filter(Boolean)) {
+    const key = resolve(candidate.skillRoot);
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    unique.push({ ...candidate, skillRoot: key });
+  }
+  return unique;
+}
+
+async function hermesProfileCandidates(hermesHome) {
+  const profilesRoot = join(hermesHome, "profiles");
+  const entries = await readdir(profilesRoot, { withFileTypes: true }).catch(() => []);
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => candidate(join(profilesRoot, entry.name, "skills"), `Hermes profile ${entry.name}`, false, false));
+}
+
+async function exists(path) {
+  return access(path).then(() => true, () => false);
+}

package/src/cli.mjs

@@ -1,3 +1,4 @@
+// allow: SIZE_OK - legacy CLI dispatcher split is deferred from the 0.2.7 release gate.
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { readFileSync } from "node:fs";
 import { dirname, isAbsolute, resolve } from "node:path";
@@ -51,16 +52,19 @@ import {
 } from "./index.mjs";
 // SIZE_OK: src/cli.mjs is pre-existing command-router debt; brief behavior delegates to src/brief-cli.mjs and hook planning delegates through src/hook-plan.mjs until a broader router split.
 import { ApplyActionError, applyActionErrorPayload, applyAdvisorAction } from "./advisor/apply-action.mjs";
+import { importAgentSkill, renderImportAgentSkill } from "./agent-skill-import.mjs";
 import { runBriefCommand } from "./brief-cli.mjs";
 import { renderSkillBrief } from "./brief-renderer.mjs";
 import { planGuardHookInstall } from "./control.mjs";
 import { writeCheckedConfig } from "./control/config-write.mjs";
-import { runInitCommand, runUninstallCommand } from "./lifecycle-cli.mjs";
+import { runInitCommand, runSetupCommand, runUninstallCommand } from "./lifecycle-cli.mjs";
 
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
 const APPLY_ACTION_VALUE_OPTIONS = new Set(["workflow", "dir", "config", "skills", "out", "skillboard-bin"]);
 const COMMAND_USAGE = new Map([
+  ["setup", ["setup [--yes] [--agent codex[,claude,opencode,hermes]]"]],
+  ["import-skill", ["import-skill --from <agent> --to <agent> --skill <id-or-dir> [--target-skill <id-or-dir>] [--adapted-file <path>] [--dry-run] [--yes] [--replace] [--json]"]],
   ["uninstall", ["uninstall [--dir <path>] [--dry-run] [--purge] [--remove-config|--reset-config] [--remove-reports] [--remove-hooks] [--keep-empty-dirs]"]],
   [
     "inventory",
@@ -94,19 +98,19 @@ const COMMAND_USAGE = new Map([
 ]);
 
 if (process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  process.exitCode = await main(process.argv.slice(2), process.stdout, process.stderr);
+  process.exitCode = await main(process.argv.slice(2), process.stdout, process.stderr, process.stdin);
 }
 
-export async function main(argv, stdout, stderr) {
-  try {
-    return await run(argv, stdout, stderr);
-  } catch (error) {
-    stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+export async function main(argv, stdout, stderr, stdin = process.stdin) {
+  try {
+    return await run(argv, stdout, stderr, stdin);
+  } catch (error) {
+    stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
     return Number.isInteger(error?.exitCode) ? error.exitCode : 1;
-  }
-}
-
-async function run(argv, stdout, stderr) {
+  }
+}
+
+async function run(argv, stdout, stderr, stdin) {
   const command = argv[0] ?? "help";
   const commandArgs = argv.slice(1);
   const options = parseOptions(commandArgs);
@@ -116,6 +120,17 @@ async function run(argv, stdout, stderr) {
     return 0;
   }
   switch (command) {
+    case "setup":
+      return await runSetupCommand(options, stdout, {
+        cwd: process.cwd(),
+        env: process.env,
+        entrypointPath: process.argv[1],
+        packageSpec: process.env.npm_config_package,
+        stdin,
+        stdout
+      });
+    case "import-skill":
+      return await importSkillCommand(options, stdout);
     case "init":
       return await runInitCommand(options, stdout);
     case "uninstall":
@@ -209,7 +224,7 @@ function selectedHelpText(command, args, options) {
   return null;
 }
 
-async function importProfile(options, stdout) {
+async function importProfile(options, stdout) {
   const profileRef = options.get("profile");
   const sourceRoot = options.get("source-root");
   if (profileRef === undefined || sourceRoot === undefined) {
@@ -256,6 +271,22 @@ async function mergeImport(options, imported, stdout) {
   return 0;
 }
 
+async function importSkillCommand(options, stdout) {
+  const result = await importAgentSkill({
+    from: options.get("from"),
+    to: options.get("to"),
+    skill: options.get("skill"),
+    targetSkill: options.get("target-skill"),
+    adaptedFile: options.get("adapted-file"),
+    dryRun: options.get("dry-run") === "true",
+    yes: options.get("yes") === "true",
+    replace: options.get("replace") === "true",
+    env: process.env
+  });
+  writeOutput(stdout, result, options, () => renderImportAgentSkill(result));
+  return result.status === "needs-adaptation" ? 2 : 0;
+}
+
 async function inventory(argv, options, stdout) {
   const args = positionalArgs(argv);
   if (args[0] === "detect") {
@@ -1061,14 +1092,18 @@ function parseOptions(args) {
   return options;
 }
 
-function formatList(values) {
-  return values.length === 0 ? "none" : values.map((value) => `\`${value}\``).join(", ");
-}
-
+function formatList(values) {
+  return values.length === 0 ? "none" : values.map((value) => `\`${value}\``).join(", ");
+}
+
+function shellQuote(value) {
+  return /^[A-Za-z0-9_./:=@-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+
 function readCsv(value) {
-  if (value === undefined || value.trim() === "") {
-    return [];
-  }
+  if (value === undefined || value.trim() === "") {
+    return [];
+  }
   return value.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
 }
 
@@ -1446,6 +1481,7 @@ function renderDoctorSummary(result) {
       lines.push(`- ${concern}`);
     }
   }
+  appendNotInitializedAttachGuidance(lines, result);
   if (result.recommendations.length > 0) {
     lines.push("Recommendations:");
     for (const recommendation of result.recommendations.slice(0, 3)) {
@@ -1477,6 +1513,7 @@ function renderDoctor(result) {
     `Runtime extension units: ${formatList(result.workspace.installUnits.runtimeExtensions)}`,
     `Uninstall dry run: remove ${result.uninstall.removed.length}, update ${result.uninstall.updated.length}, preserve ${result.uninstall.preserved.length}`
   ];
+  appendNotInitializedAttachGuidance(lines, result);
   if (result.recommendations.length > 0) {
     lines.push("Recommendations:");
     for (const recommendation of result.recommendations) {
@@ -1487,6 +1524,16 @@ function renderDoctor(result) {
   return lines.join("\n");
 }
 
+function appendNotInitializedAttachGuidance(lines, result) {
+  if (result.mode !== "not-initialized") {
+    return;
+  }
+  lines.push("SkillBoard state:");
+  lines.push("- No local SkillBoard policy file was found in this directory.");
+  lines.push("- That is OK: project management belongs to the agent/workspace layer.");
+  lines.push("- Global install normally runs agent setup automatically; run skillboard setup later only after adding another supported agent or if install scripts were skipped.");
+}
+
 function renderCounts(counts) {
   const entries = Object.entries(counts).filter(([, count]) => count > 0);
   return entries.length === 0
@@ -1499,7 +1546,14 @@ function helpText() {
     "SkillBoard - AI-mediated workflow-scoped skill policy",
     "Version: see skillboard --version",
     "",
+    "After global install:",
+    "  npm install -g agent-skillboard",
+    "  The package postinstall auto-runs agent-layer guidance setup for detected supported agents.",
+    "  Run skillboard setup later after adding another supported agent or when install scripts were skipped.",
+    "",
     "AI/automation operations:",
+    "  setup [--yes] [--agent codex[,claude,opencode,hermes]]",
+    "  import-skill --from <agent> --to <agent> --skill <id-or-dir> [--target-skill <id-or-dir>] [--adapted-file <path>] [--dry-run] [--yes] [--replace] [--json]",
     "  init [--dir <path>] [--scan-root <dir>[,<dir>]] [--no-scan-installed]",
     "  uninstall [--dir <path>] [--dry-run] [--purge] [--remove-config|--reset-config] [--remove-reports] [--remove-hooks] [--keep-empty-dirs]",
     "  inventory refresh [--dir <path>] [--config <path>] [--scan-root <dir>[,<dir>]] [--dry-run] [--json]",
@@ -1560,6 +1614,12 @@ function commandHelpText(command) {
   if (command === "init") {
     return initHelpText();
   }
+  if (command === "setup") {
+    return setupHelpText();
+  }
+  if (command === "import-skill") {
+    return importSkillHelpText();
+  }
   if (command === "uninstall") {
     return uninstallHelpText();
   }
@@ -1613,6 +1673,61 @@ function initHelpText() {
   ].join("\n");
 }
 
+function setupHelpText() {
+  return [
+    "Usage: skillboard setup [--yes] [--agent codex[,claude,opencode,hermes]]",
+    "",
+    "Installs or refreshes SkillBoard at the agent layer, not into a project.",
+    "A normal global package install already runs this automatically for detected supported agents.",
+    "Use setup later after adding another supported agent, enabling a new agent home, or skipping install scripts.",
+    "Without --yes, setup explains the user agent skill files it will write and asks before installing when run in a TTY.",
+    "In non-interactive automation, rerun with --yes after choosing the target agents.",
+    "",
+    "What changes after confirmation:",
+    "  Writes a SkillBoard guidance skill into detected user agent skill roots.",
+    "  Does not write skillboard.config.yaml, .skillboard/, AGENTS.md, or CLAUDE.md in projects.",
+    "  Teaches agents to use installed skills by default and resolve overlap by workflow priority.",
+    "",
+    "Supported agent homes:",
+    "  codex: CODEX_HOME, AGENTS_HOME, ~/.agents, or ~/.codex",
+    "  claude: CLAUDE_HOME or ~/.claude",
+    "  opencode: OPENCODE_HOME or ~/.config/opencode",
+    "  hermes: HERMES_HOME or ~/.hermes",
+    "",
+    "Examples:",
+    "  skillboard setup",
+    "  skillboard setup --yes",
+    "  skillboard setup --agent codex,claude,opencode,hermes --yes",
+    ""
+  ].join("\n");
+}
+
+function importSkillHelpText() {
+  return [
+    "Usage: skillboard import-skill --from <agent> --to <agent> --skill <id-or-dir> [--target-skill <id-or-dir>] [--adapted-file <path>] [--dry-run] [--yes] [--replace] [--json]",
+    "",
+    "Copies a user skill from one agent skill root into another agent skill root.",
+    "This is an agent-layer operation. It does not initialize, attach, or modify a project.",
+    "",
+    "Supported agents:",
+    "  codex: CODEX_HOME, AGENTS_HOME, ~/.agents, or ~/.codex",
+    "  claude: CLAUDE_HOME or ~/.claude",
+    "  opencode: OPENCODE_HOME or ~/.config/opencode",
+    "  hermes: HERMES_HOME or ~/.hermes",
+    "",
+    "AI use:",
+    "  Run this when a user asks to reuse a skill from another agent.",
+    "  If the source looks compatible, rerun with --yes to install it as-is.",
+    "  If the result status is needs-adaptation, explain the reasons and ask before changing the skill for the target agent.",
+    "  After user approval, write the adapted SKILL.md body yourself and pass it with --adapted-file <path> --yes.",
+    "",
+    "Examples:",
+    "  skillboard import-skill --from codex --to opencode --skill test-first --json",
+    "  skillboard import-skill --from codex --to opencode --skill codex-hook --target-skill opencode-hook --adapted-file /tmp/opencode-hook.SKILL.md --yes --json",
+    ""
+  ].join("\n");
+}
+
 function uninstallHelpText() {
   return [
     "Usage: skillboard uninstall [--dir <path>] [--dry-run] [--purge] [--remove-config|--reset-config] [--remove-reports] [--remove-hooks] [--keep-empty-dirs]",

package/src/control/skill-crud.mjs

@@ -1,3 +1,4 @@
+// allow: SIZE_OK - control command split is deferred from the 0.2.7 release gate.
 import {
   EXPOSURE_VALUES,
   INVOCATION_VALUES,

package/src/doctor.mjs

@@ -45,7 +45,7 @@ export async function doctorProject(options = {}) {
   };
 
   if (!configExists) {
-    return finalizeDoctor(base, ["run skillboard init"]);
+    return finalizeDoctor(base, ["run skillboard setup once per user/agent install if agents should use SkillBoard for skill priority"]);
   }
 
   let workspace;