agent-skillboard 0.2.17 → 0.3.0

package/src/advisor.mjs

@@ -4,7 +4,7 @@ import {
 } from "./control.mjs";
 import { doctorProject } from "./doctor.mjs";
 import { routeSkill } from "./route.mjs";
-import { buildActionCards, buildInitActions } from "./advisor/actions.mjs";
+import { buildActionCards, buildInitActions, buildV2ActionCards } from "./advisor/actions.mjs";
 import {
   buildBrief,
   buildCleanup,
@@ -25,14 +25,14 @@ import { loadWorkspace } from "./workspace.mjs";
 
 export async function buildSkillBrief(options = {}) {
   const paths = resolveProjectPaths(options);
-  const cleanup = await buildCleanup(paths.root);
   const configDoctor = await doctorProject({
     root: paths.root,
     configPath: paths.configPath,
     skillsRoot: paths.skillsRoot
   });
 
-  if (!configDoctor.config.exists || !configDoctor.initialized) {
+  if (!configDoctor.config.exists) {
+    const cleanup = userStateCleanup();
     return buildBrief({
       ok: false,
       error: {
@@ -50,6 +50,7 @@ export async function buildSkillBrief(options = {}) {
   }
 
   if (!configDoctor.config.valid) {
+    const cleanup = userStateCleanup();
     return buildExpectedConfigError(configDoctor, paths, cleanup, {
       code: "invalid-config",
       message: configDoctor.config.error ?? "skillboard.config.yaml is invalid"
@@ -60,12 +61,15 @@ export async function buildSkillBrief(options = {}) {
   try {
     workspace = await loadWorkspace({ configPath: paths.configPath, skillsRoot: paths.skillsRoot });
   } catch (error) {
+    const cleanup = userStateCleanup();
     return buildExpectedConfigError(configDoctor, paths, cleanup, {
       code: "invalid-config",
       message: error instanceof Error ? error.message : String(error)
     }, options);
   }
 
+  const cleanup = workspace.version === 2 ? userStateCleanup() : await buildCleanup(paths.root);
+
   const doctor = await doctorProject({
     root: paths.root,
     configPath: paths.configPath,
@@ -74,13 +78,16 @@ export async function buildSkillBrief(options = {}) {
     verifySources: options.verifySources
   });
   const sourceAudit = auditSources(workspace);
-  const workflow = resolveWorkflow(listWorkflows(workspace), options.workflow);
-  const reviewQueue = buildReviewQueue(workspace, sourceAudit);
+  const workflow = workspace.version === 2
+    ? emptyWorkflowState()
+    : resolveWorkflow(listWorkflows(workspace), options.workflow);
+  const reviewQueue = workspace.version === 2 ? [] : buildReviewQueue(workspace, sourceAudit);
 
   if (workflow.unknown) {
     const skills = skillsWithoutWorkflow(workspace);
     const actionData = actionsForBrief({ options, paths, workflow, skills, reviewQueue, cleanup, workspace });
     return buildBrief({
+      compatibility: workspace.compatibility,
       ok: false,
       error: {
         code: "unknown-workflow",
@@ -96,11 +103,13 @@ export async function buildSkillBrief(options = {}) {
     });
   }
 
-  const skills = skillsForWorkflow(workspace, workflow.selected, sourceAudit);
+  const skills = skillsForWorkflow(workspace, workflow.selected, sourceAudit, options.agent);
   const actionData = actionsForBrief({ options, paths, workflow, skills, reviewQueue, cleanup, workspace });
   const route = routeForBrief({ options, paths, workflow, workspace });
-  const availabilityOk = doctor.config.valid && doctor.policy.ok && doctor.sources.ok;
+  const availabilityOk = doctor.config.valid && doctor.policy.ok && doctor.inventory.ok
+    && (workspace.version === 2 || doctor.sources.ok);
   return buildBrief({
+    compatibility: workspace.compatibility,
     ok: availabilityOk,
     health: healthForBrief(doctor, paths, availabilityOk),
     workflow,
@@ -113,14 +122,22 @@ export async function buildSkillBrief(options = {}) {
   });
 }
 
+function userStateCleanup() {
+  return {
+    conservative: { dryRun: true, removed: [], updated: [], preserved: [] },
+    full_reset: { dryRun: true, removed: [], updated: [], preserved: [] }
+  };
+}
+
 function routeForBrief({ options, paths, workflow, workspace }) {
   const intent = options.intent?.trim();
-  if (intent === undefined || intent.length === 0 || workflow.selected === null || workflow.unknown || workflow.needs_selection) {
+  const workflowRequired = workspace.version !== 2 && workflow.selected === null;
+  if (intent === undefined || intent.length === 0 || workflowRequired || workflow.unknown || workflow.needs_selection) {
     return undefined;
   }
   return routeSkill(workspace, {
     intent,
-    workflow: workflow.selected,
+    ...(workspace.version === 2 ? { agent: options.agent } : workflow.selected === null ? {} : { workflow: workflow.selected }),
     configPath: paths.configPath,
     skillsRoot: paths.skillsRoot
   });
@@ -155,6 +172,7 @@ function actionsForBrief(context) {
   if (!requestedActions(context.options)) {
     return { reviewQueue: context.reviewQueue, actions: undefined };
   }
+  if (context.workspace.version === 2) return { reviewQueue: [], actions: buildV2ActionCards(context) };
   return buildActionCards(context);
 }
 

package/src/agent-integration-cli.mjs

@@ -1,8 +1,10 @@
 import { isAbsolute, relative, resolve } from "node:path";
+import { mkdir } from "node:fs/promises";
 import { createInterface } from "node:readline";
 import { installAgentIntegration, uninstallAgentIntegration } from "./agent-integration-files.mjs";
-import { resolveSetupHome, setupOwnership } from "./agent-integration-home.mjs";
+import { applyOwnership, resolveSetupHome, setupOwnership } from "./agent-integration-home.mjs";
 import { setupAgentSkillTargets, supportedAgentNames } from "./agent-skill-roots.mjs";
+import { refreshAgentInventory } from "./inventory-refresh.mjs";
 
 export async function runSetupCommand(options, stdout, runtime = defaultRuntime()) {
   if (options.get("dir") !== undefined) {
@@ -27,15 +29,22 @@ export async function runSetupCommand(options, stdout, runtime = defaultRuntime(
       return 1;
     }
   }
-  const result = await installAgentIntegration(targets, setupOwnership(env, runtime, home));
+  const ownership = setupOwnership(env, runtime, home);
+  const result = await installAgentIntegration(targets, ownership);
+  await mkdir(home, { recursive: true });
+  const inventory = await refreshAgentInventory({ root: home, home, env });
+  await applyOwnership(resolve(home, inventory.configPath), ownership);
+  if (inventory.inventoryPath !== null) await applyOwnership(resolve(home, inventory.inventoryPath), ownership);
   stdout.write("SkillBoard agent integration installed.\n");
   writeList(stdout, "Created", result.created);
   writeList(stdout, "Updated", result.updated);
   writeList(stdout, "Unchanged", result.unchanged);
   writeList(stdout, "Preserved", result.preserved);
+  stdout.write(`User policy: ${inventory.configPath}\n`);
+  stdout.write(`Observed skills: ${inventory.scan.scannedSkills}\n`);
   stdout.write("Next:\n");
   stdout.write("- Restart or refresh agents that cache user skills.\n");
-  stdout.write("- No project was initialized; run skillboard init only inside a workspace that needs local SkillBoard policy.\n");
+  stdout.write("- User-level policy and inventory were refreshed; no project was initialized.\n");
   stdout.write('- Ask the agent in a workspace: "Review this plan and point out weak assumptions."\n');
   stdout.write("- SkillBoard will step in when skills overlap, routing is ambiguous, or you ask for a skill decision.\n");
   return 0;
@@ -76,7 +85,7 @@ function writeList(stdout, label, values) {
 function writeSetupConfirmation(stdout, targets, command) {
   stdout.write("SkillBoard setup installs agent-layer integration, not project files.\n");
   stdout.write("It writes a SkillBoard guidance skill into detected user agent skill roots so agents can resolve skill priority when choices overlap.\n");
-  stdout.write("It does not create skillboard.config.yaml or .skillboard/; run skillboard init later only for a project that needs local policy.\n");
+  stdout.write("It creates ~/skillboard.config.yaml and ~/.skillboard/inventory.json as one user-level control plane; skillboard init is not needed for normal use.\n");
   stdout.write("Targets:\n");
   for (const target of targets) {
     stdout.write(`- ${target.agent}: ${target.skillPath}\n`);

package/src/agent-integration-content.mjs

@@ -1,10 +1,10 @@
 export const AGENT_INTEGRATION_START = "<!-- BEGIN SKILLBOARD AGENT INTEGRATION -->";
 export const AGENT_INTEGRATION_END = "<!-- END SKILLBOARD AGENT INTEGRATION -->";
 
-export function agentIntegrationSkill() {
+export function agentIntegrationSkill(agent = "<current-agent>") {
   return `---
 name: skillboard
-description: Use SkillBoard when several installed skills could apply, a skill choice is ambiguous, workflow priority matters, or the user explicitly asks which skill should be used, imported, preferred, avoided, reviewed, or prioritized.
+description: Use SkillBoard when several installed skills could apply, a skill choice is ambiguous, or the user explicitly asks which skill should be used, shared, imported, preferred, avoided, or prioritized.
 ---
 ${AGENT_INTEGRATION_START}
 # SkillBoard Agent Integration
@@ -13,21 +13,24 @@ Use this skill to let SkillBoard guide skill selection above individual projects
 
 ## Layering
 
-- SkillBoard is the user-level control plane for skill priority, overlap resolution, and workflow-aware routing.
+- SkillBoard is the user-level control plane for skill priority, overlap resolution, and opt-in cross-agent sharing.
 - Project management belongs to the agent or workspace layer. Do not initialize, attach, rewrite, or manage a project just because SkillBoard is installed.
-- Package install and \`skillboard setup\` install user-agent guidance only.
-- \`skillboard init\` is a separate project command. Use it only when the user wants project-local policy files such as \`skillboard.config.yaml\`, \`.skillboard/\`, \`AGENTS.md\`, or \`CLAUDE.md\`.
+- Package install and \`skillboard setup\` refresh user-agent guidance plus the home policy and inventory.
+- \`skillboard init\` is deprecated project-local policy bootstrap. It is not needed for normal use; use it only when maintaining an existing workspace that intentionally keeps local policy files such as \`skillboard.config.yaml\`, \`.skillboard/\`, \`AGENTS.md\`, or \`CLAUDE.md\`.
 
 ## Default Behavior
 
-- Installed user skills are usable by default unless the runtime, user, or local instructions disable them.
-- For ordinary user requests, work normally; invoke SkillBoard only when skill choice is ambiguous, skills overlap, workflow priority matters, or the user asks for a SkillBoard or skill decision.
+- Installed skills stay agent-local by default. Only a skill the user explicitly shares is promoted across supported agents.
+- This integration is running for agent \`${agent}\`; pass \`--agent ${agent}\` to brief, route, can-use, and guard.
+- For ordinary user requests, work normally; invoke SkillBoard only when skill choice is ambiguous, skills overlap, or the user asks for a SkillBoard or skill decision.
 - If the user explicitly asks for a specific installed skill, honor that request when the guard allows it instead of rerouting away solely because other skills also match.
 - Do not ask for permission merely because you selected a skill.
 - When you use a skill, disclose it briefly at the start and completion. If SkillBoard says remembered or configured policy selected this skill while other allowed skills were available, mention that at completion.
 
 ## Cross-Agent Skill Reuse
 
+- When the user wants one installed skill available to all supported agents, confirm that persistent policy change once and run \`skillboard skill share <skill> --json\`.
+- To stop SkillBoard-managed propagation, confirm once and run \`skillboard skill unshare <skill> --json\`. This preserves agent-owned originals and removes only SkillBoard-managed copies.
 - When the user wants to use a skill from another agent, run \`skillboard import-skill --from <source-agent> --to <this-agent> --skill <skill> --json\`.
 - If SkillBoard reports the skill is compatible, install it with \`--yes\` and use the copied target-agent skill.
 - If SkillBoard reports \`needs-adaptation\`, explain the compatibility reasons and ask before changing the skill body for this agent.
@@ -37,11 +40,18 @@ Use this skill to let SkillBoard guide skill selection above individual projects
 ## Ambiguity Resolution
 
 1. Start from the user's task, not from a pre-task inventory prompt.
-2. Identify candidate skills only when multiple installed skills plausibly match, a manual skill-control request is present, or workflow priority could change the route.
-3. Prefer the skill whose explicit request, description, workflow guidance, and local instructions most directly match the user's task.
-4. If a project or agent has explicit SkillBoard policy, use \`skillboard brief --intent <request> --json\` or \`skillboard route <intent> --workflow <name> --json\` to break ties.
-5. If the best choice is still ambiguous or the choice would change persistent policy, ask the user which priority to remember.
-6. Continue with the selected skill; do not stop only because other candidate skills exist.
+2. Identify candidate skills only when multiple installed skills plausibly match or a manual skill-control request is present.
+3. Prefer the skill whose explicit request, description, and local instructions most directly match the user's task.
+4. Use \`skillboard brief --agent ${agent} --intent <request> --json\` or \`skillboard route <intent> --agent ${agent} --json\` to break ties.
+5. Run \`skillboard guard use <skill-id> --agent ${agent} --json\` immediately before invoking the selected skill.
+6. If the best choice is still ambiguous or the choice would change persistent policy, ask the user which priority to remember.
+7. Continue with the selected skill; do not stop only because other candidate skills exist.
+
+## Removal
+
+- If an owning installer removed a skill and inventory refresh reports stale policy, confirm once before running \`skillboard skill forget <skill-id>\`. Forget never deletes skill files and refuses installed or shared skills.
+- When the user wants to remove SkillBoard itself, run \`skillboard uninstall --user --dry-run\`, show the managed cleanup plan, confirm once, then run \`skillboard uninstall --user --yes\`. Package removal comes afterward.
+- User cleanup preserves agent-owned and unmanaged skills while removing marker-owned shared copies, managed guidance, and SkillBoard home state.
 
 ${AGENT_INTEGRATION_END}
 `;

package/src/agent-integration-files.mjs

@@ -8,8 +8,8 @@ export async function installAgentIntegration(targets, ownership = null) {
   const updated = [];
   const unchanged = [];
   const preserved = [];
-  const content = agentIntegrationSkill();
   for (const target of targets) {
+    const content = agentIntegrationSkill(target.agent);
     if (!await isSafeManagedSkillTarget(target)) {
       preserved.push(`${target.agent}:${target.skillPath}`);
       continue;

package/src/agent-inventory-platforms.mjs

@@ -6,15 +6,21 @@ export async function defaultScanRoots(home, env) {
   const agentRoots = await Promise.all([
     agentSkillRootCandidates("codex", home, env),
     agentSkillRootCandidates("claude", home, env),
+    agentSkillRootCandidates("opencode", home, env),
     agentSkillRootCandidates("hermes", home, env)
   ]);
   return [
     join(codexHome, "skills", ".system"),
     join(codexHome, "plugins", "cache"),
+    join(home, ".agents", "shared-skills"),
     ...agentRoots.flat().map((root) => root.skillRoot)
   ];
 }
 
+export function sharedUserUnit(path, home) {
+  return userSkillUnit("shared.user-skills", path, home);
+}
+
 export function systemCodexUnit(path, home) {
   return {
     id: "codex.system-skills",
@@ -38,6 +44,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) {
@@ -416,6 +437,7 @@ async function inventoryFromGroups(groups, home, initialWarnings = []) {
       const skill = {
         id,
         path: sourceAlias.path,
+        skillFile: resolve(file),
         status: "quarantined",
         invocation: "blocked",
         exposure: "exported",

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/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)}`, "");
   }