agent-skillboard 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.2 — 2026-06-29
+
+### Added
+
+- CLI `--version` and `-v` flags for quick version verification across npm, global, source-tree, and tarball installs.
+- Test coverage for the new version flags.
+
+### Changed
+
+- README 5-Minute Quick Start now verifies the installed version as a first step.
+
+## 0.1.1 — 2026-06-26
+
+### Added
+
+- npm publication for `agent-skillboard`.
+- Consolidation of duplicate installed skill IDs into canonical entries.
+- Hermes system prompt bridge guide in README and install docs.

package/README.md

@@ -121,6 +121,7 @@ Run SkillBoard in the project you want to manage:
 
 ```bash
 npx agent-skillboard init
+npx agent-skillboard --version
 npx agent-skillboard brief
 npx agent-skillboard doctor --summary
 ```
@@ -232,6 +233,29 @@ top categories, next safe action, short section previews, and short action
 summaries. Use `skillboard brief --verbose` when you need the full list or
 full copyable command details.
 
+### Hermes System Prompt Bridge
+
+Hermes does not automatically read `AGENTS.md` or `CLAUDE.md`. To make Hermes
+follow the same SkillBoard policy, add a small bridge instruction to the Hermes
+profile or system prompt for the project:
+
+```text
+Use SkillBoard as the source of truth for agent skill availability.
+Before answering what skills can be used, run:
+skillboard brief --json --dir /path/to/your/project
+
+Do not infer availability from installed SKILL.md files. Immediately before
+invoking a skill, run:
+skillboard guard use <skill-id> --workflow <workflow-name> --dir /path/to/your/project
+
+For suggested policy changes, ask the user to approve one current action id,
+then run:
+skillboard apply-action <action-id> --dir /path/to/your/project --yes --json
+```
+
+Replace `/path/to/your/project` and `<workflow-name>` with the project and
+workflow Hermes should operate inside.
+
 Example: overloaded local agent profile
 
 ```text

package/docs/install.md

@@ -144,6 +144,29 @@ primary flow. Raw `skillboard hook install ... --dry-run --json` previews and
 the matching non-dry-run command are underlying manual detail for operators who
 need to inspect or materialize an executable guard hook directly.
 
+## Hermes System Prompt Bridge
+
+Hermes does not automatically read `AGENTS.md` or `CLAUDE.md`. If you want a
+Hermes profile to follow SkillBoard policy, add this bridge to the profile or
+system prompt for the managed project:
+
+```text
+Use SkillBoard as the source of truth for agent skill availability.
+Before answering what skills can be used, run:
+skillboard brief --json --dir /path/to/your/project
+
+Do not infer availability from installed SKILL.md files. Immediately before
+invoking a skill, run:
+skillboard guard use <skill-id> --workflow <workflow-name> --dir /path/to/your/project
+
+For suggested policy changes, ask the user to approve one current action id,
+then run:
+skillboard apply-action <action-id> --dir /path/to/your/project --yes --json
+```
+
+Use the workflow generated by init, such as `hermes-codex-local-manual`, or a
+workflow you explicitly created for that Hermes profile.
+
 After installing a new local agent skill pack, plugin, workflow bundle, or
 harness, rescan before enabling anything:
 

package/docs/versioning.md

@@ -8,7 +8,7 @@ source profiles, and the generated lockfile.
 
 ## Status
 
-Current package version: `0.1.0`
+Current package version: `0.1.2`
 
 Current config schema version:
 
@@ -177,17 +177,29 @@ 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.
-
+## 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 npm Trusted Publisher is configured for package `agent-skillboard`,
+  repository `NyXXiR/skillboard`, workflow filename `publish.yml`, and allowed
+  action `npm publish`.
+  - If `npm trust github agent-skillboard --repo NyXXiR/skillboard --file
+    publish.yml --allow-publish` cannot configure it from the CLI, use the npm
+    package settings page and add a GitHub Actions trusted publisher with the
+    same repository, workflow filename, and allowed action.
+- Push a version tag that exactly matches `package.json`, for example `v0.1.2`
+  for package version `0.1.2`.
+- 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:
 
@@ -199,3 +211,20 @@ completion notes:
 - 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.

package/package.json

@@ -1,6 +1,6 @@
-{
+{
   "name": "agent-skillboard",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Policy and visibility layer for AI agent skills.",
   "keywords": [
     "ai-agent",
@@ -26,6 +26,7 @@
     "profiles",
     "README.md",
     "CONTRIBUTING.md",
+    "CHANGELOG.md",
     "LICENSE",
     "tsconfig.lsp.json"
   ],
@@ -33,9 +34,9 @@
     "skillboard": "bin/skillboard.mjs",
     "agent-skillboard": "bin/skillboard.mjs"
   },
-  "publishConfig": {
-    "access": "public"
-  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "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",
@@ -43,16 +44,16 @@
     "diagnostics": "tsc -p tsconfig.lsp.json",
     "check": "node --check bin/skillboard.mjs && npm run diagnostics && node --test"
   },
-  "dependencies": {
-    "yaml": "^2.8.1"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "license": "MIT",
-  "devDependencies": {
-    "@types/node": "^26.0.0",
-    "typescript": "^6.0.3",
-    "typescript-language-server": "^5.3.0"
-  }
-}
+  "dependencies": {
+    "yaml": "^2.8.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "typescript": "^6.0.3",
+    "typescript-language-server": "^5.3.0"
+  }
+}

package/src/agent-inventory.mjs

@@ -125,6 +125,7 @@ export function mergeAgentSkillInventory(configText, inventory) {
   const reviewNotes = [];
   const managedSkillsByUnit = new Map();
   const localWorkflowSkillsByUnit = new Map();
+  const aliasSkillsByUnit = new Map();
 
   for (const skill of inventory.skills) {
     const unit = unitById.get(skill.ownerInstallUnit);
@@ -134,8 +135,10 @@ export function mergeAgentSkillInventory(configText, inventory) {
       skillsMap.set(skill.id, document.createNode(skillNode(skill, defaults)));
       addedSkills.push(skill.id);
       appendManagedSkill(managedSkillsByUnit, skill.ownerInstallUnit, skill.id);
+      appendSourceAliasSkills(aliasSkillsByUnit, skill.sourceAliases ?? [], skill.id);
       if (defaults.attachLocalWorkflow) {
         appendManagedSkill(localWorkflowSkillsByUnit, skill.ownerInstallUnit, skill.id);
+        appendLocalWorkflowAliasSkills(localWorkflowSkillsByUnit, skill.sourceAliases ?? [], skill.id);
       } else if (isTrustedLocalUserUnit(unit)) {
         reviewNotes.push(`Local skill ${skill.id} imported as manual-only candidate; use skillboard add workflow to attach it.`);
       }
@@ -144,24 +147,36 @@ export function mergeAgentSkillInventory(configText, inventory) {
     const owner = readYamlMapString(existing, "owner_install_unit", "");
     if (owner === skill.ownerInstallUnit) {
       appendManagedSkill(managedSkillsByUnit, skill.ownerInstallUnit, skill.id);
+      appendSourceAliases(existing, skill.sourceAliases ?? [], document);
+      appendSourceAliasSkills(aliasSkillsByUnit, skill.sourceAliases ?? [], skill.id);
+      if (defaults.attachLocalWorkflow) {
+        appendManagedSkill(localWorkflowSkillsByUnit, skill.ownerInstallUnit, skill.id);
+        appendLocalWorkflowAliasSkills(localWorkflowSkillsByUnit, skill.sourceAliases ?? [], skill.id);
+      }
     } else {
-      skippedSkills.push(skill.id);
+      const alias = sourceAliasForSkill(skill);
+      appendSourceAliases(existing, [alias], document);
+      appendManagedSkill(aliasSkillsByUnit, skill.ownerInstallUnit, skill.id);
+      if (defaults.attachLocalWorkflow) {
+        appendManagedSkill(localWorkflowSkillsByUnit, skill.ownerInstallUnit, skill.id);
+      }
     }
   }
 
   for (const unit of inventory.installUnits) {
     const managedSkills = managedSkillsByUnit.get(unit.id) ?? [];
-    if (managedSkills.length === 0 && !hasRuntimeComponents(unit)) {
+    const aliasSkills = aliasSkillsByUnit.get(unit.id) ?? [];
+    if (managedSkills.length === 0 && aliasSkills.length === 0 && !hasRuntimeComponents(unit)) {
       continue;
     }
     const existing = unitsMap.get(unit.id, true);
     if (existing === undefined) {
-      unitsMap.set(unit.id, document.createNode(installUnitNode(unit, managedSkills)));
+      unitsMap.set(unit.id, document.createNode(installUnitNode(unit, managedSkills, aliasSkills)));
       addedInstallUnits.push(unit.id);
       continue;
     }
     const unitMap = requireYamlMap(existing, `install_units.${unit.id}`);
-    if (mergeInstallUnitNode(unitMap, unit, managedSkills, document)) {
+    if (mergeInstallUnitNode(unitMap, unit, managedSkills, aliasSkills, document)) {
       updatedInstallUnits.push(unit.id);
     }
   }
@@ -367,11 +382,13 @@ async function findPluginManifests(root) {
 async function inventoryFromGroups(groups, home, initialWarnings = []) {
   const skills = [];
   const installUnits = [];
-  const usedSkillIds = new Set();
+  const skillById = new Map();
   const warnings = [...initialWarnings];
+  let scannedSkills = 0;
 
-  for (const group of groups.sort((left, right) => left.unit.id.localeCompare(right.unit.id))) {
+  for (const group of groups.sort(compareInventoryGroups)) {
     const unitSkills = [];
+    const aliasSkills = [];
     for (const file of group.files.sort((left, right) => left.localeCompare(right))) {
       let frontmatter;
       try {
@@ -380,30 +397,57 @@ async function inventoryFromGroups(groups, home, initialWarnings = []) {
         warnings.push(`skill file ${displayPath(file, home)} skipped: ${errorMessage(error)}`);
         continue;
       }
-      const baseId = skillIdFor(group.unit, group.root, file, frontmatter);
-      const id = uniqueId(baseId, usedSkillIds);
-      usedSkillIds.add(id);
+      scannedSkills += 1;
+      const id = skillIdFor(group.unit, group.root, file, frontmatter);
+      const sourceAlias = {
+        ownerInstallUnit: group.unit.id,
+        path: skillPath(group.root, file)
+      };
+      const existing = skillById.get(id);
+      if (existing !== undefined) {
+        existing.sourceAliases.push(sourceAlias);
+        aliasSkills.push(id);
+        continue;
+      }
       unitSkills.push(id);
-      skills.push({
+      const skill = {
         id,
-        path: skillPath(group.root, file),
+        path: sourceAlias.path,
         status: "quarantined",
         invocation: "blocked",
         exposure: "exported",
         category: group.unit.category,
         ownerInstallUnit: group.unit.id,
-        description: frontmatter.description
-      });
+        description: frontmatter.description,
+        sourceAliases: []
+      };
+      skillById.set(id, skill);
+      skills.push(skill);
     }
     if (unitSkills.length > 0) {
       group.unit.providedComponents = providedComponentList({ ...group.unit, skills: unitSkills });
     }
-    if (unitSkills.length > 0 || hasRuntimeComponents(group.unit)) {
-      installUnits.push(installUnitWithSkills(group.unit, unitSkills, group.root, home));
+    if (unitSkills.length > 0 || aliasSkills.length > 0 || hasRuntimeComponents(group.unit)) {
+      installUnits.push(installUnitWithSkills(group.unit, unitSkills, aliasSkills, group.root, home));
     }
   }
 
-  return { skills, installUnits, warnings };
+  return { skills, installUnits, scannedSkills, warnings };
+}
+
+function compareInventoryGroups(left, right) {
+  const rank = inventoryUnitRank(left.unit) - inventoryUnitRank(right.unit);
+  return rank === 0 ? left.unit.id.localeCompare(right.unit.id) : rank;
+}
+
+function inventoryUnitRank(unit) {
+  if (isTrustedLocalUserUnit(unit)) {
+    return 0;
+  }
+  if (unit.kind === "skill") {
+    return 1;
+  }
+  return 2;
 }
 
 function normalizeDiscoveryResult(result) {
@@ -419,7 +463,7 @@ function normalizeDiscoveryResult(result) {
   return { groups: [], warnings: [] };
 }
 
-function installUnitWithSkills(unit, skills, root, home) {
+function installUnitWithSkills(unit, skills, aliasSkills, root, home) {
   const commands = unit.commands ?? [];
   const hooks = unit.hooks ?? [];
   const mcpServers = unit.mcpServers ?? [];
@@ -433,7 +477,8 @@ function installUnitWithSkills(unit, skills, root, home) {
     mcpServers,
     modifiedConfigFiles: unit.modifiedConfigFiles ?? [],
     permissionRisk: unit.permissionRisk ?? permissionRiskFor({ commands, hooks, mcpServers }),
-    skills
+    skills,
+    sourceAliasSkills: aliasSkills
   };
 }
 
@@ -495,17 +540,18 @@ function skillPath(root, file) {
 }
 
 function skillNode(skill, defaults = {}) {
-  return {
+  return stripUndefined({
     path: skill.path,
     status: defaults.status ?? skill.status,
     invocation: defaults.invocation ?? skill.invocation,
     exposure: skill.exposure,
     category: skill.category,
-    owner_install_unit: skill.ownerInstallUnit
-  };
+    owner_install_unit: skill.ownerInstallUnit,
+    source_aliases: sourceAliasesNode(skill.sourceAliases ?? [])
+  });
 }
 
-function installUnitNode(unit, skills) {
+function installUnitNode(unit, skills, aliasSkills = []) {
   return stripUndefined({
     kind: unit.kind,
     source_class: unit.sourceClass,
@@ -518,6 +564,7 @@ function installUnitNode(unit, skills) {
     provided_components: unit.providedComponents,
     components: {
       skills,
+      source_aliases: aliasSkills,
       commands: unit.commands,
       hooks: unit.hooks,
       mcp_servers: unit.mcpServers
@@ -530,10 +577,11 @@ function installUnitNode(unit, skills) {
   });
 }
 
-function mergeInstallUnitNode(unitMap, unit, skills, document) {
+function mergeInstallUnitNode(unitMap, unit, skills, aliasSkills, document) {
   let changed = false;
   const components = ensureNestedMap(unitMap, "components", document);
   changed = appendNestedSequenceValues(components, "skills", skills, document) || changed;
+  changed = appendNestedSequenceValues(components, "source_aliases", aliasSkills, document) || changed;
   changed = appendNestedSequenceValues(components, "commands", unit.commands ?? [], document) || changed;
   changed = appendNestedSequenceValues(components, "hooks", unit.hooks ?? [], document) || changed;
   changed = appendNestedSequenceValues(components, "mcp_servers", unit.mcpServers ?? [], document) || changed;
@@ -566,6 +614,64 @@ function appendManagedSkill(map, unitId, skillId) {
   map.set(unitId, values);
 }
 
+function appendSourceAliasSkills(map, sourceAliases, skillId) {
+  for (const alias of sourceAliases) {
+    appendManagedSkill(map, alias.ownerInstallUnit, skillId);
+  }
+}
+
+function appendLocalWorkflowAliasSkills(map, sourceAliases, skillId) {
+  for (const alias of sourceAliases) {
+    appendManagedSkill(map, alias.ownerInstallUnit, skillId);
+  }
+}
+
+function sourceAliasForSkill(skill) {
+  return {
+    ownerInstallUnit: skill.ownerInstallUnit,
+    path: skill.path
+  };
+}
+
+function sourceAliasesNode(sourceAliases) {
+  const aliases = sourceAliases
+    .filter((alias) => alias.ownerInstallUnit !== undefined && alias.path !== undefined)
+    .map((alias) => ({
+      owner_install_unit: alias.ownerInstallUnit,
+      path: alias.path
+    }));
+  return aliases.length === 0 ? undefined : aliases;
+}
+
+function appendSourceAliases(skillNodeValue, sourceAliases, document) {
+  const skillMap = requireYamlMap(skillNodeValue, "skills.<id>");
+  const validAliases = sourceAliases.filter((alias) => alias.ownerInstallUnit !== undefined && alias.path !== undefined);
+  if (validAliases.length === 0) {
+    return false;
+  }
+  const seq = ensureNestedSeq(skillMap, "source_aliases", document);
+  const before = seq.items.length;
+  for (const alias of validAliases) {
+    if (sourceAliasExists(seq, alias)) {
+      continue;
+    }
+    seq.add(document.createNode({
+      owner_install_unit: alias.ownerInstallUnit,
+      path: alias.path
+    }));
+  }
+  return seq.items.length !== before;
+}
+
+function sourceAliasExists(seq, alias) {
+  return seq.items.some((item) => {
+    if (!YAML.isMap(item)) {
+      return false;
+    }
+    return item.get("owner_install_unit") === alias.ownerInstallUnit && item.get("path") === alias.path;
+  });
+}
+
 async function manifestMcpServers(value, pluginRoot) {
   if (typeof value === "string") {
     const path = resolve(pluginRoot, value);
@@ -737,17 +843,6 @@ function preserveLineEndings(text, reference) {
   return reference.includes("\r\n") ? text.replace(/\n/g, "\r\n") : text;
 }
 
-function uniqueId(base, used) {
-  if (!used.has(base)) {
-    return base;
-  }
-  let counter = 2;
-  while (used.has(`${base}-${counter}`)) {
-    counter += 1;
-  }
-  return `${base}-${counter}`;
-}
-
 function validId(value) {
   return /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(value);
 }

package/src/cli.mjs

@@ -1,4 +1,5 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import { dirname, isAbsolute } from "node:path";
 import YAML from "yaml";
 import {
@@ -49,6 +50,8 @@ import { planGuardHookInstall } from "./control.mjs";
 import { writeCheckedConfig } from "./control/config-write.mjs";
 import { runInitCommand, runUninstallCommand } from "./lifecycle-cli.mjs";
 
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
 const APPLY_ACTION_VALUE_OPTIONS = new Set(["workflow", "dir", "config", "skills", "out", "skillboard-bin"]);
 
 export async function main(argv, stdout, stderr) {
@@ -124,15 +127,19 @@ async function run(argv, stdout, stderr) {
       return await reconcile(options, stdout);
     case "impact":
       return await impact(argv.slice(1), options, stdout);
-    case "help":
-    case "--help":
-    case "-h":
-      stdout.write(helpText());
-      return 0;
-    default:
-      stderr.write(`Unknown command: ${command}\n`);
-      stdout.write(helpText());
-      return 1;
+    case "help":
+    case "--help":
+    case "-h":
+      stdout.write(helpText());
+      return 0;
+    case "--version":
+    case "-v":
+      stdout.write(`${VERSION}\n`);
+      return 0;
+    default:
+      stderr.write(`Unknown command: ${command}\n`);
+      stdout.write(helpText());
+      return 1;
   }
 }
 
@@ -1124,6 +1131,7 @@ function renderCounts(counts) {
 function helpText() {
   return [
     "SkillBoard - workflow-scoped agent skill policy",
+    "Version: see skillboard --version",
     "",
     "Commands:",
     "  init [--dir <path>] [--scan-root <dir>[,<dir>]] [--no-scan-installed]",

package/src/inventory-refresh.mjs

@@ -26,7 +26,7 @@ export async function refreshAgentInventory(options = {}) {
     changed: plan.changed,
     plan,
     scan: {
-      scannedSkills: inventory.skills.length,
+      scannedSkills: inventory.scannedSkills ?? inventory.skills.length,
       scannedInstallUnits: inventory.installUnits.length,
       addedSkills: merged.addedSkills,
       addedInstallUnits: merged.addedInstallUnits,