agent-skillboard 0.2.18 → 0.3.1

package/src/agent-inventory-platforms.mjs

@@ -1,20 +1,29 @@
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { agentSkillRootCandidates } from "./agent-skill-roots.mjs";
+import { activeAgentSkillRootCandidates } from "./agent-skill-roots.mjs";
 
-export async function defaultScanRoots(home, env) {
+export async function defaultScanRoots(home, env, options = {}) {
   const codexHome = env.CODEX_HOME ?? join(home, ".codex");
   const agentRoots = await Promise.all([
-    agentSkillRootCandidates("codex", home, env),
-    agentSkillRootCandidates("claude", home, env),
-    agentSkillRootCandidates("hermes", home, env)
+    activeAgentSkillRootCandidates("codex", home, env, options),
+    activeAgentSkillRootCandidates("claude", home, env, options),
+    activeAgentSkillRootCandidates("opencode", home, env, options),
+    activeAgentSkillRootCandidates("hermes", home, env, options)
   ]);
   return [
-    join(codexHome, "skills", ".system"),
-    join(codexHome, "plugins", "cache"),
-    ...agentRoots.flat().map((root) => root.skillRoot)
+    { path: join(codexHome, "skills", ".system") },
+    { path: join(codexHome, "plugins", "cache") },
+    { path: join(home, ".agents", "shared-skills") },
+    ...agentRoots.flatMap((roots, index) => roots.map((root) => ({
+      path: root.skillRoot,
+      agent: ["codex", "claude", "opencode", "hermes"][index]
+    })))
   ];
 }
 
+export function sharedUserUnit(path, home) {
+  return userSkillUnit("shared.user-skills", path, home);
+}
+
 export function systemCodexUnit(path, home) {
   return {
     id: "codex.system-skills",
@@ -38,6 +47,10 @@ export function userClaudeUnit(path, home) {
   return userSkillUnit("claude.user-skills", path, home);
 }
 
+export function userOpenCodeUnit(path, home) {
+  return userSkillUnit("opencode.user-skills", path, home);
+}
+
 export function userHermesUnit(path, home) {
   return userSkillUnit("hermes.user-skills", path, home);
 }

package/src/agent-inventory.mjs

@@ -9,14 +9,25 @@ import {
   hermesProfileUnit,
   isHermesProfileSkillsPath,
   safeSegment,
+  sharedUserUnit,
   systemCodexUnit,
   userClaudeUnit,
   userCodexUnit,
-  userHermesUnit
+  userHermesUnit,
+  userOpenCodeUnit
 } from "./agent-inventory-platforms.mjs";
 import { readString, requireRecord } from "./config-helpers.mjs";
 
 export const agentInventoryDetectors = Object.freeze([
+  {
+    id: "shared-user-skills",
+    matches(path) {
+      return path.endsWith("/.agents/shared-skills") || path.endsWith("\\.agents\\shared-skills");
+    },
+    async discover(path, home) {
+      return await discoverSkillDirectory(path, sharedUserUnit(path, home), { excludeSystem: true });
+    }
+  },
   {
     id: "codex-plugin-cache",
     matches(path) {
@@ -56,6 +67,16 @@ export const agentInventoryDetectors = Object.freeze([
       return await discoverSkillDirectory(path, userClaudeUnit(path, home), { excludeSystem: true });
     }
   },
+  {
+    id: "opencode-user-skills",
+    matches(path) {
+      const normalized = path.replace(/\\/g, "/");
+      return normalized.endsWith("/.config/opencode/skills") || normalized.endsWith("/.opencode/skills");
+    },
+    async discover(path, home) {
+      return await discoverSkillDirectory(path, userOpenCodeUnit(path, home), { excludeSystem: true });
+    }
+  },
   {
     id: "hermes-user-skills",
     matches(path) {
@@ -89,16 +110,16 @@ export async function discoverAgentSkillInventory(options = {}) {
   const env = options.env ?? process.env;
   const home = options.home ?? env.HOME ?? env.USERPROFILE ?? homedir();
   const detectors = options.detectors ?? agentInventoryDetectors;
-  const roots = uniquePaths([
-    ...(await defaultScanRoots(home, env)),
-    ...readCsv(env.SKILLBOARD_INIT_SCAN_ROOTS),
-    ...(options.roots ?? [])
+  const roots = uniqueRootEntries([
+    ...(await defaultScanRoots(home, env, { registeredRoots: options.registeredRoots })),
+    ...readCsv(env.SKILLBOARD_INIT_SCAN_ROOTS).map((path) => ({ path })),
+    ...(options.roots ?? []).map((path) => ({ path }))
   ], home);
   const groups = [];
   const warnings = [];
 
   for (const root of roots) {
-    const discovered = await discoverRoot(root, home, detectors);
+    const discovered = await discoverRoot(root.path, home, detectors, root.agent);
     groups.push(...discovered.groups);
     warnings.push(...discovered.warnings);
   }
@@ -272,13 +293,13 @@ function ensureLocalWorkflow(workflowsMap, target, skills, document) {
   return true;
 }
 
-async function discoverRoot(root, home, detectors) {
+async function discoverRoot(root, home, detectors, agent) {
   const path = resolvePath(root, home);
   if (!(await exists(path))) {
     return { groups: [], warnings: [] };
   }
   const warnings = [];
-  const detector = detectors.find((candidate) => {
+  const matched = detectors.find((candidate) => {
     try {
       return candidate.matches(path);
     } catch (error) {
@@ -286,6 +307,7 @@ async function discoverRoot(root, home, detectors) {
       return false;
     }
   });
+  const detector = agent === undefined ? matched : forcedAgentDetector(agent, matched, detectors);
   if (detector === undefined) {
     return { groups: [], warnings };
   }
@@ -298,6 +320,12 @@ async function discoverRoot(root, home, detectors) {
   }
 }
 
+function forcedAgentDetector(agent, matched, detectors) {
+  if (matched?.id === "hermes-profile-skills" && agent === "hermes") return matched;
+  const id = `${agent}-user-skills`;
+  return detectors.find((candidate) => candidate.id === id) ?? matched;
+}
+
 async function discoverSkillDirectory(root, unit, options) {
   const files = await findSkillFiles(root, root, options);
   return files.length === 0 ? [] : [{ unit, root, files }];
@@ -416,6 +444,7 @@ async function inventoryFromGroups(groups, home, initialWarnings = []) {
       const skill = {
         id,
         path: sourceAlias.path,
+        skillFile: resolve(file),
         status: "quarantined",
         invocation: "blocked",
         exposure: "exported",
@@ -876,21 +905,20 @@ function uniqueStrings(values) {
   return [...new Set(values.filter((value) => value.trim().length > 0))];
 }
 
-function uniquePaths(values, home) {
-  const seen = new Set();
-  const result = [];
+function uniqueRootEntries(values, home) {
+  const byPath = new Map();
   for (const value of values) {
-    const trimmed = value.trim();
+    const trimmed = value.path.trim();
     if (trimmed.length === 0) {
       continue;
     }
     const key = resolve(trimmed.startsWith("~/") ? join(home, trimmed.slice(2)) : trimmed);
-    if (!seen.has(key)) {
-      seen.add(key);
-      result.push(trimmed);
+    const existing = byPath.get(key);
+    if (existing === undefined || existing.agent === undefined && value.agent !== undefined) {
+      byPath.set(key, { path: trimmed, ...(value.agent === undefined ? {} : { agent: value.agent }) });
     }
   }
-  return result;
+  return [...byPath.values()];
 }
 
 function errorMessage(error) {

package/src/agent-root-registry.mjs

@@ -0,0 +1,127 @@
+import { lstat, readFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { atomicWrite } from "./migration/v2-files.mjs";
+
+const FORMAT_VERSION = 1;
+const SUPPORTED_AGENTS = new Set(["codex", "claude", "opencode", "hermes"]);
+
+export function agentRootRegistryPath(home) {
+  return join(resolve(home), ".skillboard", "agent-roots.json");
+}
+
+export async function loadRegisteredAgentRoots(home) {
+  const root = resolve(home);
+  const path = agentRootRegistryPath(root);
+  const stats = await lstat(path).catch(missingOnly);
+  if (stats === undefined) return [];
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    throw new Error("Agent root registry must be a regular file, not a symbolic link.");
+  }
+  const value = JSON.parse(await readFile(path, "utf8"));
+  if (value?.format_version !== FORMAT_VERSION || !Array.isArray(value.roots)) {
+    throw new Error("Invalid agent root registry format.");
+  }
+  const entries = normalizeEntries(value.roots, root);
+  for (const entry of entries) await assertSafeRootPath(root, entry.path);
+  return entries;
+}
+
+export async function proposedAgentRoot(home, agent, path, cwd = process.cwd()) {
+  assertAgent(agent);
+  const root = resolve(home);
+  const target = resolve(cwd, path);
+  const rel = relative(root, target);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+    throw new Error("Registered skill root must remain inside the invoking user's home.");
+  }
+  await assertSafeRootPath(root, target);
+  return { agent, path: target };
+}
+
+export async function writeRegisteredAgentRoots(home, entries) {
+  const root = resolve(home);
+  const normalized = normalizeEntries(entries.map((entry) => ({
+    agent: entry.agent,
+    path: portablePath(root, entry.path)
+  })), root);
+  const value = {
+    format_version: FORMAT_VERSION,
+    roots: normalized.map((entry) => ({ agent: entry.agent, path: portablePath(root, entry.path) }))
+  };
+  await atomicWrite(agentRootRegistryPath(root), Buffer.from(`${JSON.stringify(value, null, 2)}\n`));
+  return normalized;
+}
+
+export function mergeRegisteredAgentRoots(entries, proposed) {
+  const byKey = new Map();
+  const agentByPath = new Map();
+  for (const entry of proposed === undefined ? entries : [...entries, proposed]) {
+    assertAgent(entry.agent);
+    const path = resolve(entry.path);
+    const registeredAgent = agentByPath.get(path);
+    if (registeredAgent !== undefined && registeredAgent !== entry.agent) {
+      throw new Error(`Custom skill root is already registered for agent ${registeredAgent}: ${path}`);
+    }
+    agentByPath.set(path, entry.agent);
+    byKey.set(`${entry.agent}\0${path}`, { agent: entry.agent, path });
+  }
+  return [...byKey.values()].sort(compareEntries);
+}
+
+function normalizeEntries(entries, home) {
+  if (!entries.every((entry) => entry !== null && typeof entry === "object")) {
+    throw new Error("Invalid agent root registry entry.");
+  }
+  return mergeRegisteredAgentRoots(entries.map((entry) => {
+    assertAgent(entry.agent);
+    if (typeof entry.path !== "string" || entry.path.trim() === "") {
+      throw new Error("Registered skill root path must be a non-empty string.");
+    }
+    const path = isAbsolute(entry.path) ? resolve(entry.path) : resolve(home, entry.path);
+    const rel = relative(home, path);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+      throw new Error("Registered skill root must remain inside the invoking user's home.");
+    }
+    return { agent: entry.agent, path };
+  }));
+}
+
+function portablePath(home, path) {
+  return relative(home, resolve(path)).split("\\").join("/");
+}
+
+function assertAgent(agent) {
+  if (!SUPPORTED_AGENTS.has(agent)) {
+    throw new Error(`Unsupported setup agent: ${String(agent)}`);
+  }
+}
+
+function compareEntries(left, right) {
+  return `${left.agent}\0${left.path}`.localeCompare(`${right.agent}\0${right.path}`);
+}
+
+async function assertSafeRootPath(home, target) {
+  const components = [];
+  let current = resolve(target);
+  while (current !== home) {
+    components.push(current);
+    const parent = resolve(current, "..");
+    if (parent === current) break;
+    current = parent;
+  }
+  for (const component of components.reverse()) {
+    const stats = await lstat(component).catch(missingOnly);
+    if (stats === undefined) continue;
+    if (stats.isSymbolicLink()) {
+      throw new Error("Registered skill root must not traverse a symbolic link.");
+    }
+    if (!stats.isDirectory()) {
+      throw new Error("Registered skill root components must be directories.");
+    }
+  }
+}
+
+function missingOnly(error) {
+  if (error?.code === "ENOENT") return undefined;
+  throw error;
+}

package/src/agent-skill-import.mjs

@@ -157,7 +157,7 @@ async function findSourceSkill(options) {
   throw new Error(`Source skill not found: ${options.skill} under ${root}`);
 }
 
-async function findSourceSkillInRoots(options) {
+export async function findSourceSkillInRoots(options) {
   const misses = [];
   for (const root of options.roots) {
     try {
@@ -200,7 +200,7 @@ function parseSkillFrontmatter(text) {
   return parsed !== null && typeof parsed === "object" ? parsed : {};
 }
 
-function analyzeAgentCompatibility(content, options) {
+export function analyzeAgentCompatibility(content, options) {
   const reasons = [];
   for (const [agent, markers] of Object.entries(AGENT_MARKERS)) {
     if (agent === options.targetAgent) {

package/src/agent-skill-roots.mjs

@@ -1,6 +1,7 @@
-import { access, readdir } from "node:fs/promises";
+import { access, readdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { loadRegisteredAgentRoots } from "./agent-root-registry.mjs";
 
 const SUPPORTED_AGENTS = Object.freeze(["codex", "claude", "opencode", "hermes"]);
 
@@ -9,11 +10,12 @@ export function supportedAgentNames() {
 }
 
 export async function detectedAgentSkillRoots(agent, home = homedir(), env = process.env, options = {}) {
-  const candidates = await agentSkillRootCandidates(agent, home, env);
+  const candidates = await activeAgentSkillRootCandidates(agent, home, env, options);
   const detected = [];
   for (const candidate of candidates) {
     if (
       candidate.explicit
+      || candidate.registered
       || await exists(candidate.skillRoot)
       || candidate.detectWhenExists !== undefined && await exists(candidate.detectWhenExists)
     ) {
@@ -27,7 +29,7 @@ export async function detectedAgentSkillRoots(agent, home = homedir(), env = pro
 }
 
 export async function setupAgentSkillTargets(agent, home = homedir(), env = process.env, options = {}) {
-  const roots = await detectedAgentSkillRoots(agent, home, env, { includeFallback: options.includeFallback === true });
+  const roots = await detectedAgentSkillRoots(agent, home, env, options);
   return roots.map((root) => ({
     agent,
     home: resolve(home),
@@ -42,38 +44,61 @@ export async function preferredAgentSkillRoot(agent, home = homedir(), env = pro
   return root.skillRoot;
 }
 
-export async function agentSkillRootCandidates(agent, home = homedir(), env = process.env) {
+export async function activeAgentSkillRootCandidates(agent, home = homedir(), env = process.env, options = {}) {
+  const candidates = await agentSkillRootCandidates(agent, home, env, options);
+  const hasRegistered = candidates.some((entry) => entry.registered);
+  const hasExplicit = candidates.some((entry) => entry.explicit);
+  if (!hasRegistered && !hasExplicit) return candidates;
+  const active = await Promise.all(candidates.map(async (entry) => ({
+    entry,
+    keep: entry.registered
+      || entry.explicit
+      || entry.profile
+      || entry.sharedCodex
+      || await hasAgentOwnedSkillContent(entry.skillRoot)
+  })));
+  return active.filter(({ keep }) => keep).map(({ entry }) => entry);
+}
+
+export async function agentSkillRootCandidates(agent, home = homedir(), env = process.env, options = {}) {
   const normalized = normalizeAgent(agent);
   const xdgConfig = env.XDG_CONFIG_HOME ?? join(home, ".config");
+  const registered = (options.registeredRoots ?? await loadRegisteredAgentRoots(home))
+    .filter((entry) => entry.agent === normalized)
+    .map((entry) => candidate(entry.path, "registered custom skill root", false, false, undefined, { registered: true }));
   if (normalized === "codex") {
     const agentsHome = join(home, ".agents");
     return uniqueCandidates([
+      ...registered,
       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(agentsHome, "skills"), "~/.agents/skills", false, false, agentsHome),
-      candidate(join(home, ".codex", "skills"), "~/.codex/skills", false, true)
+      candidate(join(agentsHome, "skills"), "~/.agents/skills", false, false, agentsHome, { sharedCodex: true }),
+      candidate(join(home, ".codex", "skills"), "~/.codex/skills", false, true, join(home, ".codex"))
     ]);
   }
   if (normalized === "claude") {
     return uniqueCandidates([
+      ...registered,
       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(home, ".claude", "skills"), "~/.claude/skills", false, true, join(home, ".claude")),
       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([
+      ...registered,
       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(xdgConfig, "opencode", "skills"), "XDG opencode skills", false, xdgConfig !== join(home, ".config"), join(xdgConfig, "opencode")),
+      candidate(join(home, ".config", "opencode", "skills"), "~/.config/opencode/skills", false, true, join(home, ".config", "opencode")),
       candidate(join(home, ".opencode", "skills"), "~/.opencode/skills", false, false)
     ]);
   }
   const hermesHome = env.HERMES_HOME ?? join(home, ".hermes");
   return uniqueCandidates([
+    ...registered,
     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),
+    candidate(join(home, ".hermes", "skills"), "~/.hermes/skills", false, true, join(home, ".hermes")),
     ...(await hermesProfileCandidates(hermesHome))
   ]);
 }
@@ -85,8 +110,8 @@ function normalizeAgent(agent) {
   return agent;
 }
 
-function candidate(skillRoot, source, explicit, fallback, detectWhenExists) {
-  return { skillRoot, source, explicit, fallback, detectWhenExists };
+function candidate(skillRoot, source, explicit, fallback, detectWhenExists, metadata = {}) {
+  return { skillRoot, source, explicit, fallback, detectWhenExists, ...metadata };
 }
 
 function fallbackCandidate(candidates) {
@@ -112,9 +137,41 @@ async function hermesProfileCandidates(hermesHome) {
   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));
+    .map((entry) => candidate(
+      join(profilesRoot, entry.name, "skills"),
+      `Hermes profile ${entry.name}`,
+      false,
+      false,
+      join(profilesRoot, entry.name),
+      { profile: true }
+    ));
 }
 
 async function exists(path) {
   return access(path).then(() => true, () => false);
 }
+
+async function hasAgentOwnedSkillContent(skillRoot) {
+  const entries = await readdir(skillRoot, { withFileTypes: true }).catch((error) => {
+    if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return [];
+    throw error;
+  });
+  for (const entry of entries) {
+    if (entry.name === "skillboard" || entry.name === ".system") continue;
+    if (!entry.isDirectory()) return true;
+    const metadata = await readFile(join(skillRoot, entry.name, ".skillboard-share.json"), "utf8")
+      .then((text) => {
+        try {
+          return JSON.parse(text);
+        } catch {
+          return null;
+        }
+      }, (error) => {
+        if (error?.code === "ENOENT") return null;
+        throw error;
+      });
+    if (metadata?.version === 1 && metadata.managed_by === "skillboard") continue;
+    return true;
+  }
+  return false;
+}

package/src/audit-paths.mjs

@@ -0,0 +1,42 @@
+import { homedir } from "node:os";
+import { basename, isAbsolute, relative, resolve } from "node:path";
+
+export function expandPortablePath(value, paths) {
+  if (value === "${PROJECT}") return paths.rootDir;
+  if (value.startsWith("${PROJECT}/")) return resolve(paths.rootDir, value.slice("${PROJECT}/".length));
+  if (value === "${HOME}") return homedir();
+  if (value.startsWith("${HOME}/")) return resolve(homedir(), value.slice("${HOME}/".length));
+  if (value === "<external>" || value.startsWith("<external>/")) return null;
+  return value;
+}
+
+export function portableObservation(value, options) {
+  if (value.startsWith("${PROJECT}") || value.startsWith("${HOME}") || value.startsWith("<external>")) return value;
+  if (value.startsWith("~/")) return `\${HOME}/${value.slice(2)}`;
+  return isAbsolute(value) ? auditPath(value, options) : value;
+}
+
+export function auditPath(path, options) {
+  const project = relative(options.rootDir, path);
+  if (!project.startsWith("..") && !isAbsolute(project)) {
+    return project === "" ? "${PROJECT}" : `\${PROJECT}/${project.replace(/\\/g, "/")}`;
+  }
+  const home = relative(homedir(), path);
+  if (!home.startsWith("..") && !isAbsolute(home)) {
+    return home === "" ? "${HOME}" : `\${HOME}/${home.replace(/\\/g, "/")}`;
+  }
+  return `<external>/${basename(path)}`;
+}
+
+export function redactPathError(error, options) {
+  const message = error instanceof Error ? error.message : String(error);
+  return replaceText(
+    replaceText(replaceText(message, options.rootDir, "${PROJECT}"), options.configDir, "${PROJECT}"),
+    homedir(),
+    "${HOME}"
+  );
+}
+
+function replaceText(value, search, replacement) {
+  return value.split(search).join(replacement);
+}

package/src/brief-cli.mjs

@@ -5,11 +5,12 @@ import { renderSkillBrief } from "./brief-renderer.mjs";
 export async function runBriefCommand(options, stdout, paths) {
   const json = options.get("json") === "true";
   const result = await buildSkillBrief({
-    root: briefRoot(options),
+    root: briefRoot(options) ?? dirname(paths.configPath),
     configPath: paths.configPath,
     skillsRoot: paths.skillsRoot,
     workflow: options.get("workflow"),
     intent: options.get("intent"),
+    agent: options.get("agent"),
     includeActions: options.get("include-actions") === "true" || !json
   });
   writeBriefOutput(stdout, result, options);
@@ -22,7 +23,7 @@ function briefRoot(options) {
     return dir;
   }
   const config = options.get("config");
-  return config !== undefined && isAbsolute(config) ? dirname(config) : ".";
+  return config !== undefined && isAbsolute(config) ? dirname(config) : undefined;
 }
 
 function briefExitCode(result) {

package/src/brief-renderer.mjs

@@ -47,6 +47,7 @@ export function renderSkillBrief(brief, options = {}) {
     `Workflow: ${workflowSummary(brief.workflow)}`,
     ""
   ];
+  if (brief.compatibility?.notice !== undefined) lines.push(brief.compatibility.notice, "");
   if (brief.error !== undefined) {
     lines.push(`Error: ${safeText(brief.error.message)}`, "");
   }