agent-skillboard 0.2.18 → 0.3.1

package/docs/versioning.md

@@ -1,278 +1,58 @@
 # Versioning
 
-SkillBoard has several versioned surfaces. They should not all move at the same
-pace, and not every skill file belongs in central version control.
+SkillBoard is public alpha. Package releases follow semantic versioning; policy
+schema versions are explicit inside `skillboard.config.yaml`.
 
-This document defines the public alpha policy for releases, config compatibility,
-source profiles, and the generated lockfile.
+## Policy schema timeline
 
-## Status
+- v0.3.0 introduces policy schema v2; later v0.3.x releases continue to write it.
+- v0.3.x provides a one-release read-only window for policy schema v1.
+- v0.4.0 removes the v1 reader and v1 compatibility projection.
+- v1 mutation is never supported after v2 ships; migrate first.
 
-Current package version: `0.2.18`
-
-Current config schema version:
-
-```yaml
-version: 1
-```
-
-The project is a public alpha. Breaking changes are allowed before `1.0.0`, but
-they must be documented in release notes and should include a migration note when
-they affect user config.
-
-## Versioned Surfaces
-
-SkillBoard versions these surfaces deliberately:
-
-- CLI package version: the npm package and command behavior.
-- Config schema version: the top-level `version` field in
-  `skillboard.config.yaml`.
-- Source profile format: YAML files under `profiles/` and project-specific
-  `.skillboard/profiles/`.
-- Workflow contracts: workflow names, required capabilities, active skill pools,
-  required outputs, and harness choices.
-- Capability contracts: canonical skill, alternatives, and default policy for a
-  capability.
-- Exported skill entries: shared or vendor skills governed by SkillBoard.
-- Install-unit entries: plugin, marketplace, package, harness, MCP, hook, agent,
-  and LSP sources.
-- Lockfile data: pinned source/cache digest, skill content digests, policy, and
-  compatible harnesses.
-
-SkillBoard does not try to centrally version every prompt or helper skill. A
-workflow-internal private skill can remain inside that workflow package until it
-becomes shared, auto-invokable, vendor-provided, or cross-workflow.
-
-## Release Versioning
-
-The package follows SemVer with a stricter alpha convention:
-
-- Patch: bug fixes, docs, new tests, safer validation, and non-breaking profile
-  additions.
-- Minor: new commands, new config fields with safe defaults, new report sections,
-  new built-in source profiles, and new policy checks that are warnings first.
-- Major: post-`1.0.0` breaking CLI, config, or policy behavior.
-
-Before `1.0.0`, breaking changes may happen in minor releases, but the changelog
-must call them out clearly.
-
-Suggested tags:
-
-- `v0.1.0-alpha`: first public GitHub alpha.
-- `v0.2.7`: one-time runtime source review before manual activation, ask-after
-  skill routing, purge uninstall, README benefit-first positioning,
-  source inventory refresh, doctor/status, source pin refresh,
-  installer/config detection, resilient detector warnings, and richer dry-run
-  plans.
-- `v0.3.0-alpha`: signed remote source verification hardening and migration
-  workflow.
-- `v1.0.0`: config schema and core CLI behavior are stable enough for external
-  workflows to rely on.
-
-## Config Schema Version
-
-The top-level `version` field is the schema version, not the package version.
-
-Rules:
-
-- `version: 1` is the only supported schema today.
-- Missing `version` is treated as `1` for early compatibility.
-- Unsupported future versions must fail fast rather than silently parsing with
-  older semantics.
-- New fields should default to the safest behavior.
-- New automatic invocation behavior must be opt-in.
-- New policy checks should start as warnings unless they protect an important
-  safety boundary.
-
-Breaking schema changes need a migration note. A future `skillboard migrate`
-command can automate those changes, but it is not implemented yet.
-
-## Source Profile Versioning
-
-Source profiles are data, not hardcoded adapter branches. Built-in profiles live
-under `profiles/`; project profiles can live under `.skillboard/profiles/`.
-
-Profile compatibility rules:
-
-- Adding a new built-in profile is a patch or minor change.
-- Changing a built-in profile's namespace, target path prefix, default status,
-  default invocation, or default exposure is a breaking profile behavior change.
-- External profiles should not grant `global-auto` unless they also mark the
-  imported skills as `global-meta`.
-- External repository skills should normally import as `vendor`, `candidate`, or
-  `quarantined`, with `manual-only` or `router-only` invocation.
-- Harness/plugin bundle profiles should use `unit-managed` for child skills when
-  the parent bundle owns commands, hooks, MCP servers, or config mutation.
-
-Profile imports can be reviewed as fragments or merged directly:
-
-```bash
-skillboard import \
-  --profile github.mattpocock.skills \
-  --source-root /path/to/source \
-  --out .skillboard/reports/import-fragment.yaml
-```
+Exact migration commands:
 
 ```bash
-skillboard import \
-  --profile github.mattpocock.skills \
-  --source-root /path/to/source \
-  --config skillboard.config.yaml \
-  --merge \
-  --dry-run
+skillboard migrate v2 --config <path> --json
+skillboard migrate v2 --config <path> --yes --json
+skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
-`--merge` is append-only by default. `--replace` is required to overwrite
-existing skill or install-unit ids. Drop `--dry-run` only after reviewing the
-reported text and YAML semantic change plan.
-
-## Workflow And Capability Versioning
-
-The primary unit of compatibility is the workflow, not an individual skill.
-
-Version these centrally:
-
-- workflow name and intent;
-- harness and fallback harness assumptions;
-- required capabilities;
-- active, blocked, and manual-only skill pools;
-- required outputs;
-- exported skill contracts used by more than one workflow;
-- policy decisions that allow automatic invocation.
-
-Avoid central versioning for:
-
-- one-off prompts;
-- workflow-internal helper skills;
-- private skills used by only one workflow;
-- temporary templates that are not auto-invokable;
-- implementation details inside a harness bundle.
-
-When a workflow changes its required outputs, required capabilities, or
-workflow-auto skill set, treat it as a compatibility change even if no file paths
-changed.
-
-## Lockfile Policy
-
-`skillboard lock write` generates `skillboard.lock.yaml` from the current
-workspace.
-
-The lockfile pins:
-
-- config schema version;
-- install-unit source, cache path, verified path, digest, and trust status;
-- skill id, path, and content hash;
-- workflow/capability bindings;
-- generated timestamp.
-
-The lockfile should represent a verified working set, not a desired-state file.
-Users should edit `skillboard.config.yaml`; tools should generate the lockfile.
-Local `source` and `cache_path` entries are digest-verified by `skillboard audit
-sources --verify`. Remote or command-based sources need a configured
-`source_digest` and, when signatures are used, a matching `public_key`.
-Fetchable Git sources can be materialized and pinned with `skillboard sources
-refresh`, which updates `cache_path`, `source_digest`, and `verified_at` in the
-config after cloning into `.skillboard/sources/`.
-Relative local paths are resolved from the config directory first and then from
-the current working directory, so bundled examples can use project-root-relative
-paths while project configs can still keep config-local paths.
-`skillboard lock write` refuses to write when verification has errors unless
-`--allow-unverified` is passed explicitly for investigation artifacts.
-
-## Release Checklist
-
-Before tagging a public release:
-
-- Run `npm run check`.
-- Run `node --check` across `src`, `test`, and `bin`.
-- Run `npm pack --dry-run --json` and confirm internal artifacts are excluded.
-- Run at least one CLI smoke test through the public surface.
-- Confirm docs mention any breaking config, profile, or CLI changes.
-- Update package version and release notes.
-- Confirm the repository `NPM_TOKEN` secret can publish `agent-skillboard`.
-  The publish job uses that token for npm authentication and requests
-  provenance with GitHub Actions OIDC, so keep `permissions.id-token: write`,
-  the npm registry URL in `setup-node`, and
-  `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` on the publish step.
-- Push a version tag that exactly matches `package.json`, for example `v0.2.7`
-  for package version `0.2.7`.
-- Let `.github/workflows/publish.yml` publish from the tag. The workflow runs
-  the full check suite, validates that the tag matches the package version, and
-  skips `npm publish` only when that exact version already exists on npm.
-
-For alpha releases, include a short "completion notes" section. Current
-completion notes:
-
-- source inventory refresh covers known local agent skill roots, plugin-cache
-  manifests, and user-supplied scan roots;
-- `sources refresh` covers Git-compatible remote sources and digest pin refresh;
-- `inventory detect` covers installer output and explicit mutated config files
-  for commands, hooks, MCP servers, and modified config paths;
-- dry-run plans report a capped YAML semantic change list rather than full patch
-  hunks;
-- unusual YAML trivia may still be normalized during structured config writes.
-
-## 0.1.1 Completion Notes
-
-- duplicate installed skill IDs are consolidated into one canonical skill entry
-  with duplicate source locations preserved as metadata;
-- canonical duplicate skills can be shared by Codex and Hermes local workflows
-  without generating user-visible `-2` suffixes;
-- README and install docs include a Hermes system prompt bridge for profiles
-  that do not automatically read `AGENTS.md` or `CLAUDE.md`.
-
-## 0.1.2 Completion Notes
-
-- add `--version` and `-v` flags to the CLI for fast version verification in
-  npm, global, source-tree, and tarball installs;
-- add a dedicated test for the version flags;
-- update README quick-start to verify the installed version before running
-  policy commands.
-
-## 0.2.7 Completion Notes
-
-- reject direct `skillboard activate` and `skillboard prefer` attempts for
-  reviewed runtime/plugin skills that remain `status: blocked`, while
-  preserving reviewed quarantined manual-only activation.
-
-## 0.2.6 Completion Notes
-
-- keep reviewed `status: blocked` runtime/plugin skills non-activatable while
-  preserving the reviewed quarantined runtime/plugin manual activation path.
-
-## 0.2.5 Completion Notes
-
-- align reset-cleanup action-card preview and apply internals with the full
-  `.skillboard/` purge semantics used by `skillboard uninstall --purge`.
-
-## 0.2.4 Completion Notes
-
-- broaden `skillboard uninstall --purge` from reports/hooks cleanup to removal
-  of the full `.skillboard/` project state directory, covering source caches,
-  rollout logs, variant snapshots, profiles, hooks, and reports while preserving
-  local skill files.
-
-## 0.2.3 Completion Notes
-
-- add `skillboard uninstall --purge` for users who want SkillBoard's policy
-  influence and generated footprint removed while preserving local skill files;
-- document the lifecycle split between conservative bridge cleanup and full
-  SkillBoard policy-footprint removal;
-- show purge in cleanup action cards so users do not need to remember the
-  older `--reset-config --remove-reports --remove-hooks` sequence.
-
-## 0.2.2 Completion Notes
-
-- recommend one-time review, not default blocking, for high-risk runtime/plugin
-  install units;
-- after source review, allow quarantined runtime/plugin skills to be activated
-  as `manual-only` workflow skills before any ask-after preference is recorded;
-- add ask-after route policy suggestions for safe ambiguous workflow skill
-  matches while preserving the public route JSON contract;
-- carry route candidate guard and capability roles into AI-facing brief
-  guidance;
-- keep no-match and guard-denied routes free of use disclosures or post-use
-  policy suggestions;
-- update README positioning around user benefit, no-global-install usage,
-  read-only normal checks, explicit approval for policy changes, and
-  conservative previewable cleanup.
+Preview is non-mutating, apply creates an adjacent byte-for-byte backup, and
+rollback restores the selected backup. Old action ids, hooks, and lock
+projections are invalid after migration.
+
+Package install, update, setup, and doctor never automatically migrate a v1
+policy. Setup preserves its bytes and prints the preview command so the policy
+decision stays separate from package maintenance.
+
+## Versioned v2 contract
+
+Policy availability requires `enabled: true` and generated installation presence
+for the selected agent. `shared` controls only explicit managed propagation.
+Preference ranks only. Source and provenance observations are informational and
+cannot change availability. Runtime and action authorization remain outside the
+schema.
+
+## Release checklist
+
+1. Run `npm run check`.
+2. Run `npm pack --dry-run --json` and inspect public contents.
+3. Install the tarball into an isolated prefix and run
+   `skillboard doctor --summary`; verify fresh setup, v1 preservation, and a
+   late-agent shared-skill reconciliation.
+4. Confirm `CHANGELOG.md` includes the package version.
+5. Push `main` and wait for the complete cross-platform check matrix.
+6. Create a matching `vX.Y.Z` tag on that exact green commit.
+7. `.github/workflows/publish.yml` verifies the tag exactly matches
+   `package.json`, configures the registry URL in `setup-node`, then runs
+   `npm publish` with provenance.
+
+After publish, verify the registry version from a clean install. On development
+machines with system npm plus a Node version manager, use `npm config get
+prefix` and doctor to detect multiple SkillBoard installations; release tooling
+never automatically uninstalls another prefix.
+
+Publishing uses `NPM_TOKEN` through `NODE_AUTH_TOKEN`. Prefer npm trusted
+publishing with OIDC when available. Release automation skips `npm publish`
+only when that exact version already exists on npm.

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.1",
   "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,