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

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/install/SKILL.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)

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/{vat-development-agents/skills/vibe-agent-toolkit__resources → vibe-agent-toolkit/skills/resources}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: vibe-agent-toolkit:resources
+name: resources
 description: Use when working with VAT resource collections, per-directory frontmatter schema validation, link validation, or the vat resources command. Covers collection configuration, schema mapping, and validation modes.
 ---
 

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

@@ -28,22 +28,23 @@ non-TypeScript/JavaScript projects, or cases where you need deep framework-speci
 
 | If you're working on... | Use this skill |
 |---|---|
-| Writing or structuring a `SKILL.md` file | `vibe-agent-toolkit:agent-authoring` |
-| Agent archetypes, orchestration patterns, result envelopes | `vibe-agent-toolkit:agent-authoring` |
-| `packagingOptions` (linkFollowDepth, excludeReferencesFromBundle) | `vibe-agent-toolkit:agent-authoring` |
+| Writing or structuring a `SKILL.md` file | `vibe-agent-toolkit:authoring` |
+| Agent archetypes, orchestration patterns, result envelopes | `vibe-agent-toolkit:authoring` |
+| `packagingOptions` (linkFollowDepth, excludeReferencesFromBundle) | `vibe-agent-toolkit:authoring` |
 | Resource collections, frontmatter schema validation | `vibe-agent-toolkit:resources` |
 | `vat resources validate`, collection config | `vibe-agent-toolkit:resources` |
-| Setting up `vat build` + `vat claude build` for a project | `vibe-agent-toolkit:skills-distribution` |
-| Configuring `claude:` section in vibe-agent-toolkit.config.yaml | `vibe-agent-toolkit:skills-distribution` |
-| npm publishing with plugin postinstall | `vibe-agent-toolkit:skills-distribution` |
-| `vat build` / `vat verify` orchestration | `vibe-agent-toolkit:skills-distribution` |
-| `--target claude-web` ZIP format | `vibe-agent-toolkit:skills-distribution` |
+| Setting up `vat build` + `vat claude build` for a project | `vibe-agent-toolkit:distribution` |
+| Configuring `claude:` section in vibe-agent-toolkit.config.yaml | `vibe-agent-toolkit:distribution` |
+| npm publishing with plugin postinstall | `vibe-agent-toolkit:distribution` |
+| `vat build` / `vat verify` orchestration | `vibe-agent-toolkit:distribution` |
+| `--target claude-web` ZIP format | `vibe-agent-toolkit:distribution` |
+| Install/uninstall methods, enterprise deployment, Desktop vs CLI paths | `vibe-agent-toolkit:install` |
 | `vat audit`, `--compat`, CI validation | `vibe-agent-toolkit:audit` |
 | VAT behaves unexpectedly, debugging VAT, testing local VAT changes, VAT_ROOT_DIR | `vibe-agent-toolkit:debugging` |
 
 ## Agent Archetypes (Quick Reference)
 
-Four patterns cover most use cases. For full code examples, see `vibe-agent-toolkit:agent-authoring`.
+Four patterns cover most use cases. For full code examples, see `vibe-agent-toolkit:authoring`.
 
 | Archetype | When to Use |
 |---|---|

package/dist/generated/resources/skills/SKILL.js

@@ -7,7 +7,7 @@ export const meta = {
   description: "Use when building, adopting, or learning vibe-agent-toolkit (VAT). Covers agent creation, CLI commands (vat skills, vat resources, vat audit, vat rag), runtime adapters, skill packaging, and resource validation. Routes to specialized sub-skills."
 };
 
-export const text = "\n# Vibe Agent Toolkit Skill\n\n**Vibe Agent Toolkit (VAT)** is a modular toolkit for building portable AI agents that work across\nmultiple LLM frameworks and deployment targets. Write your agent logic once as plain TypeScript,\nthen deploy it to Vercel AI SDK, LangChain, OpenAI, Claude Agent SDK, or any other runtime using\nframework adapters. No vendor lock-in.\n\n## Purpose: For Users, Not Contributors\n\n- **This skill** = How to USE VAT to build agents\n- **\`vibe-agent-toolkit:debugging\`** = When VAT itself behaves unexpectedly or you need to test a fix\n- **Root CLAUDE.md** = How to DEVELOP the VAT codebase itself\n\n## When to Use VAT\n\n**VAT is great for:** Multi-framework projects, reusable agent libraries, testing across LLM\nproviders, complex multi-agent orchestration, human-in-the-loop workflows.\n\n**VAT may not be needed for:** Simple one-off scripts where the framework is already decided,\nnon-TypeScript/JavaScript projects, or cases where you need deep framework-specific features.\n\n## Skill Routing Table\n\n| If you\'re working on... | Use this skill |\n|---|---|\n| Writing or structuring a \`SKILL.md\` file | \`vibe-agent-toolkit:agent-authoring\` |\n| Agent archetypes, orchestration patterns, result envelopes | \`vibe-agent-toolkit:agent-authoring\` |\n| \`packagingOptions\` (linkFollowDepth, excludeReferencesFromBundle) | \`vibe-agent-toolkit:agent-authoring\` |\n| Resource collections, frontmatter schema validation | \`vibe-agent-toolkit:resources\` |\n| \`vat resources validate\`, collection config | \`vibe-agent-toolkit:resources\` |\n| Setting up \`vat build\` + \`vat claude build\` for a project | \`vibe-agent-toolkit:skills-distribution\` |\n| Configuring \`claude:\` section in vibe-agent-toolkit.config.yaml | \`vibe-agent-toolkit:skills-distribution\` |\n| npm publishing with plugin postinstall | \`vibe-agent-toolkit:skills-distribution\` |\n| \`vat build\` / \`vat verify\` orchestration | \`vibe-agent-toolkit:skills-distribution\` |\n| \`--target claude-web\` ZIP format | \`vibe-agent-toolkit:skills-distribution\` |\n| \`vat audit\`, \`--compat\`, CI validation | \`vibe-agent-toolkit:audit\` |\n| VAT behaves unexpectedly, debugging VAT, testing local VAT changes, VAT_ROOT_DIR | \`vibe-agent-toolkit:debugging\` |\n\n## Agent Archetypes (Quick Reference)\n\nFour patterns cover most use cases. For full code examples, see \`vibe-agent-toolkit:agent-authoring\`.\n\n| Archetype | When to Use |\n|---|---|\n| **Pure Function Tool** | Stateless validation, transformation, computation — no LLM needed |\n| **One-Shot LLM Analyzer** | Single LLM call for analysis, classification, or generation |\n| **Conversational Assistant** | Multi-turn dialogue with session state across turns |\n| **External Event Integrator** | Waiting for human approval, webhooks, or third-party APIs |\n\n## Core CLI Commands\n\n\`\`\`bash\n# Install VAT CLI globally\nnpm install -g vibe-agent-toolkit\n\n# Top-level orchestration\nvat build                                # build all artifacts (skills then claude plugins)\nvat verify                               # verify all artifacts (resources, skills, claude)\n\n# Claude plugin commands\nvat claude build                         # generate plugin artifacts from built skills\nvat claude verify                        # validate plugin artifacts\n\n# Skills\nvat skills list                          # list skills in current project\nvat skills list --user                   # list user-installed skills\nvat skills install npm:@org/my-skills    # install from npm (routes through plugin system)\nvat skills build                         # build portable skills only\nvat skills validate                      # validate skill quality\n\n# Resources\nvat resources validate                   # validate collections (reads config)\nvat resources validate docs/ --frontmatter-schema schema.json\n\n# Audit\nvat audit                                # audit current directory recursively\nvat audit --user                         # audit entire Claude installation\nvat audit ./plugins/ --compat            # check surface compatibility\n\n# RAG\nvat rag index docs/                      # index markdown into vector DB\nvat rag query \"my question\" --limit 5    # semantic search\n\n# Get help for any command\nvat --help\nvat skills --help\n\`\`\`\n\n## agent-generator: Creating New Agents\n\nThe **agent-generator** is a built-in meta-agent that guides you through designing\nhigh-quality agents via a 4-phase workflow:\n\n1. **GATHER** — Understand your intent and goals\n2. **ANALYZE** — Identify agent pattern and requirements\n3. **DESIGN** — Make architecture decisions (LLM, tools, prompts)\n4. **GENERATE** — Create validated agent package\n\nMinimum input needed:\n\`\`\`json\n{\n  \"agentPurpose\": \"Review PRs for security issues\",\n  \"successCriteria\": \"Catches 100% of critical vulnerabilities\"\n}\n\`\`\`\n\nThe generator produces: \`agent.yaml\`, \`prompts/system.md\`, \`prompts/user.md\`,\n\`schemas/input.schema.json\`, \`schemas/output.schema.json\`, and \`README.md\`.\n\n**Tips for better results:**\n- Be specific about success criteria (\"Under 30s, zero false negatives\") not vague (\"fast enough\")\n- Name the tools the agent needs upfront (file readers, APIs, etc.)\n- Describe domain context (OWASP Top 10, company coding standards, etc.)\n\n## Packaging Markdown for Reuse\n\nVAT\'s resource compiler transforms markdown files into type-safe TypeScript modules,\nenabling prompt libraries, RAG knowledge bases, and shared content across projects.\n\n\`\`\`bash\nnpm install -D @vibe-agent-toolkit/resource-compiler\nnpx vat-compile-resources compile resources/ generated/resources/\n\`\`\`\n\n\`\`\`typescript\nimport * as Doc from \'./generated/resources/doc.js\';\n\nDoc.meta.title;                        // type-safe frontmatter\nDoc.fragments.introduction.text;       // H2 section content\nDoc.text;                              // full markdown\n\`\`\`\n\nUse cases: agent prompt libraries, RAG knowledge bases packaged as npm modules,\nmulti-project content sharing with versioning.\n\n## Common Workflows\n\n**Create a new agent:**\n\`\`\`bash\n# Use agent-generator interactively, then:\nvat agent import my-skill/SKILL.md   # import to VAT format\nvat skills validate                   # check quality\nvat skills build                      # package for distribution\n\`\`\`\n\n**Install and use a community skill:**\n\`\`\`bash\nvat skills install npm:@vibe-agent-toolkit/vat-cat-agents\nvat skills list --user\n# Plugin-aware packages register in Claude\'s plugin system\n# Skills are invoked as /plugin-name:skill-name in Claude Code\n\`\`\`\n\n**Build and publish your own skill package:**\n\`\`\`bash\n# Configure vat.skills in package.json + claude: in vibe-agent-toolkit.config.yaml, then:\nvat build                 # builds skills + claude plugin artifacts\nvat verify                # validates everything\nnpm publish               # publishes to npm (postinstall registers the plugin)\n# Users install with: vat skills install npm:@myorg/my-skills\n\`\`\`\n\n## Success Criteria\n\nYou\'ve successfully adopted VAT when:\n- Agents have clear input/output schemas (Zod-validated)\n- Errors are handled as data (result envelopes), never thrown\n- Tests cover success and error paths without real API calls (mock mode)\n- Agents work across multiple runtimes via adapters\n- Multi-agent pipelines compose via \`andThen()\` / \`match()\` helpers\n\n## Documentation Index\n\n- [Getting Started Guide](../../../../docs/getting-started.md)\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) — patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) — multi-agent workflows\n- [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md)\n- [Resource Compiler Guide](../../../../docs/guides/resource-compiler/compiling-markdown-to-typescript.md)\n- [Runtime Adapters](../../../../docs/adding-runtime-adapters.md)\n- Examples: \`@vibe-agent-toolkit/vat-example-cat-agents\`\n\n## Getting Help\n\n- **CLI Help:** \`vat --help\`, \`vat skills --help\`, etc.\n- **Examples:** \`packages/vat-example-cat-agents/\`\n- **GitHub Issues:** Report bugs or ask questions\n\nHappy agent building!\n";
+export const text = "\n# Vibe Agent Toolkit Skill\n\n**Vibe Agent Toolkit (VAT)** is a modular toolkit for building portable AI agents that work across\nmultiple LLM frameworks and deployment targets. Write your agent logic once as plain TypeScript,\nthen deploy it to Vercel AI SDK, LangChain, OpenAI, Claude Agent SDK, or any other runtime using\nframework adapters. No vendor lock-in.\n\n## Purpose: For Users, Not Contributors\n\n- **This skill** = How to USE VAT to build agents\n- **\`vibe-agent-toolkit:debugging\`** = When VAT itself behaves unexpectedly or you need to test a fix\n- **Root CLAUDE.md** = How to DEVELOP the VAT codebase itself\n\n## When to Use VAT\n\n**VAT is great for:** Multi-framework projects, reusable agent libraries, testing across LLM\nproviders, complex multi-agent orchestration, human-in-the-loop workflows.\n\n**VAT may not be needed for:** Simple one-off scripts where the framework is already decided,\nnon-TypeScript/JavaScript projects, or cases where you need deep framework-specific features.\n\n## Skill Routing Table\n\n| If you\'re working on... | Use this skill |\n|---|---|\n| Writing or structuring a \`SKILL.md\` file | \`vibe-agent-toolkit:authoring\` |\n| Agent archetypes, orchestration patterns, result envelopes | \`vibe-agent-toolkit:authoring\` |\n| \`packagingOptions\` (linkFollowDepth, excludeReferencesFromBundle) | \`vibe-agent-toolkit:authoring\` |\n| Resource collections, frontmatter schema validation | \`vibe-agent-toolkit:resources\` |\n| \`vat resources validate\`, collection config | \`vibe-agent-toolkit:resources\` |\n| Setting up \`vat build\` + \`vat claude build\` for a project | \`vibe-agent-toolkit:distribution\` |\n| Configuring \`claude:\` section in vibe-agent-toolkit.config.yaml | \`vibe-agent-toolkit:distribution\` |\n| npm publishing with plugin postinstall | \`vibe-agent-toolkit:distribution\` |\n| \`vat build\` / \`vat verify\` orchestration | \`vibe-agent-toolkit:distribution\` |\n| \`--target claude-web\` ZIP format | \`vibe-agent-toolkit:distribution\` |\n| Install/uninstall methods, enterprise deployment, Desktop vs CLI paths | \`vibe-agent-toolkit:install\` |\n| \`vat audit\`, \`--compat\`, CI validation | \`vibe-agent-toolkit:audit\` |\n| VAT behaves unexpectedly, debugging VAT, testing local VAT changes, VAT_ROOT_DIR | \`vibe-agent-toolkit:debugging\` |\n\n## Agent Archetypes (Quick Reference)\n\nFour patterns cover most use cases. For full code examples, see \`vibe-agent-toolkit:authoring\`.\n\n| Archetype | When to Use |\n|---|---|\n| **Pure Function Tool** | Stateless validation, transformation, computation — no LLM needed |\n| **One-Shot LLM Analyzer** | Single LLM call for analysis, classification, or generation |\n| **Conversational Assistant** | Multi-turn dialogue with session state across turns |\n| **External Event Integrator** | Waiting for human approval, webhooks, or third-party APIs |\n\n## Core CLI Commands\n\n\`\`\`bash\n# Install VAT CLI globally\nnpm install -g vibe-agent-toolkit\n\n# Top-level orchestration\nvat build                                # build all artifacts (skills then claude plugins)\nvat verify                               # verify all artifacts (resources, skills, claude)\n\n# Claude plugin commands\nvat claude build                         # generate plugin artifacts from built skills\nvat claude verify                        # validate plugin artifacts\n\n# Skills\nvat skills list                          # list skills in current project\nvat skills list --user                   # list user-installed skills\nvat skills install npm:@org/my-skills    # install from npm (routes through plugin system)\nvat skills build                         # build portable skills only\nvat skills validate                      # validate skill quality\n\n# Resources\nvat resources validate                   # validate collections (reads config)\nvat resources validate docs/ --frontmatter-schema schema.json\n\n# Audit\nvat audit                                # audit current directory recursively\nvat audit --user                         # audit entire Claude installation\nvat audit ./plugins/ --compat            # check surface compatibility\n\n# RAG\nvat rag index docs/                      # index markdown into vector DB\nvat rag query \"my question\" --limit 5    # semantic search\n\n# Get help for any command\nvat --help\nvat skills --help\n\`\`\`\n\n## agent-generator: Creating New Agents\n\nThe **agent-generator** is a built-in meta-agent that guides you through designing\nhigh-quality agents via a 4-phase workflow:\n\n1. **GATHER** — Understand your intent and goals\n2. **ANALYZE** — Identify agent pattern and requirements\n3. **DESIGN** — Make architecture decisions (LLM, tools, prompts)\n4. **GENERATE** — Create validated agent package\n\nMinimum input needed:\n\`\`\`json\n{\n  \"agentPurpose\": \"Review PRs for security issues\",\n  \"successCriteria\": \"Catches 100% of critical vulnerabilities\"\n}\n\`\`\`\n\nThe generator produces: \`agent.yaml\`, \`prompts/system.md\`, \`prompts/user.md\`,\n\`schemas/input.schema.json\`, \`schemas/output.schema.json\`, and \`README.md\`.\n\n**Tips for better results:**\n- Be specific about success criteria (\"Under 30s, zero false negatives\") not vague (\"fast enough\")\n- Name the tools the agent needs upfront (file readers, APIs, etc.)\n- Describe domain context (OWASP Top 10, company coding standards, etc.)\n\n## Packaging Markdown for Reuse\n\nVAT\'s resource compiler transforms markdown files into type-safe TypeScript modules,\nenabling prompt libraries, RAG knowledge bases, and shared content across projects.\n\n\`\`\`bash\nnpm install -D @vibe-agent-toolkit/resource-compiler\nnpx vat-compile-resources compile resources/ generated/resources/\n\`\`\`\n\n\`\`\`typescript\nimport * as Doc from \'./generated/resources/doc.js\';\n\nDoc.meta.title;                        // type-safe frontmatter\nDoc.fragments.introduction.text;       // H2 section content\nDoc.text;                              // full markdown\n\`\`\`\n\nUse cases: agent prompt libraries, RAG knowledge bases packaged as npm modules,\nmulti-project content sharing with versioning.\n\n## Common Workflows\n\n**Create a new agent:**\n\`\`\`bash\n# Use agent-generator interactively, then:\nvat agent import my-skill/SKILL.md   # import to VAT format\nvat skills validate                   # check quality\nvat skills build                      # package for distribution\n\`\`\`\n\n**Install and use a community skill:**\n\`\`\`bash\nvat skills install npm:@vibe-agent-toolkit/vat-cat-agents\nvat skills list --user\n# Plugin-aware packages register in Claude\'s plugin system\n# Skills are invoked as /plugin-name:skill-name in Claude Code\n\`\`\`\n\n**Build and publish your own skill package:**\n\`\`\`bash\n# Configure vat.skills in package.json + claude: in vibe-agent-toolkit.config.yaml, then:\nvat build                 # builds skills + claude plugin artifacts\nvat verify                # validates everything\nnpm publish               # publishes to npm (postinstall registers the plugin)\n# Users install with: vat skills install npm:@myorg/my-skills\n\`\`\`\n\n## Success Criteria\n\nYou\'ve successfully adopted VAT when:\n- Agents have clear input/output schemas (Zod-validated)\n- Errors are handled as data (result envelopes), never thrown\n- Tests cover success and error paths without real API calls (mock mode)\n- Agents work across multiple runtimes via adapters\n- Multi-agent pipelines compose via \`andThen()\` / \`match()\` helpers\n\n## Documentation Index\n\n- [Getting Started Guide](../../../../docs/getting-started.md)\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) — patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) — multi-agent workflows\n- [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md)\n- [Resource Compiler Guide](../../../../docs/guides/resource-compiler/compiling-markdown-to-typescript.md)\n- [Runtime Adapters](../../../../docs/adding-runtime-adapters.md)\n- Examples: \`@vibe-agent-toolkit/vat-example-cat-agents\`\n\n## Getting Help\n\n- **CLI Help:** \`vat --help\`, \`vat skills --help\`, etc.\n- **Examples:** \`packages/vat-example-cat-agents/\`\n- **GitHub Issues:** Report bugs or ask questions\n\nHappy agent building!\n";
 
 export const fragments = {
   purposeForUsersNotContributors: {
@@ -22,13 +22,13 @@ export const fragments = {
   },
   skillRoutingTable: {
     header: "## Skill Routing Table",
-    body: "| If you\'re working on... | Use this skill |\n|---|---|\n| Writing or structuring a \`SKILL.md\` file | \`vibe-agent-toolkit:agent-authoring\` |\n| Agent archetypes, orchestration patterns, result envelopes | \`vibe-agent-toolkit:agent-authoring\` |\n| \`packagingOptions\` (linkFollowDepth, excludeReferencesFromBundle) | \`vibe-agent-toolkit:agent-authoring\` |\n| Resource collections, frontmatter schema validation | \`vibe-agent-toolkit:resources\` |\n| \`vat resources validate\`, collection config | \`vibe-agent-toolkit:resources\` |\n| Setting up \`vat build\` + \`vat claude build\` for a project | \`vibe-agent-toolkit:skills-distribution\` |\n| Configuring \`claude:\` section in vibe-agent-toolkit.config.yaml | \`vibe-agent-toolkit:skills-distribution\` |\n| npm publishing with plugin postinstall | \`vibe-agent-toolkit:skills-distribution\` |\n| \`vat build\` / \`vat verify\` orchestration | \`vibe-agent-toolkit:skills-distribution\` |\n| \`--target claude-web\` ZIP format | \`vibe-agent-toolkit:skills-distribution\` |\n| \`vat audit\`, \`--compat\`, CI validation | \`vibe-agent-toolkit:audit\` |\n| VAT behaves unexpectedly, debugging VAT, testing local VAT changes, VAT_ROOT_DIR | \`vibe-agent-toolkit:debugging\` |",
-    text: "## Skill Routing Table\n\n| If you\'re working on... | Use this skill |\n|---|---|\n| Writing or structuring a \`SKILL.md\` file | \`vibe-agent-toolkit:agent-authoring\` |\n| Agent archetypes, orchestration patterns, result envelopes | \`vibe-agent-toolkit:agent-authoring\` |\n| \`packagingOptions\` (linkFollowDepth, excludeReferencesFromBundle) | \`vibe-agent-toolkit:agent-authoring\` |\n| Resource collections, frontmatter schema validation | \`vibe-agent-toolkit:resources\` |\n| \`vat resources validate\`, collection config | \`vibe-agent-toolkit:resources\` |\n| Setting up \`vat build\` + \`vat claude build\` for a project | \`vibe-agent-toolkit:skills-distribution\` |\n| Configuring \`claude:\` section in vibe-agent-toolkit.config.yaml | \`vibe-agent-toolkit:skills-distribution\` |\n| npm publishing with plugin postinstall | \`vibe-agent-toolkit:skills-distribution\` |\n| \`vat build\` / \`vat verify\` orchestration | \`vibe-agent-toolkit:skills-distribution\` |\n| \`--target claude-web\` ZIP format | \`vibe-agent-toolkit:skills-distribution\` |\n| \`vat audit\`, \`--compat\`, CI validation | \`vibe-agent-toolkit:audit\` |\n| VAT behaves unexpectedly, debugging VAT, testing local VAT changes, VAT_ROOT_DIR | \`vibe-agent-toolkit:debugging\` |"
+    body: "| If you\'re working on... | Use this skill |\n|---|---|\n| Writing or structuring a \`SKILL.md\` file | \`vibe-agent-toolkit:authoring\` |\n| Agent archetypes, orchestration patterns, result envelopes | \`vibe-agent-toolkit:authoring\` |\n| \`packagingOptions\` (linkFollowDepth, excludeReferencesFromBundle) | \`vibe-agent-toolkit:authoring\` |\n| Resource collections, frontmatter schema validation | \`vibe-agent-toolkit:resources\` |\n| \`vat resources validate\`, collection config | \`vibe-agent-toolkit:resources\` |\n| Setting up \`vat build\` + \`vat claude build\` for a project | \`vibe-agent-toolkit:distribution\` |\n| Configuring \`claude:\` section in vibe-agent-toolkit.config.yaml | \`vibe-agent-toolkit:distribution\` |\n| npm publishing with plugin postinstall | \`vibe-agent-toolkit:distribution\` |\n| \`vat build\` / \`vat verify\` orchestration | \`vibe-agent-toolkit:distribution\` |\n| \`--target claude-web\` ZIP format | \`vibe-agent-toolkit:distribution\` |\n| Install/uninstall methods, enterprise deployment, Desktop vs CLI paths | \`vibe-agent-toolkit:install\` |\n| \`vat audit\`, \`--compat\`, CI validation | \`vibe-agent-toolkit:audit\` |\n| VAT behaves unexpectedly, debugging VAT, testing local VAT changes, VAT_ROOT_DIR | \`vibe-agent-toolkit:debugging\` |",
+    text: "## Skill Routing Table\n\n| If you\'re working on... | Use this skill |\n|---|---|\n| Writing or structuring a \`SKILL.md\` file | \`vibe-agent-toolkit:authoring\` |\n| Agent archetypes, orchestration patterns, result envelopes | \`vibe-agent-toolkit:authoring\` |\n| \`packagingOptions\` (linkFollowDepth, excludeReferencesFromBundle) | \`vibe-agent-toolkit:authoring\` |\n| Resource collections, frontmatter schema validation | \`vibe-agent-toolkit:resources\` |\n| \`vat resources validate\`, collection config | \`vibe-agent-toolkit:resources\` |\n| Setting up \`vat build\` + \`vat claude build\` for a project | \`vibe-agent-toolkit:distribution\` |\n| Configuring \`claude:\` section in vibe-agent-toolkit.config.yaml | \`vibe-agent-toolkit:distribution\` |\n| npm publishing with plugin postinstall | \`vibe-agent-toolkit:distribution\` |\n| \`vat build\` / \`vat verify\` orchestration | \`vibe-agent-toolkit:distribution\` |\n| \`--target claude-web\` ZIP format | \`vibe-agent-toolkit:distribution\` |\n| Install/uninstall methods, enterprise deployment, Desktop vs CLI paths | \`vibe-agent-toolkit:install\` |\n| \`vat audit\`, \`--compat\`, CI validation | \`vibe-agent-toolkit:audit\` |\n| VAT behaves unexpectedly, debugging VAT, testing local VAT changes, VAT_ROOT_DIR | \`vibe-agent-toolkit:debugging\` |"
   },
   agentArchetypesQuickReference: {
     header: "## Agent Archetypes (Quick Reference)",
-    body: "Four patterns cover most use cases. For full code examples, see \`vibe-agent-toolkit:agent-authoring\`.\n\n| Archetype | When to Use |\n|---|---|\n| **Pure Function Tool** | Stateless validation, transformation, computation — no LLM needed |\n| **One-Shot LLM Analyzer** | Single LLM call for analysis, classification, or generation |\n| **Conversational Assistant** | Multi-turn dialogue with session state across turns |\n| **External Event Integrator** | Waiting for human approval, webhooks, or third-party APIs |",
-    text: "## Agent Archetypes (Quick Reference)\n\nFour patterns cover most use cases. For full code examples, see \`vibe-agent-toolkit:agent-authoring\`.\n\n| Archetype | When to Use |\n|---|---|\n| **Pure Function Tool** | Stateless validation, transformation, computation — no LLM needed |\n| **One-Shot LLM Analyzer** | Single LLM call for analysis, classification, or generation |\n| **Conversational Assistant** | Multi-turn dialogue with session state across turns |\n| **External Event Integrator** | Waiting for human approval, webhooks, or third-party APIs |"
+    body: "Four patterns cover most use cases. For full code examples, see \`vibe-agent-toolkit:authoring\`.\n\n| Archetype | When to Use |\n|---|---|\n| **Pure Function Tool** | Stateless validation, transformation, computation — no LLM needed |\n| **One-Shot LLM Analyzer** | Single LLM call for analysis, classification, or generation |\n| **Conversational Assistant** | Multi-turn dialogue with session state across turns |\n| **External Event Integrator** | Waiting for human approval, webhooks, or third-party APIs |",
+    text: "## Agent Archetypes (Quick Reference)\n\nFour patterns cover most use cases. For full code examples, see \`vibe-agent-toolkit:authoring\`.\n\n| Archetype | When to Use |\n|---|---|\n| **Pure Function Tool** | Stateless validation, transformation, computation — no LLM needed |\n| **One-Shot LLM Analyzer** | Single LLM call for analysis, classification, or generation |\n| **Conversational Assistant** | Multi-turn dialogue with session state across turns |\n| **External Event Integrator** | Waiting for human approval, webhooks, or third-party APIs |"
   },
   coreCliCommands: {
     header: "## Core CLI Commands",

package/dist/generated/resources/skills/vat-agent-authoring.js

@@ -3,7 +3,7 @@
  */
 
 export const meta = {
-  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/generated/resources/skills/vat-audit.js

@@ -3,7 +3,7 @@
  */
 
 export const meta = {
-  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/generated/resources/skills/vat-debugging.js

@@ -3,7 +3,7 @@
  */
 
 export const meta = {
-  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, and validate fixes with the full build pipeline before publishing"
 };
 

package/dist/generated/resources/skills/vat-install-architecture.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Generated TypeScript declarations - DO NOT EDIT
+ */
+
+export interface Fragment {
+  readonly header: string;
+  readonly body: string;
+  readonly text: string;
+}
+
+export const meta: {
+  readonly name: string;
+  readonly description: string;
+};
+
+export const text: string;
+
+export const fragments: {
+  readonly theProblemSpace: Fragment;
+  readonly installMethodLandscape: Fragment;
+  readonly whatVatCurrentlySupports: Fragment;
+  readonly whatVatDoesNotSupportAndWhy: Fragment;
+  readonly vatPluginsUninstall-DesignIntent: Fragment;
+  readonly guidanceForAdopters: Fragment;
+  readonly whatIsOutOfScopeForVat: Fragment;
+};
+
+export type FragmentName = keyof typeof fragments;

package/dist/generated/resources/skills/vat-install-architecture.js

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

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

@@ -3,7 +3,7 @@
  */
 
 export const meta = {
-  name: "vibe-agent-toolkit:resources",
+  name: "resources",
   description: "Use when working with VAT resource collections, per-directory frontmatter schema validation, link validation, or the vat resources command. Covers collection configuration, schema mapping, and validation modes."
 };
 

package/dist/generated/resources/skills/vat-skills-distribution.d.ts

@@ -16,9 +16,11 @@ export const meta: {
 export const text: string;
 
 export const fragments: {
+  readonly scope: Fragment;
   readonly overview: Fragment;
   readonly projectStructure: Fragment;
   readonly step1PackagejsonConfiguration: Fragment;
+  readonly handlingPluginRenamesVatreplaces: Fragment;
   readonly step2VibeAgentToolkitconfigyaml: Fragment;
   readonly step3Build: Fragment;
   readonly step4Publish: Fragment;
@@ -26,6 +28,7 @@ export const fragments: {
   readonly managedSettingsjsonValidationEnterprise: Fragment;
   readonly -TargetClaudeWebZipUpload: Fragment;
   readonly quickReference: Fragment;
+  readonly futureZeroDependencyPostinstallOptionB: Fragment;
 };
 
 export type FragmentName = keyof typeof fragments;