@vibe-agent-toolkit/vat-development-agents 0.1.20 → 0.1.21-rc.2

package/dist/generated/resources/skills/vat-skills-distribution.js

@@ -3,17 +3,22 @@
  */
 
 export const meta = {
-  name: "vibe-agent-toolkit:skills-distribution",
+  name: "distribution",
   description: "Use when setting up vat build, configuring plugin distribution for the Claude ecosystem (marketplace, plugins, managed settings), npm publishing with postinstall hooks, or vat verify orchestration. Covers the full pipeline from skill source to installed plugin."
 };
 
-export const text = "\n# VAT Distribution: Build, Publish & Install\n\n## Overview\n\nVAT distributes skills as **Claude plugins** via npm packages. The pipeline:\n\n1. \`vat build\` compiles SKILL.md sources into plugin artifacts\n2. \`npm publish\` pushes the package to a registry\n3. \`npm install\` triggers a postinstall hook that registers the plugin in Claude\'s plugin system\n\nSkills installed this way appear in Claude Code as \`/plugin-name:skill-name\`.\n\n## Project Structure\n\n\`\`\`\nmy-project/\n├── package.json                    ← vat.skills + postinstall hook + publishConfig\n├── vibe-agent-toolkit.config.yaml  ← skills: + claude: config\n├── resources/\n│   └── skills/\n│       └── SKILL.md\n└── dist/                           ← generated by vat build\n    ├── skills/my-skill/            ← packaged skill\n    └── .claude/plugins/marketplaces/\n        └── my-marketplace/plugins/my-plugin/\n            ├── .claude-plugin/plugin.json\n            └── skills/my-skill/SKILL.md\n\`\`\`\n\n## Step 1: package.json Configuration\n\n\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"version\": \"1.0.0\",\n  \"vat\": {\n    \"version\": \"1.0\",\n    \"skills\": [\"my-skill\"]\n  },\n  \"scripts\": {\n    \"build:vat\": \"vat build\",\n    \"postinstall\": \"vat skills install --npm-postinstall || exit 0\"\n  },\n  \"files\": [\"dist\", \"README.md\"],\n  \"publishConfig\": {\n    \"registry\": \"https://registry.npmjs.org\"\n  }\n}\n\`\`\`\n\nThe \`vat.skills\` array contains skill name strings for npm discoverability. Skill source paths and packaging config live in \`vibe-agent-toolkit.config.yaml\` (see Step 2).\n\nFor private GitHub Packages registry:\n\`\`\`json\n\"publishConfig\": {\n  \"registry\": \"https://npm.pkg.github.com\",\n  \"access\": \"restricted\"\n}\n\`\`\`\n\nUsers installing from GitHub Packages need \`.npmrc\` with the scope registry and auth token:\n\`\`\`\n@myorg:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n\`\`\`\n\n## Step 2: vibe-agent-toolkit.config.yaml\n\n\`\`\`yaml\nversion: 1\n\nskills:\n  include:\n    - \"resources/skills/**/SKILL.md\"\n\nclaude:\n  marketplaces:\n    my-marketplace:                   # org/publisher identity\n      owner:\n        name: My Organization\n      plugins:\n        - name: my-plugin             # installable unit\n          description: My plugin description\n          skills: \"*\"                  # all discovered skills\n\`\`\`\n\nThe \`skills:\` section discovers SKILL.md files via include/exclude globs. The \`claude:\` section defines how skills are packaged into plugins. Each marketplace has \`owner\` and \`plugins\` fields (strict schema — no extra fields).\n\n**Naming convention:** marketplace = org identity (e.g. \`acme\`), plugin = this package\n(e.g. \`acme-tools\`). Registers as \`my-plugin@my-marketplace\` in Claude\'s plugin registry.\n\n### Multiple skills in one package\n\nList all skills in \`vat.skills\` for npm discoverability:\n\n\`\`\`json\n\"vat\": {\n  \"version\": \"1.0\",\n  \"skills\": [\"my-linting\", \"my-testing\"]\n}\n\`\`\`\n\nUse a selector in the plugin config to include matching skills:\n\n\`\`\`yaml\nplugins:\n  - name: my-plugin\n    description: Linting and testing skills\n    skills:\n      - \"my-linting\"\n      - \"my-testing\"\n\`\`\`\n\nOr use \`\"*\"\` to include all discovered skills in the plugin.\n\n## Step 3: Build\n\n\`\`\`bash\nvat build        # skills phase then claude phase\nvat verify       # validates resources + skills + claude artifacts\n\`\`\`\n\n### What vat build does\n\nTwo phases, run in dependency order:\n\n1. **\`vat skills build\`** — reads \`vibe-agent-toolkit.config.yaml skills:\` section, discovers SKILL.md files via include/exclude globs, compiles each into \`dist/skills/<name>/\`\n2. **\`vat claude build\`** — reads \`vibe-agent-toolkit.config.yaml claude:\` section, wraps built skills into \`dist/.claude/plugins/marketplaces/<mp>/plugins/<plugin>/\` structure with \`.claude-plugin/plugin.json\`\n\nIndividual commands still work:\n\`\`\`bash\nvat skills build       # skills phase only\nvat claude build       # claude plugin phase only (requires skills already built)\nvat claude verify      # validate plugin artifacts only\n\`\`\`\n\n## Step 4: Publish\n\n\`\`\`bash\nnpm publish --tag next    # RC/pre-release\nnpm publish               # stable release\n\`\`\`\n\n## Step 5: User Install\n\n\`\`\`bash\nvat skills install npm:@myorg/my-skills\n\`\`\`\n\nOr via standard npm install (postinstall hook triggers automatically):\n\`\`\`bash\nnpm install -g @myorg/my-skills\n\`\`\`\n\n### How plugin installation works\n\nWhen \`npm install\` runs the postinstall hook (\`vat skills install --npm-postinstall\`):\n\n- VAT detects \`dist/.claude/plugins/marketplaces/\` directory in the installed package\n- Copies the plugin tree to Claude\'s plugin directory (dumb recursive copy)\n- Writes to these locations:\n  1. \`~/.claude/plugins/marketplaces/<marketplace>/plugins/<plugin>/\` — plugin files\n  2. \`~/.claude/plugins/known_marketplaces.json\` — marketplace registry\n  3. \`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/\` — version cache\n  4. \`~/.claude/plugins/installed_plugins.json\` — installation record\n  5. \`~/.claude/settings.json\` \`enabledPlugins\` — activates the plugin\n\nIf no \`dist/.claude/plugins/marketplaces/\` directory exists (package wasn\'t built before publish): a guidance message is emitted and the hook exits 0. The publisher must run \`vat build\` and re-publish.\n\nSkills are then available in Claude Code as \`/plugin-name:skill-name\`.\n\n## managed-settings.json Validation (Enterprise)\n\n\`\`\`yaml\nclaude:\n  managedSettings: managed-settings.json\n\`\`\`\n\n\`vat verify\` validates this file against the ManagedSettings schema. Catches typos and schema errors before deployment. Does NOT deploy the file — deployment is a separate concern.\n\n## --target claude-web (ZIP Upload)\n\nFor uploading skills directly to \`claude.ai/settings/capabilities\`:\n\n\`\`\`bash\nvat skills package ./SKILL.md -o ./dist/ --target claude-web\n\`\`\`\n\nProduces a ZIP:\n\`\`\`\nmy-skill.zip\n└── my-skill/\n    ├── SKILL.md             # skill definition (required)\n    ├── scripts/             # executable code (.mjs, .py, .sh) — optional\n    ├── references/          # markdown reference material — optional\n    └── assets/              # static data, templates, config — optional\n\`\`\`\n\nConfigure source path mappings in \`vibe-agent-toolkit.config.yaml\`:\n\`\`\`yaml\nskills:\n  include:\n    - \"skills/**/SKILL.md\"\n  config:\n    my-skill:\n      claudeWebTarget:\n        scripts: [\"./src/helpers/**/*.ts\"]\n        assets: [\"./assets/**\"]\n\`\`\`\n\nTypeScript files in \`scripts\` are tree-shaken and compiled to standalone \`.mjs\`.\n\n## Quick Reference\n\n| Task | Command |\n|---|---|\n| Build everything | \`vat build\` |\n| Verify everything | \`vat verify\` |\n| Build skills only | \`vat skills build\` |\n| Build claude artifacts only | \`vat claude build\` |\n| Verify claude artifacts only | \`vat claude verify\` |\n| Install from npm | \`vat skills install npm:@org/pkg\` |\n| Package for claude.ai upload | \`vat skills package ./SKILL.md -o ./dist/ --target claude-web\` |\n";
+export const text = "\n# VAT Distribution: Build, Publish & Install\n\n## Scope\n\nThis skill covers the **file-based install method for Claude Code CLI** (\`~/.claude/plugins/\`).\nThis is the only install method VAT currently supports.\n\nFor the full install landscape — Claude Desktop paths, enterprise CI deployment,\nAnthropic Cloud org management, MDM integration, and the \`vat plugins uninstall\`\ndesign — see [Install & Uninstall Architecture](vat-install-architecture.md).\n\n## Overview\n\nVAT distributes skills as **Claude plugins** via npm packages. The pipeline:\n\n1. \`vat build\` compiles SKILL.md sources into plugin artifacts\n2. \`npm publish\` pushes the package to a registry\n3. \`npm install\` triggers a postinstall hook that registers the plugin in Claude Code\'s plugin system\n\nSkills installed this way appear in Claude Code as \`/plugin-name:skill-name\`.\n\n## Project Structure\n\n\`\`\`\nmy-project/\n├── package.json                    ← vat.skills + postinstall hook + publishConfig\n├── vibe-agent-toolkit.config.yaml  ← skills: + claude: config\n├── resources/\n│   └── skills/\n│       └── SKILL.md\n└── dist/                           ← generated by vat build\n    ├── skills/my-skill/            ← packaged skill\n    └── .claude/plugins/marketplaces/\n        └── my-marketplace/plugins/my-plugin/\n            ├── .claude-plugin/plugin.json\n            └── skills/my-skill/SKILL.md\n\`\`\`\n\n## Step 1: package.json Configuration\n\n\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"version\": \"1.0.0\",\n  \"vat\": {\n    \"version\": \"1.0\",\n    \"skills\": [\"my-skill\"]\n  },\n  \"dependencies\": {\n    \"vibe-agent-toolkit\": \"latest\"\n  },\n  \"scripts\": {\n    \"build:vat\": \"vat build\",\n    \"postinstall\": \"node ./node_modules/vibe-agent-toolkit/dist/bin/vat.js claude plugin install --npm-postinstall 2>/dev/null || exit 0\"\n  },\n  \"files\": [\"dist\", \"README.md\"],\n  \"publishConfig\": {\n    \"registry\": \"https://registry.npmjs.org\"\n  }\n}\n\`\`\`\n\n**\`vibe-agent-toolkit\` must be in \`dependencies\` (not \`devDependencies\`)** so it is present in \`node_modules\` when the postinstall hook runs on the user\'s machine. Never assume \`vat\` is available globally — your users may not be developers.\n\nThe \`vat.skills\` array contains skill name strings for npm discoverability. Skill source paths and packaging config live in \`vibe-agent-toolkit.config.yaml\` (see Step 2).\n\nFor private GitHub Packages registry:\n\`\`\`json\n\"publishConfig\": {\n  \"registry\": \"https://npm.pkg.github.com\",\n  \"access\": \"restricted\"\n}\n\`\`\`\n\nUsers (or IT) installing from GitHub Packages need \`.npmrc\` configured with the scope registry and a read-only token:\n\`\`\`\n@myorg:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n\`\`\`\n\nIT deploying to managed machines should pre-configure \`.npmrc\` at the system or user level before running install commands. End users do not need to understand npm or the registry — IT handles it once.\n\n## Handling Plugin Renames: vat.replaces\n\n> **Use this only when renaming a plugin, merging plugins, or cleaning up legacy flat-skill installs. Normal upgrades (same plugin name, same skills) do NOT need \`vat.replaces\` — the installer already overwrites the plugin directory on every install.**\n\n### The problem: silent stale skills\n\nWhen you rename a plugin or reorganize skills across packages, the old registration remains in Claude Code. Claude Code **does not warn you** when two plugins provide conflicting skill names — the first-registered (stale) skill silently wins. Users continue loading old content from the renamed plugin unless the old registration is explicitly removed.\n\nThis is the scenario where \`vat.replaces\` is needed:\n- Plugin renamed: \`old-plugin-name\` → \`new-plugin-name\`\n- Two old plugins merged into one new plugin\n- Skills previously installed to \`~/.claude/skills/<name>\` (legacy pre-0.1.20 flat install) now delivered via the plugin tree\n\n### How it works\n\nWhen a VAT package is installed (via postinstall hook or \`--dev\`), the installer reads \`vat.replaces\` from \`package.json\` and — **before** installing the new plugin:\n\n1. For each name in \`replaces.plugins\`: uninstalls \`<name>@<marketplace>\` — removes plugin directory, cache entry, registry entry, and \`settings.json\` entry\n2. For each name in \`replaces.flatSkills\`: deletes \`~/.claude/skills/<name>\` — removes legacy pre-0.1.20 flat installs\n\nBoth operations are idempotent — \"not found\" is handled gracefully.\n\n### Schema\n\n\`\`\`json\n\"vat\": {\n  \"version\": \"1.0\",\n  \"skills\": [\"authoring\", \"audit\"],\n  \"replaces\": {\n    \"plugins\": [\"my-old-plugin-name\"],\n    \"flatSkills\": [\"my-old-skill\", \"another-old-skill\"]\n  }\n}\n\`\`\`\n\nBoth \`plugins\` and \`flatSkills\` are optional arrays. The entire \`replaces\` key is optional — omit it when there is nothing to clean up.\n\n### Real example: vat-development-agents 0.1.21\n\nThis package (\`vat-development-agents\`) renamed its plugin from \`vat-development-agents\` to \`vibe-agent-toolkit\` in v0.1.21. Without \`vat.replaces\`, users who had already installed v0.1.20 would have both \`vat-development-agents@vat-skills\` and \`vibe-agent-toolkit@vat-skills\` registered — Claude Code would serve stale skill content from the old plugin.\n\nThe fix in \`package.json\`:\n\n\`\`\`json\n\"vat\": {\n  \"version\": \"1.0\",\n  \"skills\": [\"vibe-agent-toolkit\", \"resources\", \"distribution\", \"authoring\", \"audit\", \"debugging\", \"install\"],\n  \"replaces\": {\n    \"plugins\": [\"vat-development-agents\"],\n    \"flatSkills\": [\"vibe-agent-toolkit\", \"resources\"]\n  }\n}\n\`\`\`\n\n- \`plugins\`: removes the old plugin registration (same marketplace, old plugin name)\n- \`flatSkills\`: removes legacy \`~/.claude/skills/vibe-agent-toolkit\` and \`~/.claude/skills/resources\` entries from users who installed before 0.1.20 switched to the plugin tree\n\n### Non-obvious gotchas\n\n**1. Plugin names in \`replaces.plugins\` have NO \`@marketplace\`**\n\nThe format is just the plugin name — e.g. \`\"vat-development-agents\"\` — NOT \`\"vat-development-agents@vat-skills\"\`. The installer infers the marketplace from the current package\'s dist tree. Using \`@marketplace\` syntax here would be wrong.\n\n**2. \`replaces.plugins\` is for old plugin registrations, not for skills that moved between plugins**\n\nIf a skill moved from \`plugin-a\` to \`plugin-b\` within the same marketplace, list \`\"plugin-a\"\` in \`replaces.plugins\` to clean up the entire old plugin. You do not manage individual skills — you manage plugins.\n\n**3. \`replaces.flatSkills\` is ONLY for the legacy \`~/.claude/skills/\` location**\n\nThis is specifically for skills that were previously installed as flat files to \`~/.claude/skills/<name>\` (pre-plugin-tree, before v0.1.20). Skills within the plugin tree (under \`~/.claude/plugins/\`) are handled via \`replaces.plugins\`. Do not mix them up.\n\n**4. Normal upgrades need nothing**\n\nIf you publish a new version of the same package with the same plugin name, the installer overwrites the plugin directory automatically. \`vat.replaces\` is only for the case where the old name is different from the new name.\n\n**5. The symptom is subtle and delayed**\n\nYou will not see an error. Claude Code simply loads the first-registered skill with a given name. If the stale plugin is registered first (alphabetically or by install order), your new content is invisible until you remove the old registration.\n\n## Step 2: vibe-agent-toolkit.config.yaml\n\n\`\`\`yaml\nversion: 1\n\nskills:\n  include:\n    - \"resources/skills/**/SKILL.md\"\n\nclaude:\n  marketplaces:\n    my-marketplace:                   # org/publisher identity\n      owner:\n        name: My Organization\n      plugins:\n        - name: my-plugin             # installable unit\n          description: My plugin description\n          skills: \"*\"                  # all discovered skills\n\`\`\`\n\nThe \`skills:\` section discovers SKILL.md files via include/exclude globs. The \`claude:\` section defines how skills are packaged into plugins. Each marketplace has \`owner\` and \`plugins\` fields (strict schema — no extra fields).\n\n**Naming convention:** marketplace = org identity (e.g. \`acme\`), plugin = this package\n(e.g. \`acme-tools\`). Registers as \`my-plugin@my-marketplace\` in Claude\'s plugin registry.\n\n### Multiple skills in one package\n\nList all skills in \`vat.skills\` for npm discoverability:\n\n\`\`\`json\n\"vat\": {\n  \"version\": \"1.0\",\n  \"skills\": [\"my-linting\", \"my-testing\"]\n}\n\`\`\`\n\nUse a selector in the plugin config to include matching skills:\n\n\`\`\`yaml\nplugins:\n  - name: my-plugin\n    description: Linting and testing skills\n    skills:\n      - \"my-linting\"\n      - \"my-testing\"\n\`\`\`\n\nOr use \`\"*\"\` to include all discovered skills in the plugin.\n\n## Step 3: Build\n\n\`\`\`bash\nvat build        # skills phase then claude phase\nvat verify       # validates resources + skills + claude artifacts\n\`\`\`\n\n### What vat build does\n\nTwo phases, run in dependency order:\n\n1. **\`vat skills build\`** — reads \`vibe-agent-toolkit.config.yaml skills:\` section, discovers SKILL.md files via include/exclude globs, compiles each into \`dist/skills/<name>/\`\n2. **\`vat claude plugin build\`** — reads \`vibe-agent-toolkit.config.yaml claude:\` section, wraps built skills into \`dist/.claude/plugins/marketplaces/<mp>/plugins/<plugin>/\` structure with \`.claude-plugin/plugin.json\`. Cleans stale output before each build.\n\nIndividual commands still work:\n\`\`\`bash\nvat skills build            # skills phase only\nvat claude plugin build     # claude plugin phase only (requires skills already built)\n\`\`\`\n\n## Step 4: Publish\n\n\`\`\`bash\nnpm publish --tag next    # RC/pre-release\nnpm publish               # stable release\n\`\`\`\n\n## Step 5: User Install\n\n### Recommended: npm global install (postinstall runs automatically)\n\n\`\`\`bash\nnpm install -g @myorg/my-skills\n\`\`\`\n\nThe postinstall hook fires automatically and registers the plugin in Claude. This is the correct path for IT-managed deployments — no other tools required on the user\'s machine.\n\n### Developer/IT one-off install via npx\n\n\`\`\`bash\nnpx vibe-agent-toolkit claude plugin install npm:@myorg/my-skills\n\`\`\`\n\nDownloads and runs VAT via npx to install a package without a global install. Useful for CI, scripting, or testing from a developer machine. Requires the npm scope registry to be configured (\`.npmrc\`) if installing from a private registry.\n\n### How plugin installation works\n\nWhen \`npm install\` runs the postinstall hook (\`node ./node_modules/vibe-agent-toolkit/dist/bin/vat.js claude plugin install --npm-postinstall\`):\n\n- VAT detects \`dist/.claude/plugins/marketplaces/\` directory in the installed package\n- Copies the plugin tree to Claude\'s plugin directory (dumb recursive copy)\n- Writes to these locations:\n  1. \`~/.claude/plugins/marketplaces/<marketplace>/plugins/<plugin>/\` — plugin files\n  2. \`~/.claude/plugins/known_marketplaces.json\` — marketplace registry\n  3. \`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/\` — version cache\n  4. \`~/.claude/plugins/installed_plugins.json\` — installation record\n  5. \`~/.claude/settings.json\` \`enabledPlugins\` — activates the plugin\n\nIf no \`dist/.claude/plugins/marketplaces/\` directory exists (package wasn\'t built before publish): a guidance message is emitted and the hook exits 0. The publisher must run \`vat build\` and re-publish.\n\nSkills are then available in Claude Code as \`/plugin-name:skill-name\`.\n\n## managed-settings.json Validation (Enterprise)\n\n\`\`\`yaml\nclaude:\n  managedSettings: managed-settings.json\n\`\`\`\n\n\`vat verify\` validates this file against the ManagedSettings schema. Catches typos and schema errors before deployment. Does NOT deploy the file — deployment is a separate concern.\n\n## --target claude-web (ZIP Upload)\n\nFor uploading skills directly to \`claude.ai/settings/capabilities\`:\n\n\`\`\`bash\nvat skills package ./SKILL.md -o ./dist/ --target claude-web\n\`\`\`\n\nProduces a ZIP:\n\`\`\`\nmy-skill.zip\n└── my-skill/\n    ├── SKILL.md             # skill definition (required)\n    ├── scripts/             # executable code (.mjs, .py, .sh) — optional\n    ├── references/          # markdown reference material — optional\n    └── assets/              # static data, templates, config — optional\n\`\`\`\n\nConfigure source path mappings in \`vibe-agent-toolkit.config.yaml\`:\n\`\`\`yaml\nskills:\n  include:\n    - \"skills/**/SKILL.md\"\n  config:\n    my-skill:\n      claudeWebTarget:\n        scripts: [\"./src/helpers/**/*.ts\"]\n        assets: [\"./assets/**\"]\n\`\`\`\n\nTypeScript files in \`scripts\` are tree-shaken and compiled to standalone \`.mjs\`.\n\n## Quick Reference\n\n| Task | Command |\n|---|---|\n| Build everything | \`vat build\` |\n| Verify everything | \`vat verify\` |\n| Build skills only | \`vat skills build\` |\n| Build claude plugin artifacts only | \`vat claude plugin build\` |\n| Install via npm (end user) | \`npm install -g @org/pkg\` |\n| Install via npx (developer/IT) | \`npx vibe-agent-toolkit claude plugin install npm:@org/pkg\` |\n| List installed plugins | \`vat claude plugin list\` |\n| Uninstall a plugin | \`vat claude plugin uninstall --all\` |\n| Package for claude.ai upload | \`vat skills package ./SKILL.md -o ./dist/ --target claude-web\` |\n\n## Future: Zero-Dependency Postinstall (Option B)\n\nA planned improvement: \`vat build\` would bundle the plugin install logic into \`dist/postinstall.js\` — a fully self-contained script with no npm dependencies. The postinstall script would become simply \`node ./dist/postinstall.js\`. This eliminates \`vibe-agent-toolkit\` as a runtime dependency entirely, reducing install footprint for end users. Until then, Option C (runtime \`vibe-agent-toolkit\` dep) is the correct approach.\n";
 
 export const fragments = {
+  scope: {
+    header: "## Scope",
+    body: "This skill covers the **file-based install method for Claude Code CLI** (\`~/.claude/plugins/\`).\nThis is the only install method VAT currently supports.\n\nFor the full install landscape — Claude Desktop paths, enterprise CI deployment,\nAnthropic Cloud org management, MDM integration, and the \`vat plugins uninstall\`\ndesign — see [Install & Uninstall Architecture](vat-install-architecture.md).",
+    text: "## Scope\n\nThis skill covers the **file-based install method for Claude Code CLI** (\`~/.claude/plugins/\`).\nThis is the only install method VAT currently supports.\n\nFor the full install landscape — Claude Desktop paths, enterprise CI deployment,\nAnthropic Cloud org management, MDM integration, and the \`vat plugins uninstall\`\ndesign — see [Install & Uninstall Architecture](vat-install-architecture.md)."
+  },
   overview: {
     header: "## Overview",
-    body: "VAT distributes skills as **Claude plugins** via npm packages. The pipeline:\n\n1. \`vat build\` compiles SKILL.md sources into plugin artifacts\n2. \`npm publish\` pushes the package to a registry\n3. \`npm install\` triggers a postinstall hook that registers the plugin in Claude\'s plugin system\n\nSkills installed this way appear in Claude Code as \`/plugin-name:skill-name\`.",
-    text: "## Overview\n\nVAT distributes skills as **Claude plugins** via npm packages. The pipeline:\n\n1. \`vat build\` compiles SKILL.md sources into plugin artifacts\n2. \`npm publish\` pushes the package to a registry\n3. \`npm install\` triggers a postinstall hook that registers the plugin in Claude\'s plugin system\n\nSkills installed this way appear in Claude Code as \`/plugin-name:skill-name\`."
+    body: "VAT distributes skills as **Claude plugins** via npm packages. The pipeline:\n\n1. \`vat build\` compiles SKILL.md sources into plugin artifacts\n2. \`npm publish\` pushes the package to a registry\n3. \`npm install\` triggers a postinstall hook that registers the plugin in Claude Code\'s plugin system\n\nSkills installed this way appear in Claude Code as \`/plugin-name:skill-name\`.",
+    text: "## Overview\n\nVAT distributes skills as **Claude plugins** via npm packages. The pipeline:\n\n1. \`vat build\` compiles SKILL.md sources into plugin artifacts\n2. \`npm publish\` pushes the package to a registry\n3. \`npm install\` triggers a postinstall hook that registers the plugin in Claude Code\'s plugin system\n\nSkills installed this way appear in Claude Code as \`/plugin-name:skill-name\`."
   },
   projectStructure: {
     header: "## Project Structure",
@@ -22,8 +27,13 @@ export const fragments = {
   },
   step1PackagejsonConfiguration: {
     header: "## Step 1: package.json Configuration",
-    body: "\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"version\": \"1.0.0\",\n  \"vat\": {\n    \"version\": \"1.0\",\n    \"skills\": [\"my-skill\"]\n  },\n  \"scripts\": {\n    \"build:vat\": \"vat build\",\n    \"postinstall\": \"vat skills install --npm-postinstall || exit 0\"\n  },\n  \"files\": [\"dist\", \"README.md\"],\n  \"publishConfig\": {\n    \"registry\": \"https://registry.npmjs.org\"\n  }\n}\n\`\`\`\n\nThe \`vat.skills\` array contains skill name strings for npm discoverability. Skill source paths and packaging config live in \`vibe-agent-toolkit.config.yaml\` (see Step 2).\n\nFor private GitHub Packages registry:\n\`\`\`json\n\"publishConfig\": {\n  \"registry\": \"https://npm.pkg.github.com\",\n  \"access\": \"restricted\"\n}\n\`\`\`\n\nUsers installing from GitHub Packages need \`.npmrc\` with the scope registry and auth token:\n\`\`\`\n@myorg:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n\`\`\`",
-    text: "## Step 1: package.json Configuration\n\n\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"version\": \"1.0.0\",\n  \"vat\": {\n    \"version\": \"1.0\",\n    \"skills\": [\"my-skill\"]\n  },\n  \"scripts\": {\n    \"build:vat\": \"vat build\",\n    \"postinstall\": \"vat skills install --npm-postinstall || exit 0\"\n  },\n  \"files\": [\"dist\", \"README.md\"],\n  \"publishConfig\": {\n    \"registry\": \"https://registry.npmjs.org\"\n  }\n}\n\`\`\`\n\nThe \`vat.skills\` array contains skill name strings for npm discoverability. Skill source paths and packaging config live in \`vibe-agent-toolkit.config.yaml\` (see Step 2).\n\nFor private GitHub Packages registry:\n\`\`\`json\n\"publishConfig\": {\n  \"registry\": \"https://npm.pkg.github.com\",\n  \"access\": \"restricted\"\n}\n\`\`\`\n\nUsers installing from GitHub Packages need \`.npmrc\` with the scope registry and auth token:\n\`\`\`\n@myorg:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n\`\`\`"
+    body: "\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"version\": \"1.0.0\",\n  \"vat\": {\n    \"version\": \"1.0\",\n    \"skills\": [\"my-skill\"]\n  },\n  \"dependencies\": {\n    \"vibe-agent-toolkit\": \"latest\"\n  },\n  \"scripts\": {\n    \"build:vat\": \"vat build\",\n    \"postinstall\": \"node ./node_modules/vibe-agent-toolkit/dist/bin/vat.js claude plugin install --npm-postinstall 2>/dev/null || exit 0\"\n  },\n  \"files\": [\"dist\", \"README.md\"],\n  \"publishConfig\": {\n    \"registry\": \"https://registry.npmjs.org\"\n  }\n}\n\`\`\`\n\n**\`vibe-agent-toolkit\` must be in \`dependencies\` (not \`devDependencies\`)** so it is present in \`node_modules\` when the postinstall hook runs on the user\'s machine. Never assume \`vat\` is available globally — your users may not be developers.\n\nThe \`vat.skills\` array contains skill name strings for npm discoverability. Skill source paths and packaging config live in \`vibe-agent-toolkit.config.yaml\` (see Step 2).\n\nFor private GitHub Packages registry:\n\`\`\`json\n\"publishConfig\": {\n  \"registry\": \"https://npm.pkg.github.com\",\n  \"access\": \"restricted\"\n}\n\`\`\`\n\nUsers (or IT) installing from GitHub Packages need \`.npmrc\` configured with the scope registry and a read-only token:\n\`\`\`\n@myorg:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n\`\`\`\n\nIT deploying to managed machines should pre-configure \`.npmrc\` at the system or user level before running install commands. End users do not need to understand npm or the registry — IT handles it once.",
+    text: "## Step 1: package.json Configuration\n\n\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"version\": \"1.0.0\",\n  \"vat\": {\n    \"version\": \"1.0\",\n    \"skills\": [\"my-skill\"]\n  },\n  \"dependencies\": {\n    \"vibe-agent-toolkit\": \"latest\"\n  },\n  \"scripts\": {\n    \"build:vat\": \"vat build\",\n    \"postinstall\": \"node ./node_modules/vibe-agent-toolkit/dist/bin/vat.js claude plugin install --npm-postinstall 2>/dev/null || exit 0\"\n  },\n  \"files\": [\"dist\", \"README.md\"],\n  \"publishConfig\": {\n    \"registry\": \"https://registry.npmjs.org\"\n  }\n}\n\`\`\`\n\n**\`vibe-agent-toolkit\` must be in \`dependencies\` (not \`devDependencies\`)** so it is present in \`node_modules\` when the postinstall hook runs on the user\'s machine. Never assume \`vat\` is available globally — your users may not be developers.\n\nThe \`vat.skills\` array contains skill name strings for npm discoverability. Skill source paths and packaging config live in \`vibe-agent-toolkit.config.yaml\` (see Step 2).\n\nFor private GitHub Packages registry:\n\`\`\`json\n\"publishConfig\": {\n  \"registry\": \"https://npm.pkg.github.com\",\n  \"access\": \"restricted\"\n}\n\`\`\`\n\nUsers (or IT) installing from GitHub Packages need \`.npmrc\` configured with the scope registry and a read-only token:\n\`\`\`\n@myorg:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n\`\`\`\n\nIT deploying to managed machines should pre-configure \`.npmrc\` at the system or user level before running install commands. End users do not need to understand npm or the registry — IT handles it once."
+  },
+  handlingPluginRenamesVatreplaces: {
+    header: "## Handling Plugin Renames: vat.replaces",
+    body: "> **Use this only when renaming a plugin, merging plugins, or cleaning up legacy flat-skill installs. Normal upgrades (same plugin name, same skills) do NOT need \`vat.replaces\` — the installer already overwrites the plugin directory on every install.**\n\n### The problem: silent stale skills\n\nWhen you rename a plugin or reorganize skills across packages, the old registration remains in Claude Code. Claude Code **does not warn you** when two plugins provide conflicting skill names — the first-registered (stale) skill silently wins. Users continue loading old content from the renamed plugin unless the old registration is explicitly removed.\n\nThis is the scenario where \`vat.replaces\` is needed:\n- Plugin renamed: \`old-plugin-name\` → \`new-plugin-name\`\n- Two old plugins merged into one new plugin\n- Skills previously installed to \`~/.claude/skills/<name>\` (legacy pre-0.1.20 flat install) now delivered via the plugin tree\n\n### How it works\n\nWhen a VAT package is installed (via postinstall hook or \`--dev\`), the installer reads \`vat.replaces\` from \`package.json\` and — **before** installing the new plugin:\n\n1. For each name in \`replaces.plugins\`: uninstalls \`<name>@<marketplace>\` — removes plugin directory, cache entry, registry entry, and \`settings.json\` entry\n2. For each name in \`replaces.flatSkills\`: deletes \`~/.claude/skills/<name>\` — removes legacy pre-0.1.20 flat installs\n\nBoth operations are idempotent — \"not found\" is handled gracefully.\n\n### Schema\n\n\`\`\`json\n\"vat\": {\n  \"version\": \"1.0\",\n  \"skills\": [\"authoring\", \"audit\"],\n  \"replaces\": {\n    \"plugins\": [\"my-old-plugin-name\"],\n    \"flatSkills\": [\"my-old-skill\", \"another-old-skill\"]\n  }\n}\n\`\`\`\n\nBoth \`plugins\` and \`flatSkills\` are optional arrays. The entire \`replaces\` key is optional — omit it when there is nothing to clean up.\n\n### Real example: vat-development-agents 0.1.21\n\nThis package (\`vat-development-agents\`) renamed its plugin from \`vat-development-agents\` to \`vibe-agent-toolkit\` in v0.1.21. Without \`vat.replaces\`, users who had already installed v0.1.20 would have both \`vat-development-agents@vat-skills\` and \`vibe-agent-toolkit@vat-skills\` registered — Claude Code would serve stale skill content from the old plugin.\n\nThe fix in \`package.json\`:\n\n\`\`\`json\n\"vat\": {\n  \"version\": \"1.0\",\n  \"skills\": [\"vibe-agent-toolkit\", \"resources\", \"distribution\", \"authoring\", \"audit\", \"debugging\", \"install\"],\n  \"replaces\": {\n    \"plugins\": [\"vat-development-agents\"],\n    \"flatSkills\": [\"vibe-agent-toolkit\", \"resources\"]\n  }\n}\n\`\`\`\n\n- \`plugins\`: removes the old plugin registration (same marketplace, old plugin name)\n- \`flatSkills\`: removes legacy \`~/.claude/skills/vibe-agent-toolkit\` and \`~/.claude/skills/resources\` entries from users who installed before 0.1.20 switched to the plugin tree\n\n### Non-obvious gotchas\n\n**1. Plugin names in \`replaces.plugins\` have NO \`@marketplace\`**\n\nThe format is just the plugin name — e.g. \`\"vat-development-agents\"\` — NOT \`\"vat-development-agents@vat-skills\"\`. The installer infers the marketplace from the current package\'s dist tree. Using \`@marketplace\` syntax here would be wrong.\n\n**2. \`replaces.plugins\` is for old plugin registrations, not for skills that moved between plugins**\n\nIf a skill moved from \`plugin-a\` to \`plugin-b\` within the same marketplace, list \`\"plugin-a\"\` in \`replaces.plugins\` to clean up the entire old plugin. You do not manage individual skills — you manage plugins.\n\n**3. \`replaces.flatSkills\` is ONLY for the legacy \`~/.claude/skills/\` location**\n\nThis is specifically for skills that were previously installed as flat files to \`~/.claude/skills/<name>\` (pre-plugin-tree, before v0.1.20). Skills within the plugin tree (under \`~/.claude/plugins/\`) are handled via \`replaces.plugins\`. Do not mix them up.\n\n**4. Normal upgrades need nothing**\n\nIf you publish a new version of the same package with the same plugin name, the installer overwrites the plugin directory automatically. \`vat.replaces\` is only for the case where the old name is different from the new name.\n\n**5. The symptom is subtle and delayed**\n\nYou will not see an error. Claude Code simply loads the first-registered skill with a given name. If the stale plugin is registered first (alphabetically or by install order), your new content is invisible until you remove the old registration.",
+    text: "## Handling Plugin Renames: vat.replaces\n\n> **Use this only when renaming a plugin, merging plugins, or cleaning up legacy flat-skill installs. Normal upgrades (same plugin name, same skills) do NOT need \`vat.replaces\` — the installer already overwrites the plugin directory on every install.**\n\n### The problem: silent stale skills\n\nWhen you rename a plugin or reorganize skills across packages, the old registration remains in Claude Code. Claude Code **does not warn you** when two plugins provide conflicting skill names — the first-registered (stale) skill silently wins. Users continue loading old content from the renamed plugin unless the old registration is explicitly removed.\n\nThis is the scenario where \`vat.replaces\` is needed:\n- Plugin renamed: \`old-plugin-name\` → \`new-plugin-name\`\n- Two old plugins merged into one new plugin\n- Skills previously installed to \`~/.claude/skills/<name>\` (legacy pre-0.1.20 flat install) now delivered via the plugin tree\n\n### How it works\n\nWhen a VAT package is installed (via postinstall hook or \`--dev\`), the installer reads \`vat.replaces\` from \`package.json\` and — **before** installing the new plugin:\n\n1. For each name in \`replaces.plugins\`: uninstalls \`<name>@<marketplace>\` — removes plugin directory, cache entry, registry entry, and \`settings.json\` entry\n2. For each name in \`replaces.flatSkills\`: deletes \`~/.claude/skills/<name>\` — removes legacy pre-0.1.20 flat installs\n\nBoth operations are idempotent — \"not found\" is handled gracefully.\n\n### Schema\n\n\`\`\`json\n\"vat\": {\n  \"version\": \"1.0\",\n  \"skills\": [\"authoring\", \"audit\"],\n  \"replaces\": {\n    \"plugins\": [\"my-old-plugin-name\"],\n    \"flatSkills\": [\"my-old-skill\", \"another-old-skill\"]\n  }\n}\n\`\`\`\n\nBoth \`plugins\` and \`flatSkills\` are optional arrays. The entire \`replaces\` key is optional — omit it when there is nothing to clean up.\n\n### Real example: vat-development-agents 0.1.21\n\nThis package (\`vat-development-agents\`) renamed its plugin from \`vat-development-agents\` to \`vibe-agent-toolkit\` in v0.1.21. Without \`vat.replaces\`, users who had already installed v0.1.20 would have both \`vat-development-agents@vat-skills\` and \`vibe-agent-toolkit@vat-skills\` registered — Claude Code would serve stale skill content from the old plugin.\n\nThe fix in \`package.json\`:\n\n\`\`\`json\n\"vat\": {\n  \"version\": \"1.0\",\n  \"skills\": [\"vibe-agent-toolkit\", \"resources\", \"distribution\", \"authoring\", \"audit\", \"debugging\", \"install\"],\n  \"replaces\": {\n    \"plugins\": [\"vat-development-agents\"],\n    \"flatSkills\": [\"vibe-agent-toolkit\", \"resources\"]\n  }\n}\n\`\`\`\n\n- \`plugins\`: removes the old plugin registration (same marketplace, old plugin name)\n- \`flatSkills\`: removes legacy \`~/.claude/skills/vibe-agent-toolkit\` and \`~/.claude/skills/resources\` entries from users who installed before 0.1.20 switched to the plugin tree\n\n### Non-obvious gotchas\n\n**1. Plugin names in \`replaces.plugins\` have NO \`@marketplace\`**\n\nThe format is just the plugin name — e.g. \`\"vat-development-agents\"\` — NOT \`\"vat-development-agents@vat-skills\"\`. The installer infers the marketplace from the current package\'s dist tree. Using \`@marketplace\` syntax here would be wrong.\n\n**2. \`replaces.plugins\` is for old plugin registrations, not for skills that moved between plugins**\n\nIf a skill moved from \`plugin-a\` to \`plugin-b\` within the same marketplace, list \`\"plugin-a\"\` in \`replaces.plugins\` to clean up the entire old plugin. You do not manage individual skills — you manage plugins.\n\n**3. \`replaces.flatSkills\` is ONLY for the legacy \`~/.claude/skills/\` location**\n\nThis is specifically for skills that were previously installed as flat files to \`~/.claude/skills/<name>\` (pre-plugin-tree, before v0.1.20). Skills within the plugin tree (under \`~/.claude/plugins/\`) are handled via \`replaces.plugins\`. Do not mix them up.\n\n**4. Normal upgrades need nothing**\n\nIf you publish a new version of the same package with the same plugin name, the installer overwrites the plugin directory automatically. \`vat.replaces\` is only for the case where the old name is different from the new name.\n\n**5. The symptom is subtle and delayed**\n\nYou will not see an error. Claude Code simply loads the first-registered skill with a given name. If the stale plugin is registered first (alphabetically or by install order), your new content is invisible until you remove the old registration."
   },
   step2VibeAgentToolkitconfigyaml: {
     header: "## Step 2: vibe-agent-toolkit.config.yaml",
@@ -32,8 +42,8 @@ export const fragments = {
   },
   step3Build: {
     header: "## Step 3: Build",
-    body: "\`\`\`bash\nvat build        # skills phase then claude phase\nvat verify       # validates resources + skills + claude artifacts\n\`\`\`\n\n### What vat build does\n\nTwo phases, run in dependency order:\n\n1. **\`vat skills build\`** — reads \`vibe-agent-toolkit.config.yaml skills:\` section, discovers SKILL.md files via include/exclude globs, compiles each into \`dist/skills/<name>/\`\n2. **\`vat claude build\`** — reads \`vibe-agent-toolkit.config.yaml claude:\` section, wraps built skills into \`dist/.claude/plugins/marketplaces/<mp>/plugins/<plugin>/\` structure with \`.claude-plugin/plugin.json\`\n\nIndividual commands still work:\n\`\`\`bash\nvat skills build       # skills phase only\nvat claude build       # claude plugin phase only (requires skills already built)\nvat claude verify      # validate plugin artifacts only\n\`\`\`",
-    text: "## Step 3: Build\n\n\`\`\`bash\nvat build        # skills phase then claude phase\nvat verify       # validates resources + skills + claude artifacts\n\`\`\`\n\n### What vat build does\n\nTwo phases, run in dependency order:\n\n1. **\`vat skills build\`** — reads \`vibe-agent-toolkit.config.yaml skills:\` section, discovers SKILL.md files via include/exclude globs, compiles each into \`dist/skills/<name>/\`\n2. **\`vat claude build\`** — reads \`vibe-agent-toolkit.config.yaml claude:\` section, wraps built skills into \`dist/.claude/plugins/marketplaces/<mp>/plugins/<plugin>/\` structure with \`.claude-plugin/plugin.json\`\n\nIndividual commands still work:\n\`\`\`bash\nvat skills build       # skills phase only\nvat claude build       # claude plugin phase only (requires skills already built)\nvat claude verify      # validate plugin artifacts only\n\`\`\`"
+    body: "\`\`\`bash\nvat build        # skills phase then claude phase\nvat verify       # validates resources + skills + claude artifacts\n\`\`\`\n\n### What vat build does\n\nTwo phases, run in dependency order:\n\n1. **\`vat skills build\`** — reads \`vibe-agent-toolkit.config.yaml skills:\` section, discovers SKILL.md files via include/exclude globs, compiles each into \`dist/skills/<name>/\`\n2. **\`vat claude plugin build\`** — reads \`vibe-agent-toolkit.config.yaml claude:\` section, wraps built skills into \`dist/.claude/plugins/marketplaces/<mp>/plugins/<plugin>/\` structure with \`.claude-plugin/plugin.json\`. Cleans stale output before each build.\n\nIndividual commands still work:\n\`\`\`bash\nvat skills build            # skills phase only\nvat claude plugin build     # claude plugin phase only (requires skills already built)\n\`\`\`",
+    text: "## Step 3: Build\n\n\`\`\`bash\nvat build        # skills phase then claude phase\nvat verify       # validates resources + skills + claude artifacts\n\`\`\`\n\n### What vat build does\n\nTwo phases, run in dependency order:\n\n1. **\`vat skills build\`** — reads \`vibe-agent-toolkit.config.yaml skills:\` section, discovers SKILL.md files via include/exclude globs, compiles each into \`dist/skills/<name>/\`\n2. **\`vat claude plugin build\`** — reads \`vibe-agent-toolkit.config.yaml claude:\` section, wraps built skills into \`dist/.claude/plugins/marketplaces/<mp>/plugins/<plugin>/\` structure with \`.claude-plugin/plugin.json\`. Cleans stale output before each build.\n\nIndividual commands still work:\n\`\`\`bash\nvat skills build            # skills phase only\nvat claude plugin build     # claude plugin phase only (requires skills already built)\n\`\`\`"
   },
   step4Publish: {
     header: "## Step 4: Publish",
@@ -42,8 +52,8 @@ export const fragments = {
   },
   step5UserInstall: {
     header: "## Step 5: User Install",
-    body: "\`\`\`bash\nvat skills install npm:@myorg/my-skills\n\`\`\`\n\nOr via standard npm install (postinstall hook triggers automatically):\n\`\`\`bash\nnpm install -g @myorg/my-skills\n\`\`\`\n\n### How plugin installation works\n\nWhen \`npm install\` runs the postinstall hook (\`vat skills install --npm-postinstall\`):\n\n- VAT detects \`dist/.claude/plugins/marketplaces/\` directory in the installed package\n- Copies the plugin tree to Claude\'s plugin directory (dumb recursive copy)\n- Writes to these locations:\n  1. \`~/.claude/plugins/marketplaces/<marketplace>/plugins/<plugin>/\` — plugin files\n  2. \`~/.claude/plugins/known_marketplaces.json\` — marketplace registry\n  3. \`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/\` — version cache\n  4. \`~/.claude/plugins/installed_plugins.json\` — installation record\n  5. \`~/.claude/settings.json\` \`enabledPlugins\` — activates the plugin\n\nIf no \`dist/.claude/plugins/marketplaces/\` directory exists (package wasn\'t built before publish): a guidance message is emitted and the hook exits 0. The publisher must run \`vat build\` and re-publish.\n\nSkills are then available in Claude Code as \`/plugin-name:skill-name\`.",
-    text: "## Step 5: User Install\n\n\`\`\`bash\nvat skills install npm:@myorg/my-skills\n\`\`\`\n\nOr via standard npm install (postinstall hook triggers automatically):\n\`\`\`bash\nnpm install -g @myorg/my-skills\n\`\`\`\n\n### How plugin installation works\n\nWhen \`npm install\` runs the postinstall hook (\`vat skills install --npm-postinstall\`):\n\n- VAT detects \`dist/.claude/plugins/marketplaces/\` directory in the installed package\n- Copies the plugin tree to Claude\'s plugin directory (dumb recursive copy)\n- Writes to these locations:\n  1. \`~/.claude/plugins/marketplaces/<marketplace>/plugins/<plugin>/\` — plugin files\n  2. \`~/.claude/plugins/known_marketplaces.json\` — marketplace registry\n  3. \`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/\` — version cache\n  4. \`~/.claude/plugins/installed_plugins.json\` — installation record\n  5. \`~/.claude/settings.json\` \`enabledPlugins\` — activates the plugin\n\nIf no \`dist/.claude/plugins/marketplaces/\` directory exists (package wasn\'t built before publish): a guidance message is emitted and the hook exits 0. The publisher must run \`vat build\` and re-publish.\n\nSkills are then available in Claude Code as \`/plugin-name:skill-name\`."
+    body: "### Recommended: npm global install (postinstall runs automatically)\n\n\`\`\`bash\nnpm install -g @myorg/my-skills\n\`\`\`\n\nThe postinstall hook fires automatically and registers the plugin in Claude. This is the correct path for IT-managed deployments — no other tools required on the user\'s machine.\n\n### Developer/IT one-off install via npx\n\n\`\`\`bash\nnpx vibe-agent-toolkit claude plugin install npm:@myorg/my-skills\n\`\`\`\n\nDownloads and runs VAT via npx to install a package without a global install. Useful for CI, scripting, or testing from a developer machine. Requires the npm scope registry to be configured (\`.npmrc\`) if installing from a private registry.\n\n### How plugin installation works\n\nWhen \`npm install\` runs the postinstall hook (\`node ./node_modules/vibe-agent-toolkit/dist/bin/vat.js claude plugin install --npm-postinstall\`):\n\n- VAT detects \`dist/.claude/plugins/marketplaces/\` directory in the installed package\n- Copies the plugin tree to Claude\'s plugin directory (dumb recursive copy)\n- Writes to these locations:\n  1. \`~/.claude/plugins/marketplaces/<marketplace>/plugins/<plugin>/\` — plugin files\n  2. \`~/.claude/plugins/known_marketplaces.json\` — marketplace registry\n  3. \`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/\` — version cache\n  4. \`~/.claude/plugins/installed_plugins.json\` — installation record\n  5. \`~/.claude/settings.json\` \`enabledPlugins\` — activates the plugin\n\nIf no \`dist/.claude/plugins/marketplaces/\` directory exists (package wasn\'t built before publish): a guidance message is emitted and the hook exits 0. The publisher must run \`vat build\` and re-publish.\n\nSkills are then available in Claude Code as \`/plugin-name:skill-name\`.",
+    text: "## Step 5: User Install\n\n### Recommended: npm global install (postinstall runs automatically)\n\n\`\`\`bash\nnpm install -g @myorg/my-skills\n\`\`\`\n\nThe postinstall hook fires automatically and registers the plugin in Claude. This is the correct path for IT-managed deployments — no other tools required on the user\'s machine.\n\n### Developer/IT one-off install via npx\n\n\`\`\`bash\nnpx vibe-agent-toolkit claude plugin install npm:@myorg/my-skills\n\`\`\`\n\nDownloads and runs VAT via npx to install a package without a global install. Useful for CI, scripting, or testing from a developer machine. Requires the npm scope registry to be configured (\`.npmrc\`) if installing from a private registry.\n\n### How plugin installation works\n\nWhen \`npm install\` runs the postinstall hook (\`node ./node_modules/vibe-agent-toolkit/dist/bin/vat.js claude plugin install --npm-postinstall\`):\n\n- VAT detects \`dist/.claude/plugins/marketplaces/\` directory in the installed package\n- Copies the plugin tree to Claude\'s plugin directory (dumb recursive copy)\n- Writes to these locations:\n  1. \`~/.claude/plugins/marketplaces/<marketplace>/plugins/<plugin>/\` — plugin files\n  2. \`~/.claude/plugins/known_marketplaces.json\` — marketplace registry\n  3. \`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/\` — version cache\n  4. \`~/.claude/plugins/installed_plugins.json\` — installation record\n  5. \`~/.claude/settings.json\` \`enabledPlugins\` — activates the plugin\n\nIf no \`dist/.claude/plugins/marketplaces/\` directory exists (package wasn\'t built before publish): a guidance message is emitted and the hook exits 0. The publisher must run \`vat build\` and re-publish.\n\nSkills are then available in Claude Code as \`/plugin-name:skill-name\`."
   },
   managedSettingsjsonValidationEnterprise: {
     header: "## managed-settings.json Validation (Enterprise)",
@@ -57,7 +67,12 @@ export const fragments = {
   },
   quickReference: {
     header: "## Quick Reference",
-    body: "| Task | Command |\n|---|---|\n| Build everything | \`vat build\` |\n| Verify everything | \`vat verify\` |\n| Build skills only | \`vat skills build\` |\n| Build claude artifacts only | \`vat claude build\` |\n| Verify claude artifacts only | \`vat claude verify\` |\n| Install from npm | \`vat skills install npm:@org/pkg\` |\n| Package for claude.ai upload | \`vat skills package ./SKILL.md -o ./dist/ --target claude-web\` |",
-    text: "## Quick Reference\n\n| Task | Command |\n|---|---|\n| Build everything | \`vat build\` |\n| Verify everything | \`vat verify\` |\n| Build skills only | \`vat skills build\` |\n| Build claude artifacts only | \`vat claude build\` |\n| Verify claude artifacts only | \`vat claude verify\` |\n| Install from npm | \`vat skills install npm:@org/pkg\` |\n| Package for claude.ai upload | \`vat skills package ./SKILL.md -o ./dist/ --target claude-web\` |"
+    body: "| Task | Command |\n|---|---|\n| Build everything | \`vat build\` |\n| Verify everything | \`vat verify\` |\n| Build skills only | \`vat skills build\` |\n| Build claude plugin artifacts only | \`vat claude plugin build\` |\n| Install via npm (end user) | \`npm install -g @org/pkg\` |\n| Install via npx (developer/IT) | \`npx vibe-agent-toolkit claude plugin install npm:@org/pkg\` |\n| List installed plugins | \`vat claude plugin list\` |\n| Uninstall a plugin | \`vat claude plugin uninstall --all\` |\n| Package for claude.ai upload | \`vat skills package ./SKILL.md -o ./dist/ --target claude-web\` |",
+    text: "## Quick Reference\n\n| Task | Command |\n|---|---|\n| Build everything | \`vat build\` |\n| Verify everything | \`vat verify\` |\n| Build skills only | \`vat skills build\` |\n| Build claude plugin artifacts only | \`vat claude plugin build\` |\n| Install via npm (end user) | \`npm install -g @org/pkg\` |\n| Install via npx (developer/IT) | \`npx vibe-agent-toolkit claude plugin install npm:@org/pkg\` |\n| List installed plugins | \`vat claude plugin list\` |\n| Uninstall a plugin | \`vat claude plugin uninstall --all\` |\n| Package for claude.ai upload | \`vat skills package ./SKILL.md -o ./dist/ --target claude-web\` |"
+  },
+  futureZeroDependencyPostinstallOptionB: {
+    header: "## Future: Zero-Dependency Postinstall (Option B)",
+    body: "A planned improvement: \`vat build\` would bundle the plugin install logic into \`dist/postinstall.js\` — a fully self-contained script with no npm dependencies. The postinstall script would become simply \`node ./dist/postinstall.js\`. This eliminates \`vibe-agent-toolkit\` as a runtime dependency entirely, reducing install footprint for end users. Until then, Option C (runtime \`vibe-agent-toolkit\` dep) is the correct approach.",
+    text: "## Future: Zero-Dependency Postinstall (Option B)\n\nA planned improvement: \`vat build\` would bundle the plugin install logic into \`dist/postinstall.js\` — a fully self-contained script with no npm dependencies. The postinstall script would become simply \`node ./dist/postinstall.js\`. This eliminates \`vibe-agent-toolkit\` as a runtime dependency entirely, reducing install footprint for end users. Until then, Option C (runtime \`vibe-agent-toolkit\` dep) is the correct approach."
   }
 };

package/dist/{.claude/plugins/marketplaces/vat-skills/plugins/vat-development-agents/skills/vibe-agent-toolkit__audit → skills/audit}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: vibe-agent-toolkit:audit
+name: audit
 description: Use when running vat audit to validate Claude plugins, agent skills, or marketplaces. Covers the audit command, --compat flag for surface compatibility analysis, --exclude for noise filtering, and interpreting audit output.
 ---
 

package/dist/{.claude/plugins/marketplaces/vat-skills/plugins/vat-development-agents/skills/vibe-agent-toolkit__agent-authoring → skills/authoring}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: vibe-agent-toolkit:agent-authoring
+name: authoring
 description: Use when authoring SKILL.md files, designing agent architectures, or configuring packaging options. Covers SKILL.md structure, agent archetypes, orchestration patterns, and validation override patterns.
 ---
 

package/dist/{.claude/plugins/marketplaces/vat-skills/plugins/vat-development-agents/skills/vibe-agent-toolkit__debugging → skills/debugging}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: vibe-agent-toolkit:debugging
+name: debugging
 description: >-
   Debug unexpected VAT behavior, reproduce bugs, test local vibe-agent-toolkit
   changes in adopter projects (VAT_ROOT_DIR), write failing tests before fixing,

package/dist/skills/distribution/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: distribution
+description: Use when setting up vat build, configuring plugin distribution for the Claude ecosystem (marketplace, plugins, managed settings), npm publishing with postinstall hooks, or vat verify orchestration. Covers the full pipeline from skill source to installed plugin.
+---
+
+# VAT Distribution: Build, Publish & Install
+
+## Scope
+
+This skill covers the **file-based install method for Claude Code CLI** (`~/.claude/plugins/`).
+This is the only install method VAT currently supports.
+
+For the full install landscape — Claude Desktop paths, enterprise CI deployment,
+Anthropic Cloud org management, MDM integration, and the `vat plugins uninstall`
+design — see [Install & Uninstall Architecture](resources/vat-install-architecture.md).
+
+## Overview
+
+VAT distributes skills as **Claude plugins** via npm packages. The pipeline:
+
+1. `vat build` compiles SKILL.md sources into plugin artifacts
+2. `npm publish` pushes the package to a registry
+3. `npm install` triggers a postinstall hook that registers the plugin in Claude Code's plugin system
+
+Skills installed this way appear in Claude Code as `/plugin-name:skill-name`.
+
+## Project Structure
+
+```
+my-project/
+├── package.json                    ← vat.skills + postinstall hook + publishConfig
+├── vibe-agent-toolkit.config.yaml  ← skills: + claude: config
+├── resources/
+│   └── skills/
+│       └── SKILL.md
+└── dist/                           ← generated by vat build
+    ├── skills/my-skill/            ← packaged skill
+    └── .claude/plugins/marketplaces/
+        └── my-marketplace/plugins/my-plugin/
+            ├── .claude-plugin/plugin.json
+            └── skills/my-skill/SKILL.md
+```
+
+## Step 1: package.json Configuration
+
+```json
+{
+  "name": "@myorg/my-skills",
+  "version": "1.0.0",
+  "vat": {
+    "version": "1.0",
+    "skills": ["my-skill"]
+  },
+  "dependencies": {
+    "vibe-agent-toolkit": "latest"
+  },
+  "scripts": {
+    "build:vat": "vat build",
+    "postinstall": "node ./node_modules/vibe-agent-toolkit/dist/bin/vat.js claude plugin install --npm-postinstall 2>/dev/null || exit 0"
+  },
+  "files": ["dist", "README.md"],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  }
+}
+```
+
+**`vibe-agent-toolkit` must be in `dependencies` (not `devDependencies`)** so it is present in `node_modules` when the postinstall hook runs on the user's machine. Never assume `vat` is available globally — your users may not be developers.
+
+The `vat.skills` array contains skill name strings for npm discoverability. Skill source paths and packaging config live in `vibe-agent-toolkit.config.yaml` (see Step 2).
+
+For private GitHub Packages registry:
+```json
+"publishConfig": {
+  "registry": "https://npm.pkg.github.com",
+  "access": "restricted"
+}
+```
+
+Users (or IT) installing from GitHub Packages need `.npmrc` configured with the scope registry and a read-only token:
+```
+@myorg:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+IT deploying to managed machines should pre-configure `.npmrc` at the system or user level before running install commands. End users do not need to understand npm or the registry — IT handles it once.
+
+## Handling Plugin Renames: vat.replaces
+
+> **Use this only when renaming a plugin, merging plugins, or cleaning up legacy flat-skill installs. Normal upgrades (same plugin name, same skills) do NOT need `vat.replaces` — the installer already overwrites the plugin directory on every install.**
+
+### The problem: silent stale skills
+
+When you rename a plugin or reorganize skills across packages, the old registration remains in Claude Code. Claude Code **does not warn you** when two plugins provide conflicting skill names — the first-registered (stale) skill silently wins. Users continue loading old content from the renamed plugin unless the old registration is explicitly removed.
+
+This is the scenario where `vat.replaces` is needed:
+- Plugin renamed: `old-plugin-name` → `new-plugin-name`
+- Two old plugins merged into one new plugin
+- Skills previously installed to `~/.claude/skills/<name>` (legacy pre-0.1.20 flat install) now delivered via the plugin tree
+
+### How it works
+
+When a VAT package is installed (via postinstall hook or `--dev`), the installer reads `vat.replaces` from `package.json` and — **before** installing the new plugin:
+
+1. For each name in `replaces.plugins`: uninstalls `<name>@<marketplace>` — removes plugin directory, cache entry, registry entry, and `settings.json` entry
+2. For each name in `replaces.flatSkills`: deletes `~/.claude/skills/<name>` — removes legacy pre-0.1.20 flat installs
+
+Both operations are idempotent — "not found" is handled gracefully.
+
+### Schema
+
+```json
+"vat": {
+  "version": "1.0",
+  "skills": ["authoring", "audit"],
+  "replaces": {
+    "plugins": ["my-old-plugin-name"],
+    "flatSkills": ["my-old-skill", "another-old-skill"]
+  }
+}
+```
+
+Both `plugins` and `flatSkills` are optional arrays. The entire `replaces` key is optional — omit it when there is nothing to clean up.
+
+### Real example: vat-development-agents 0.1.21
+
+This package (`vat-development-agents`) renamed its plugin from `vat-development-agents` to `vibe-agent-toolkit` in v0.1.21. Without `vat.replaces`, users who had already installed v0.1.20 would have both `vat-development-agents@vat-skills` and `vibe-agent-toolkit@vat-skills` registered — Claude Code would serve stale skill content from the old plugin.
+
+The fix in `package.json`:
+
+```json
+"vat": {
+  "version": "1.0",
+  "skills": ["vibe-agent-toolkit", "resources", "distribution", "authoring", "audit", "debugging", "install"],
+  "replaces": {
+    "plugins": ["vat-development-agents"],
+    "flatSkills": ["vibe-agent-toolkit", "resources"]
+  }
+}
+```
+
+- `plugins`: removes the old plugin registration (same marketplace, old plugin name)
+- `flatSkills`: removes legacy `~/.claude/skills/vibe-agent-toolkit` and `~/.claude/skills/resources` entries from users who installed before 0.1.20 switched to the plugin tree
+
+### Non-obvious gotchas
+
+**1. Plugin names in `replaces.plugins` have NO `@marketplace`**
+
+The format is just the plugin name — e.g. `"vat-development-agents"` — NOT `"vat-development-agents@vat-skills"`. The installer infers the marketplace from the current package's dist tree. Using `@marketplace` syntax here would be wrong.
+
+**2. `replaces.plugins` is for old plugin registrations, not for skills that moved between plugins**
+
+If a skill moved from `plugin-a` to `plugin-b` within the same marketplace, list `"plugin-a"` in `replaces.plugins` to clean up the entire old plugin. You do not manage individual skills — you manage plugins.
+
+**3. `replaces.flatSkills` is ONLY for the legacy `~/.claude/skills/` location**
+
+This is specifically for skills that were previously installed as flat files to `~/.claude/skills/<name>` (pre-plugin-tree, before v0.1.20). Skills within the plugin tree (under `~/.claude/plugins/`) are handled via `replaces.plugins`. Do not mix them up.
+
+**4. Normal upgrades need nothing**
+
+If you publish a new version of the same package with the same plugin name, the installer overwrites the plugin directory automatically. `vat.replaces` is only for the case where the old name is different from the new name.
+
+**5. The symptom is subtle and delayed**
+
+You will not see an error. Claude Code simply loads the first-registered skill with a given name. If the stale plugin is registered first (alphabetically or by install order), your new content is invisible until you remove the old registration.
+
+## Step 2: vibe-agent-toolkit.config.yaml
+
+```yaml
+version: 1
+
+skills:
+  include:
+    - "resources/skills/**/SKILL.md"
+
+claude:
+  marketplaces:
+    my-marketplace:                   # org/publisher identity
+      owner:
+        name: My Organization
+      plugins:
+        - name: my-plugin             # installable unit
+          description: My plugin description
+          skills: "*"                  # all discovered skills
+```
+
+The `skills:` section discovers SKILL.md files via include/exclude globs. The `claude:` section defines how skills are packaged into plugins. Each marketplace has `owner` and `plugins` fields (strict schema — no extra fields).
+
+**Naming convention:** marketplace = org identity (e.g. `acme`), plugin = this package
+(e.g. `acme-tools`). Registers as `my-plugin@my-marketplace` in Claude's plugin registry.
+
+### Multiple skills in one package
+
+List all skills in `vat.skills` for npm discoverability:
+
+```json
+"vat": {
+  "version": "1.0",
+  "skills": ["my-linting", "my-testing"]
+}
+```
+
+Use a selector in the plugin config to include matching skills:
+
+```yaml
+plugins:
+  - name: my-plugin
+    description: Linting and testing skills
+    skills:
+      - "my-linting"
+      - "my-testing"
+```
+
+Or use `"*"` to include all discovered skills in the plugin.
+
+## Step 3: Build
+
+```bash
+vat build        # skills phase then claude phase
+vat verify       # validates resources + skills + claude artifacts
+```
+
+### What vat build does
+
+Two phases, run in dependency order:
+
+1. **`vat skills build`** — reads `vibe-agent-toolkit.config.yaml skills:` section, discovers SKILL.md files via include/exclude globs, compiles each into `dist/skills/<name>/`
+2. **`vat claude plugin build`** — reads `vibe-agent-toolkit.config.yaml claude:` section, wraps built skills into `dist/.claude/plugins/marketplaces/<mp>/plugins/<plugin>/` structure with `.claude-plugin/plugin.json`. Cleans stale output before each build.
+
+Individual commands still work:
+```bash
+vat skills build            # skills phase only
+vat claude plugin build     # claude plugin phase only (requires skills already built)
+```
+
+## Step 4: Publish
+
+```bash
+npm publish --tag next    # RC/pre-release
+npm publish               # stable release
+```
+
+## Step 5: User Install
+
+### Recommended: npm global install (postinstall runs automatically)
+
+```bash
+npm install -g @myorg/my-skills
+```
+
+The postinstall hook fires automatically and registers the plugin in Claude. This is the correct path for IT-managed deployments — no other tools required on the user's machine.
+
+### Developer/IT one-off install via npx
+
+```bash
+npx vibe-agent-toolkit claude plugin install npm:@myorg/my-skills
+```
+
+Downloads and runs VAT via npx to install a package without a global install. Useful for CI, scripting, or testing from a developer machine. Requires the npm scope registry to be configured (`.npmrc`) if installing from a private registry.
+
+### How plugin installation works
+
+When `npm install` runs the postinstall hook (`node ./node_modules/vibe-agent-toolkit/dist/bin/vat.js claude plugin install --npm-postinstall`):
+
+- VAT detects `dist/.claude/plugins/marketplaces/` directory in the installed package
+- Copies the plugin tree to Claude's plugin directory (dumb recursive copy)
+- Writes to these locations:
+  1. `~/.claude/plugins/marketplaces/<marketplace>/plugins/<plugin>/` — plugin files
+  2. `~/.claude/plugins/known_marketplaces.json` — marketplace registry
+  3. `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` — version cache
+  4. `~/.claude/plugins/installed_plugins.json` — installation record
+  5. `~/.claude/settings.json` `enabledPlugins` — activates the plugin
+
+If no `dist/.claude/plugins/marketplaces/` directory exists (package wasn't built before publish): a guidance message is emitted and the hook exits 0. The publisher must run `vat build` and re-publish.
+
+Skills are then available in Claude Code as `/plugin-name:skill-name`.
+
+## managed-settings.json Validation (Enterprise)
+
+```yaml
+claude:
+  managedSettings: managed-settings.json
+```
+
+`vat verify` validates this file against the ManagedSettings schema. Catches typos and schema errors before deployment. Does NOT deploy the file — deployment is a separate concern.
+
+## --target claude-web (ZIP Upload)
+
+For uploading skills directly to `claude.ai/settings/capabilities`:
+
+```bash
+vat skills package ./SKILL.md -o ./dist/ --target claude-web
+```
+
+Produces a ZIP:
+```
+my-skill.zip
+└── my-skill/
+    ├── SKILL.md             # skill definition (required)
+    ├── scripts/             # executable code (.mjs, .py, .sh) — optional
+    ├── references/          # markdown reference material — optional
+    └── assets/              # static data, templates, config — optional
+```
+
+Configure source path mappings in `vibe-agent-toolkit.config.yaml`:
+```yaml
+skills:
+  include:
+    - "skills/**/SKILL.md"
+  config:
+    my-skill:
+      claudeWebTarget:
+        scripts: ["./src/helpers/**/*.ts"]
+        assets: ["./assets/**"]
+```
+
+TypeScript files in `scripts` are tree-shaken and compiled to standalone `.mjs`.
+
+## Quick Reference
+
+| Task | Command |
+|---|---|
+| Build everything | `vat build` |
+| Verify everything | `vat verify` |
+| Build skills only | `vat skills build` |
+| Build claude plugin artifacts only | `vat claude plugin build` |
+| Install via npm (end user) | `npm install -g @org/pkg` |
+| Install via npx (developer/IT) | `npx vibe-agent-toolkit claude plugin install npm:@org/pkg` |
+| List installed plugins | `vat claude plugin list` |
+| Uninstall a plugin | `vat claude plugin uninstall --all` |
+| Package for claude.ai upload | `vat skills package ./SKILL.md -o ./dist/ --target claude-web` |
+
+## Future: Zero-Dependency Postinstall (Option B)
+
+A planned improvement: `vat build` would bundle the plugin install logic into `dist/postinstall.js` — a fully self-contained script with no npm dependencies. The postinstall script would become simply `node ./dist/postinstall.js`. This eliminates `vibe-agent-toolkit` as a runtime dependency entirely, reducing install footprint for end users. Until then, Option C (runtime `vibe-agent-toolkit` dep) is the correct approach.