agent-skillboard 0.2.18 → 0.3.0

package/examples/v2-multi-source.config.yaml

@@ -0,0 +1,35 @@
+version: 2
+
+skills:
+  anthropic.docx:
+    enabled: true
+    shared: true
+
+  omo.review-work:
+    enabled: true
+    shared: false
+    preference:
+      intents:
+        - review
+      priority: 90
+
+  private.tdd-work-continuity:
+    enabled: true
+    shared: false
+    preference:
+      intents:
+        - implementation
+        - testing
+      priority: 100
+
+  private.workflow-router:
+    enabled: true
+    shared: false
+    preference:
+      intents:
+        - routing
+      priority: 100
+
+  unused.example:
+    enabled: false
+    shared: false

package/examples/v2-policy-error.config.yaml

@@ -0,0 +1,6 @@
+version: 2
+
+skills:
+  invalid-sharing-value:
+    enabled: true
+    shared: all

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-skillboard",
-  "version": "0.2.18",
+  "version": "0.3.0",
   "description": "Keep agent skills broadly available while routing overlaps consistently.",
   "keywords": [
     "ai-agent",

package/src/advisor/actions.mjs

@@ -17,17 +17,17 @@ const NON_ACTIVATABLE_STATUSES = new Set(["blocked", "deprecated", "archived", "
 
 export function buildInitActions(paths) {
   return [makeAction({
-    kind: "init-project",
+    kind: "setup-user",
     targetId: paths.root,
-    label: "Initialize SkillBoard in this project",
-    reason: "SkillBoard is not initialized for this project.",
+    label: "Set up the SkillBoard user control plane",
+    reason: "The user-level SkillBoard policy and generated inventory do not exist yet.",
     risk: "low",
     requiresUserConfirmation: true,
     dryRun: null,
     apply: null,
-    appliesTo: { kind: "project", id: paths.root },
-    blockedReason: "skillboard init does not have a dry-run preview command.",
-    advanced: { root: paths.root }
+    appliesTo: { kind: "user_state", id: paths.root },
+    blockedReason: "Run `skillboard setup --yes` after user confirmation.",
+    advanced: { root: paths.root, command: "skillboard setup --yes" }
   })];
 }
 
@@ -47,6 +47,102 @@ export function buildActionCards(context) {
   };
 }
 
+export function buildV2ActionCards({ options, paths, workflow, workspace }) {
+  if (workflow.unknown || workflow.needs_selection) {
+    return [];
+  }
+  const actions = [];
+  const observedSkills = new Set(workspace.inventory.skillIds);
+  for (const skill of workspace.skills) {
+    if (!observedSkills.has(skill.id)) {
+      actions.push(skill.shared
+        ? v2SharingAction(skill, paths, "unshare")
+        : v2ForgetAction(skill, paths));
+      continue;
+    }
+    const kind = skill.enabled ? "v2:disable-skill" : "v2:enable-skill";
+    const operation = skill.enabled ? "disable" : "enable";
+    const policyArgs = ["skillboard", "skill", operation, skill.id, "--config", paths.configPath,
+      ...(paths.skillsRoot === undefined ? [] : ["--skills", paths.skillsRoot])];
+    const dryRun = command([...policyArgs, "--dry-run", "--json"]);
+    actions.push(makeAction({
+      kind,
+      targetId: skill.id,
+      label: `${skill.enabled ? "Disable" : "Enable"} ${skill.id}`,
+      reason: `${skill.enabled ? "Stop" : "Allow"} SkillBoard from selecting this skill.`,
+      risk: "medium",
+      dryRun,
+      apply: command([...policyArgs, "--json"]),
+      appliesTo: { kind: "skill", id: skill.id },
+      blockedReason: null,
+      advanced: { enabled: !skill.enabled, policy_projection_version: 2 }
+    }));
+    actions.push(v2SharingAction(skill, paths, skill.shared ? "unshare" : "share"));
+    const intent = options?.intent?.trim();
+    if (intent !== undefined && intent.length > 0
+      && skill.enabled
+      && !samePreference(skill.preference, intent)) {
+      const intents = [...new Set([...(skill.preference?.intents ?? []), intent])]
+        .sort((left, right) => left.localeCompare(right));
+      const preferenceArgs = ["skillboard", "skill", "preference", skill.id, "--intent", intents.join(","), "--priority", "100", "--config", paths.configPath,
+        ...(paths.skillsRoot === undefined ? [] : ["--skills", paths.skillsRoot])];
+      actions.push(makeAction({
+        kind: "v2:prefer-skill",
+        targetId: `${skill.id}:${encodeURIComponent(intent)}`,
+        label: `Prefer ${skill.id} for ${intent}`,
+        reason: "Rank this enabled skill higher when it is installed for the current agent and the intent matches.",
+        risk: "medium",
+        dryRun: command([...preferenceArgs, "--dry-run", "--json"]),
+        apply: command([...preferenceArgs, "--json"]),
+        appliesTo: { kind: "skill", id: skill.id },
+        blockedReason: null,
+        advanced: { intents, priority: 100, policy_projection_version: 2 }
+      }));
+    }
+  }
+  return withApplicationCommands(actions.sort(sortActions), { options, paths, workflow, workspace });
+}
+
+function v2SharingAction(skill, paths, operation) {
+  const args = ["skillboard", "skill", operation, skill.id, "--config", paths.configPath];
+  const unshare = operation === "unshare";
+  return makeAction({
+    kind: unshare ? "v2:unshare-skill" : "v2:share-skill",
+    targetId: skill.id,
+    label: `${unshare ? "Stop sharing" : "Share"} ${skill.id}`,
+    reason: unshare
+      ? "Stop SkillBoard-managed cross-agent sharing while preserving agent-owned originals."
+      : "Make this skill available through the user shared-skill layer.",
+    risk: "medium",
+    dryRun: command([...args, "--dry-run", "--json"]),
+    apply: command([...args, "--json"]),
+    appliesTo: { kind: "skill", id: skill.id },
+    blockedReason: null,
+    advanced: { shared: !unshare, policy_projection_version: 2 }
+  });
+}
+
+function v2ForgetAction(skill, paths) {
+  const args = ["skillboard", "skill", "forget", skill.id, "--config", paths.configPath,
+    ...(paths.skillsRoot === undefined ? [] : ["--skills", paths.skillsRoot])];
+  return makeAction({
+    kind: "v2:forget-skill",
+    targetId: skill.id,
+    label: `Forget removed skill ${skill.id}`,
+    reason: "Remove stale SkillBoard policy after the owning installer removed this unshared skill.",
+    risk: "medium",
+    dryRun: command([...args, "--dry-run", "--json"]),
+    apply: command([...args, "--json"]),
+    appliesTo: { kind: "skill", id: skill.id },
+    blockedReason: null,
+    advanced: { policy_only: true, policy_projection_version: 2 }
+  });
+}
+
+function samePreference(preference, intent) {
+  return preference?.priority === 100 && preference.intents.includes(intent);
+}
+
 function reviewInstallUnitActions({ paths, workflow, reviewQueue }) {
   const units = new Map();
   for (const entry of reviewQueue) {

package/src/advisor/application-commands.mjs

@@ -3,17 +3,17 @@ import {
   workflowResolved
 } from "./action-core.mjs";
 
-export function withApplicationCommands(actions, { paths, workflow }) {
+export function withApplicationCommands(actions, { paths, workflow, workspace, options }) {
   return actions.map((action) => {
     return {
       ...action,
-      application: applicationCommand(action, paths, workflow)
+      application: applicationCommand(action, paths, workflow, workspace, options)
     };
   });
 }
 
-function applicationCommand(action, paths, workflow) {
-  const blockedReason = applicationBlockedReason(action, workflow);
+function applicationCommand(action, paths, workflow, workspace, options) {
+  const blockedReason = applicationBlockedReason(action, workflow, workspace);
   if (blockedReason !== null) {
     return {
       preview: null,
@@ -24,11 +24,12 @@ function applicationCommand(action, paths, workflow) {
 
   const base = [
     "skillboard", "apply-action", action.id,
-    ...workflowArgs(workflow),
+    ...(workspace.version === 2 ? [] : workflowArgs(workflow)),
     "--dir", paths.root,
     "--config", paths.configPath,
-    "--skills", paths.skillsRoot,
-    "--json"
+    ...(paths.skillsRoot === undefined ? [] : ["--skills", paths.skillsRoot]),
+    "--json",
+    ...(workspace.version === 2 && options?.agent !== undefined ? ["--agent", options.agent] : [])
   ];
   return {
     preview: command([...base, "--dry-run"]),
@@ -37,14 +38,14 @@ function applicationCommand(action, paths, workflow) {
   };
 }
 
-function applicationBlockedReason(action, workflow) {
+function applicationBlockedReason(action, workflow, workspace) {
   if (action.blocked_reason !== null) {
     return action.blocked_reason;
   }
   if (action.apply === null) {
     return "Action cannot be applied directly.";
   }
-  if (!workflowResolved(workflow)) {
+  if (workspace.version !== 2 && !workflowResolved(workflow)) {
     return workflow.blocked_reason ?? "Select a workflow before applying action cards.";
   }
   return null;

package/src/advisor/apply-action.mjs

@@ -5,8 +5,15 @@ import {
   installGuardHook,
   removeSkill
 } from "../control.mjs";
+import { setV2SkillEnabled, setV2SkillPreference } from "../control/v2-skill-crud.mjs";
+import { forgetV2Skill } from "../control/v2-skill-forget.mjs";
+import { setSkillSharing } from "../shared-skill.mjs";
+import { resolveUserStatePaths } from "../user-state-paths.mjs";
 import { reviewInstallUnit } from "../review.mjs";
 import { uninstallProject } from "../uninstall.mjs";
+import { isPreV2ActionId, V1_MUTATION_ERROR } from "../compatibility.mjs";
+import { loadWorkspace } from "../workspace.mjs";
+import { resolveProjectPaths } from "./schema.mjs";
 
 const INSTALL_UNIT_ACTIONS = new Set([
   "block-install-unit",
@@ -27,17 +34,30 @@ export async function applyAdvisorAction(actionId, options) {
     throw new ApplyActionError("missing-action-id", "Usage: skillboard apply-action <action-id>");
   }
 
+  const paths = resolveProjectPaths(options);
+  options = { ...options, root: paths.root, configPath: paths.configPath, skillsRoot: paths.skillsRoot };
+  const workspace = await loadWorkspace({ configPath: options.configPath, skillsRoot: options.skillsRoot });
+  if (workspace.version === 1 && options.yes === true && options.dryRun !== true) {
+    throw new ApplyActionError("migration-required", V1_MUTATION_ERROR);
+  }
+  if (workspace.version === 2 && isPreV2ActionId(actionId)) {
+    throw new ApplyActionError("stale-policy-version", `Pre-v2 action id is stale: ${actionId}. Run skillboard brief --include-actions to get current actions.`);
+  }
   const action = await resolveCurrentAction(actionId, options);
   if (action.blocked_reason !== null) {
     throw new ApplyActionError("blocked-action", action.blocked_reason);
   }
 
   if (previewMode(options)) {
+    const control = action.kind.startsWith("v2:")
+      ? await dispatchAction(action, { ...options, dryRun: true })
+      : null;
     return {
       ok: true,
       mode: "preview",
       changed: false,
-      action
+      action,
+      control
     };
   }
 
@@ -96,6 +116,8 @@ async function resolveCurrentAction(actionId, options) {
 function buildActionBrief(options) {
   return buildSkillBrief({
     includeActions: true,
+    agent: options.agent,
+    intent: options.intent,
     workflow: options.workflow,
     configPath: options.configPath,
     skillsRoot: options.skillsRoot,
@@ -108,6 +130,57 @@ function previewMode(options) {
 }
 
 async function dispatchAction(action, options) {
+  if (action.kind === "v2:enable-skill" || action.kind === "v2:disable-skill") {
+    return await setV2SkillEnabled({
+      skillId: action.applies_to.id,
+      enabled: action.kind === "v2:enable-skill",
+      configPath: options.configPath,
+      skillsRoot: options.skillsRoot,
+      dryRun: options.dryRun === true
+    });
+  }
+  if (action.kind === "v2:share-skill" || action.kind === "v2:unshare-skill") {
+    const state = resolveUserStatePaths({
+      home: options.home,
+      env: options.env ?? process.env,
+      configPath: options.configPath,
+      inventoryPath: options.inventoryPath
+    });
+    return await setSkillSharing({
+      skillId: action.applies_to.id,
+      shared: action.kind === "v2:share-skill",
+      configPath: options.configPath,
+      inventoryPath: state.inventoryPath,
+      home: state.home,
+      env: options.env ?? process.env,
+      dryRun: options.dryRun === true
+    });
+  }
+  if (action.kind === "v2:prefer-skill") {
+    return await setV2SkillPreference({
+      skillId: action.applies_to.id,
+      intents: action.advanced.intents,
+      priority: action.advanced.priority,
+      configPath: options.configPath,
+      skillsRoot: options.skillsRoot,
+      dryRun: options.dryRun === true
+    });
+  }
+  if (action.kind === "v2:forget-skill") {
+    const state = resolveUserStatePaths({
+      home: options.home,
+      env: options.env ?? process.env,
+      configPath: options.configPath,
+      inventoryPath: options.inventoryPath
+    });
+    return await forgetV2Skill({
+      skillId: action.applies_to.id,
+      configPath: options.configPath,
+      inventoryPath: state.inventoryPath,
+      skillsRoot: options.skillsRoot,
+      dryRun: options.dryRun === true
+    });
+  }
   if (INSTALL_UNIT_ACTIONS.has(action.kind)) {
     return await reviewInstallUnit({
       unitId: action.applies_to.id,

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) {