agent-skillboard 0.2.6 → 0.2.8

package/src/control/skill-crud.mjs

@@ -1,4 +1,4 @@
-import YAML from "yaml";
+// allow: SIZE_OK - control command split is deferred from the 0.2.7 release gate.
 import {
   EXPOSURE_VALUES,
   INVOCATION_VALUES,
@@ -28,6 +28,7 @@ import {
 import { canUseSkill } from "./can-use-guard.mjs";
 
 const WRITABLE_INVOCATIONS = new Set(["manual-only", "router-only", "workflow-auto", "global-auto"]);
+const NON_ACTIVATABLE_STATUSES = new Set(["blocked", "deprecated", "archived", "removed"]);
 
 export async function activateSkill(options) {
   const { document, originalText } = await loadConfig(options.configPath);
@@ -38,6 +39,7 @@ export async function activateSkill(options) {
   if (!WRITABLE_INVOCATIONS.has(mode) || mode === "global-auto") {
     throw new Error(`activate requires --mode manual-only, router-only, or workflow-auto; got ${mode}`);
   }
+  ensureCanActivateSkill(options.skillId, skill, mode);
   skill.set("status", "active");
   skill.set("invocation", mode);
   addUnique(ensureSeq(workflow, "active_skills", document), options.skillId);
@@ -193,6 +195,7 @@ export async function preferSkill(options) {
   if (capabilityDefinition === undefined) {
     throw new Error(`Unknown capability: ${options.capability}`);
   }
+  ensureCanPreferSkill(options.skillId, skill);
   const required = ensureRequiredCapability(workflow, options.capability, document);
   const previousPreferred = readMapString(required, "preferred", "");
   if (previousPreferred.length > 0 && previousPreferred !== options.skillId) {
@@ -202,17 +205,6 @@ export async function preferSkill(options) {
   removeValue(ensureSeq(required, "fallback", document), options.skillId);
   addUnique(ensureSeq(workflow, "active_skills", document), options.skillId);
   removeValue(ensureSeq(workflow, "blocked_skills", document), options.skillId);
-  const status = readMapString(skill, "status", "vendor");
-  const invocation = readMapString(skill, "invocation", "manual-only");
-  if (status === "quarantined" || status === "blocked") {
-    skill.set("status", "active");
-  }
-  if (invocation === "blocked" || invocation === "deprecated") {
-    const requiredPolicy = readMapString(required, "policy", "");
-    const defaultPolicy = YAML.isMap(capabilityDefinition) ? readMapString(capabilityDefinition, "default_policy", "manual-only") : "manual-only";
-    skill.set("invocation", requiredPolicy.length > 0 ? requiredPolicy : defaultPolicy);
-  }
-
   return await writeCheckedConfig(
     document,
     originalText,
@@ -221,6 +213,31 @@ export async function preferSkill(options) {
   );
 }
 
+function ensureCanActivateSkill(skillId, skill, mode) {
+  const status = readMapString(skill, "status", "vendor");
+  const invocation = readMapString(skill, "invocation", "manual-only");
+  if (NON_ACTIVATABLE_STATUSES.has(status)) {
+    throw new Error(`Cannot activate non-callable skill ${skillId} with status: ${status}`);
+  }
+  if (status === "quarantined" && mode !== "manual-only") {
+    throw new Error(`Cannot activate quarantined skill ${skillId} as ${mode}; use manual-only after source review`);
+  }
+  if (NON_CALLABLE_WORKFLOW_INVOCATIONS.has(invocation) && !(status === "quarantined" && invocation === "blocked" && mode === "manual-only")) {
+    throw new Error(`Cannot activate non-callable skill ${skillId} with invocation: ${invocation}`);
+  }
+}
+
+function ensureCanPreferSkill(skillId, skill) {
+  const status = readMapString(skill, "status", "vendor");
+  const invocation = readMapString(skill, "invocation", "manual-only");
+  if (NON_CALLABLE_WORKFLOW_STATUSES.has(status)) {
+    throw new Error(`Cannot prefer non-callable skill ${skillId} with status: ${status}`);
+  }
+  if (NON_CALLABLE_WORKFLOW_INVOCATIONS.has(invocation)) {
+    throw new Error(`Cannot prefer non-callable skill ${skillId} with invocation: ${invocation}`);
+  }
+}
+
 function requireConfigSkill(document, skillId) {
   const skills = requireMapAt(document, ["skills"], "skills");
   const skill = skills.get(skillId, true);

package/src/doctor.mjs

@@ -45,7 +45,7 @@ export async function doctorProject(options = {}) {
   };
 
   if (!configExists) {
-    return finalizeDoctor(base, ["run skillboard init"]);
+    return finalizeDoctor(base, ["run skillboard setup once per user/agent install if agents should use SkillBoard for skill priority"]);
   }
 
   let workspace;

package/src/lifecycle-cli.mjs

@@ -1,7 +1,13 @@
-import { isAbsolute, relative, resolve } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { setupAgentSkillTargets, supportedAgentNames } from "./agent-skill-roots.mjs";
 import { initProject } from "./init.mjs";
 import { uninstallProject } from "./uninstall.mjs";
 
+const AGENT_INTEGRATION_START = "<!-- BEGIN SKILLBOARD AGENT INTEGRATION -->";
+const AGENT_INTEGRATION_END = "<!-- END SKILLBOARD AGENT INTEGRATION -->";
+
 export async function runInitCommand(options, stdout, runtime = defaultRuntime()) {
   const root = resolve(options.get("dir") ?? ".");
   const result = await initProject({
@@ -36,6 +42,39 @@ export async function runInitCommand(options, stdout, runtime = defaultRuntime()
   return 0;
 }
 
+export async function runSetupCommand(options, stdout, runtime = defaultRuntime()) {
+  if (options.get("dir") !== undefined) {
+    throw new Error("skillboard setup is agent-layer setup and does not accept --dir");
+  }
+  const targets = await agentSetupTargets(options, runtime);
+  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`);
+    return 1;
+  }
+  if (options.get("yes") !== "true") {
+    writeSetupConfirmation(stdout, targets, commandPrefix(runtime));
+    if (!canPrompt(runtime)) {
+      return 1;
+    }
+    const confirmed = await promptForSetup(runtime);
+    if (!confirmed) {
+      stdout.write("Skipped SkillBoard setup.\n");
+      return 1;
+    }
+  }
+  const result = await installAgentIntegration(targets);
+  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("Next:\n");
+  stdout.write("- Restart or refresh agents that cache user skills.\n");
+  stdout.write('- Ask the agent in a workspace: "Which skill should you use for this?"\n');
+  return 0;
+}
+
 export async function runUninstallCommand(options, stdout) {
   const removeConfig = options.get("remove-config") === "true";
   const resetConfig = options.get("reset-config") === "true";
@@ -85,15 +124,15 @@ function writeCountedList(stdout, label, values) {
 }
 
 function writeSafetyDefault(stdout, safety) {
-  stdout.write("Safety default:\n");
-  stdout.write("- Installed does not mean allowed.\n");
+  stdout.write("Skill selection default:\n");
+  stdout.write("- Installed user skills are usable unless runtime, user, or local instructions disable them.\n");
   if (safety.automatic === 0) {
     stdout.write("- No automatic model invocation was enabled.\n");
   } else {
     stdout.write(`- ${safety.automatic} automatic skills enabled by existing policy.\n`);
   }
-  stdout.write("- Imported local skills are manual-only.\n");
-  stdout.write("- Runtime/plugin/system skills require source review before manual activation.\n");
+  stdout.write("- Imported local skills are available on request in generated local policy.\n");
+  stdout.write("- Runtime/plugin/system skills require source review before automatic invocation.\n");
   stdout.write(`- ${safety.automatic} automatic skills enabled\n`);
   stdout.write(`- ${safety.manualOnly} manual-only skills available\n`);
   stdout.write(`- ${safety.routerOnly} router-only skills available\n`);
@@ -120,6 +159,34 @@ function writeNextCommands(stdout, next) {
   stdout.write(`- ${next.command} brief --workflow ${shellQuote(workflow)}${dir} --verbose\n`);
 }
 
+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("Targets:\n");
+  for (const target of targets) {
+    stdout.write(`- ${target.agent}: ${target.skillPath}\n`);
+  }
+  stdout.write("Run with --yes to install agent-layer integration:\n");
+  stdout.write(`- ${command} setup --agent ${targets.map((target) => target.agent).join(",")} --yes\n`);
+}
+
+function canPrompt(runtime) {
+  return runtime.stdin?.isTTY === true && runtime.stdout?.isTTY === true;
+}
+
+async function promptForSetup(runtime) {
+  const rl = createInterface({
+    input: runtime.stdin,
+    output: runtime.stdout
+  });
+  try {
+    const answer = await rl.question("Install SkillBoard agent integration now? [y/N] ");
+    return /^(y|yes)$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
 function formatList(values) {
   return values.length === 0 ? "none" : values.map((value) => `\`${value}\``).join(", ");
 }
@@ -143,6 +210,93 @@ function defaultRuntime() {
   };
 }
 
+async function agentSetupTargets(options, runtime) {
+  const env = runtime.env ?? process.env;
+  const home = env.HOME ?? env.USERPROFILE;
+  const requested = readCsv(options.get("agent"));
+  const supported = new Set(supportedAgentNames());
+  const names = requested.length === 0 ? supportedAgentNames() : requested;
+  const targets = [];
+  for (const name of names) {
+    if (!supported.has(name)) {
+      throw new Error(`Unsupported setup agent: ${name}`);
+    }
+    targets.push(...await setupAgentSkillTargets(name, home, env, { includeFallback: requested.length > 0 }));
+  }
+  return targets;
+}
+
+async function installAgentIntegration(targets) {
+  const created = [];
+  const updated = [];
+  const unchanged = [];
+  const preserved = [];
+  const content = agentIntegrationSkill();
+  for (const target of targets) {
+    const existing = await readFile(target.skillPath, "utf8").catch((error) => {
+      if (error?.code === "ENOENT") {
+        return null;
+      }
+      throw error;
+    });
+    if (existing === content) {
+      unchanged.push(`${target.agent}:${target.skillPath}`);
+      continue;
+    }
+    if (existing !== null && !existing.includes(AGENT_INTEGRATION_START)) {
+      preserved.push(`${target.agent}:${target.skillPath}`);
+      continue;
+    }
+    await mkdir(dirname(target.skillPath), { recursive: true });
+    await writeFile(target.skillPath, content, "utf8");
+    (existing === null ? created : updated).push(`${target.agent}:${target.skillPath}`);
+  }
+  return { created, updated, unchanged, preserved };
+}
+
+function agentIntegrationSkill() {
+  return `---
+name: skillboard
+description: Use SkillBoard when several installed skills could apply, a skill choice is ambiguous, or the user asks which skill should be used, preferred, avoided, reviewed, or prioritized for the current workflow.
+---
+${AGENT_INTEGRATION_START}
+# SkillBoard Agent Integration
+
+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.
+- 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.
+
+## Default Behavior
+
+- Installed user skills are usable by default unless the runtime, user, or local instructions disable them.
+- Do not ask for permission merely because you selected a skill.
+- When you use a skill, disclose it briefly at the start and completion.
+- Use SkillBoard when more than one skill matches, when skills overlap, or when workflow priority should choose between plausible skills.
+
+## Cross-Agent Skill Reuse
+
+- 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.
+- If the user approves, inspect the source skill, write an adapted \`SKILL.md\` for this agent, then install it with \`skillboard import-skill --from <source-agent> --to <this-agent> --skill <skill> --adapted-file <adapted-skill.md> --yes --json\`.
+- This is still user-agent setup. Do not create or mutate project policy files for cross-agent skill reuse.
+
+## Ambiguity Resolution
+
+1. Identify the candidate skills that match the request.
+2. Prefer the skill whose description, workflow guidance, and local instructions most directly match the user's task.
+3. 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.
+4. If the best choice is still ambiguous or the choice would change persistent policy, ask the user which priority to remember.
+5. Continue with the selected skill; do not stop only because other candidate skills exist.
+
+${AGENT_INTEGRATION_END}
+`;
+}
+
 function commandPrefix(runtime) {
   const entrypoint = runtime.entrypointPath ?? "";
   const normalized = entrypoint.replaceAll("\\", "/");

package/src/lifecycle-content.mjs

@@ -31,7 +31,7 @@ Your responsibility is to answer skill availability questions from SkillBoard, t
 
 ## Availability
 
-- Use SkillBoard as the source of truth; installed \`SKILL.md\` files are not automatically callable.
+- Use SkillBoard as the source of truth for project-local policy and workflow priority; installed \`SKILL.md\` files are candidates, not enough to resolve overlap by themselves.
 - Read the current brief before answering: \`skillboard brief --json --config skillboard.config.yaml --skills skills\`. If the workflow is known, include \`--workflow <name>\`; add \`--include-actions\` when the user wants you to mediate a change.
 - When the user asks which skill fits a task, read \`skillboard brief --intent <request> --json --config skillboard.config.yaml --skills skills\`. Include \`--workflow <name>\` when known. Read \`assistant_guidance.route\`; use \`recommended_skill\`, \`fallback_skills\`, \`route_candidates\`, \`post_use_policy_suggestion\`, and \`guard_command\` instead of guessing from raw skill text. Inspect \`route_candidates\` when several skills match so denied candidates and selected fallbacks are clear. If \`post_use_policy_suggestion\` is present, work first with the allowed routed skill, then ask after completion whether to remember the suggested policy. If no skill matches, ask a clarifying question before choosing a skill.
 - Treat the brief sections headed "What your AI can use now", "Needs your decision", and "Blocked for safety" as the availability summary; do not infer availability from \`SKILL.md\` bodies.

package/src/uninstall.mjs

@@ -1,3 +1,4 @@
+// allow: SIZE_OK - uninstall lifecycle split is deferred from the 0.2.7 release gate.
 import { access, lstat, readFile, readdir, rm, rmdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { BRIDGE_END, BRIDGE_START, defaultConfig, hookReadme, profileReadme } from "./lifecycle-content.mjs";