@vegastack/skills 0.1.0 → 0.3.0

package/README.md

@@ -1,31 +1,51 @@
 # @vegastack/skills
 
-Installer for VegaStack Agent Skills. Installs the **vegastack-arch-guardian** skill — an architecture advisor with stable normative rules and deterministic checks — into Claude Code (`.claude/skills`) and Codex (`.agents/skills`).
+Installer for VegaStack Agent Skills — a family of self-contained skills for Claude Code, Codex, and Hermes, shipped in one integrity-checked package.
 
 ```sh
-npx @vegastack/skills add vegastack-arch-guardian
+npx @vegastack/skills list
+npx @vegastack/skills add arch-guardian
 ```
 
+## Skills in this package
+
+| Skill | What it does |
+|---|---|
+| `arch-guardian` | Architecture advisor: tier-scoped normative rules activated by declared capabilities, evidence-backed advisory reports, slim committed profile, source-freshness contract |
+| `skill-maintainer` | Encodes the Agent Skills standards (Claude Code, Codex, Hermes, agentskills.io) for creating, updating, and releasing skills in a skills repo |
+| `skillify` | Turns a feature or workflow into a complete skill conforming to the VegaStack skills contract, or audits an existing one |
+
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `add <skill>` | Install (or upgrade) the skill into the selected agent directories |
-| `verify <skill>` | Check an installed copy against the bundled checksum manifest |
-| `doctor` | Diagnose an install: integrity, profile presence, installed-vs-latest version |
-| `remove <skill>` | Uninstall the skill from the selected agent directories |
+| `list` | Show the bundled skills |
+| `add <skill>` | Install (or upgrade) a skill into the selected agent directories |
+| `verify [skill]` | Check installed copies against the bundled checksum manifest (all bundled skills when no name given) |
+| `doctor` | Diagnose an install: integrity across all skills, profile presence, installed-vs-latest version |
+| `remove <skill>` | Uninstall a skill from the selected agent directories |
 
 ## Flags
 
 | Flag | Meaning |
 |---|---|
 | `--project` / `--global` | Install into the current project (default) or the user's home directory |
-| `--agent codex\|claude\|both` | Target agent runtime(s) |
+| `--agent codex\|claude\|hermes\|both\|all` | Target agent runtime(s); `both` = codex+claude |
 | `--dir PATH` | Operate on a different project directory |
 | `--dry-run` | Show what would change without writing |
 | `--force` | Overwrite a modified installed copy |
 | `--non-interactive` | Skip prompts and use defaults: `--agent both`, project-local (for automation) |
 
+## Agent surfaces
+
+| Agent | Project install | Global install |
+|---|---|---|
+| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
+| Codex | `.agents/skills/` | `~/.agents/skills/` |
+| Hermes | — (Hermes discovers skills globally only) | `~/.hermes/skills/` |
+
+`--agent hermes` therefore requires `--global`; `--agent all` on a project install covers codex+claude and prints a notice about hermes.
+
 ## Integrity model
 
 The package ships a checksum manifest that is verified at install and by `verify` — it proves the installed bytes match what was packed, not who published it. Publisher identity is attested separately by npm provenance, generated by the trusted-publishing release pipeline. Verify it with `npm audit signatures` or on the package's npm page.

package/dist/index.js

@@ -10,25 +10,32 @@ import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline/promises";
 import { spawnSync } from "node:child_process";
 var packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-var skillName = "vegastack-arch-guardian";
-var surfaces = { codex: ".agents/skills", claude: ".claude/skills" };
+var bundleRoot = join(packageRoot, "skill");
+var surfaces = { codex: ".agents/skills", claude: ".claude/skills", hermes: ".hermes/skills" };
 var packageVersion = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8")).version;
 function usage() {
-  return `Usage: vegastack-skills <add|verify|doctor|remove> [vegastack-arch-guardian] [options]
+  return `Usage: vegastack-skills <add|verify|remove> <skill> [options]
+       vegastack-skills <list|doctor> [options]
 
 Options:
-  --agent codex|claude|both
+  --agent codex|claude|hermes|both|all   (both = codex+claude; hermes is global-only)
   --project | --global
   --dir PATH
   --dry-run
   --force
   --non-interactive
   --version
+
+Run "vegastack-skills list" to see the bundled skills.
 `;
 }
+async function bundledSkills() {
+  const entries = await readdir(bundleRoot, { withFileTypes: true });
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+}
 function parse(argv) {
   const command = argv[0] && !argv[0].startsWith("-") ? argv.shift() : "help";
-  const options = { command, skill: skillName, dryRun: false, force: false, nonInteractive: false };
+  const options = { command, dryRun: false, force: false, nonInteractive: false };
   if (argv[0] && !argv[0].startsWith("-"))
     options.skill = argv.shift();
   while (argv.length) {
@@ -54,16 +61,22 @@ function parse(argv) {
     else
       throw new Error(`Unknown option: ${flag}`);
   }
-  if (!["add", "verify", "doctor", "remove", "version", "help"].includes(options.command))
+  if (!["add", "verify", "doctor", "remove", "list", "version", "help"].includes(options.command))
     throw new Error(`Unknown command: ${options.command}`);
-  if (options.skill !== skillName)
-    throw new Error(`Unknown skill: ${options.skill}`);
-  if (options.agent && !["codex", "claude", "both"].includes(options.agent))
+  if (options.agent && !["codex", "claude", "hermes", "both", "all"].includes(options.agent))
     throw new Error(`Invalid --agent: ${options.agent}`);
   if (options.mode === "global" && options.dir)
     throw new Error("--dir cannot be combined with --global");
   return options;
 }
+async function requireSkill(options) {
+  const skills = await bundledSkills();
+  if (!options.skill)
+    throw new Error(`Specify a skill: ${skills.join(", ")}`);
+  if (!skills.includes(options.skill))
+    throw new Error(`Unknown skill: ${options.skill}. Bundled skills: ${skills.join(", ")}`);
+  return options.skill;
+}
 async function prompt(options) {
   if (options.agent && options.mode)
     return { agent: options.agent, mode: options.mode };
@@ -71,15 +84,25 @@ async function prompt(options) {
     return { agent: options.agent ?? "both", mode: options.mode ?? "project" };
   }
   const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const agentAnswer = options.agent ?? await rl.question("Install for codex, claude, or both? [both] ");
+  const agentAnswer = options.agent ?? await rl.question("Install for codex, claude, hermes, both (codex+claude), or all? [both] ");
   const modeAnswer = options.mode ?? await rl.question("Install project-local or user-global? [project] ");
   rl.close();
   const agent = agentAnswer || "both";
   const mode = modeAnswer === "global" ? "global" : "project";
-  if (!["codex", "claude", "both"].includes(agent))
+  if (!["codex", "claude", "hermes", "both", "all"].includes(agent))
     throw new Error(`Invalid agent choice: ${agent}`);
   return { agent, mode };
 }
+function resolveAgents(choice, mode) {
+  const wanted = choice === "both" ? ["codex", "claude"] : choice === "all" ? ["codex", "claude", "hermes"] : [choice];
+  if (mode === "project" && wanted.includes("hermes")) {
+    if (choice === "hermes")
+      throw new Error("Hermes discovers skills only in the global ~/.hermes/skills directory; use --global (without --dir) with --agent hermes, or --agent all");
+    console.log("note: skipping hermes for a project install — Hermes discovers skills globally only; run with --global --agent hermes");
+    return wanted.filter((agent) => agent !== "hermes");
+  }
+  return wanted;
+}
 async function exists(path) {
   try {
     await lstat(path);
@@ -140,24 +163,29 @@ async function recoverInstall(base) {
     return;
   await assertNoSymlink(journalPath, false);
   const journal = JSON.parse(await readFile(journalPath, "utf8"));
-  if (journal.schemaVersion !== 1 || !["prepared", "committed"].includes(journal.status) || !Array.isArray(journal.operations))
-    throw new Error(`Invalid installer recovery journal: ${journalPath}`);
-  const seenAgents = new Set;
+  if (journal.schemaVersion !== 2 || !["prepared", "committed"].includes(journal.status) || !Array.isArray(journal.operations)) {
+    throw new Error(`Unsupported installer recovery journal (schemaVersion ${journal.schemaVersion ?? "unknown"}); inspect and remove it manually: ${journalPath}`);
+  }
+  const skills = new Set(await bundledSkills());
+  const seen = new Set;
   for (const operation of journal.operations) {
-    if (!["codex", "claude"].includes(operation.agent) || seenAgents.has(operation.agent))
-      throw new Error(`Untrusted installer recovery journal: invalid agent`);
-    seenAgents.add(operation.agent);
-    const expectedDestination = join(base, surfaces[operation.agent], skillName);
+    if (!["codex", "claude", "hermes"].includes(operation.agent) || typeof operation.skill !== "string" || !skills.has(operation.skill))
+      throw new Error(`Untrusted installer recovery journal: invalid agent or skill; inspect and remove it manually: ${journalPath}`);
+    const key = `${operation.agent}/${operation.skill}`;
+    if (seen.has(key))
+      throw new Error("Untrusted installer recovery journal: duplicate operation");
+    seen.add(key);
+    const expectedDestination = join(base, surfaces[operation.agent], operation.skill);
     if (resolve(operation.destination) !== expectedDestination || typeof operation.existed !== "boolean")
-      throw new Error(`Untrusted installer recovery journal: destination outside installer roots`);
+      throw new Error("Untrusted installer recovery journal: destination outside installer roots");
     const expectedParent = dirname(expectedDestination);
     const validateTemporary = (path, kind) => {
       if (!path)
         return kind === "backup" && !operation.existed;
-      return dirname(resolve(path)) === expectedParent && basename(path).startsWith(`.${skillName}.${kind}-`);
+      return dirname(resolve(path)) === expectedParent && basename(path).startsWith(`.${operation.skill}.${kind}-`);
     };
     if (!validateTemporary(operation.stage, "stage") || !validateTemporary(operation.backup, "backup"))
-      throw new Error(`Untrusted installer recovery journal: invalid transaction path`);
+      throw new Error("Untrusted installer recovery journal: invalid transaction path");
   }
   for (const operation of [...journal.operations].reverse()) {
     for (const path of [operation.destination, operation.stage, operation.backup].filter(Boolean))
@@ -237,76 +265,89 @@ async function listFiles(root) {
   return output.sort();
 }
 var hash = (body) => createHash("sha256").update(body).digest("hex");
-async function loadSource() {
-  const source = join(packageRoot, "skill", skillName);
-  const integrityPath = join(packageRoot, "skill-integrity.json");
-  const manifest = JSON.parse(await readFile(integrityPath, "utf8"));
-  if (manifest.schemaVersion !== 1 || manifest.skill !== skillName)
+async function loadManifest() {
+  const manifest = JSON.parse(await readFile(join(packageRoot, "skill-integrity.json"), "utf8"));
+  if (manifest.schemaVersion !== 2 || typeof manifest.skills !== "object")
     throw new Error("Invalid bundled skill manifest");
+  return manifest;
+}
+async function loadSource(skillName) {
+  const manifest = await loadManifest();
+  const skillManifest = manifest.skills[skillName];
+  if (!skillManifest)
+    throw new Error(`Bundled manifest has no entry for skill ${skillName}`);
+  const source = join(bundleRoot, skillName);
   const skill = await readFile(join(source, "SKILL.md"), "utf8");
   if (!skill.startsWith(`---
-`) || !/^name: vegastack-arch-guardian$/m.test(skill) || !/^description: .+/m.test(skill)) {
-    throw new Error("Bundled skill fails Agent Skills frontmatter validation");
+`) || !new RegExp(`^name: ${skillName}$`, "m").test(skill) || !/^description: .+/m.test(skill)) {
+    throw new Error(`Bundled skill ${skillName} fails Agent Skills frontmatter validation`);
   }
   const observed = {};
   for (const file of await listFiles(source))
     observed[relative(source, file).split(sep).join("/")] = hash(await readFile(file));
-  if (JSON.stringify(observed) !== JSON.stringify(manifest.files))
-    throw new Error("Bundled skill checksum mismatch");
-  return { source, manifest };
+  if (JSON.stringify(observed) !== JSON.stringify(skillManifest.files))
+    throw new Error(`Bundled skill ${skillName} checksum mismatch`);
+  return { source, files: skillManifest.files };
 }
-function destinations(agent, mode, directory) {
-  const agents = agent === "both" ? ["codex", "claude"] : [agent];
-  const base = mode === "global" ? homedir() : resolve(directory ?? process.cwd());
-  return agents.map((item) => ({ agent: item, destination: join(base, surfaces[item], skillName) }));
+function baseFor(mode, directory) {
+  return mode === "global" ? homedir() : resolve(directory ?? process.cwd());
 }
-async function compare(destination, manifest) {
+async function compare(destination, files) {
   if (!await exists(destination))
     return { status: "missing", issues: ["not installed"] };
   await assertNoSymlink(destination, false);
   const issues = [];
   const actualFiles = await listFiles(destination);
   const actualKeys = new Set(actualFiles.map((file) => relative(destination, file).split(sep).join("/")).filter((key) => key !== ".vegastack-install.json"));
-  for (const [key, expected] of Object.entries(manifest.files)) {
+  for (const [key, expected] of Object.entries(files)) {
     if (!actualKeys.has(key))
       issues.push(`missing ${key}`);
     else if (hash(await readFile(join(destination, key))) !== expected)
       issues.push(`changed ${key}`);
   }
   for (const key of actualKeys)
-    if (!(key in manifest.files))
+    if (!(key in files))
       issues.push(`unexpected ${key}`);
   return { status: issues.length ? "drifted" : "verified", issues };
 }
 async function install(options) {
+  const skillName = await requireSkill(options);
   const choice = await prompt(options);
-  const base = choice.mode === "global" ? homedir() : resolve(options.dir ?? process.cwd());
+  const base = baseFor(choice.mode, options.dir);
+  const agents = resolveAgents(choice.agent, choice.mode);
+  if (!agents.length)
+    return;
   if (!options.dryRun)
-    return withInstallLock(base, () => installLocked(options, choice, base));
-  return installLocked(options, choice, base, false);
+    return withInstallLock(base, () => installLocked(options, skillName, agents, base));
+  return installLocked(options, skillName, agents, base, false);
 }
-async function installLocked(options, choice, base, recover = true) {
+async function installLocked(options, skillName, agents, base, recover = true) {
   if (recover)
     await recoverInstall(base);
-  const { source, manifest } = await loadSource();
-  const targets = destinations(choice.agent, choice.mode, options.dir);
+  const { source, files } = await loadSource(skillName);
   const operations = [];
-  for (const target of targets) {
-    await assertNoSymlink(target.destination);
-    const parent = dirname(target.destination);
+  for (const agent of agents) {
+    const destination = join(base, surfaces[agent], skillName);
+    await assertNoSymlink(destination);
+    const parent = dirname(destination);
     await assertNoSymlink(parent);
-    const existed = await exists(target.destination);
+    const existed = await exists(destination);
     if (existed) {
-      const comparison = await compare(target.destination, manifest);
+      const comparison = await compare(destination, files);
       if (comparison.status === "verified" && !options.force) {
-        console.log(`unchanged ${target.agent}: ${target.destination}`);
+        console.log(`unchanged ${agent}: ${destination}`);
         continue;
       }
-      if (!options.force)
-        throw new Error(`Refusing differing installation without --force: ${target.destination}`);
+      if (!options.force) {
+        if (options.dryRun) {
+          console.log(`would replace ${agent} (requires --force; installed copy differs): ${destination}`);
+          continue;
+        }
+        throw new Error(`Refusing differing installation without --force: ${destination}`);
+      }
     }
     const suffix = randomUUID();
-    operations.push({ ...target, existed, stage: join(parent, `.${skillName}.stage-${suffix}`), backup: existed ? join(parent, `.${skillName}.backup-${suffix}`) : undefined });
+    operations.push({ skill: skillName, agent, destination, existed, stage: join(parent, `.${skillName}.stage-${suffix}`), backup: existed ? join(parent, `.${skillName}.backup-${suffix}`) : undefined });
   }
   if (options.dryRun) {
     for (const operation of operations)
@@ -323,14 +364,14 @@ async function installLocked(options, choice, base, recover = true) {
       await mkdir(dirname(operation.destination), { recursive: true });
       await assertNoSymlink(dirname(operation.destination), false);
       await cp(source, operation.stage, { recursive: true, dereference: false, errorOnExist: true });
-      await writeFile(join(operation.stage, ".vegastack-install.json"), `${JSON.stringify({ installer: "@vegastack/skills", version: packageVersion, manifest }, null, 2)}
+      await writeFile(join(operation.stage, ".vegastack-install.json"), `${JSON.stringify({ installer: "@vegastack/skills", version: packageVersion, skill: skillName, files }, null, 2)}
 `, { flag: "wx" });
-      const stagedCheck = await compare(operation.stage, manifest);
+      const stagedCheck = await compare(operation.stage, files);
       if (stagedCheck.status !== "verified")
         throw new Error(`Staged copy failed verification: ${stagedCheck.issues.join(", ")}`);
       staged.push(operation);
     }
-    await durableJson(journalPath, { schemaVersion: 1, status: "prepared", operations });
+    await durableJson(journalPath, { schemaVersion: 2, status: "prepared", operations });
     for (const operation of operations) {
       await assertNoSymlink(dirname(operation.destination), false);
       if (await exists(operation.destination))
@@ -346,7 +387,7 @@ async function installLocked(options, choice, base, recover = true) {
       }
       applied.push(operation);
     }
-    await durableJson(journalPath, { schemaVersion: 1, status: "committed", operations });
+    await durableJson(journalPath, { schemaVersion: 2, status: "committed", operations });
   } catch (error) {
     if (await exists(journalPath))
       await recoverInstall(base);
@@ -375,17 +416,44 @@ async function installLocked(options, choice, base, recover = true) {
 }
 async function verify(options) {
   const choice = await prompt(options);
-  const { manifest } = await loadSource();
+  const base = baseFor(choice.mode, options.dir);
+  const agents = resolveAgents(choice.agent, choice.mode);
+  const explicit = Boolean(options.skill);
+  const skills = explicit ? [await requireSkill(options)] : await bundledSkills();
   let failed = false;
-  for (const target of destinations(choice.agent, choice.mode, options.dir)) {
-    const result = await compare(target.destination, manifest);
-    console.log(`${result.status} ${target.agent}: ${target.destination}${result.issues.length ? ` (${result.issues.join(", ")})` : ""}`);
-    if (result.status !== "verified")
-      failed = true;
+  let found = 0;
+  for (const skillName of skills) {
+    const { files } = await loadSource(skillName);
+    for (const agent of agents) {
+      const destination = join(base, surfaces[agent], skillName);
+      const result = await compare(destination, files);
+      if (result.status === "missing" && !explicit) {
+        console.log(`not installed ${agent} ${skillName}`);
+        continue;
+      }
+      found += 1;
+      console.log(`${result.status} ${agent} ${skillName}: ${destination}${result.issues.length ? ` (${result.issues.join(", ")})` : ""}`);
+      if (result.status !== "verified")
+        failed = true;
+    }
+  }
+  if (!explicit && found === 0) {
+    console.log("no bundled skills are installed on the selected surfaces");
+    failed = true;
   }
   if (failed)
     process.exitCode = 1;
 }
+function semverLess(a, b) {
+  const parse2 = (value) => value.split("-")[0].split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const [aMajor = 0, aMinor = 0, aPatch = 0] = parse2(a);
+  const [bMajor = 0, bMinor = 0, bPatch = 0] = parse2(b);
+  if (aMajor !== bMajor)
+    return aMajor < bMajor;
+  if (aMinor !== bMinor)
+    return aMinor < bMinor;
+  return aPatch < bPatch;
+}
 async function latestPublishedVersion() {
   try {
     const response = await fetch("https://registry.npmjs.org/@vegastack%2fskills/latest", { signal: AbortSignal.timeout(3000) });
@@ -398,37 +466,57 @@ async function latestPublishedVersion() {
   }
 }
 async function removeSkill(options) {
+  const skillName = await requireSkill(options);
   const choice = await prompt(options);
+  const base = baseFor(choice.mode, options.dir);
+  const agents = resolveAgents(choice.agent, choice.mode);
+  if (!options.dryRun)
+    return withInstallLock(base, () => removeLocked(options, skillName, agents, base));
+  return removeLocked(options, skillName, agents, base);
+}
+async function removeLocked(options, skillName, agents, base) {
   let removed = 0;
-  for (const target of destinations(choice.agent, choice.mode, options.dir)) {
-    if (!await exists(target.destination)) {
-      console.log(`not installed ${target.agent}: ${target.destination}`);
+  for (const agent of agents) {
+    const destination = join(base, surfaces[agent], skillName);
+    if (!await exists(destination)) {
+      console.log(`not installed ${agent}: ${destination}`);
       continue;
     }
-    await assertNoSymlink(target.destination, false);
+    await assertNoSymlink(destination, false);
     if (!options.force) {
-      const { manifest } = await loadSource();
-      const comparison = await compare(target.destination, manifest);
+      const { files } = await loadSource(skillName);
+      const comparison = await compare(destination, files);
       if (comparison.status === "drifted")
-        throw new Error(`Installation differs from the bundled skill (possibly locally modified); re-run with --force to remove anyway: ${target.destination}`);
+        throw new Error(`Installation differs from the bundled skill (possibly locally modified); re-run with --force to remove anyway: ${destination}`);
     }
     if (options.dryRun) {
-      console.log(`would remove ${target.agent}: ${target.destination}`);
+      console.log(`would remove ${agent}: ${destination}`);
       continue;
     }
-    await rm(target.destination, { recursive: true, force: true });
+    await rm(destination, { recursive: true, force: true });
     removed += 1;
-    console.log(`removed ${target.agent}: ${target.destination}`);
+    console.log(`removed ${agent}: ${destination}`);
   }
   if (!removed && !options.dryRun)
     process.exitCode = 1;
 }
+async function list() {
+  const manifest = await loadManifest();
+  for (const skillName of await bundledSkills()) {
+    const skill = await readFile(join(bundleRoot, skillName, "SKILL.md"), "utf8");
+    const description = skill.match(/^description: (.+)$/m)?.[1] ?? "";
+    const fileCount = Object.keys(manifest.skills[skillName]?.files ?? {}).length;
+    console.log(`${skillName} (${fileCount} files)`);
+    console.log(`  ${description.length > 160 ? `${description.slice(0, 157)}...` : description}`);
+  }
+}
 async function doctor(options) {
-  const base = options.mode === "global" ? homedir() : resolve(options.dir ?? process.cwd());
+  const base = baseFor(options.mode ?? "project", options.dir);
   await access(base, fsConstants.R_OK | fsConstants.W_OK);
   await assertNoSymlink(base, false);
   let failed = false;
   const profileCandidates = [join(base, ".vegastack", "architecture.json"), join(base, ".vegastack", "architecture.yaml")];
+  let foundProfilePath = null;
   if (options.mode !== "global") {
     let profile = null;
     for (const candidate of profileCandidates)
@@ -436,56 +524,62 @@ async function doctor(options) {
         profile = candidate;
         break;
       }
+    foundProfilePath = profile;
     if (profile) {
       if (profile.endsWith(".yaml"))
         console.log(`notice: ${profile} uses the legacy .yaml name for a JSON document; rename to architecture.json`);
       try {
         const parsed = JSON.parse(await readFile(profile, "utf8"));
-        if (parsed.schemaVersion !== 3 || parsed.profileStatus !== "confirmed" || !parsed.project?.name || !parsed.environments?.production)
-          throw new Error("required identity fields are absent or profile is not confirmed schema v3");
+        if (parsed.schemaVersion !== 4 || !parsed.project?.name || !parsed.project?.tier || !Array.isArray(parsed.capabilities))
+          throw new Error("required identity fields are absent or profile is not schema v4 (run profile-tool.mjs migrate for v3 profiles)");
         console.log(`ok architecture profile: ${profile}`);
       } catch (error) {
         console.log(`invalid architecture profile: ${profile} (${error.message})`);
         failed = true;
       }
     } else {
-      console.log(`missing architecture profile: ${profileCandidates[0]}`);
-      failed = true;
+      console.log(`missing architecture profile: ${profileCandidates[0]} (only needed for arch-guardian checks)`);
     }
   }
   console.log(`ok runtime: Node ${process.versions.node}`);
   const latest = await latestPublishedVersion();
-  if (latest && latest !== packageVersion)
-    console.log(`update available: installed ${packageVersion}, latest ${latest} — run: npx @vegastack/skills@latest add ${skillName} --force`);
+  if (latest && semverLess(packageVersion, latest))
+    console.log(`update available: installed ${packageVersion}, latest ${latest} — run: npx @vegastack/skills@latest add <skill> --force`);
+  else if (latest && semverLess(latest, packageVersion))
+    console.log(`ok installer version: ${packageVersion} (ahead of registry latest ${latest})`);
   else if (latest)
     console.log(`ok installer version: ${packageVersion} (latest)`);
   else
     console.log(`skipped installer version check (npmjs.org unreachable); installed ${packageVersion}`);
-  const { manifest } = await loadSource();
   let installations = 0;
-  let checkScript = "";
-  for (const agent of ["codex", "claude"]) {
-    const destination = join(base, surfaces[agent], skillName);
-    if (!await exists(destination)) {
-      console.log(`missing ${agent} guardian installation`);
-      continue;
+  const checkScripts = [];
+  for (const skillName of await bundledSkills()) {
+    const { files } = await loadSource(skillName);
+    for (const agent of ["codex", "claude", "hermes"]) {
+      const destination = join(agent === "hermes" ? homedir() : base, surfaces[agent], skillName);
+      if (!await exists(destination))
+        continue;
+      installations += 1;
+      const result = await compare(destination, files);
+      console.log(`${result.status === "verified" ? "ok" : "invalid"} ${agent} ${skillName} installation${result.issues.length ? ` (${result.issues.join(", ")})` : ""}`);
+      if (result.status !== "verified")
+        failed = true;
+      const candidate = join(destination, "scripts", "validate-profile.mjs");
+      if (await exists(candidate))
+        checkScripts.push(candidate);
     }
-    installations += 1;
-    const result = await compare(destination, manifest);
-    console.log(`${result.status === "verified" ? "ok" : "invalid"} ${agent} guardian installation${result.issues.length ? ` (${result.issues.join(", ")})` : ""}`);
-    if (result.status !== "verified")
-      failed = true;
-    if (!checkScript)
-      checkScript = join(destination, "scripts", "architecture-check.mjs");
   }
-  if (!installations)
+  if (!installations) {
+    console.log("no bundled skills installed on any surface");
     failed = true;
-  if (options.mode !== "global" && checkScript && !failed) {
-    const result = spawnSync(process.execPath, [checkScript, base, "--json"], { encoding: "utf8" });
+  }
+  const firstCheckScript = checkScripts[0];
+  if (options.mode !== "global" && firstCheckScript && foundProfilePath && !failed) {
+    const result = spawnSync(process.execPath, [firstCheckScript, foundProfilePath], { encoding: "utf8" });
     if (result.status === 0)
-      console.log("ok architecture invariants");
+      console.log("ok profile validation");
     else {
-      console.log(`invalid architecture invariants: ${result.stdout.trim() || result.stderr.trim()}`);
+      console.log(`invalid profile: ${result.stdout.trim() || result.stderr.trim()}`);
       failed = true;
     }
   }
@@ -498,6 +592,8 @@ async function main() {
     return console.log(usage());
   if (options.command === "version")
     return console.log(packageVersion);
+  if (options.command === "list")
+    return list();
   if (options.command === "add")
     return install(options);
   if (options.command === "verify")

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vegastack/skills",
-  "version": "0.1.0",
-  "description": "Installer and verifier for VegaStack Agent Skills (Claude Code and Codex)",
+  "version": "0.3.0",
+  "description": "Installer and verifier for VegaStack Agent Skills (Claude Code, Codex, and Hermes)",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -16,13 +16,24 @@
     "agent-skills",
     "claude-code",
     "codex",
+    "hermes",
     "skill",
     "architecture",
     "vegastack"
   ],
-  "bin": { "vegastack-skills": "dist/index.js" },
-  "files": ["dist", "skill", "skill-integrity.json", "README.md", "LICENSE"],
-  "engines": { "node": ">=20.11" },
+  "bin": {
+    "vegastack-skills": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "skill-integrity.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
   "scripts": {
     "sync": "bun scripts/sync-skill.mjs",
     "build": "bun run sync && bun build src/index.ts --target=node --outfile dist/index.js && chmod +x dist/index.js",