@vegastack/skills 0.12.1 → 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.12.1",
+  "version": "0.14.0",
   "description": "Installer and verifier for VegaStack Agent Skills (Claude Code, Codex, and Hermes)",
   "license": "MIT",
   "type": "module",

package/skill/dev-architect/SKILL.md

@@ -14,7 +14,9 @@ honestly. VegaStack is a 3-4 person team; every extra service is maintenance som
 Nearest neighbors: `dev-setup` writes `.vegastack/dev.md` including its `## Architecture`
 section — setup owns the file, this skill owns the judgment reading it. `dev-intake` routes
 stack-bearing approach choices here while writing a brief; `vegastack-design-system` owns
-component and token choices inside the UI.
+component and token choices inside the UI. Artifact formats — the register line included — follow
+`references/conventions.md`, the spec `dev-setup` authors and every dev-family skill ships a
+copy of.
 
 ## Every task
 
@@ -32,8 +34,8 @@ component and token choices inside the UI.
 3. Load only the references the task touches (table below). Do not bulk-read the set.
 4. Separate what is fact, what is assumption, and what is MK's recorded decision. A
    directive tagged "(inferred)" is a researched extrapolation MK has not ratified —
-   confirm on first use, and a confirmation is proposed as a register line
-   (`- DD-MM-YYYY operator (<username>) — ratified: <the directive>`); recording it drops
+   confirm on first use, and a confirmation is proposed as a register line in conventions'
+   Operator identity format, its decision text `ratified: <the directive>`; recording it drops
    the tag from the reference file in the same change, so inferred never lingers as
    ratified-in-practice. Everything untagged is his recorded decision or a verified fact.
    Never re-litigate a recorded decision to route around a blocker — surface the blocker.

package/skill/dev-chronicle/SKILL.md

@@ -7,7 +7,7 @@ description: The project's narrative record — what got built, why, and how it
 
 `.vegastack/chronicle.md` is the project's story, newest first — the answer to "what did I build here and what happened?" months later, when the operator remembers nothing. Entries are **story language for a human**, never commit-log prose: the changelog tells consumers what changed; the chronicle tells the operator what happened.
 
-Nearest neighbors: `dev-implement` writes the entries at hand-back (the write rule lives there; the format lives here); `dev-status` answers "what needs me now" — this skill answers "how did we get here". `dev-ship`'s ship-gate checks entry presence when dev.md says `chronicle: on`.
+Nearest neighbors: `dev-implement` writes the entries at hand-back (the write rule lives there; the format lives here); `dev-status` answers "what needs me now" — this skill answers "how did we get here". `dev-ship`'s ship-gate checks entry presence when dev.md says `chronicle: on`. Artifact formats follow `references/conventions.md`, the spec `dev-setup` authors and every dev-family skill ships a copy of.
 
 ## The entry — one per behavior-changing branch
 

package/skill/dev-debug/SKILL.md

@@ -7,7 +7,7 @@ description: Reproduce-first bug work. Use when given a bug to fix — "debug th
 
 The failure this skill prevents: reading code, forming one theory, and "fixing" something that was never the cause. The discipline is a hard order — **reproduce, shrink, suspect, test, prove, clean** — and each phase has a completion criterion you can check, not vibe. It runs inside dev-implement's dark mode: no operator questions; missing-artifact stops are one `handback` comment; every phase result is a ledger checkpoint.
 
-Nearest neighbors: `dev-intake`'s bug variant writes the brief this skill executes; `dev-implement` owns the surrounding build ceremony; `dev-review` judges the finished fix.
+Nearest neighbors: `dev-intake`'s bug variant writes the brief this skill executes; `dev-implement` owns the surrounding build ceremony; `dev-review` judges the finished fix. Artifact formats follow `references/conventions.md`, the spec `dev-setup` authors and every dev-family skill ships a copy of.
 
 ## Phase 1 — the red command. No red command, no theorizing.
 

package/skill/dev-implement/SKILL.md

@@ -5,7 +5,7 @@ description: Implement an approved GitHub issue end to end without further user
 
 # dev-implement
 
-One issue, one session, end to end: preflight → claim → build dark → verify → review → evidence → stop. The operator reads the result in the issue on their own time; nothing here creates a PR or merges — those are `dev-ship`, on the operator's word. Artifact formats follow the `dev-setup` skill's `references/conventions.md`; the ledger discipline lives in [ledger-and-resume](references/ledger-and-resume.md).
+One issue, one session, end to end: preflight → claim → build dark → verify → review → evidence → stop. The operator reads the result in the issue on their own time; nothing here creates a PR or merges — those are `dev-ship`, on the operator's word. Artifact formats follow `references/conventions.md`, the spec `dev-setup` authors and every dev-family skill ships a copy of; the ledger discipline lives in [ledger-and-resume](references/ledger-and-resume.md).
 
 Nearest neighbors: `dev-plan` writes the plan this skill executes task by task; `dev-review` judges the result; issues that turn out to need decisions go back through `needs-operator`, never guessed. `.vegastack/dev.md` missing → run `dev-setup` first. Read dev.md before anything; its knobs govern this skill, and the `## Architecture` section governs stack-touching choices.
 

package/skill/dev-implement/references/ledger-and-resume.md

@@ -1,6 +1,6 @@
 # Using the ledger
 
-The ledger comment's format, line vocabulary, and the resume read-order (brief → plan → ledger → `git log`, nothing else) live in the `dev-setup` skill's `references/conventions.md` — this file owns only how dev-implement **uses** them. The ledger is the build's recovery map and the operator's live progress view.
+The ledger comment's format, line vocabulary, and the resume read-order (brief → plan → ledger → `git log`, nothing else) live in `references/conventions.md`, the spec `dev-setup` authors and every dev-family skill ships a copy of — this file owns only how dev-implement **uses** them. The ledger is the build's recovery map and the operator's live progress view.
 
 ## When to checkpoint
 

package/skill/dev-intake/SKILL.md

@@ -5,7 +5,7 @@ description: Turn ideas, brainstorms, feature requests, bug reports, or SOW docu
 
 # dev-intake
 
-Requirements come in as the operator's brainstorm, feature thought, bug report, or SOW; issues go out complete enough that a fresh agent needs nothing but the URL. Every question gets asked **here** — once implementation starts, dark mode means no questions, so an under-specified issue becomes either an interruption or a guess. Artifact formats (markers, operator identity, labels, revisions) follow the `dev-setup` skill's `references/conventions.md`.
+Requirements come in as the operator's brainstorm, feature thought, bug report, or SOW; issues go out complete enough that a fresh agent needs nothing but the URL. Every question gets asked **here** — once implementation starts, dark mode means no questions, so an under-specified issue becomes either an interruption or a guess. Artifact formats (markers, operator identity, labels, revisions) follow `references/conventions.md`, the spec `dev-setup` authors and every dev-family skill ships a copy of.
 
 Nearest neighbors: `dev-plan` owns the how once a brief is approved — intake owns the what/why and the approval mechanics; `dev-implement` builds. If `.vegastack/dev.md` is missing → run `dev-setup` first, then continue.
 

package/skill/dev-plan/SKILL.md

@@ -5,7 +5,7 @@ description: Write the implementation plan for an approved issue before any code
 
 # dev-plan
 
-The planning stage: an approved brief goes in, an operator-approved plan comes out, and only then does code exist. Plans are written against the repo **as it is now** — a separate session from intake for `full-plan` issues, because code drifts between brief approval and build. Formats follow the `dev-setup` skill's `references/conventions.md` (cited by name — read it wherever dev-setup is installed).
+The planning stage: an approved brief goes in, an operator-approved plan comes out, and only then does code exist. Plans are written against the repo **as it is now** — a separate session from intake for `full-plan` issues, because code drifts between brief approval and build. Formats follow `references/conventions.md`, the spec `dev-setup` authors and every dev-family skill ships a copy of.
 
 Nearest neighbors: `dev-intake` owns the brief and its approval mechanics — this skill owns the how; `dev-implement` executes what this produces, task by task. If `.vegastack/dev.md` is missing → run `dev-setup` first.
 
@@ -37,7 +37,7 @@ Checkboxes belong to the implement session — never pre-tick them.
 
 ## Labels and approval
 
-Post the plan → flip to `needs-operator`. On the operator's "plan approved": record `<!-- vsk:v1 type=approval scope=plan -->` with their quoted words (`operator (<username>)` format), flip to `ready`, stop — building is dev-implement's.
+Post the plan → flip to `needs-operator`. On the operator's "plan approved": record the approval marker comment per conventions with `scope=plan`, quoting their words in its operator-identity format, flip to `ready`, stop — building is dev-implement's.
 
 ## The ratchet — one home, this file
 

package/skill/dev-review/SKILL.md

@@ -5,7 +5,7 @@ description: Independent review of finished implementation work — a diff again
 
 # dev-review
 
-Review is a specified system, not a vibe: fresh eyes per axis, severities with teeth, a bounded fix loop, and every dismissal on the record. The reviewer's job is findings or verified absence of findings — never praise. Formats follow the `dev-setup` skill's `references/conventions.md`; the reviewer briefs live in [dispatch-prompts](references/dispatch-prompts.md).
+Review is a specified system, not a vibe: fresh eyes per axis, severities with teeth, a bounded fix loop, and every dismissal on the record. The reviewer's job is findings or verified absence of findings — never praise. Formats follow `references/conventions.md`, the spec `dev-setup` authors and every dev-family skill ships a copy of; the reviewer briefs live in [dispatch-prompts](references/dispatch-prompts.md).
 
 Nearest neighbors: `dev-implement` invokes this per dev.md's `review:` knob and applies the findings; `dev-ship` consumes the verdict marker; `dev-plan`'s approval gate reviews plans before build — this skill reviews built work after.
 

package/skill/dev-setup/SKILL.md

@@ -65,7 +65,7 @@ Everything else — merge style, branch naming, the stop-and-ask list — takes
 | `AGENTS.md` | create it, or insert/replace only the block between `<!-- vsk-dev:start -->` and `<!-- vsk-dev:end -->` using the [agents-section template](assets/agents-section.md.template); content outside the markers is the user's and stays untouched |
 | `CLAUDE.md` | ensure its first line is `@AGENTS.md` — Claude Code does not read AGENTS.md natively and needs this import ([harness-facts](references/harness-facts.md)); create the file when absent |
 | labels | `gh label create <name> --color <hex> --description "<text>"` for the names the `labels:` knob records, skipping ones that exist; default names and creation colors ([conventions](references/conventions.md) holds meanings): state `needs-operator` FBCA04 · `needs-plan` E36209 · `ready` 0E8A16 · `working` 1D76DB · `for-operator` 5319E7; modifiers `risky` B60205 · scope `research` C5DEF5 · `quick-build` 76C7C0 · `full-plan` 2A9D8F · `epic` 24292E (only when the org has no native Epic issue type) |
-| decision register | create the file the `decisions:` knob names (default `.vegastack/decisions.md`) when missing, with a two-line header stating the format: `- DD-MM-YYYY operator (github-username) — the decision` (username via `gh api user -q .login`, fallback `git config user.name`); a project with an existing register keeps it and the knob points there |
+| decision register | create the file the `decisions:` knob names (default `.vegastack/decisions.md`) when missing, with a two-line header stating the register-line format conventions' Operator identity section defines (username via `gh api user -q .login`, fallback `git config user.name`); a project with an existing register keeps it and the knob points there |
 | guard workflows / hook files | only the ones the user said yes to in Round C |
 
 ## Step 4 — Report

package/skill/dev-ship/SKILL.md

@@ -7,7 +7,7 @@ description: Land finished work, each step only on the operator's explicit word.
 
 Gates spent only by the user's words: their words asking for a PR authorize the PR and nothing more; their words asking to merge authorize the merge. The dev.md `gates` knob sets how many actions one word covers — `3` keeps PR and merge as separate words, `2` lets one "ship it" cover both, `1` is direct-to-main (the ship word merges locally and pushes; no PR object, everything else identical). Passing checks, PR permissions, and the calendar authorize nothing by themselves.
 
-Nearest neighbor: `dev-implement` produces the `for-operator` issue with its evidence comment; ship packages and lands it. Corrections found here go back through implement's corrections loop.
+Nearest neighbor: `dev-implement` produces the `for-operator` issue with its evidence comment; ship packages and lands it. Corrections found here go back through implement's corrections loop. Artifact formats — the register line included — follow `references/conventions.md`, the spec `dev-setup` authors and every dev-family skill ships a copy of.
 
 ## Gate 1 — the PR
 
@@ -33,7 +33,7 @@ With `gates: 1` there is no PR: the same verifications run, then the ship word t
 On the user's merge instruction:
 
 - Re-check that the PR head is still the revision the evidence comment names and checks are green — a branch that moved since review gets re-verified before it lands.
-- Pending `Decision:` lines exist (issue comments, or the evidence comment's `**Decision:**` line) → name them in the merge confirmation — "merging will record: …" — so the operator's word demonstrably covers them; never append on inferred consent. On the word, append each to the register dev.md names (`decisions:` knob) in its `- DD-MM-YYYY operator (github-username) — …` format; the register is append-only and this is its moment.
+- Pending `Decision:` lines exist (issue comments, or the evidence comment's `**Decision:**` line) → name them in the merge confirmation — "merging will record: …" — so the operator's word demonstrably covers them; never append on inferred consent. On the word, append each to the register dev.md names (`decisions:` knob) in conventions' Operator identity format; the register is append-only and this is its moment.
 - A merge conflict with the default branch is corrections work: update the branch, re-verify what the update touched, and the standing merge instruction holds once checks are green again — unless the update changed behavior, or more than 7 days have passed since the word; either way, re-confirm with one sentence rather than acting on a stale instruction.
 - Merge per the dev.md `merge` knob (default `gh pr merge --squash`; `gates: 1` merges locally per the same knob and pushes). `Closes #<n>` closes the issue; confirm both happened.
 - A bot PR (Renovate, Dependabot) has no issue or evidence comment and merging it is still shipping: green checks qualify it, only the operator's explicit word — per PR or per named batch — merges it; majors and security advisories get named before their word is acted on.

package/skill/dev-status/SKILL.md

@@ -7,7 +7,7 @@ description: The operator's board — whose move is it, across every issue in th
 
 One question, answered from deterministic data: **whose move is it?** The bundled script gathers; this skill orders and narrates — it never invents state, and an unverifiable board is reported as exactly that.
 
-Nearest neighbors: `dev-chronicle` answers "how did we get here"; this skill answers "what needs whom right now". Formats read via the `dev-setup` skill's `references/conventions.md` markers.
+Nearest neighbors: `dev-chronicle` answers "how did we get here"; this skill answers "what needs whom right now". Formats read via the markers in `references/conventions.md`, the spec `dev-setup` authors and every dev-family skill ships a copy of.
 
 ## Gather
 

package/skill/skill-maintainer/SKILL.md

@@ -9,14 +9,14 @@ Maintenance skill for this repository. Every change under `skills/` must satisfy
 
 ## Operating rules
 
-1. Skill content lives only in `skills/<name>/`. Wiring lives outside it: the per-skill packaging allowlist in `packages/cli/packaging.json`, the root `README.md` skills table, and `CHANGELOG.md` (via changesets). The skillify scaffolder writes all three when creating a skill.
+1. Skill content lives only in the skill's own directory, at one of exactly two depths: `skills/<name>/` ungrouped, or `skills/<group>/<name>/` inside a group. Both are first-class; deeper is a build error. A group is a directory holding skills plus a `GROUP.md` (an H1 display title, then one blurb line), and group and skill names share one namespace and one grammar. Wiring lives outside the skill: the per-skill packaging allowlist in `packages/cli/packaging.json` — always keyed by **bare** skill name, because the packaged bundle is flat and an install command never carries a group — the root `README.md` skills table, and `CHANGELOG.md` (via changesets). The skillify scaffolder writes all three when creating a skill.
 2. Frontmatter is exactly two keys: `name` and `description`. The open spec also allows `license`, `compatibility`, and `metadata`, but this repo defaults to the minimal two; adding any other key is a policy exception needing maintainer sign-off.
 3. `name` must equal the directory name. Grammar: starts with a lowercase letter, then only lowercase letters, digits, and hyphens; no leading/trailing hyphen, no consecutive hyphens; at most 64 chars.
 4. `description`: at most 1024 chars, third person, states WHAT the skill does and WHEN to load it, trigger words front-loaded, no angle brackets. Never summarize the workflow in it — agents follow the summary and skip the body. Err slightly pushy: agents under-trigger.
 5. `SKILL.md` under 500 lines (target under 150) and roughly under 5k tokens. Detail goes to `references/`, executables to `scripts/`, templates to `assets/`. Relative links stay inside the skill, one level deep.
 6. No Claude-only body syntax anywhere in a skill: no dynamic command injection, no argument placeholders, no Claude environment-variable paths — the exact token list is in [standards](references/standards.md). Reference scripts as plain relative paths runnable from the skill directory.
 7. Never hand-edit checksums, versions, or timestamps in any `refresh/sources.json` — they must come from a refresh-runner run.
-8. Before finishing any change: `node packages/cli/scripts/validate-skill.mjs skills/<name>` and `bun test skills/<name>` (both from repo root) must pass.
+8. Before finishing any change: `node packages/cli/scripts/validate-skill.mjs <skill-dir>` and `bun test <skill-dir>` for the skill you touched, plus `node packages/cli/scripts/structure.mjs check` for the repo shape (all from repo root) must pass. `bun run check` runs the structure check as one of its stages.
 
 ## Route progressively
 
@@ -24,13 +24,26 @@ Maintenance skill for this repository. Every change under `skills/` must satisfy
 |---|---|
 | tri-harness standards: discovery paths, frontmatter rules, context budgets, install surfaces, portability rules, unverified items | [standards](references/standards.md) |
 | new skill: should-it-exist gate, scaffolding, the 8-item contract audit, behavioral evals | the `skillify` skill |
+| repo shape: groups, `GROUP.md`, the README sections, the structure check | the group workflow below |
 | release, rename, deprecate, rollback mechanics | [release ops](references/release-ops.md) |
 | this skill's own freshness contract | [REFRESH](refresh/REFRESH.md), [sources](refresh/sources.json) |
 | authoritative repo policy | `CONTRIBUTING.md` and `.vegastack/dev.md` at the repo root (release runbook, content semver, rollback) |
 
+## Workflow: create or maintain a group
+
+Groups are this skill's responsibility: the repo shape, its `GROUP.md` files, and the root README sections that mirror them. The deterministic method is `packages/cli/scripts/structure.mjs`, run from the repo root.
+
+1. **Create a group** — `node packages/cli/scripts/structure.mjs create-group <name> --title "<Display Title>" --blurb "<one line>"` prints the plan; add `--write` to apply. It writes `skills/<name>/GROUP.md` and inserts the matching `### <Display Title>` README section after the existing tables. Dry-run by default, and idempotent when re-run with the same title. Every refusal happens before it writes anything: a name that breaks the grammar, names an existing skill at either depth, or resolves to a symlink; a title another group already uses, or a different title on an existing group (that is a rename — edit `GROUP.md` and the README heading together); a title or blurb that would produce a `GROUP.md` its own reader rejects; an existing but malformed `GROUP.md`; and a README with no `## Skills` table to hold the section.
+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 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
 
-1. Run skillify's `scripts/scaffold-skill.mjs` — it creates the contract tree (`SKILL.md`, `README.md`, `refresh/`, `agents/openai.yaml`, tests and the trigger fixture) and performs the repo wiring itself: the `packages/cli/packaging.json` entry, the root README row, and the changeset (a new skill is MINOR). Fill in the README row description and changeset text it leaves as TODOs; files added after scaffolding go into the skill's `packaging.json` entry by hand (the build fails loudly on unlisted files).
+1. Run skillify's `scripts/scaffold-skill.mjs` — it creates the contract tree (`SKILL.md`, `README.md`, `refresh/`, `agents/openai.yaml`, tests and the trigger fixture) and performs the repo wiring itself: the `packages/cli/packaging.json` entry, the root README row in the right section, and the changeset (a new skill is MINOR). Pass `--group <name>` to place it in an existing group. Fill in the README row description and changeset text it leaves as placeholders; files added after scaffolding go into the skill's `packaging.json` entry by hand (the build fails loudly on unlisted files).
 2. Write frontmatter and body per operating rules 2–6; the body routes to references, it does not inline them. `skillify` owns the full authoring and eval discipline.
 3. Seed refresh baselines with the deterministic runner, never by hand — invocation in [REFRESH](refresh/REFRESH.md).
 4. Run the checks in operating rule 8.
@@ -61,7 +74,7 @@ Run this checklist before merging any skill change; per-harness detail in [stand
 - [ ] No Claude-only body syntax (token list in standards).
 - [ ] `agents/openai.yaml` present for Codex; extra files are safely ignored by the other harnesses.
 - [ ] Install surfaces respected: Claude Code `.claude/skills` (project) / `~/.claude/skills` (global); Codex `.agents/skills` (project and global); Hermes `~/.hermes/skills` **global only** — never assume Hermes project-level discovery.
-- [ ] `node packages/cli/scripts/validate-skill.mjs skills/<name>` and `bun test skills/<name>` pass.
+- [ ] `node packages/cli/scripts/validate-skill.mjs <skill-dir>` and `bun test <skill-dir>` pass, and `node packages/cli/scripts/structure.mjs check` is clean.
 
 ## Hard limits
 

package/skill/skill-maintainer/references/release-ops.md

@@ -46,14 +46,14 @@ Skill names are consumer-facing identifiers — treat a rename as a stable-ID br
 2. Update every wiring point in the same PR: the skill's entry in `packages/cli/packaging.json`, the root README skills table row, and any cross-skill or docs links.
 3. Changeset: MINOR by default — major only when the operator declares it. Either way, note the migration in `CHANGELOG.md`: copies installed under the old name are orphaned, and installer operations addressed to the old name stop resolving once the shipped manifest no longer knows it.
 4. Registry source IDs inside `refresh/sources.json` are skill-internal and unaffected, but every `affected` ref must still resolve to a real reference in the renamed tree.
-5. Re-run `node packages/cli/scripts/validate-skill.mjs skills/<new-name>` and the skill's tests — name/directory equality is validated.
+5. Re-run `node packages/cli/scripts/validate-skill.mjs <new-skill-dir>`, the skill's tests, and `node packages/cli/scripts/structure.mjs check` — name/directory equality is validated, and the structure check catches a README row left pointing at the old path.
 
 ## Deprecate / remove a skill
 
 1. Announce deprecation in the root README table and `CHANGELOG.md` at least one release before removal when practical.
-2. Removal: delete `skills/<name>/`, remove its allowlist entries and README row, MAJOR changeset with migration notes.
+2. Removal: delete the skill's directory, remove its allowlist entries and README row, MAJOR changeset with migration notes. Removing the last skill from a group also removes the group's `GROUP.md` and its README section.
 3. Removing a skill in a new MAJOR does **not** deprecate previously published package versions — `npm deprecate` only versions that are themselves broken.
 
 ## Refresh branches
 
-Branches named `refresh/**` are reserved for the automated freshness loop and are CI-restricted to `skills/*/refresh/`. Human content changes go on normal branches. Never hand-edit checksums/versions/timestamps anywhere — CI re-fetches claimed baselines, so hand-edited values cannot merge.
+Branches named `refresh/**` are reserved for the automated freshness loop and are CI-restricted to refresh metadata at either legal depth (`skills/<name>/refresh/` and `skills/<group>/<name>/refresh/`). Human content changes go on normal branches. Never hand-edit checksums/versions/timestamps anywhere — CI re-fetches claimed baselines, so hand-edited values cannot merge.

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/SKILL.md

@@ -5,7 +5,7 @@ description: Repo-local skill factory and auditor for the vegastack-skills monor
 
 # Skillify
 
-Turn a raw workflow into a properly-skilled unit of this monorepo, or audit an existing `skills/<name>/` tree against the repo contract (CONTRIBUTING.md, "Adding a new skill"). Skillify is repo-only: it creates and scores skills in this repository, not anywhere else. Deep wiring/release mechanics belong to `skill-maintainer`; cross-reference it rather than restating it.
+Turn a raw workflow into a properly-skilled unit of this monorepo, or audit an existing skill tree — `skills/<name>/` or `skills/<group>/<name>/` — against the repo contract (CONTRIBUTING.md, "Adding a new skill"). Skillify is repo-only: it creates and scores skills in this repository, not anywhere else. Deep wiring/release mechanics belong to `skill-maintainer`; cross-reference it rather than restating it.
 
 ## The contract checklist
 
@@ -41,7 +41,7 @@ Scope upper bound: **one skill = one capability = one coherent trigger family.**
 For an existing skill, score the checklist against the actual tree and stop with the verdict:
 
 ```
-Skill: <name>            Path: skills/<name>/
+Skill: <name>            Path: skills/<name>/ | skills/<group>/<name>/
 Score: <passed>/8        Verdict: <verdict>
 Missing: <item>: <one-line evidence> ...
 ```
@@ -94,8 +94,9 @@ Now that quality is proven:
 ## Phase 6 — Verify
 
 ```sh
-node packages/cli/scripts/validate-skill.mjs skills/<name>
-bun test skills/<name>
+node packages/cli/scripts/validate-skill.mjs <skill-dir>
+bun test <skill-dir>
+node packages/cli/scripts/structure.mjs check
 bun run check
 ```
 

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/assets/templates/skill.test.ts.template

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'bun:test'
 import { readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
-import { validateSkill } from '../../../packages/cli/scripts/validate-skill.mjs'
+import { validateSkill } from '{{validatorPath}}'
 
 const skillRoot = resolve(import.meta.dir, '..')
 

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

@@ -1,7 +1,12 @@
 #!/usr/bin/env node
-// Scaffold a new skill tree at skills/<name>/ from skillify's templates.
+// Scaffold a new skill tree at skills/<name>/ (or skills/<group>/<name>/) from skillify's
+// templates.
 //
-//   node scripts/scaffold-skill.mjs <skill-name> --dir <repo-root> [--write] [--json]
+//   node scripts/scaffold-skill.mjs <skill-name> --dir <repo-root> [--group <group>] [--write] [--json]
+//
+// --group places the skill in an existing group. Creating a group is skill-maintainer's job
+// (packages/cli/scripts/structure.mjs create-group), so an unknown group is refused rather than
+// invented: a mistyped group must never bring a stray family into existence.
 //
 // Dry-run by default: prints the plan (files that would be created plus the
 // wiring actions that would be performed) and creates nothing. --write stages
@@ -9,14 +14,14 @@
 // refusing existing directories and symlinks, then performs the repo wiring
 // itself: packaging.json entry, root README row, changeset. Exit codes: 0 ok,
 // 1 refusal or failure, 2 usage error.
-import { lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const here = dirname(fileURLToPath(import.meta.url))
 const templatesRoot = resolve(here, '..', 'assets', 'templates')
 
-// Template file -> output path inside skills/<name>/ (null = tests/<name>.test.ts).
+// Template file -> output path inside the skill (null = tests/<name>.test.ts).
 export const templateFiles = [
   ['SKILL.md.template', 'SKILL.md'],
   ['README.md.template', 'README.md'],
@@ -44,6 +49,31 @@ export function validateName(name) {
   return null
 }
 
+// This script ships inside the skillify skill, so it must stay dependency-free and cannot import
+// the repo's lib/skills.mjs. Deliberate small duplication of its GROUP.md title read; the two are
+// kept honest by structure.mjs check, which fails when the README and GROUP.md disagree.
+export function groupTitle(markdown) {
+  const lines = markdown.split('\n')
+  const headingIndex = lines.findIndex(line => /^#\s+\S/.test(line))
+  if (headingIndex === -1) return null
+  const title = lines[headingIndex].replace(/^#\s+/, '').trim()
+  const blurb = lines.slice(headingIndex + 1).find(line => line.trim() !== '')?.trim()
+  if (!title || !blurb || blurb.startsWith('#')) return null
+  return title
+}
+
+// Two-level scan mirroring lib/skills.mjs's discovery. Duplicated for the same reason as
+// groupTitle: this script ships inside the skillify skill and cannot import repo tooling.
+async function findSkillAnywhere(skillsRoot, name) {
+  if ((await entryAt(join(skillsRoot, name, 'SKILL.md')))?.isFile()) return join(skillsRoot, name)
+  for (const entry of await readdir(skillsRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    const path = join(skillsRoot, entry.name, name)
+    if ((await entryAt(join(path, 'SKILL.md')))?.isFile()) return path
+  }
+  return null
+}
+
 async function entryAt(path) {
   try {
     return await lstat(path)
@@ -73,21 +103,50 @@ async function wirePackaging(repoRoot, name, write) {
   return { step: 'packaging.json entry', status: 'done' }
 }
 
-// Inserts a row for the new skill at the end of the root README's Skills table.
-async function wireReadme(repoRoot, name, write) {
+// Resolves where a row belongs: the end of the ungrouped table, or of the table under the
+// group's "### <title>" section. Both windows are bounded by the "## Skills" region, so a row can
+// never land in a neighbouring family's table or in an unrelated table elsewhere in the README.
+// Returns null when the README has no usable table, so callers can refuse before writing rather
+// than report a "skipped:" success afterwards.
+export function findRowInsertion(lines, group, groupHeading) {
+  const regionStart = lines.findIndex(line => /^##\s+Skills\s*$/.test(line))
+  if (regionStart < 0) return null
+  const afterRegion = lines.findIndex((line, index) => index > regionStart && /^##\s+/.test(line) && !/^###/.test(line))
+  const regionEnd = afterRegion < 0 ? lines.length : afterRegion
+
+  let from = regionStart
+  let to = regionEnd
+  if (group) {
+    from = lines.findIndex((line, index) => index > regionStart && index < regionEnd && line.trim() === `### ${groupHeading}`)
+    if (from < 0) return { missingSection: true }
+    const next = lines.findIndex((line, index) => index > from && index < regionEnd && /^###\s+/.test(line))
+    to = next < 0 ? regionEnd : next
+  } else {
+    const firstSection = lines.findIndex((line, index) => index > regionStart && index < regionEnd && /^###\s+/.test(line))
+    if (firstSection >= 0) to = firstSection
+  }
+
+  const header = lines.findIndex((line, index) => index >= from && index < to && /^\| *Skill *\|/.test(line))
+  if (header < 0 || !/^\|[ -]*---/.test(lines[header + 1] ?? '')) return null
+  let last = header + 1
+  while (last + 1 < to && lines[last + 1]?.startsWith('|')) last += 1
+  return { index: last }
+}
+
+async function wireReadme(repoRoot, name, group, groupHeading, write) {
   const path = join(repoRoot, 'README.md')
   if (!(await entryAt(path))?.isFile()) return { step: 'root README row', status: 'skipped: README.md not found' }
   const body = await readFile(path, 'utf8')
-  if (body.includes(`](skills/${name}/)`)) return { step: 'root README row', status: 'skipped: row already exists' }
+  const relativePath = group ? `${group}/${name}` : name
+  if (body.includes(`](skills/${relativePath}/)`)) return { step: 'root README row', status: 'skipped: row already exists' }
   const lines = body.split('\n')
-  const header = lines.findIndex(line => /^\| *Skill *\|/.test(line))
-  if (header < 0 || !/^\|[ -]*---/.test(lines[header + 1] ?? '')) {
-    return { step: 'root README row', status: 'skipped: Skills table not found' }
-  }
-  let last = header + 1
-  while (lines[last + 1]?.startsWith('|')) last += 1
+
+  const target = findRowInsertion(lines, group, groupHeading)
+  if (target?.missingSection) throw new Error(`README.md has no "### ${groupHeading}" section for group "${group}" - create it with structure.mjs create-group`)
+  if (!target) return { step: 'root README row', status: 'skipped: Skills table not found' }
+  const last = target.index
   if (!write) return { step: 'root README row', status: 'planned' }
-  const row = `| [${name}](skills/${name}/) | TODO: one-line description | [Walkthrough](skills/${name}/README.md) · [SKILL.md](skills/${name}/SKILL.md) |`
+  const row = `| [${name}](skills/${relativePath}/) | TODO: one-line description | [Walkthrough](skills/${relativePath}/README.md) · [SKILL.md](skills/${relativePath}/SKILL.md) |`
   lines.splice(last + 1, 0, row)
   await writeAtomic(path, lines.join('\n'))
   return { step: 'root README row', status: 'done' }
@@ -104,15 +163,24 @@ async function wireChangeset(repoRoot, name, write) {
   return { step: 'changeset', status: 'done' }
 }
 
-export async function wireSkill({ name, repoRoot, write = false }) {
+export async function wireSkill({ name, repoRoot, group = null, groupHeading = null, write = false }) {
+  // groupHeading is an optimisation for scaffoldSkill, which has already read GROUP.md. A caller
+  // using the documented { name, repoRoot, group, write } shape gets it derived here rather than
+  // a row addressed to "### null".
+  if (group && !groupHeading) {
+    const doc = await entryAt(join(repoRoot, 'skills', group, 'GROUP.md'))
+    if (!doc?.isFile()) throw new Error(`Group "${group}" has no GROUP.md - every group carries one`)
+    groupHeading = groupTitle(await readFile(join(repoRoot, 'skills', group, 'GROUP.md'), 'utf8'))
+    if (!groupHeading) throw new Error(`skills/${group}/GROUP.md is malformed - it needs an H1 title followed by one non-empty blurb line`)
+  }
   return [
     await wirePackaging(repoRoot, name, write),
-    await wireReadme(repoRoot, name, write),
+    await wireReadme(repoRoot, name, group, groupHeading, write),
     await wireChangeset(repoRoot, name, write),
   ]
 }
 
-export async function scaffoldSkill({ name, dir, write = false, now = new Date() }) {
+export async function scaffoldSkill({ name, dir, group = null, write = false, now = new Date() }) {
   const nameError = validateName(name)
   if (nameError) throw new Error(`Invalid skill name ${JSON.stringify(name ?? null)}: ${nameError}`)
   if (!dir) throw new Error('--dir <repo-root> is required')
@@ -123,19 +191,74 @@ export async function scaffoldSkill({ name, dir, write = false, now = new Date()
   if (!skillsEntry || !skillsEntry.isDirectory()) {
     throw new Error(`${skillsRoot} is not a real directory - point --dir at the vegastack-skills repo root`)
   }
-  const target = join(skillsRoot, name)
+
+  // A group must already exist and carry a well-formed GROUP.md; creating one is
+  // skill-maintainer's structure.mjs create-group, never a side effect of scaffolding a skill.
+  let groupHeading = null
+  if (group) {
+    const groupError = validateName(group)
+    if (groupError) throw new Error(`Invalid group name ${JSON.stringify(group)}: ${groupError}`)
+    const groupRoot = join(skillsRoot, group)
+    const groupEntry = await entryAt(groupRoot)
+    if (!groupEntry || !groupEntry.isDirectory()) {
+      throw new Error(`Group "${group}" does not exist at ${groupRoot} - create it first with: node packages/cli/scripts/structure.mjs create-group ${group} --title <title> --blurb <blurb> --write`)
+    }
+    const groupDoc = await entryAt(join(groupRoot, 'GROUP.md'))
+    if (!groupDoc?.isFile()) throw new Error(`Group "${group}" has no GROUP.md - every group carries one; see skill-maintainer's group workflow`)
+    groupHeading = groupTitle(await readFile(join(groupRoot, 'GROUP.md'), 'utf8'))
+    if (!groupHeading) throw new Error(`skills/${group}/GROUP.md is malformed - it needs an H1 title followed by one non-empty blurb line`)
+  }
+
+  const parent = group ? join(skillsRoot, group) : skillsRoot
+  const target = join(parent, name)
   if (await entryAt(target)) throw new Error(`Refusing to scaffold: ${target} already exists`)
 
+  // Skill names are unique across the whole tree, not just within one directory: the packaged
+  // bundle is flat, so a duplicate at the other depth would break the next build. Checked here,
+  // before anything is written, rather than left to that build.
+  const clash = await findSkillAnywhere(skillsRoot, name)
+  if (clash) throw new Error(`Refusing to scaffold: a skill named "${name}" already exists at ${clash} - the packaged bundle is flat, so skill names are unique across the whole tree`)
+
+  // 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 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 (!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`)
+    }
+  }
+
+  // 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, target, files: outputs.map(([, output]) => output), wrote: false }
-  if (!write) return { ...plan, wiring: await wireSkill({ name, repoRoot }) }
+  const plan = { name, group, target, files: outputs.map(([, output]) => output), wrote: false }
+  if (!write) return { ...plan, wiring: await wireSkill({ name, repoRoot, group, groupHeading }) }
 
   const date = now.toISOString().slice(0, 10)
-  const staging = await mkdtemp(join(skillsRoot, `.${name}.scaffold-`))
+  const staging = await mkdtemp(join(parent, `.${name}.scaffold-`))
   try {
     for (const [source, output] of outputs) {
       const body = await readFile(join(templatesRoot, source), 'utf8')
-      const rendered = body.replaceAll('{{name}}', name).replaceAll('{{date}}', date)
+      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)
@@ -146,11 +269,11 @@ export async function scaffoldSkill({ name, dir, write = false, now = new Date()
     await rm(staging, { recursive: true, force: true })
     throw error
   }
-  return { ...plan, wrote: true, wiring: await wireSkill({ name, repoRoot, write: true }) }
+  return { ...plan, wrote: true, wiring: await wireSkill({ name, repoRoot, group, groupHeading, write: true }) }
 }
 
 function parseArguments(argv) {
-  const options = { name: undefined, dir: undefined, write: false, json: false }
+  const options = { name: undefined, dir: undefined, group: null, write: false, json: false }
   const rest = [...argv]
   while (rest.length) {
     const flag = rest.shift()
@@ -158,6 +281,10 @@ function parseArguments(argv) {
       const value = rest.shift()
       if (value === undefined || value.startsWith('-')) throw new Error('--dir requires a value')
       options.dir = value
+    } else if (flag === '--group') {
+      const value = rest.shift()
+      if (value === undefined || value.startsWith('-')) throw new Error('--group requires a value')
+      options.group = value
     } else if (flag === '--write') options.write = true
     else if (flag === '--json') options.json = true
     else if (flag.startsWith('-')) throw new Error(`Unknown option: ${flag}`)
@@ -165,7 +292,7 @@ function parseArguments(argv) {
     else throw new Error(`Unexpected argument: ${flag}`)
   }
   if (!options.name || !options.dir) {
-    throw new Error('Usage: node scripts/scaffold-skill.mjs <skill-name> --dir <repo-root> [--write] [--json]')
+    throw new Error('Usage: node scripts/scaffold-skill.mjs <skill-name> --dir <repo-root> [--group <group>] [--write] [--json]')
   }
   return options
 }

package/skill-integrity.json

@@ -2,8 +2,10 @@
   "schemaVersion": 2,
   "skills": {
     "dev-architect": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
-        "SKILL.md": "3b0b6f2d18f63f644bb396be9fdd7fbc8c8473c0b29190741c9623407bf82cc3",
+        "SKILL.md": "74150dde2d3c83598769a4c9f8cd295a7496d9eb9a5e920a29cba8464eb58128",
         "agents/openai.yaml": "99023b056d5c568ff3acc059e5bb7a4e6cfa5261cd0d35a525407f9e159de562",
         "references/ai-agents.md": "565e5d480f7e342adf43f9b864ab4cb66b7e513f0ea676de66909fe0ccd95988",
         "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
@@ -20,8 +22,10 @@
       }
     },
     "dev-chronicle": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
-        "SKILL.md": "e43f50fc570992de0766d4e569693babd05cde08d2e1c271c267df6b7552ac89",
+        "SKILL.md": "23c6266758726d6435de38cb0cc142a94a0b55f2329f7ab6404e42fa5d0dee3a",
         "agents/openai.yaml": "765b12e17b7fce88c53ca0fae735bf0efceb843cc3703b91bc1801ab5cac06b4",
         "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
         "refresh/REFRESH.md": "760e66642eec426cd5ab2319613e817adf5bbd7b64c8eaa22dd13497351bf9c1",
@@ -29,8 +33,10 @@
       }
     },
     "dev-debug": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
-        "SKILL.md": "62f86b8b88a66c6e8f44eba434fdc8b8dc044deda814cb9a2d1e8ec0dee79538",
+        "SKILL.md": "38ba9e67c00925f4e4738be333dc398218008df929fcf17b61398966ce4deee1",
         "agents/openai.yaml": "4aa52b5c620b0bf4de7f1609867956ce762d83dc4297ab5670a68c206ae63075",
         "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
         "references/loop-ladder.md": "ddcb45ec2241bc5dc25936348074cdcc8f9af848e90b363351a7faf97007c256",
@@ -39,11 +45,13 @@
       }
     },
     "dev-implement": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
-        "SKILL.md": "8be83688920875aa16566d20497b2a249a53de6f2fceeae463825154e064e502",
+        "SKILL.md": "724f6bc83467c28dc61a45161d3ffba7fecef2712eff3333bdf40d762731db44",
         "agents/openai.yaml": "1abab383deca54d32749fd9156f9a6211fe96e02e0166dc8a16ff8459ac31b74",
         "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
-        "references/ledger-and-resume.md": "46bd4ad38eb70376d9ad36ac80269abc337c12e692e2b7de6483584f1003346a",
+        "references/ledger-and-resume.md": "5e3deae2af67735940564e04adcbc23c0c0dc86da2f6c80d68b8c1207c8f5900",
         "refresh/REFRESH.md": "7b854109d897b78b3055bf1ab89517afdca65c12eb65a4d009141e3ee11cf58f",
         "refresh/sources.json": "7bd883e5b3512e236a909ad6ff20c97f3555785867c31fd728256c7c2c514c74",
         "scripts/evidence-check.mjs": "9a360e6c5460d46b271b28457ee6be92f165c54c771c2dc6860c4a52e6890a9a",
@@ -52,8 +60,10 @@
       }
     },
     "dev-intake": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
-        "SKILL.md": "b5d89453176ad23c047fd38e38199c682c358df0468c9082edd8a6e34e6f229f",
+        "SKILL.md": "4754383297822d3f6e0ad8a391ac76499d83c74f424b90b928199d6c2649dc71",
         "agents/openai.yaml": "5473d2d3efffc518c07dfa8e6788c6535a5054ceca696119c5856ad265ef5581",
         "references/brief-template.md": "906c6b805f9737755f4d4b34fd16d4296924b95039379ea86bc59973949d9823",
         "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
@@ -63,8 +73,10 @@
       }
     },
     "dev-plan": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
-        "SKILL.md": "3c38b3f78f0f03d04370ea91aad99966fca5313fbe2919f44187d7c585c87866",
+        "SKILL.md": "eb2ce1542b1769fa6e7d9dc7be9fc9c84df8b353ded16e39e1e578ee372c1aca",
         "agents/openai.yaml": "4b9ccc9870b4eafb73c1bc4492a0b5a530097bbcbae11dbf3235160f4f05587b",
         "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
         "references/plan-format.md": "a915acce2fc447e685077756aeb94fdc3f84139800703034987b8409971493db",
@@ -74,8 +86,10 @@
       }
     },
     "dev-review": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
-        "SKILL.md": "00c1b86038ef8497480b440ee490019702013692c8ac5266a8340464745e0cf5",
+        "SKILL.md": "be32aa737cfd3309f7413407470ebffeedf6284f0f98cef6ae185c478c896c26",
         "agents/openai.yaml": "3f35d3dc60f179d4ac2526997c4d10173ba3018d06f0dbe77e209ce2978fa702",
         "assets/review-known-patterns.md.template": "2fe7dbcc4d0eeac542e7624111130265b2bb4f08806f20dbd2087842cbb22b5c",
         "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
@@ -87,8 +101,10 @@
       }
     },
     "dev-setup": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
-        "SKILL.md": "bb82e375b580954a5dae1044c2372e574a954bc8c14f79e4854aa8e39de98dc4",
+        "SKILL.md": "d8eb7741983998f56ff8aff52f66ec3887b7fd055c26cc232e1ff41da6fab7c1",
         "agents/openai.yaml": "be790c04fdf910e71642cfadf1a7c07c217bf7fad18581610feb4c31a79651f2",
         "assets/agents-section.md.template": "6c9591d50f73e1e05e78c8969c7836767432cf32487af7205b2cb9f4a410440e",
         "assets/dev-profile.md.template": "45b2a90fc7aee39e7b975151f1281787d6dd4d3b7d5f9df5b8f282d020a1d7a9",
@@ -100,8 +116,10 @@
       }
     },
     "dev-ship": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
-        "SKILL.md": "25cfb1eb2937cd33824f77cf008113406a54787b03edadc45762e688b1d3b5e0",
+        "SKILL.md": "aa3bd8b0a1ac076309190f2008896f24ebe1216352872ff428c1b88b55c06e65",
         "agents/openai.yaml": "8f18cfd505131557eb4c9f7b7f54e9069f787be4c162403fc30253eed49a06ea",
         "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
         "references/runbook.md": "5cbf3f89b2fcad1a2873f729b6c1a027566344d5dffcb799ed1d039e76b3e679",
@@ -111,8 +129,10 @@
       }
     },
     "dev-status": {
+      "group": "dev-skills",
+      "repoOnly": false,
       "files": {
-        "SKILL.md": "42d1dfbda5602d68b114060c83cc9f61e14b9059d09a2b436218afdf0f009706",
+        "SKILL.md": "56415c2f69bb1a2fcb488b9846a20e632eb902b05c5b2b58ae9206d3eaffd77b",
         "agents/openai.yaml": "72435947f5afef0c8a2c170e987b14fe6057b174318c16b6b538ae8d129791fb",
         "references/conventions.md": "815f5189daff1b71b3251b7a57de183a4a387fcdedbd5875e673d5bd3de398fc",
         "refresh/REFRESH.md": "52aee9bae64d8342e127704d1db282e43ed57c101148727bf10172d6cb975bfa",
@@ -121,31 +141,35 @@
       }
     },
     "skill-maintainer": {
+      "group": "repo-tooling",
+      "repoOnly": true,
       "files": {
-        "SKILL.md": "0947155a4e7c87d6f200a1e565013beac8e3093b17e3216d6901a20be863bb21",
+        "SKILL.md": "1733d2f1fa756cbb37c74ecee0d48ddd9abf31155c4dd72eba10af31c33d88ec",
         "agents/openai.yaml": "0b89d4e6416cf20b448f5322f3d7433cfde333d2b4a05b42ed53db3759701fb4",
-        "references/release-ops.md": "14ef97980a81a4a767ad6888122a08e07f40602fd7673fcabf2d6af85799d4b0",
-        "references/standards.md": "3646d0dd0560a87b333f70febf670b093c89b35111132cdb641b763bf184b02f",
-        "refresh/REFRESH.md": "3955bff5f0a14c83336a73cdbd07ba18d9398996934af87fac4454206cd14023",
+        "references/release-ops.md": "b5df1922b34daf7751c332c019a0ea770a48283aaa2e25f83c9851bef47999b1",
+        "references/standards.md": "0dd7fcb6e2f0dd3aae7167227d7ec085481bc629aa027af35d48e5d0f7b9df86",
+        "refresh/REFRESH.md": "d3ba44be2c264b849d8a815111c049e782720428d5d0c5cea23998b05e50d58f",
         "refresh/sources.json": "4977152381d53555196ac676f95e61b4eaa301309a17560da5cda722010eb80f"
       }
     },
     "skillify": {
+      "group": "repo-tooling",
+      "repoOnly": true,
       "files": {
-        "SKILL.md": "8469080261cf1911d054fb5b08cdec170566f5fcd07de6fa374d847d1b9d87aa",
+        "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",
-        "assets/templates/skill.test.ts.template": "7fead4f3a45a0b781bbe30b2686ca81bb432eb1ad92bf0d12b4db87ba998a32c",
+        "assets/templates/skill.test.ts.template": "9ca1e63ba6566350284c742e0e7958816d571fa57bd979b2c6a09104a0d9477c",
         "assets/templates/sources.json.template": "39449adcef33e6ffbc369a342bbfd1f299e9327157fe873991e1ed8d243288d1",
         "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": "108ffae496120777ee40414e058aa7e0cdfbfee81766f7124083bd36eaf1b727"
+        "scripts/scaffold-skill.mjs": "8bc3314f800fcff0bf5f797fdd82424ceb16a45ac03c4ee0eebcc416dfc41b97"
       }
     }
   }