agent-skillboard 0.2.18 → 0.3.1

package/src/advisor/guidance.mjs

@@ -1,9 +1,9 @@
 import { command } from "./action-core.mjs";
 
-const GUARD_WHEN = "before invoking a skill";
+const GUARD_WHEN = "immediately before skill use";
 const GOAL_DOCUMENT = Object.freeze({
   path: "docs/ai-skill-routing-goal.md",
-  purpose: "Preserve SkillBoard as a permissive AI skill routing layer: keep skills broadly available, resolve overlaps deterministically, explain briefly, ask after use when policy learning helps, and remember usage policy without rewriting skill bodies.",
+  purpose: "Preserve SkillBoard v2 as a user-level control plane: enable or disable a skill, opt individual skills into cross-agent sharing, and use optional preference only to rank available overlaps.",
   loop: Object.freeze([
     "observe",
     "route",
@@ -18,7 +18,7 @@ const GOAL_DOCUMENT = Object.freeze({
     "before changing brief output",
     "before changing bridge instructions",
     "before changing policy UX",
-    "before changing workflow UX"
+    "before changing sharing UX"
   ])
 });
 const GUARD_ALLOWED_USE = Object.freeze({
@@ -71,6 +71,9 @@ function guidanceStatus(brief) {
   if (brief.error?.code === "unknown-workflow" || brief.workflow?.unknown === true) {
     return "unknown-workflow";
   }
+  if (brief.health?.config?.version === 2 && brief.workflow?.selected === null && (brief.workflow?.candidates?.length ?? 0) === 0) {
+    return "ready";
+  }
   if (brief.workflow?.needs_selection === true || brief.workflow?.selected === null) {
     return "workflow-selection-needed";
   }
@@ -92,20 +95,20 @@ function hasInvalidConfig(brief) {
 }
 
 function summaryForStatus(status, brief) {
-  const readyCount = (brief.skills?.automatic_allowed?.length ?? 0) + (brief.skills?.manual_allowed?.length ?? 0);
+  const readyCount = availableSkillCount(brief);
   const decisionCount = guidanceDecisionCount(brief);
   const blockedCount = brief.skills?.blocked?.length ?? 0;
   switch (status) {
     case "ready":
-      return `SkillBoard is ready; ${readyCount} skills are available in this workflow.`;
+      return `SkillBoard is ready; ${readyCount} skills are available for the current agent.`;
     case "needs-decision":
-      return `SkillBoard needs ${decisionCount} user ${decisionWord(decisionCount)} before this workflow is fully ready.`;
+      return `SkillBoard needs ${decisionCount} user ${decisionWord(decisionCount)} before the requested policy change is applied.`;
     case "blocked":
       return `SkillBoard found blocking policy issues; ${blockedCount} skills are blocked for safety.`;
     case "not-initialized":
-      return "SkillBoard is not initialized in this project.";
+      return "SkillBoard user state has not been set up yet.";
     case "invalid-config":
-      return "SkillBoard cannot read the project configuration.";
+      return "SkillBoard cannot read the selected user policy configuration.";
     case "workflow-selection-needed":
       return "SkillBoard needs a workflow selection before applying action cards.";
     case "unknown-workflow":
@@ -115,6 +118,10 @@ function summaryForStatus(status, brief) {
   }
 }
 
+function availableSkillCount(brief) {
+  return (brief.skills?.automatic_allowed?.length ?? 0) + (brief.skills?.manual_allowed?.length ?? 0);
+}
+
 function guidanceDecisionCount(brief) {
   const skillDecisionCount = brief.skills?.needs_review?.length ?? 0;
   if (skillDecisionCount > 0) {
@@ -137,7 +144,9 @@ function recommendedNextStep(status, brief, choices, route = null) {
           ? "Ask a clarifying question; no workflow capability matched this request."
           : `Use ${route.recommended_skill} for this request after the guard check passes${postUsePolicyStep(route)}.`;
       }
-      return "Run the guard check before invoking any selected skill.";
+      return availableSkillCount(brief) === 0
+        ? "No policy change is required; valid installed skills default to enabled and agent-local."
+        : "Run the guard check immediately before using any selected skill.";
     case "needs-decision":
       if (route?.recommended_skill !== null && route?.guard_allowed === true) {
         return route.post_use_policy_suggestion === null
@@ -156,7 +165,7 @@ function recommendedNextStep(status, brief, choices, route = null) {
         : `Review the blocked item before applying: ${firstChoice.label}.`;
     case "not-initialized":
       return firstChoice === undefined
-        ? "Initialize SkillBoard before checking skill availability."
+        ? "Run SkillBoard setup before checking skill availability."
         : `Ask the user whether to approve: ${firstChoice.label}.`;
     case "invalid-config":
       return "Fix the SkillBoard configuration before checking skill availability.";
@@ -237,16 +246,15 @@ function confirmableAction(action) {
 }
 
 function guardCommandHint(brief) {
-  if (hasInvalidConfig(brief)) {
-    return null;
-  }
-  if (brief.workflow?.selected === null || brief.workflow?.unknown === true || brief.workflow?.needs_selection === true) {
+  if (hasInvalidConfig(brief) || brief.error?.code === "not-initialized" || availableSkillCount(brief) === 0) {
     return null;
   }
+  const version = brief.health?.config?.version;
+  if (version === 1 && (brief.workflow?.selected === null || brief.workflow?.unknown === true || brief.workflow?.needs_selection === true)) return null;
   return command([
     "skillboard", "guard", "use", "<skill-id>",
-    "--workflow", brief.workflow.selected,
+    ...(version === 1 ? ["--workflow", brief.workflow.selected] : []),
     "--config", brief.health.config_path,
-    "--skills", brief.health.skills_root
+    ...(brief.health.skills_root === undefined || brief.health.skills_root === null ? [] : ["--skills", brief.health.skills_root])
   ]).display;
 }

package/src/advisor/schema.mjs

@@ -1,4 +1,4 @@
-import { isAbsolute, resolve } from "node:path";
+import { dirname, isAbsolute, resolve } from "node:path";
 import { uninstallProject } from "../uninstall.mjs";
 import { buildAssistantGuidance } from "./guidance.mjs";
 import { sortedStrings } from "./sort.mjs";
@@ -18,6 +18,7 @@ export function buildBrief(data) {
     ok: data.ok,
     schema_version: SCHEMA_VERSION
   };
+  if (data.compatibility !== undefined && data.compatibility !== null) brief.compatibility = data.compatibility;
   if (data.error !== undefined) {
     brief.error = data.error;
   }
@@ -35,11 +36,12 @@ export function buildBrief(data) {
 }
 
 export function resolveProjectPaths(options) {
-  const root = resolve(options.root ?? ".");
+  const configPath = resolve(options.configPath ?? "skillboard.config.yaml");
+  const root = resolve(options.root ?? dirname(configPath));
   return {
     root,
-    configPath: resolveUnderRoot(root, options.configPath ?? "skillboard.config.yaml"),
-    skillsRoot: resolveUnderRoot(root, options.skillsRoot ?? "skills")
+    configPath: resolveUnderRoot(root, configPath),
+    skillsRoot: options.skillsRoot === undefined ? undefined : resolveUnderRoot(root, options.skillsRoot)
   };
 }
 
@@ -66,14 +68,14 @@ export async function buildCleanup(root) {
 }
 
 export function healthFromDoctor(doctor, paths) {
-  return {
+  const health = {
     mode: doctor.mode,
     review_required: doctor.reviewRequired,
     strict_ok: doctor.strictOk,
     initialized: doctor.initialized,
     root: paths.root,
     config_path: paths.configPath,
-    skills_root: paths.skillsRoot,
+    skills_root: paths.skillsRoot ?? null,
     config: {
       exists: doctor.config.exists,
       valid: doctor.config.valid,
@@ -86,6 +88,15 @@ export function healthFromDoctor(doctor, paths) {
       warnings: sortedStrings(doctor.policy.warnings)
     }
   };
+  if (doctor.inventory.required) {
+    health.inventory = {
+      required: true,
+      ok: doctor.inventory.ok,
+      path: doctor.inventory.path,
+      errors: sortedStrings(doctor.inventory.errors)
+    };
+  }
+  return health;
 }
 
 export function emptyWorkflowState() {

package/src/advisor/skills.mjs

@@ -12,8 +12,8 @@ export function skillsWithoutWorkflow(workspace) {
   return sortSkillGroups(groups);
 }
 
-export function skillsForWorkflow(workspace, workflowName, sourceAudit = { units: [] }) {
-  if (workflowName === null) {
+export function skillsForWorkflow(workspace, workflowName, sourceAudit = { units: [] }, agentName) {
+  if (workflowName === null && workspace.version !== 2) {
     const groups = emptySkillGroups();
     groups.installed_only = installedOnlyEntries(workspace);
     return sortSkillGroups(groups);
@@ -24,7 +24,7 @@ export function skillsForWorkflow(workspace, workflowName, sourceAudit = { units
   for (const summary of listSkills(workspace)) {
     const skill = workspace.skills.find((candidate) => candidate.id === summary.id);
     const explanation = explainSkill(workspace, summary.id);
-    const use = canUseSkill(workspace, summary.id, workflowName);
+    const use = canUseSkill(workspace, summary.id, workflowName, agentName);
     const group = groupForDeclaredSkill(workspace, skill, use, sourceFindings);
     const entry = declaredSkillEntry(summary, explanation, use, group);
     if (use.allowed) {
@@ -42,6 +42,16 @@ export function skillsForWorkflow(workspace, workflowName, sourceAudit = { units
 }
 
 function declaredSkillEntry(summary, explanation, use, group) {
+  if (summary.enabled !== undefined) {
+    return {
+      id: summary.id, label: summary.id, path: summary.path,
+      reason: reasonForGroup(group, use?.reasons ?? []),
+      advanced: {
+        enabled: summary.enabled, shared: summary.shared, installed_on: explanation.inventory?.installed_on ?? [], preference: summary.preference,
+        runtime_ready: !(use?.reasons ?? []).some((reason) => reason.includes("Inventory integrity error"))
+      }
+    };
+  }
   return {
     id: summary.id,
     label: summary.id,
@@ -79,8 +89,9 @@ function groupForDeclaredSkill(workspace, skill, use, sourceFindings) {
 
 function installedOnlyEntries(workspace) {
   const declaredPaths = new Set(workspace.skills.map((skill) => skill.path));
+  const declaredIds = new Set(workspace.skills.map((skill) => skill.id));
   return workspace.installedSkills
-    .filter((skill) => !declaredPaths.has(skill.path))
+    .filter((skill) => !declaredPaths.has(skill.path) && !declaredIds.has(skill.id))
     .map((skill) => ({
       id: skill.id,
       label: skill.name ?? skill.id,
@@ -151,7 +162,9 @@ function findingsBySource(sourceAudit) {
 }
 
 function isNotInWorkflowReason(reason) {
-  return reason.includes("is not active, preferred, or fallback in workflow");
+  return reason.includes("is not active, preferred, or fallback in workflow")
+    || reason.includes("is not available in workflow")
+    || reason.includes("requires workflow");
 }
 
 function isReviewReason(reason) {

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,16 +1,30 @@
 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, applyOwnershipTree, resolveSetupHome, setupOwnership } from "./agent-integration-home.mjs";
 import { setupAgentSkillTargets, supportedAgentNames } from "./agent-skill-roots.mjs";
+import {
+  agentRootRegistryPath,
+  loadRegisteredAgentRoots,
+  mergeRegisteredAgentRoots,
+  proposedAgentRoot,
+  writeRegisteredAgentRoots
+} from "./agent-root-registry.mjs";
+import { refreshAgentInventory } from "./inventory-refresh.mjs";
+import { reconcileSharedSkills } from "./shared-skill-reconcile.mjs";
 
 export async function runSetupCommand(options, stdout, runtime = defaultRuntime()) {
+  assertSetupOptions(options);
   if (options.get("dir") !== undefined) {
     throw new Error("skillboard setup is agent-layer setup and does not accept --dir");
   }
   const env = runtime.env ?? process.env;
   const home = await resolveSetupHome(env, runtime);
-  const targets = await agentSetupTargets(options, runtime, home);
+  const existingRoots = await loadRegisteredAgentRoots(home);
+  const proposedRoot = await setupSkillRoot(options, home, runtime.cwd ?? process.cwd());
+  const registeredRoots = mergeRegisteredAgentRoots(existingRoots, proposedRoot);
+  const targets = await agentSetupTargets(options, runtime, home, registeredRoots);
   if (targets.length === 0) {
     stdout.write("No supported agent user skill roots were detected.\n");
     stdout.write(`Create a supported agent home or pass --agent ${supportedAgentNames().join(",")} to choose targets.\n`);
@@ -27,15 +41,53 @@ 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 });
+  let inventory = await refreshAgentInventory({
+    root: home,
+    home,
+    env,
+    registeredRoots,
+    preserveLegacyPolicy: true
+  });
+  const configPath = resolve(home, inventory.configPath);
+  const inventoryPath = inventory.inventoryPath === null ? null : resolve(home, inventory.inventoryPath);
+  const shared = inventoryPath === null
+    ? { created: [], unchanged: [], preserved: [], blocked: [] }
+    : await reconcileSharedSkills({ home, env, targets, configPath, inventoryPath });
+  if (shared.created.length > 0) {
+    inventory = await refreshAgentInventory({ root: home, home, env, registeredRoots });
+  }
+  for (const entry of [...shared.created, ...shared.unchanged]) {
+    await applyOwnershipTree(entry.path, ownership);
+  }
+  if (proposedRoot !== undefined) {
+    await writeRegisteredAgentRoots(home, registeredRoots);
+    await applyOwnership(agentRootRegistryPath(home), ownership);
+  }
+  await applyOwnership(configPath, ownership);
+  if (inventoryPath !== null) await applyOwnership(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);
+  if (proposedRoot !== undefined) stdout.write(`Registered agent roots: ${registeredRoots.length}\n`);
+  if (shared.created.length > 0) stdout.write(`Created shared copies: ${shared.created.length}\n`);
+  if (shared.unchanged.length > 0) stdout.write(`Unchanged shared copies: ${shared.unchanged.length}\n`);
+  writeList(stdout, "Preserved shared copies", shared.preserved.map(formatSharedEntry));
+  writeList(stdout, "Blocked shared copies", shared.blocked.map(formatBlockedEntry));
+  stdout.write(`User policy: ${inventory.configPath}\n`);
+  stdout.write(`Observed skills: ${inventory.scan.scannedSkills}\n`);
+  if (inventory.inventoryPath === null) {
+    stdout.write("Policy version 1 remains read-only during SkillBoard v0.3.x.\n");
+    stdout.write(`Preview migration: ${commandPrefix(runtime)} migrate v2 --config ${shellQuote(configPath, runtime.platform)} --json\n`);
+  }
   stdout.write("Next:\n");
   stdout.write("- Restart or refresh agents that cache user skills.\n");
-  stdout.write("- No project was initialized; skillboard init is deprecated project-local policy bootstrap and is not needed for normal use.\n");
+  stdout.write("- Run skillboard doctor --summary to check policy and executable paths.\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 +128,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/; skillboard init is deprecated project-local policy bootstrap and is not needed for normal use.\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`);
@@ -127,7 +179,7 @@ function defaultRuntime() {
   };
 }
 
-async function agentSetupTargets(options, runtime, setupHome) {
+async function agentSetupTargets(options, runtime, setupHome, registeredRoots) {
   const env = runtime.env ?? process.env;
   const home = setupHome ?? await resolveSetupHome(env, runtime);
   const requested = readCsv(options.get("agent"));
@@ -138,20 +190,48 @@ async function agentSetupTargets(options, runtime, setupHome) {
     if (!supported.has(name)) {
       throw new Error(`Unsupported setup agent: ${name}`);
     }
-    targets.push(...await setupAgentSkillTargets(name, home, env, { includeFallback: requested.length > 0 }));
+    targets.push(...await setupAgentSkillTargets(name, home, env, {
+      includeFallback: requested.length > 0,
+      registeredRoots
+    }));
   }
   return targets;
 }
 
+async function setupSkillRoot(options, home, cwd) {
+  const skillRoot = options.get("skill-root");
+  if (skillRoot === undefined) return undefined;
+  const requested = readCsv(options.get("agent"));
+  if (requested.length !== 1) {
+    throw new Error("--skill-root requires exactly one --agent value.");
+  }
+  return await proposedAgentRoot(home, requested[0], skillRoot, cwd);
+}
+
+function assertSetupOptions(options) {
+  const allowed = new Set(["yes", "agent", "skill-root"]);
+  for (const option of options.keys()) {
+    if (!allowed.has(option)) throw new Error(`Unknown setup option: --${option}`);
+  }
+}
+
+function formatSharedEntry(entry) {
+  return `${entry.agent}:${entry.skill}:${entry.path}`;
+}
+
+function formatBlockedEntry(entry) {
+  return `${entry.agent ?? "unknown"}:${entry.skill}:${entry.reason}`;
+}
+
 function commandPrefix(runtime) {
   const entrypoint = runtime.entrypointPath ?? "";
   const normalized = entrypoint.replace(/\\/g, "/");
   if (normalized.includes("/_npx/")) {
     const packageSpec = runtime.packageSpec ?? "agent-skillboard";
-    return `npx --yes --package ${shellQuote(packageSpec)} skillboard`;
+    return `npx --yes --package ${shellQuote(packageSpec, runtime.platform)} skillboard`;
   }
   if (isSourceTreeEntrypoint(entrypoint)) {
-    return `node ${sourceTreeEntrypoint(entrypoint, runtime.cwd ?? process.cwd())}`;
+    return `node ${sourceTreeEntrypoint(entrypoint, runtime.cwd ?? process.cwd(), runtime.platform)}`;
   }
   return "skillboard";
 }
@@ -167,18 +247,21 @@ function isSourceTreeEntrypoint(entrypoint) {
     && !normalized.includes("/.npm/");
 }
 
-function sourceTreeEntrypoint(entrypoint, cwd) {
+function sourceTreeEntrypoint(entrypoint, cwd, platform) {
   const absoluteEntrypoint = isAbsolute(entrypoint) ? entrypoint : resolve(cwd, entrypoint);
   const relativeEntrypoint = relative(cwd, absoluteEntrypoint).replace(/\\/g, "/");
   if (!relativeEntrypoint.startsWith("../") && relativeEntrypoint !== ".." && !isAbsolute(relativeEntrypoint)) {
-    return shellQuote(relativeEntrypoint);
+    return shellQuote(relativeEntrypoint, platform);
   }
-  return shellQuote(absoluteEntrypoint);
+  return shellQuote(absoluteEntrypoint, platform);
 }
 
-function shellQuote(value) {
+function shellQuote(value, platform = process.platform) {
   if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
     return value;
   }
+  if (platform === "win32") {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
   return `'${value.replace(/'/g, "'\\''")}'`;
 }

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.
+- 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-integration-home.mjs

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { access, chown, lstat, readFile } from "node:fs/promises";
+import { access, chown, lstat, readFile, readdir } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { promisify } from "node:util";
 
@@ -53,6 +53,19 @@ export async function applyOwnership(path, ownership) {
   }
 }
 
+export async function applyOwnershipTree(path, ownership) {
+  if (ownership === null) return;
+  const stats = await pathStats(path);
+  if (stats === null || stats.isSymbolicLink()) return;
+  await applyOwnership(path, ownership);
+  if (!stats.isDirectory()) return;
+  const entries = await readdir(path, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) continue;
+    await applyOwnershipTree(resolve(path, entry.name), ownership);
+  }
+}
+
 function canApplyProcessOwnership(uid, gid) {
   if (typeof process.getuid !== "function") {
     return false;