@vegastack/skills 0.13.0 → 0.14.0

package/README.md

@@ -3,16 +3,19 @@
 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 list
-npx @vegastack/skills add dev-architect
+npx @vegastack/skills list                      # what is bundled, by group
+npx @vegastack/skills add --group dev-skills    # the whole dev workflow, one command
+npx @vegastack/skills add dev-architect         # or a single skill
 ```
 
 ## Skills in this package
 
+### `dev-skills` — the issue-driven dev workflow
+
+Install the family with `add --group dev-skills`.
+
 | Skill | What it does |
 |---|---|
-| `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 |
 | `dev-setup` | Bootstraps any project, greenfield included, for the issue-driven dev workflow: stack-playbook-drafted profile, AGENTS.md section, labels, guards, decision register |
 | `dev-intake` | Turns ideas, brainstorms, and SOWs into agent-ready GitHub issues with recorded user approval |
 | `dev-plan` | Plans an approved issue before any code exists: fresh-grounded questionnaire, strict plan format with Interfaces blocks, the scope ratchet, quick-build inline mode |
@@ -24,26 +27,60 @@ npx @vegastack/skills add dev-architect
 | `dev-status` | The operator's board: whose move is it, from deterministic gh data |
 | `dev-chronicle` | The project's narrative record: story entries per branch and the "catch me up" digest |
 
+### `repo-tooling` — repo-only
+
+These operate on the vegastack-skills repository itself and do nothing useful in another project, so **`--all` skips them**. Install one by name if you are contributing to that repo.
+
+| Skill | What it does |
+|---|---|
+| `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 |
 |---|---|
 | `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) |
+| `add <selection>` | Install (or upgrade) skills into the selected agent directories |
+| `verify [selection]` | Check installed copies against the bundled checksum manifest (all bundled skills when nothing is selected) |
 | `doctor` | Diagnose an install: integrity across all skills, dev profile (`.vegastack/dev.md`) presence, installed-vs-latest version |
-| `remove <skill>` | Uninstall a skill from the selected agent directories |
+| `remove <selection>` | Uninstall skills from the selected agent directories |
+
+### Selecting what to act on
+
+`add`, `verify`, and `remove` each take **exactly one** selector. Combining two is an error, not a merge.
+
+| Selector | Means |
+|---|---|
+| `<skill>` | That one skill. Works for every bundled skill, repo-only ones included |
+| `--group <group>` | Every skill in that group |
+| `--all` | Every bundled skill **except** the repo-only ones |
+
+A `--group` or `--all` install is **one transaction**: every skill is checked and staged before any of them is committed, so if one fails, none are installed and the destination is left exactly as it was.
+
+```sh
+npx @vegastack/skills add --group dev-skills    # the ten dev-workflow skills
+npx @vegastack/skills add --all                 # everything worth installing in your project
+npx @vegastack/skills verify --group dev-skills # check the family against the manifest
+npx @vegastack/skills remove --group dev-skills # uninstall it again
+```
 
 ## Flags
 
 | Flag | Meaning |
 |---|---|
 | `--project` / `--global` | Install into the current project (default) or the user's home directory |
+| `--group NAME` | Select every skill in a group (see `list` for the groups) |
+| `--all` | Select every bundled skill except the repo-only ones |
 | `--agent codex\|claude\|hermes\|both\|all` | Target agent runtime(s); `both` = codex+claude |
-| `--dir PATH` | Operate on a different project directory |
+| `--dir PATH` | Operate on a different project directory; not valid with `--global` |
 | `--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) |
+| `--version` / `-v` | Print the installer version |
+| `--help` / `-h` | Print usage |
+
+`--all` and `--agent all` are different axes and are easy to confuse: `--all` chooses **which skills**, `--agent all` chooses **which agent runtimes**. `add --all --agent all --global` is valid and means every installable skill, on every runtime, in your home directory.
 
 Agent targeting is automatic: the CLI detects which agents you have (`~/.claude`, `~/.codex`/`~/.agents`, `~/.hermes`) and targets them without asking — `--agent` overrides. A numbered picker appears only when nothing is detected. Installs are project-local by default; pass `--global` for the home directory (required for Hermes).
 

package/dist/index.js

@@ -3,20 +3,69 @@
 // src/index.ts
 import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { access, cp, lstat, mkdir, open, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { access, cp, lstat, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline/promises";
+
+// src/selection.ts
+var sorted = (names) => [...new Set(names)].sort();
+function groupsIn(catalog) {
+  return sorted(catalog.map((entry) => entry.group).filter((group) => group !== null));
+}
+function selectSkills(selector, catalog, verb = "install") {
+  const chosen = [
+    selector.skill ? "a skill name" : null,
+    selector.group ? "--group" : null,
+    selector.all ? "--all" : null
+  ].filter(Boolean);
+  if (chosen.length > 1) {
+    throw new Error(`Use only one of ${chosen.join(", ")} — they select different things and are not combined`);
+  }
+  if (selector.all) {
+    const installable = sorted(catalog.filter((entry) => !entry.repoOnly).map((entry) => entry.name));
+    if (!installable.length) {
+      throw new Error("Nothing to install: every bundled skill is repo-only. Name one explicitly, or use --group, to install it anyway.");
+    }
+    return installable;
+  }
+  if (selector.group) {
+    const members = sorted(catalog.filter((entry) => entry.group === selector.group).map((entry) => entry.name));
+    if (!members.length) {
+      const groups2 = groupsIn(catalog);
+      throw new Error(`Unknown group: ${selector.group}. Available groups: ${groups2.length ? groups2.join(", ") : "(none)"}`);
+    }
+    return members;
+  }
+  if (selector.skill) {
+    if (!catalog.some((entry) => entry.name === selector.skill)) {
+      throw new Error(`Unknown skill: ${selector.skill}. Bundled skills: ${sorted(catalog.map((entry) => entry.name)).join(", ")}`);
+    }
+    return [selector.skill];
+  }
+  const groups = groupsIn(catalog);
+  throw new Error(`Specify what to ${verb}: a skill name (${sorted(catalog.map((entry) => entry.name)).join(", ")})` + `${groups.length ? `, --group (${groups.join(", ")})` : ""}, or --all`);
+}
+
+// src/index.ts
 var packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 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|remove> <skill> [options]
+       vegastack-skills <add|verify|remove> --group <group> [options]
+       vegastack-skills <add|verify|remove> --all [options]
        vegastack-skills <list|doctor> [options]
 
+Select exactly one of: a skill name, --group <group>, or --all.
+--all installs every skill except the repo-only ones; name those explicitly.
+A --group or --all install is one transaction: if any skill fails, none are installed.
+
 Options:
+  --group NAME                           install every skill in that group
+  --all                                  every bundled skill except the repo-only ones
   --agent codex|claude|hermes|both|all   (both = codex+claude; hermes is global-only)
   --project | --global
   --dir PATH
@@ -34,12 +83,21 @@ async function bundledSkills() {
 }
 function parse(argv) {
   const command = argv[0] && !argv[0].startsWith("-") ? argv.shift() : "help";
-  const options = { command, dryRun: false, force: false, nonInteractive: false };
+  const options = { command, all: false, dryRun: false, force: false, nonInteractive: false };
   if (argv[0] && !argv[0].startsWith("-"))
     options.skill = argv.shift();
   while (argv.length) {
     const flag = argv.shift();
-    if (flag === "--agent")
+    if (flag === "--group") {
+      const value = argv.shift();
+      if (value === undefined || value === "" || value.startsWith("-"))
+        throw new Error("--group requires a value");
+      if (options.group !== undefined)
+        throw new Error("--group may be given only once; select one group per run");
+      options.group = value;
+    } else if (flag === "--all")
+      options.all = true;
+    else if (flag === "--agent")
       options.agent = argv.shift();
     else if (flag === "--project")
       options.mode = "project";
@@ -68,13 +126,19 @@ function parse(argv) {
     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 skillCatalog() {
+  const manifest = await loadManifest();
+  return Object.entries(manifest.skills).map(([name, entry]) => ({
+    name,
+    group: entry.group ?? null,
+    repoOnly: Boolean(entry.repoOnly)
+  }));
+}
+function hasSelector(options) {
+  return Boolean(options.skill || options.group || options.all);
+}
+async function requireSelection(options, verb = "install") {
+  return selectSkills({ skill: options.skill, group: options.group, all: options.all }, await skillCatalog(), verb);
 }
 var agentLabels = { claude: "Claude Code", codex: "Codex", hermes: "Hermes" };
 async function detectAgents() {
@@ -330,51 +394,69 @@ async function compare(destination, files) {
   return { status: issues.length ? "drifted" : "verified", issues };
 }
 async function install(options) {
-  const skillName = await requireSkill(options);
+  const skillNames = await requireSelection(options);
   const choice = await prompt(options);
   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, skillName, agents, base));
-  return installLocked(options, skillName, agents, base, false);
+    return withInstallLock(base, () => installLocked(options, skillNames, agents, base));
+  return installLocked(options, skillNames, agents, base, false);
 }
-async function installLocked(options, skillName, agents, base, recover = true) {
+async function installLocked(options, skillNames, agents, base, recover = true) {
   if (recover)
     await recoverInstall(base);
-  const { source, files } = await loadSource(skillName);
+  const sources = new Map;
+  for (const skillName of skillNames)
+    sources.set(skillName, await loadSource(skillName));
   const operations = [];
-  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(destination);
-    if (existed) {
-      const comparison = await compare(destination, files);
-      if (comparison.status === "verified" && !options.force) {
-        console.log(`unchanged ${agent}: ${destination}`);
-        continue;
+  const refusals = [];
+  for (const skillName of skillNames) {
+    const { files } = sources.get(skillName);
+    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(destination);
+      if (existed && !(await stat(destination)).isDirectory()) {
+        throw new Error(`Refusing to install over a non-directory: ${destination} — remove it and retry`);
       }
-      if (!options.force) {
-        if (options.dryRun) {
-          console.log(`would replace ${agent} (requires --force; installed copy differs): ${destination}`);
+      if (existed) {
+        const comparison = await compare(destination, files);
+        if (comparison.status === "verified" && !options.force) {
+          console.log(`unchanged ${agent}: ${destination}`);
           continue;
         }
-        throw new Error(`Refusing differing installation without --force: ${destination}`);
+        if (!options.force) {
+          if (options.dryRun) {
+            refusals.push({ agent, path: destination });
+            continue;
+          }
+          throw new Error(`Refusing differing installation without --force: ${destination}`);
+        }
       }
+      const suffix = randomUUID();
+      operations.push({ skill: skillName, agent, destination, existed, stage: join(parent, `.${skillName}.stage-${suffix}`), backup: existed ? join(parent, `.${skillName}.backup-${suffix}`) : undefined });
     }
-    const suffix = randomUUID();
-    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)
       console.log(`would install ${operation.agent}: ${operation.destination}`);
+    for (const destination of refusals)
+      console.log(`would replace ${destination.agent} (requires --force; installed copy differs): ${destination.path}`);
+    if (refusals.length && skillNames.length > 1) {
+      console.log(`this run would install nothing: ${refusals.length} destination(s) differ and --force was not given`);
+      process.exitCode = 1;
+    }
     return;
   }
-  if (!operations.length)
+  if (!operations.length) {
+    if (skillNames.length > 1)
+      console.log(`${skillNames.length} skills already installed and unchanged${options.group ? ` (${options.group})` : ""}`);
     return;
+  }
   const journalPath = join(base, ".vegastack", ".skills-install-transaction.json");
   const staged = [];
   const applied = [];
@@ -382,8 +464,9 @@ async function installLocked(options, skillName, agents, base, recover = true) {
     for (const operation of operations) {
       await mkdir(dirname(operation.destination), { recursive: true });
       await assertNoSymlink(dirname(operation.destination), false);
+      const { source, files } = sources.get(operation.skill);
       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, skill: skillName, files }, null, 2)}
+      await writeFile(join(operation.stage, ".vegastack-install.json"), `${JSON.stringify({ installer: "@vegastack/skills", version: packageVersion, skill: operation.skill, files }, null, 2)}
 `, { flag: "wx" });
       const stagedCheck = await compare(operation.stage, files);
       if (stagedCheck.status !== "verified")
@@ -432,13 +515,21 @@ async function installLocked(options, skillName, agents, base, recover = true) {
   await syncDirectory(dirname(journalPath));
   for (const operation of applied)
     console.log(`installed ${operation.agent}: ${operation.destination}`);
+  if (skillNames.length > 1) {
+    const skipped = options.all ? (await skillCatalog()).filter((entry) => entry.repoOnly).map((entry) => entry.name) : [];
+    const note = skipped.length ? ` (skipped ${skipped.length} repo-only: ${skipped.join(", ")} — name one explicitly to install it)` : "";
+    const installedCount = new Set(applied.map((operation) => operation.skill)).size;
+    const unchanged = skillNames.length - installedCount;
+    const unchangedNote = unchanged > 0 ? `, ${unchanged} already up to date` : "";
+    console.log(`installed ${installedCount} skills${options.group ? ` from ${options.group}` : ""}${unchangedNote}${note}`);
+  }
 }
 async function verify(options) {
   const choice = await prompt(options);
   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();
+  const explicit = hasSelector(options);
+  const skills = explicit ? await requireSelection(options, "verify") : await bundledSkills();
   let failed = false;
   let found = 0;
   for (const skillName of skills) {
@@ -485,48 +576,74 @@ async function latestPublishedVersion() {
   }
 }
 async function removeSkill(options) {
-  const skillName = await requireSkill(options);
+  const skillNames = await requireSelection(options, "remove");
   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 agent of agents) {
-    const destination = join(base, surfaces[agent], skillName);
-    if (!await exists(destination)) {
-      console.log(`not installed ${agent}: ${destination}`);
-      continue;
-    }
-    await assertNoSymlink(destination, false);
-    if (!options.force) {
-      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: ${destination}`);
-    }
-    if (options.dryRun) {
-      console.log(`would remove ${agent}: ${destination}`);
-      continue;
+    return withInstallLock(base, () => removeLocked(options, skillNames, agents, base));
+  return removeLocked(options, skillNames, agents, base, false);
+}
+async function removeLocked(options, skillNames, agents, base, recover = true) {
+  if (recover)
+    await recoverInstall(base);
+  const targets = [];
+  for (const skill of skillNames) {
+    for (const agent of agents) {
+      const destination = join(base, surfaces[agent], skill);
+      if (!await exists(destination)) {
+        console.log(`not installed ${agent}: ${destination}`);
+        continue;
+      }
+      await assertNoSymlink(destination, false);
+      if (!options.force) {
+        const { files } = await loadSource(skill);
+        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: ${destination}`);
+      }
+      targets.push({ skill, agent, destination });
     }
-    await rm(destination, { recursive: true, force: true });
-    removed += 1;
-    console.log(`removed ${agent}: ${destination}`);
   }
-  if (!removed && !options.dryRun)
+  if (options.dryRun) {
+    for (const target of targets)
+      console.log(`would remove ${target.agent}: ${target.destination}`);
+    return;
+  }
+  for (const target of targets) {
+    await rm(target.destination, { recursive: true, force: true });
+    console.log(`removed ${target.agent}: ${target.destination}`);
+  }
+  if (options.all) {
+    const skipped = (await skillCatalog()).filter((entry) => entry.repoOnly).map((entry) => entry.name);
+    if (skipped.length)
+      console.log(`left ${skipped.length} repo-only skills in place: ${skipped.join(", ")} — name one explicitly to remove it`);
+  }
+  if (!targets.length)
     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 entries = await skillCatalog();
+  const groups = [...new Set(entries.map((entry) => entry.group).filter((group) => group !== null))].sort();
+  const show = async (entry) => {
+    const skill = await readFile(join(bundleRoot, entry.name, "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}`);
+    const fileCount = Object.keys(manifest.skills[entry.name]?.files ?? {}).length;
+    console.log(`  ${entry.name} (${fileCount} files)${entry.repoOnly ? "  [repo-only: not installed by --all]" : ""}`);
+    console.log(`    ${description.length > 160 ? `${description.slice(0, 157)}...` : description}`);
+  };
+  for (const group of groups) {
+    console.log(`${group}  —  vegastack-skills add --group ${group}`);
+    for (const entry of entries.filter((item) => item.group === group).sort((a, b) => a.name.localeCompare(b.name)))
+      await show(entry);
+    console.log("");
+  }
+  const ungrouped = entries.filter((entry) => entry.group === null).sort((a, b) => a.name.localeCompare(b.name));
+  if (ungrouped.length) {
+    console.log("ungrouped");
+    for (const entry of ungrouped)
+      await show(entry);
   }
 }
 async function doctor(options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vegastack/skills",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Installer and verifier for VegaStack Agent Skills (Claude Code, Codex, and Hermes)",
   "license": "MIT",
   "type": "module",

package/skill/skill-maintainer/SKILL.md

@@ -37,7 +37,9 @@ Groups are this skill's responsibility: the repo shape, its `GROUP.md` files, an
 2. **Put skills in it** — skillify's scaffolder places a new skill with `--group <name>`; it refuses — before writing anything — an unknown group, a malformed `GROUP.md`, a group with no README section, and a skill name already used at either depth, so a mistyped group never creates a stray family and the flat bundle never gets two skills of one name. Moving an existing skill into a group is a `git mv` plus its README row and its test's validator-import depth; `structure.mjs check` names anything left inconsistent.
 3. **Check the shape** — `node packages/cli/scripts/structure.mjs check` blocks on illegal depth, name collisions, a missing or malformed `GROUP.md`, two groups sharing one `GROUP.md` title, a group with no README section, stray files in a group, a skill missing a contract meta file, packaging entries that disagree with the authored tree, a group-qualified packaging key, and README rows that are absent, duplicated, mispathed, or in the wrong section. It warns — without blocking, so warnings never fail `bun run check` — on an empty group, a group of one, and scaffolded placeholder text; `--strict` makes warnings exit 1. Dot-prefixed files and directories under `skills/` are ignored everywhere — discovery, this check, and the packaging build alike: they are tool and OS leftovers, not skills.
 
-A group never reaches an installer: the bundle is flat, so `GROUP.md` ships nowhere and `add <skill>` never names a group. Ungrouped skills at `skills/<name>/` stay fully supported; grouping is a choice, not a migration.
+A group never reaches an installed **path**: the bundle is flat, so `GROUP.md` ships nowhere and an installed skill is always `<surface>/<bare-name>/`. A group is a *selection*, and the installer does expose it — `add`, `verify`, and `remove` each take one of a skill name, `--group <name>`, or `--all`, and a group install is one all-or-nothing transaction. Ungrouped skills at `skills/<name>/` stay fully supported; grouping is a choice, not a migration.
+
+Two skills are marked repo-only in `packages/cli/repo-only.json`: `skill-maintainer` and `skillify` operate on this repository and do nothing useful elsewhere, so `--all` skips them while naming one explicitly still installs it. That list is data, validated by the build against the authored skills — never inferred from a skill's prose. Repo-only and group membership are independent: a group says where a skill is authored, the marker says who should install it.
 
 ## Workflow: scaffold a new skill
 

package/skill/skill-maintainer/references/standards.md

@@ -68,6 +68,8 @@ Source: https://hermes-agent.nousresearch.com/docs/user-guide/features/skills. <
 
 Installer implication: the `@vegastack/skills` installer must treat Hermes as global-only — a "project install" for Hermes does not exist.
 
+These paths are the harnesses' own discovery rules and are unaffected by how skills are selected. The installer's `--group` and `--all` flags choose *which* skills to act on; an installed skill is always `<surface>/<bare-name>/`, never `<surface>/<group>/<name>/`.
+
 ## Portability rules (this repo's policy)
 
 One authored tree, three harnesses. Every skill in `skills/` follows all seven:

package/skill/skill-maintainer/refresh/REFRESH.md

@@ -13,10 +13,10 @@ Instructions for the scheduled refresh agent (and any human running a manual ref
 The deterministic runner is repo-shared, hosted at `tooling/refresh/`. Run from the repo root:
 
 1. **Deterministic pass first** (no LLM judgment):
-   `node tooling/refresh/refresh-evidence.mjs --registry skills/skill-maintainer/refresh/sources.json`
+   `node tooling/refresh/refresh-evidence.mjs --registry skills/repo-tooling/skill-maintainer/refresh/sources.json`
    drift/stale/unavailable results are the work-list. Exit 1 with a critical entry means fail-closed: the run must not be silently skipped. All four sources here are critical.
 2. **Accept verified changes** in the same code path:
-   `node tooling/refresh/refresh-evidence.mjs --registry skills/skill-maintainer/refresh/sources.json --accept-baselines`
+   `node tooling/refresh/refresh-evidence.mjs --registry skills/repo-tooling/skill-maintainer/refresh/sources.json --accept-baselines`
    This writes registry, cache, and drift report together — never hand-edit checksums, versions, or timestamps; they must always come from a run. Baselines are runner-seeded; when a new source is added or a verified change is accepted, this accept-baselines invocation is the only sanctioned way to update them.
 3. **Semantic verification** for every source the deterministic pass flagged: read the changed page (fetch the registry URL), decide whether any `<!-- source: X -->` marked sentence in `references/standards.md` (or the mirrored SKILL.md hard-limits row) is now wrong, and propose the minimal edit. Unlike version-pin registries, checksum drift here is presumed meaningful until a human reads the diff — these pages define the standards themselves. Editorial churn may be accepted silently only after that read.
 4. **One standing refresh PR**, branch `refresh/weekly`, force-updated on every run (never stacked duplicates; the weekly workflow .github/workflows/refresh.yml maintains it). PR body lists: each changed source, old→new checksum, links to the evidence, and which marked sentences changed and why. A maintainer review is mandatory before merge.

package/skill/skillify/assets/templates/README.md.template

@@ -5,7 +5,7 @@ TODO: one-paragraph summary for humans and agents browsing the repo. The agent e
 ## Install
 
 ```sh
-npx @vegastack/skills add {{name}}
+npx @vegastack/skills add {{name}}{{groupInstallLine}}
 ```
 
 ## What's in this skill

package/skill/skillify/refresh/REFRESH.md

@@ -9,7 +9,7 @@ Instructions for the scheduled refresh agent (and any human running a manual ref
   - the numeric limits and harness listing budgets table in `references/authoring.md` (marked `<!-- mirrored -->`);
   - the model guidance section in `references/eval-playbook.md` (marked `<!-- volatile -->`).
 
-  Both mirror facts whose sources of truth are the agent-skills standards sources tracked in the **skill-maintainer** registry (`skills/skill-maintainer/refresh/sources.json`). `sources` here is therefore deliberately empty, and the refresh runner treats this registry as valid with nothing to fetch.
+  Both mirror facts whose sources of truth are the agent-skills standards sources tracked in the **skill-maintainer** registry (`skills/repo-tooling/skill-maintainer/refresh/sources.json`). `sources` here is therefore deliberately empty, and the refresh runner treats this registry as valid with nothing to fetch.
 
 ## How to refresh
 

package/skill/skillify/scripts/scaffold-skill.mjs

@@ -222,14 +222,18 @@ export async function scaffoldSkill({ name, dir, group = null, write = false, no
   // Every refusal belongs in this pre-flight. wireReadme runs after the tree is renamed into
   // place and the packaging entry written, so anything discovered there would leave a half-wired
   // skill on disk while reporting a refusal - or, worse, report success with no row at all.
+  // When a README exists, its row target must be resolvable BEFORE the tree is staged, so a
+  // refusal writes nothing. A wholly absent README or packaging.json keeps the documented
+  // degrade-to-`skipped:` contract (skillify's README, and the bare-repo test) - tightening that
+  // is a behaviour change of its own, tracked separately.
   const readmePath = join(repoRoot, 'README.md')
   if ((await entryAt(readmePath))?.isFile()) {
     const lines = (await readFile(readmePath, 'utf8')).split('\n')
-    const target = findRowInsertion(lines, group, groupHeading)
-    if (target?.missingSection) {
+    const rowTarget = findRowInsertion(lines, group, groupHeading)
+    if (rowTarget?.missingSection) {
       throw new Error(`README.md has no "### ${groupHeading}" section for group "${group}" - create it with structure.mjs create-group`)
     }
-    if (!target) {
+    if (!rowTarget) {
       throw new Error(`README.md has no ${group ? `table under "### ${groupHeading}"` : 'ungrouped Skills table'} to add a row to - every skill needs its row, so refusing rather than scaffolding a skill the structure check would block`)
     }
   }
@@ -237,6 +241,9 @@ export async function scaffoldSkill({ name, dir, group = null, write = false, no
   // The generated test imports the repo validator by relative path, so its depth follows the
   // skill's: skills/<name>/tests/ is three levels up, skills/<group>/<name>/tests/ is four.
   const validatorPath = `${group ? '../../../..' : '../../..'}/packages/cli/scripts/validate-skill.mjs`
+  // Only a grouped skill gets the family-install line; an ungrouped one would otherwise ship a
+  // command naming a group that does not exist.
+  const groupInstallLine = group ? `\nnpx @vegastack/skills add --group ${group}   # or the whole ${group} family` : ''
 
   const outputs = templateFiles.map(([source, output]) => [source, output ?? `tests/${name}.test.ts`])
   const plan = { name, group, target, files: outputs.map(([, output]) => output), wrote: false }
@@ -247,7 +254,11 @@ export async function scaffoldSkill({ name, dir, group = null, write = false, no
   try {
     for (const [source, output] of outputs) {
       const body = await readFile(join(templatesRoot, source), 'utf8')
-      const rendered = body.replaceAll('{{name}}', name).replaceAll('{{date}}', date).replaceAll('{{validatorPath}}', validatorPath)
+      const rendered = body
+        .replaceAll('{{name}}', name)
+        .replaceAll('{{date}}', date)
+        .replaceAll('{{validatorPath}}', validatorPath)
+        .replaceAll('{{groupInstallLine}}', groupInstallLine)
       const destination = join(staging, output)
       await mkdir(dirname(destination), { recursive: true })
       await writeFile(destination, rendered)

package/skill-integrity.json

@@ -2,6 +2,8 @@
   "schemaVersion": 2,
   "skills": {
     "dev-architect": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
         "SKILL.md": "74150dde2d3c83598769a4c9f8cd295a7496d9eb9a5e920a29cba8464eb58128",
         "agents/openai.yaml": "99023b056d5c568ff3acc059e5bb7a4e6cfa5261cd0d35a525407f9e159de562",
@@ -20,6 +22,8 @@
       }
     },
     "dev-chronicle": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
         "SKILL.md": "23c6266758726d6435de38cb0cc142a94a0b55f2329f7ab6404e42fa5d0dee3a",
         "agents/openai.yaml": "765b12e17b7fce88c53ca0fae735bf0efceb843cc3703b91bc1801ab5cac06b4",
@@ -29,6 +33,8 @@
       }
     },
     "dev-debug": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
         "SKILL.md": "38ba9e67c00925f4e4738be333dc398218008df929fcf17b61398966ce4deee1",
         "agents/openai.yaml": "4aa52b5c620b0bf4de7f1609867956ce762d83dc4297ab5670a68c206ae63075",
@@ -39,6 +45,8 @@
       }
     },
     "dev-implement": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
         "SKILL.md": "724f6bc83467c28dc61a45161d3ffba7fecef2712eff3333bdf40d762731db44",
         "agents/openai.yaml": "1abab383deca54d32749fd9156f9a6211fe96e02e0166dc8a16ff8459ac31b74",
@@ -52,6 +60,8 @@
       }
     },
     "dev-intake": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
         "SKILL.md": "4754383297822d3f6e0ad8a391ac76499d83c74f424b90b928199d6c2649dc71",
         "agents/openai.yaml": "5473d2d3efffc518c07dfa8e6788c6535a5054ceca696119c5856ad265ef5581",
@@ -63,6 +73,8 @@
       }
     },
     "dev-plan": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
         "SKILL.md": "eb2ce1542b1769fa6e7d9dc7be9fc9c84df8b353ded16e39e1e578ee372c1aca",
         "agents/openai.yaml": "4b9ccc9870b4eafb73c1bc4492a0b5a530097bbcbae11dbf3235160f4f05587b",
@@ -74,6 +86,8 @@
       }
     },
     "dev-review": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
         "SKILL.md": "be32aa737cfd3309f7413407470ebffeedf6284f0f98cef6ae185c478c896c26",
         "agents/openai.yaml": "3f35d3dc60f179d4ac2526997c4d10173ba3018d06f0dbe77e209ce2978fa702",
@@ -87,6 +101,8 @@
       }
     },
     "dev-setup": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
         "SKILL.md": "d8eb7741983998f56ff8aff52f66ec3887b7fd055c26cc232e1ff41da6fab7c1",
         "agents/openai.yaml": "be790c04fdf910e71642cfadf1a7c07c217bf7fad18581610feb4c31a79651f2",
@@ -100,6 +116,8 @@
       }
     },
     "dev-ship": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
         "SKILL.md": "aa3bd8b0a1ac076309190f2008896f24ebe1216352872ff428c1b88b55c06e65",
         "agents/openai.yaml": "8f18cfd505131557eb4c9f7b7f54e9069f787be4c162403fc30253eed49a06ea",
@@ -111,6 +129,8 @@
       }
     },
     "dev-status": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
         "SKILL.md": "56415c2f69bb1a2fcb488b9846a20e632eb902b05c5b2b58ae9206d3eaffd77b",
         "agents/openai.yaml": "72435947f5afef0c8a2c170e987b14fe6057b174318c16b6b538ae8d129791fb",
@@ -121,20 +141,24 @@
       }
     },
     "skill-maintainer": {
+      "group": "repo-tooling",
+      "repoOnly": true,
       "files": {
-        "SKILL.md": "4645ed387cc6cf1c6c1e8aa0f08f7dd73274727030018af3d42fbaa360a001c0",
+        "SKILL.md": "1733d2f1fa756cbb37c74ecee0d48ddd9abf31155c4dd72eba10af31c33d88ec",
         "agents/openai.yaml": "0b89d4e6416cf20b448f5322f3d7433cfde333d2b4a05b42ed53db3759701fb4",
         "references/release-ops.md": "b5df1922b34daf7751c332c019a0ea770a48283aaa2e25f83c9851bef47999b1",
-        "references/standards.md": "3646d0dd0560a87b333f70febf670b093c89b35111132cdb641b763bf184b02f",
-        "refresh/REFRESH.md": "3955bff5f0a14c83336a73cdbd07ba18d9398996934af87fac4454206cd14023",
+        "references/standards.md": "0dd7fcb6e2f0dd3aae7167227d7ec085481bc629aa027af35d48e5d0f7b9df86",
+        "refresh/REFRESH.md": "d3ba44be2c264b849d8a815111c049e782720428d5d0c5cea23998b05e50d58f",
         "refresh/sources.json": "4977152381d53555196ac676f95e61b4eaa301309a17560da5cda722010eb80f"
       }
     },
     "skillify": {
+      "group": "repo-tooling",
+      "repoOnly": true,
       "files": {
         "SKILL.md": "310ac32ff4d557cc166a470fd1866060dfc5f03898e8ff3da9c406b84580742b",
         "agents/openai.yaml": "df320cf32a8db06c213f7892844dab810b7e96cfbf32502d25185d4a4167ef87",
-        "assets/templates/README.md.template": "68230ada702ad39f5de1f35e838ba590d89ca19b23868d4499353db6034fcc2c",
+        "assets/templates/README.md.template": "49dccb4e9b5bdb07c254f9142502b3fd11fd5b083d8661b0ae6a567dec79de74",
         "assets/templates/REFRESH.md.template": "ff86afade565d668333e7f6d0432213760fd68a62b8ba22897a8601b74c94ac0",
         "assets/templates/SKILL.md.template": "b038775f97b13b54227fe41a767a48cdaa922a93d1732f22c2d1d79bff52ca00",
         "assets/templates/openai.yaml.template": "2fbf488369825109d6cad4f17e7b729a40d9e3c43c7f01bc5dfa16361d59c086",
@@ -143,9 +167,9 @@
         "assets/templates/trigger-queries.json.template": "37517e5f3dc66819f61f5a7bb8ace1921282415f10551d2defa5c3eb0985b570",
         "references/authoring.md": "de61bc54140e07bb1910d5adac4e988e10fea9bd11b3e27234c0c699aa7bbf0d",
         "references/eval-playbook.md": "1f463dfea8d69b7022712776794369892643aa020186fe3a3707c493a6c2d4e9",
-        "refresh/REFRESH.md": "fb74342bec10fbb8d28590dfde9147564346f2eba8976777073901a56e2742a8",
+        "refresh/REFRESH.md": "695f3283b27c14accf4095137898ce1f6dc40749483c5a5705e80aa9693f08c2",
         "refresh/sources.json": "e554e80c72c16dc70587361804db9e0cf2716c128820b2612d5983a009b2b242",
-        "scripts/scaffold-skill.mjs": "7304795fa30834ce2e44c834e99d1cf2d07caafcdd5c30ebf0f49e13096a5d57"
+        "scripts/scaffold-skill.mjs": "8bc3314f800fcff0bf5f797fdd82424ceb16a45ac03c4ee0eebcc416dfc41b97"
       }
     }
   }