agent-skillboard 0.2.7 → 0.2.8

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## 0.2.8 — 2026-07-03
+
+### Added
+
+- `skillboard import-skill` can reuse a user skill across Codex, Claude,
+  OpenCode, and Hermes by copying compatible skills or installing an
+  user-approved adapted `SKILL.md` with provenance.
+- Global npm installs now run best-effort agent-layer setup for detected
+  supported user skill roots; `skillboard setup` remains available for later
+  agent additions, skipped lifecycle scripts, or repair.
+
+### Changed
+
+- Agent root scanning is now shared across setup, cross-agent import, and
+  installed-skill inventory. Codex detection includes `CODEX_HOME/skills`,
+  `AGENTS_HOME/skills`, `~/.agents/skills`, and `~/.codex/skills`.
+- Setup stays conservative: broad auto-detection writes only to explicit env
+  roots or existing known roots, while `--agent` keeps an explicit fallback for
+  fresh agent homes.
+
 ## 0.2.7 — 2026-07-03
 
 ### Fixed

package/README.md

@@ -4,8 +4,9 @@ Use the right AI-agent skills without managing another checklist.
 
 Ask your AI normal questions: "what skills can you use?", "which skill should
 write tests first?", or "can you make this reviewed skill available here?"
-SkillBoard runs behind the scenes so you get the benefit: the right allowed
-skill, a short disclosure of what was used, and fewer setup interruptions.
+SkillBoard runs behind the scenes so you get the benefit: the right skill, a
+short disclosure of what was used, and fewer setup interruptions when skills
+overlap.
 
 The burden stays low:
 
@@ -19,10 +20,10 @@ The burden stays low:
 Status: public alpha. The current config schema is config schema v1; breaking
 changes may still happen before `1.0.0` and are documented in release notes.
 
-Under the hood, SkillBoard is workflow-scoped skill policy and routing for AI
-agents. It separates `installed` from `allowed`, checks workflow policy and
-guard state before use, and leaves a clear record of which skill influenced the
-answer.
+Under the hood, SkillBoard is workflow-scoped skill priority and routing for AI
+agents. Installed user skills are usable by default unless runtime, user, or
+local instructions disable them; SkillBoard helps agents resolve overlap,
+policy, and workflow priority instead of guessing from raw skill files.
 
 Start with normal requests:
 
@@ -83,31 +84,48 @@ See [Tested Value Proof](#tested-value-proof) for the executable proof.
 
 ## 5-Minute Quick Start
 
-Ask your AI to set up SkillBoard in the project you want to manage. The AI runs
-SkillBoard behind the scenes, then answers from the generated brief instead of
-from memory or raw skill files.
-
-Use without a global install:
+Install the CLI. On a normal global install, SkillBoard auto-connects the
+agent layer for detected Codex, Claude, OpenCode, and Hermes user skill roots:
 
 AI/automation/operator details:
 
+```bash
+npm install -g agent-skillboard
+```
+
+The install-time setup writes a user-level `skillboard` guidance skill under
+detected agent homes. For Codex, detection includes `CODEX_HOME/skills`,
+`AGENTS_HOME/skills`, `~/.agents/skills`, and `~/.codex/skills`.
+It does not create `skillboard.config.yaml`,
+`.skillboard/`, `AGENTS.md`, or `CLAUDE.md` in projects.
+No separate setup command is required after a normal global install.
+
+Run `skillboard setup --agent codex,claude,opencode,hermes --yes` later only
+after adding another supported agent, enabling a new agent home, or installing
+with lifecycle scripts disabled. Restart or refresh agents that cache user
+skills, then ask normal questions:
+
+- "Which skill should you use to write tests first?"
+- "What skills can you use here?"
+- "Use the Codex test-first skill in OpenCode too."
+- "When two skills overlap, which one should take priority?"
+
+When a target agent needs a skill from another agent, it can use
+`skillboard import-skill --from codex --to opencode --skill <skill> --json`
+behind the scenes. Compatible skills are copied into the target agent's user
+skill root. If the source contains agent-specific instructions, the agent asks
+before creating an adapted target-agent `SKILL.md` and installs that file with
+provenance.
+
+If you intentionally maintain local workspace policy files, use the explicit
+operator commands for that layer:
+
 ```bash
 npx --yes --package agent-skillboard skillboard init
 npx --yes --package agent-skillboard skillboard doctor --summary
 npx --yes --package agent-skillboard skillboard brief --workflow <workflow-from-init>
 ```
 
-`init` creates the local control-plane files, scans known local skill roots,
-and writes agent bridge instructions. It prints the workflows it found and a
-copyable workflow-scoped `brief` command. If `init` does not print a workflow,
-run the unscoped `brief` command it prints instead. Trusted user-local skills
-start as manual-only. Runtime, plugin, and external skills stay quarantined
-until their source is reviewed; the brief presents that as a one-time review
-decision, then individual quarantined skills can be activated as manual-only
-workflow skills before any later ask-after preference is recorded. The explicit
-package/binary spelling avoids an extra npx install prompt and keeps the
-`skillboard` executable name clear.
-
 Remove the project bridge when you are done:
 
 ```bash
@@ -137,6 +155,7 @@ builds, clone-based development, Hermes bridge setup, refresh, and uninstall.
 - Inventory that separates installed skills from callable skills.
 - Workflow-scoped policy instead of global "everything is active" behavior.
 - `brief`, `route`, `can-use`, and `guard use` surfaces for AI-mediated selection and availability.
+- `import-skill` for agent-layer skill reuse across Codex, Claude, OpenCode, and Hermes.
 - Workflow conflict checks so overlapping skills cannot quietly degrade an answer.
 - Action cards that apply one approved policy change, then re-resolve state.
 - Source and install-unit review for plugins, hooks, MCP servers, harnesses,
@@ -145,8 +164,10 @@ builds, clone-based development, Hermes bridge setup, refresh, and uninstall.
 - Manual skill variant lifecycle for relationships such as `a -> claude.a`,
   with draft, approval, drift, and reset checkpoints.
 
-SkillBoard is deny-by-default. Installing a skill does not make it automatically
-callable. A workflow, source, and invocation decision must make that explicit.
+SkillBoard is priority-first at the agent layer: installed user skills are
+usable unless runtime, user, or local instructions disable them. Local workspace
+policy files can still model stricter workflow, source, and invocation
+decisions when a team needs that control.
 For action cards, use `skillboard apply-action <action-id> --yes --json`; raw
 `skillboard hook install ... --dry-run --json` previews are underlying manual
 operator detail, not the primary action-card flow.
@@ -163,6 +184,7 @@ SkillBoard currently supports:
 - Disable-impact analysis and reconcile plans.
 - Workflow-scoped activation, blocking, preference, and guard checks.
 - Action-card approval and post-apply brief refresh.
+- Agent-layer skill import with compatible copy or user-approved AI-mediated adaptation.
 - Manual variant registration, fork, status, approval, and reset.
 
 For the full command catalog and config shape, use

package/bin/postinstall.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+import { runSetupCommand } from "../src/lifecycle-cli.mjs";
+
+if (isTruthy(process.env.SKILLBOARD_SKIP_POSTINSTALL)) {
+  process.exit(0);
+}
+
+process.stderr.write(`${[
+  "SkillBoard installed.",
+  "It does not change agent configs or project files.",
+  ""
+].join("\n")}\n`);
+
+if (!shouldAutoSetup(process.env)) {
+  process.stderr.write(`${[
+    "Global installs auto-run agent setup when supported agent homes are detected.",
+    "Run skillboard setup later after adding another supported agent:",
+    "  skillboard setup",
+    "",
+    "Setup only writes user agent skill files and does not initialize projects.",
+    ""
+  ].join("\n")}`);
+  process.exit(0);
+}
+
+process.stderr.write("Auto-running agent setup for detected supported agents.\n");
+
+const stderr = {
+  write(chunk) {
+    process.stderr.write(chunk);
+  }
+};
+
+try {
+  const exitCode = await runSetupCommand(new Map([["yes", "true"]]), stderr, {
+    cwd: process.env.INIT_CWD ?? process.cwd(),
+    env: process.env,
+    entrypointPath: "skillboard",
+    packageSpec: "agent-skillboard"
+  });
+  if (exitCode === 0) {
+    process.stderr.write("Agent setup complete. Run skillboard setup later after adding another supported agent.\n");
+  } else {
+    process.stderr.write("Agent setup did not find supported agent homes. Run skillboard setup after installing or enabling a supported agent.\n");
+  }
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`Agent setup skipped: ${message}\n`);
+  process.stderr.write("Run skillboard setup after install if supported agents should recognize SkillBoard.\n");
+}
+
+function shouldAutoSetup(env) {
+  return isTruthy(env.SKILLBOARD_POSTINSTALL_SETUP)
+    || env.npm_config_global === "true"
+    || env.npm_config_location === "global";
+}
+
+function isTruthy(value) {
+  return /^(1|true|yes)$/i.test(value ?? "");
+}

package/docs/install.md

@@ -3,37 +3,74 @@
 SkillBoard sits one layer above skill installers, plugin marketplaces, harness
 bundles, and local skill repositories.
 
-After install, ask your AI questions like "what skills can you use in this
-project?" or "can you make this reviewed skill available for the current
-workflow?" The AI runs SkillBoard behind the scenes: it reads the current brief,
-uses one current action id only after confirmation when policy would change, and
-runs the guard automatically before actual skill use. For already-allowed
-skills, the AI should tell you which skill it is about to use and which skill it
-used in the result instead of asking for another approval. That disclosure is an
-audit trace, not a permission prompt. You do not need to memorize the SkillBoard
-command loop.
+After install, ask your AI questions like "what skills can you use here?" or
+"which skill should you use for this task?" The AI runs SkillBoard behind the
+scenes when skill choices overlap or workflow priority matters. Installed user
+skills are usable by default unless runtime, user, or local instructions disable
+them; SkillBoard should not turn every skill choice into a permission prompt.
+When it selects a skill, the AI should briefly say which skill it will use and
+which skill it used. You do not need to memorize the SkillBoard command loop.
 
 ## Install From npm
 
-Use no-prompt npx package execution when you want to bootstrap a project
-without keeping a global SkillBoard binary installed:
+Global install auto-runs agent integration. Installing the package makes the
+CLI available and the postinstall step runs agent-layer setup for detected
+Codex, Claude, OpenCode, and Hermes user skill roots. The setup is best-effort:
+it never fails the package install, does not edit agent config files, and does
+not create project policy files.
 
 AI/automation/operator details:
 
+```bash
+npm install -g agent-skillboard
+```
+
+The install-time setup writes a user-level SkillBoard guidance skill under
+detected agent homes such as `CODEX_HOME`, `AGENTS_HOME`, `CLAUDE_HOME`,
+`OPENCODE_HOME`, and `HERMES_HOME`. Codex detection also checks
+`~/.agents/skills` and `~/.codex/skills`.
+No separate setup command is required after a normal global install.
+
+Run `skillboard setup` later when you add another supported agent, enable a new
+agent home, intentionally skipped lifecycle scripts, or need to repair the
+agent-layer guidance install:
+
+```bash
+skillboard setup
+skillboard setup --agent codex,claude,opencode,hermes --yes
+```
+
+After setup, the target agent can reuse a skill from another supported agent:
+
+```bash
+skillboard import-skill --from codex --to opencode --skill <skill> --json
+```
+
+If the source skill can be used as-is, the agent installs it with `--yes`. If
+SkillBoard reports `needs-adaptation`, the agent explains why, asks before
+changing the skill body for the target runtime, then installs the approved
+adapted file with `--adapted-file <path> --yes`.
+
+Use no-prompt npx package execution only when you intentionally want to create
+or inspect local workspace policy files without keeping a global SkillBoard
+binary installed:
+
 ```bash
 npx --yes --package agent-skillboard skillboard init
 npx --yes --package agent-skillboard skillboard doctor --summary
 npx --yes --package agent-skillboard skillboard brief --workflow <workflow-from-init>
 ```
 
-SkillBoard does not make installed skills automatically callable. It imports
-trusted local skills as manual-only and keeps runtime/plugin skills quarantined
-until their source is reviewed. The brief presents unreviewed runtime sources as
-one-time review decisions rather than default block recommendations; after
-review, individual quarantined skills can be activated as manual-only workflow
-skills. When `init` creates or discovers workflows, use one of the workflow names
-it prints for the first brief. If `init` does not print a workflow, run the unscoped `brief` command it prints instead. The explicit package/binary spelling
-avoids an extra npx install prompt and keeps the executable name clear.
+Local workspace policy files can be stricter than the first agent-layer setup.
+When you intentionally run `init`, it imports trusted local skills as
+manual-only and keeps runtime/plugin skills quarantined until their source is
+reviewed. The brief presents unreviewed runtime sources as one-time review
+decisions rather than default block recommendations; after review, individual
+quarantined skills can be activated as manual-only workflow skills. When `init`
+creates or discovers workflows, use one of the workflow names it prints for the
+first brief. If `init` does not print a workflow, run the unscoped `brief`
+command it prints instead. The explicit package/binary spelling avoids an extra
+npx install prompt and keeps the executable name clear.
 
 The equivalent `npm exec` spelling is also no-prompt and works well in scripts:
 
@@ -49,8 +86,7 @@ AI/automation/operator details:
 
 ```bash
 npm install -g agent-skillboard
-skillboard init
-skillboard doctor
+skillboard setup --agent codex,claude,opencode,hermes --yes
 ```
 
 The executable remains `skillboard` even though the npm package name is
@@ -94,10 +130,9 @@ node bin/skillboard.mjs brief --dir /path/to/your/project --workflow <workflow-f
 
 ## What init Does
 
-`skillboard init` is the safe mutating step. npm installation itself does not
-modify a project, but init creates the files that let agents discover the control
-plane without a manual prompt and inventories already installed local agent
-skills.
+`skillboard init` is the optional local policy-file generation step. npm
+installation and `skillboard setup` do not modify a project, but init creates
+local files for teams that intentionally keep workflow policy in a workspace.
 
 Created project files:
 

package/docs/reference.md

@@ -24,6 +24,12 @@ npm exec --yes --package agent-skillboard -- skillboard doctor --summary
 npm exec --yes --package agent-skillboard -- skillboard brief --workflow <workflow-from-init>
 ```
 
+After a global install, postinstall auto-runs agent-layer setup for detected
+supported agent homes. Use `skillboard setup` later when you add another
+supported agent, skipped lifecycle scripts, or need to repair user-level agent
+guidance. This is agent-layer integration; it does not initialize, attach, or
+manage individual projects.
+
 If `init` does not print a workflow, run the unscoped `brief` command it prints
 instead.
 
@@ -51,6 +57,8 @@ node bin/skillboard.mjs brief --dir /path/to/your/project --workflow <workflow-f
 ## Commands
 
 ```bash
+skillboard setup [--yes] [--agent codex[,claude,opencode,hermes]]
+skillboard import-skill --from <agent> --to <agent> --skill <id-or-dir> [--target-skill <id-or-dir>] [--adapted-file <path>] [--dry-run] [--yes] [--replace] [--json]
 skillboard init [--dir <path>] [--scan-root <dir>[,<dir>]] [--no-scan-installed]
 skillboard uninstall [--dir <path>] [--dry-run] [--purge] [--remove-config|--reset-config] [--remove-reports] [--remove-hooks] [--keep-empty-dirs]
 skillboard inventory refresh [--dir <path>] [--config <path>] [--scan-root <dir>[,<dir>]] [--dry-run] [--json]
@@ -92,6 +100,41 @@ skillboard reconcile --config <path> --skills <dir> [--actual-harnesses a,b] [--
 skillboard impact disable <skill-id> --config <path> --skills <dir> [--out <path>] [--json]
 ```
 
+## Agent Skill Reuse
+
+`import-skill` operates above projects. It reads one supported agent's user
+skill root and writes to another supported agent's user skill root:
+
+```bash
+skillboard import-skill --from codex --to opencode --skill test-first --json
+skillboard import-skill --from codex --to opencode --skill test-first --yes --json
+```
+
+Supported agents are `codex`, `claude`, `opencode`, and `hermes`. Roots come
+from `CODEX_HOME`, `AGENTS_HOME`, `CLAUDE_HOME`, `OPENCODE_HOME`, and
+`HERMES_HOME`, or from their default user locations. Codex source scanning also
+checks `~/.agents/skills` and `~/.codex/skills`.
+
+If the source skill contains markers for another agent runtime, the command
+returns `status: "needs-adaptation"` with compatibility reasons and no writes.
+The target agent should ask the user before changing the skill body. After
+approval, it writes an adapted `SKILL.md` and installs it with provenance:
+
+```bash
+skillboard import-skill \
+  --from codex \
+  --to opencode \
+  --skill codex-hook \
+  --target-skill opencode-hook \
+  --adapted-file /tmp/opencode-hook.SKILL.md \
+  --yes \
+  --json
+```
+
+This is separate from `variant` commands. `import-skill` installs a target-agent
+user skill file; `variant` records project-local policy relationships,
+snapshots, and workflow preferences.
+
 ## Capability Routing
 
 For the normal AI-mediated flow, prefer `brief --intent`: it returns the current

package/docs/user-flow.md

@@ -15,6 +15,17 @@ memorize the SkillBoard command loop. The command examples below are
 AI/automation/operator details for the agent, scripts, or people maintaining the
 setup.
 
+If you ask OpenCode to use a skill you previously used in Codex, the target
+agent should call:
+
+```bash
+skillboard import-skill --from codex --to opencode --skill <skill> --json
+```
+
+Compatible skills are installed into the target agent's user skill root. When
+the source is agent-specific, the agent should explain the compatibility issue
+and ask before producing a target-agent adapted `SKILL.md`.
+
 Before changing this routing or workflow UX, read
 [`docs/ai-skill-routing-goal.md`](ai-skill-routing-goal.md). The goal is to keep
 SkillBoard non-blocking: observe the request, route to the current best skill,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-skillboard",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Let AI agents pick and use allowed skills in each workflow.",
   "keywords": [
     "ai-agent",
@@ -41,6 +41,7 @@
     "access": "public"
   },
   "scripts": {
+    "postinstall": "node bin/postinstall.mjs",
     "test": "node --test",
     "test:unit": "node --test test/advisor-brief-actions.test.mjs test/advisor-brief.test.mjs test/ecosystem-docs.test.mjs test/install-units.test.mjs test/package.test.mjs test/policy.test.mjs test/skillboard.test.mjs",
     "test:integration": "node --test test/brief-cli.test.mjs test/cli.test.mjs test/control-exports.test.mjs test/first-time-ux.test.mjs test/hook-dry-run.test.mjs test/hook-install-cli.test.mjs test/hook-json-errors.test.mjs test/install-units.test.mjs test/lifecycle-cli.test.mjs test/lifecycle-reset-cli.test.mjs test/multi-source-integration.test.mjs test/package.test.mjs test/policy-hardening.test.mjs test/review-cli.test.mjs test/source-profiles.test.mjs",

package/src/advisor/actions.mjs

@@ -1,3 +1,4 @@
+// allow: SIZE_OK - action-card construction split is deferred from the 0.2.7 release gate.
 import {
   applyOrNull,
   blockedByWorkflow,

package/src/agent-inventory-platforms.mjs

@@ -1,16 +1,17 @@
-import { readdir } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { agentSkillRootCandidates } from "./agent-skill-roots.mjs";
 
 export async function defaultScanRoots(home, env) {
   const codexHome = env.CODEX_HOME ?? join(home, ".codex");
-  const hermesHome = env.HERMES_HOME ?? join(home, ".hermes");
+  const agentRoots = await Promise.all([
+    agentSkillRootCandidates("codex", home, env),
+    agentSkillRootCandidates("claude", home, env),
+    agentSkillRootCandidates("hermes", home, env)
+  ]);
   return [
     join(codexHome, "skills", ".system"),
-    join(codexHome, "skills"),
     join(codexHome, "plugins", "cache"),
-    join(home, ".claude", "skills"),
-    join(hermesHome, "skills"),
-    ...(await hermesProfileSkillRoots(hermesHome))
+    ...agentRoots.flat().map((root) => root.skillRoot)
   ];
 }
 
@@ -76,14 +77,6 @@ export function displayPath(path, home) {
   return resolvedPath;
 }
 
-async function hermesProfileSkillRoots(hermesHome) {
-  const profilesRoot = join(hermesHome, "profiles");
-  const entries = await readdir(profilesRoot, { withFileTypes: true }).catch(() => []);
-  return entries
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => join(profilesRoot, entry.name, "skills"));
-}
-
 function userSkillUnit(id, path, home) {
   return {
     id,

package/src/agent-inventory.mjs

@@ -38,7 +38,10 @@ export const agentInventoryDetectors = Object.freeze([
   {
     id: "codex-user-skills",
     matches(path) {
-      return path.endsWith("/.codex/skills") || path.endsWith("\\.codex\\skills");
+      return path.endsWith("/.codex/skills")
+        || path.endsWith("\\.codex\\skills")
+        || path.endsWith("/.agents/skills")
+        || path.endsWith("\\.agents\\skills");
     },
     async discover(path, home) {
       return await discoverSkillDirectory(path, userCodexUnit(path, home), { excludeSystem: true });