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

package/dist/.claude/plugins/marketplaces/vat-skills/.claude-plugin/marketplace.json

@@ -6,9 +6,9 @@
   },
   "plugins": [
     {
-      "name": "vat-development-agents",
+      "name": "vibe-agent-toolkit",
       "description": "Development agents and skills for building with vibe-agent-toolkit",
-      "source": "../plugins/vat-development-agents",
+      "source": "../plugins/vibe-agent-toolkit",
       "author": {
         "name": "vibe-agent-toolkit contributors"
       }

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/{vat-development-agents → vibe-agent-toolkit}/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
-  "name": "vat-development-agents",
+  "name": "vibe-agent-toolkit",
   "description": "Development agents and skills for building with vibe-agent-toolkit",
   "author": {
     "name": "vibe-agent-toolkit contributors"

package/dist/{skills/vibe-agent-toolkit__audit → .claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/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/{skills/vibe-agent-toolkit__agent-authoring → .claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/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/{skills/vibe-agent-toolkit__debugging → .claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/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/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/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.

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/distribution/resources/vat-install-architecture.md

@@ -0,0 +1,229 @@
+---
+name: install
+description: Architecture reference for VAT skill/plugin install and uninstall — what is currently supported, what is not, and the full design vision across install methods (file-based, cloud, MDM, enterprise CI). Read this before designing or advising on any install/uninstall feature.
+---
+
+# VAT Skill Install & Uninstall: Architecture and Vision
+
+## The Problem Space
+
+Skills and plugins need to reach users' Claude installations through several distinct
+delivery channels. Each channel has different operators (developers, IT, Anthropic),
+different trust levels, and different UX requirements. VAT today only covers one of
+these channels.
+
+This document defines the full landscape, what VAT currently supports, what it does
+not, and the architectural direction for each gap.
+
+---
+
+## Install Method Landscape
+
+| Method | Operator | Current State | Notes |
+|--------|----------|---------------|-------|
+| **File-based: Code CLI** | Developer / IT | ✅ Supported | `~/.claude/plugins/` — only supported method |
+| **File-based: Claude Desktop** | Developer / IT | ❌ Not supported | Different config path; same file structure expected |
+| **npm postinstall** | IT / end-user | ✅ Supported | Requires `vibe-agent-toolkit` as runtime dep |
+| **Managed settings file** | IT / Enterprise | ✅ Partial | `vat verify` validates; deployment is out of scope |
+| **MDM-driven npm install** | IT | ✅ Works (via postinstall) | Jamf/SCCM/Intune runs `npm install -g` |
+| **Anthropic Cloud / claude.ai org** | Org admin | ❌ Not supported | No API available; future Anthropic feature |
+| **GitHub CI enterprise push** | IT / DevOps | ❌ Not supported | VAT design vision — see below |
+| **Shared network registry** | IT | ❌ Not supported | Internal npm registry approach |
+
+---
+
+## What VAT Currently Supports
+
+### File-based install: Claude Code CLI only
+
+`vat skills install` and `vat skills uninstall` operate exclusively on:
+```
+~/.claude/
+├── plugins/
+│   ├── marketplaces/<marketplace>/plugins/<plugin>/   ← plugin files
+│   ├── cache/<marketplace>/<plugin>/<version>/        ← version cache
+│   ├── known_marketplaces.json
+│   └── installed_plugins.json
+├── skills/                                            ← legacy skills (no plugin system)
+└── settings.json                                      ← enabledPlugins, permissions
+```
+
+This is the **Claude Code CLI** configuration directory. It is the only path VAT
+resolves. Claude Desktop uses a different path (see below) and is out of scope.
+
+### Install sources (all resolve to the file-based method above)
+
+```bash
+# npm package (downloads, extracts, copies plugin tree)
+vat skills install npm:@myorg/my-skills
+
+# Local directory (copies plugin tree from local path)
+vat skills install ./path/to/package
+
+# ZIP file
+vat skills install ./my-skills.zip
+
+# npm postinstall hook (triggered by npm install -g)
+# package.json: "postinstall": "node ./node_modules/vibe-agent-toolkit/dist/bin/vat.js skills install --npm-postinstall"
+```
+
+### Uninstall (current state)
+
+`vat skills uninstall` removes skills from `~/.claude/skills/` only. It does NOT
+remove plugin-system installs (the `~/.claude/plugins/` tree).
+
+**A full `vat plugins uninstall` command does not yet exist.** See design notes below.
+
+---
+
+## What VAT Does NOT Support (and Why)
+
+### Claude Desktop file-based installs
+
+Claude Desktop on macOS uses `~/Library/Application Support/Claude/` rather than
+`~/.claude/`. On Windows it uses `%APPDATA%\Claude\`.
+
+**Why not supported today**: VAT's `getClaudeUserPaths()` is hardcoded to `~/.claude/`.
+Extending it requires detecting which applications are installed and resolving both
+paths. This is well-understood work with no architectural unknowns.
+
+**Architectural note**: When implemented, both paths should be handled by a single
+`getClaudeInstallTargets()` function returning multiple targets. CLI commands gain a
+`--target code-cli|desktop|all` flag. Default is `code-cli` until Desktop path
+handling is verified stable.
+
+### Anthropic Cloud / claude.ai organization-level skills
+
+Anthropic operates a cloud-based skill system for claude.ai. Organization admins can
+manage skills for all users through the admin console. VAT has no integration with
+this system today because Anthropic has not published a public API for programmatic
+management.
+
+**Architectural note**: When Anthropic publishes an org management API, VAT should
+add `vat skills publish --target claude-ai` as a first-class install method. The
+`dist/` artifacts from `vat build` are format-compatible with this target. The gap
+is authentication and the API itself.
+
+### GitHub CI enterprise push (vision)
+
+The goal: a GitHub Actions workflow in a skills repository automatically deploys
+skills to all users in an enterprise whenever a new version is merged to main.
+
+This is a multi-layer problem with several viable approaches:
+
+#### Approach A: MDM-integrated npm publish (recommended near-term)
+```
+GitHub Actions on release →
+  npm publish @myorg/my-skills →
+    MDM policy (Jamf/SCCM/Intune) detects new package version →
+      Runs: npm install -g @myorg/my-skills
+        → postinstall hook installs plugin to user's ~/.claude/
+```
+VAT already supports this end-to-end. The MDM layer is outside VAT's scope and is
+configured by IT using standard MDM software management policies. The VAT piece is
+complete; IT must configure the npm-to-MDM trigger.
+
+#### Approach B: Managed settings deployment (near-term, no MDM required)
+```
+GitHub Actions on release →
+  vat build &&
+  Generates managed-settings.json with plugin enablement →
+    Deploys managed-settings.json to shared network path or cloud storage →
+      Claude Code reads managed-settings.json at startup
+```
+`vat verify` validates `managed-settings.json` today. The deployment step is IT's
+responsibility. This approach requires no per-machine npm install; Claude Code reads
+the settings file directly if it is placed at the expected path or if the path is
+configured.
+
+**Gap**: VAT does not yet have a `vat claude deploy` command that handles the push
+step. Adding this would require IT to configure cloud storage credentials once.
+
+#### Approach C: Anthropic org API (long-term, requires Anthropic)
+```
+GitHub Actions on release →
+  vat skills publish --target claude-ai --org myorg →
+    Anthropic API activates skills for all org users in claude.ai
+```
+Blocked on Anthropic publishing an org management API. VAT's `dist/` output format
+is already designed for this target.
+
+---
+
+## `vat plugins uninstall` — Design Intent
+
+A `vat plugins uninstall <plugin>@<marketplace>` command should exist but does not yet.
+
+### What it must reverse
+
+Uninstalling a plugin installed via the file-based method requires reversing 5 artifacts:
+
+1. Delete `~/.claude/plugins/marketplaces/<marketplace>/plugins/<plugin>/`
+2. Delete `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/`
+3. Remove `<plugin>@<marketplace>` from `installed_plugins.json`
+4. Remove `<marketplace>` from `known_marketplaces.json` if no plugins remain
+5. Remove `enabledPlugins[<plugin>@<marketplace>]` from `settings.json`
+
+### Design decisions
+
+- **Idempotent**: exit 0 if plugin not found — safe for IT automation scripts
+- **Not-VAT-installed case**: if plugin directory exists but no registry entries, delete
+  the directory and clean settings.json; emit a warning that the plugin was not
+  installed via VAT
+- **`--dry-run`**: show what would be deleted without deleting (follow `vat skills uninstall` pattern)
+- **`--target`**: code-cli | desktop | all (default: code-cli until Desktop is implemented)
+- **`vat plugins list`**: companion command to show installed plugins — needed for
+  discoverability before uninstalling
+
+### Implementation location
+
+Per the CLI "dumb orchestration" principle:
+- Logic: `packages/claude-marketplace/src/install/plugin-uninstall.ts` (new file alongside plugin-registry.ts)
+- CLI: `packages/cli/src/commands/plugins/uninstall.ts` (thin wrapper)
+- New command group: `vat plugins` with subcommands `list` and `uninstall`
+
+---
+
+## Guidance for Adopters
+
+### For end-user / IT-managed deployments (recommended)
+
+Add `vibe-agent-toolkit` as a **runtime dependency** (not devDependencies) and use
+the local node_modules binary in postinstall. Never assume `vat` is globally installed.
+
+```json
+{
+  "dependencies": { "vibe-agent-toolkit": "latest" },
+  "scripts": {
+    "postinstall": "node ./node_modules/vibe-agent-toolkit/dist/bin/vat.js skills install --npm-postinstall || exit 0"
+  }
+}
+```
+
+IT runs: `npm install -g @myorg/my-skills` — no other tools required on the user's machine.
+
+For private GitHub Packages registries, IT pre-configures `.npmrc` with a read-only
+token for the `@myorg` scope. End users do not need to know about registries or tokens.
+
+### For developer self-install
+
+```bash
+npx vibe-agent-toolkit skills install npm:@myorg/my-skills
+```
+
+### For enterprise CI (near-term best option)
+
+Use Approach A (MDM-integrated npm publish) or Approach B (managed-settings deployment).
+Both work today with no additional VAT features.
+
+---
+
+## What Is Out of Scope for VAT
+
+VAT is a **packaging and local install tool**. The following are permanently out of scope:
+
+- MDM software management configuration (Jamf, SCCM, Intune policies)
+- Internal npm registry setup and authentication management
+- Anthropic cloud API authentication or org provisioning
+- Per-user credential management for private registries
+- Claude Desktop configuration (until Desktop and Code CLI paths converge)