@vegastack/skills 0.16.1 → 0.16.2

package/README.md

@@ -2,17 +2,25 @@
 
 Installer for VegaStack Agent Skills — a family of self-contained skills for Claude Code, Codex, and Hermes, shipped in one integrity-checked package.
 
+Install the whole dev workflow, once per machine:
+
+```sh
+npx @vegastack/skills add --group dev-skills --global
+```
+
+`--global` is the recommended install: the skills land in your home directory and are available in every project you open. Drop it for a project-local install when a repository should carry its own copy.
+
+See what else is bundled:
+
 ```sh
-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
+npx @vegastack/skills list
 ```
 
 ## Skills in this package
 
 ### `dev-skills` — the issue-driven dev workflow
 
-Install the family with `add --group dev-skills`.
+Install the family with `add --group dev-skills --global`.
 
 | Skill | What it does |
 |---|---|
@@ -58,13 +66,46 @@ These operate on the vegastack-skills repository itself and do nothing useful in
 
 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.
 
+The ten dev-workflow skills:
+
+```sh
+npx @vegastack/skills add --group dev-skills --global
+```
+
+Everything worth installing outside this repo:
+
+```sh
+npx @vegastack/skills add --all --global
+```
+
+Check the family against the manifest:
+
 ```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
+npx @vegastack/skills verify --group dev-skills --global
 ```
 
+Uninstall it again:
+
+```sh
+npx @vegastack/skills remove --group dev-skills --global
+```
+
+## Upgrading and health checks
+
+Upgrade to the latest release. `--force` is required because `add` refuses to overwrite an installed copy that differs from the bundle rather than silently discarding local edits:
+
+```sh
+npx @vegastack/skills@latest add --group dev-skills --global --force
+```
+
+Diagnose an install — integrity across all skills, plus installed-vs-latest version:
+
+```sh
+npx @vegastack/skills doctor --global
+```
+
+Run `doctor` without `--global` from inside a project to additionally check that project's `.vegastack/dev.md` profile; the global run skips that check, since the profile is per-project by design.
+
 ## Flags
 
 | Flag | Meaning |
@@ -82,18 +123,22 @@ npx @vegastack/skills remove --group dev-skills # uninstall it again
 
 `--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).
+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.
 
 ## Agent surfaces
 
-| Agent | Project install | Global install |
+`--global` is the recommended install and the only one that can cover all three runtimes at once. `--project` is the flag default, so pass `--global` explicitly.
+
+| Agent | Global install (recommended) | Project install |
 |---|---|---|
-| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
-| Codex | `.agents/skills/` | `~/.agents/skills/` |
-| Hermes | — (Hermes discovers skills globally only) | `~/.hermes/skills/` |
+| Claude Code | `~/.claude/skills/` | `.claude/skills/` |
+| Codex | `~/.agents/skills/` | `.agents/skills/` |
+| Hermes | `~/.hermes/skills/` | — (Hermes discovers skills globally only) |
 
 `--agent hermes` therefore requires `--global`; `--agent all` on a project install covers codex+claude and prints a notice about hermes.
 
+Prefer a project install when a repository should carry its own copy — so collaborators get the same skills from a checkout, or so one project can pin a version while the rest of the machine moves on. Pick one or the other per skill rather than both: in Claude Code a personal (global) skill takes precedence over a project one, so a project-local copy would not override a global install of the same skill.
+
 ## Integrity model
 
 The package ships a checksum manifest that is verified at install and by `verify` — it proves the installed bytes match what was packed, not who published it. Publisher identity is attested separately by npm provenance, generated by the trusted-publishing release pipeline. Verify it with `npm audit signatures` or on the package's npm page.

package/package.json

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

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

@@ -5,8 +5,10 @@ TODO: one-paragraph summary for humans and agents browsing the repo. The agent e
 ## Install
 
 ```sh
-npx @vegastack/skills add {{name}}{{groupInstallLine}}
+npx @vegastack/skills add {{name}} --global
 ```
+{{groupInstallBlock}}
+`--global` installs into your home directory, where the skill is available in every project; drop it for a project-local install.
 
 ## What's in this skill
 

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

@@ -247,9 +247,12 @@ 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` : ''
+  // Only a grouped skill gets the family-install block; an ungrouped one would otherwise ship a
+  // command naming a group that does not exist. It is its own fence, not a second line in the
+  // first one: pasting a shared fence would run the alternative too.
+  const groupInstallBlock = group
+    ? `\nOr the whole ${group} family at once:\n\n\`\`\`sh\nnpx @vegastack/skills add --group ${group} --global\n\`\`\`\n`
+    : ''
 
   const outputs = templateFiles.map(([source, output]) => [source, output ?? `tests/${name}.test.ts`])
   const plan = { name, group, target, files: outputs.map(([, output]) => output), wrote: false }
@@ -264,7 +267,7 @@ export async function scaffoldSkill({ name, dir, group = null, write = false, no
         .replaceAll('{{name}}', name)
         .replaceAll('{{date}}', date)
         .replaceAll('{{validatorPath}}', validatorPath)
-        .replaceAll('{{groupInstallLine}}', groupInstallLine)
+        .replaceAll('{{groupInstallBlock}}', groupInstallBlock)
       const destination = join(staging, output)
       await mkdir(dirname(destination), { recursive: true })
       await writeFile(destination, rendered)

package/skill-integrity.json

@@ -159,7 +159,7 @@
       "files": {
         "SKILL.md": "310ac32ff4d557cc166a470fd1866060dfc5f03898e8ff3da9c406b84580742b",
         "agents/openai.yaml": "df320cf32a8db06c213f7892844dab810b7e96cfbf32502d25185d4a4167ef87",
-        "assets/templates/README.md.template": "49dccb4e9b5bdb07c254f9142502b3fd11fd5b083d8661b0ae6a567dec79de74",
+        "assets/templates/README.md.template": "74750e59514bff2211b043f6584ed75271529ff4b304e82b207c282396d3e2a1",
         "assets/templates/REFRESH.md.template": "ff86afade565d668333e7f6d0432213760fd68a62b8ba22897a8601b74c94ac0",
         "assets/templates/SKILL.md.template": "b038775f97b13b54227fe41a767a48cdaa922a93d1732f22c2d1d79bff52ca00",
         "assets/templates/openai.yaml.template": "2fbf488369825109d6cad4f17e7b729a40d9e3c43c7f01bc5dfa16361d59c086",
@@ -170,7 +170,7 @@
         "references/eval-playbook.md": "1f463dfea8d69b7022712776794369892643aa020186fe3a3707c493a6c2d4e9",
         "refresh/REFRESH.md": "695f3283b27c14accf4095137898ce1f6dc40749483c5a5705e80aa9693f08c2",
         "refresh/sources.json": "e554e80c72c16dc70587361804db9e0cf2716c128820b2612d5983a009b2b242",
-        "scripts/scaffold-skill.mjs": "849370bd152e488c66753882928cdb18db356f21468647c8e0a51ee58a385183"
+        "scripts/scaffold-skill.mjs": "d9edbe912ca20aad29afe1b0b904f85bbc4c9bfefb2c75e2986949ce00cb7fae"
       }
     }
   }