@vibe-agent-toolkit/vat-development-agents 0.1.33 → 0.1.34-rc.2

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

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

package/dist/skills/vat-adoption-and-configuration/SKILL.md

@@ -84,7 +84,6 @@ claude:
       plugins:
         - name: my-plugin
           description: "What this plugin does"
-          skills: "*"
 
 rag:
   stores:

package/dist/skills/vat-skill-distribution/SKILL.md

@@ -182,15 +182,14 @@ claude:
       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).
+The top-level `skills:` section drives standalone skill builds (output: `dist/skills/`). The `claude:` section defines plugins, which are assembled from their own `plugins/<name>/` directories (plugin-local skills under `plugins/<name>/skills/**/SKILL.md`). 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
+### Multiple skills in one plugin
 
 List all skills in `vat.skills` for npm discoverability:
 
@@ -201,18 +200,16 @@ List all skills in `vat.skills` for npm discoverability:
 }
 ```
 
-Use a selector in the plugin config to include matching skills:
+Each skill lives as a subdirectory of the plugin under `plugins/<name>/skills/<skill>/SKILL.md`:
 
-```yaml
-plugins:
-  - name: my-plugin
-    description: Linting and testing skills
-    skills:
-      - "my-linting"
-      - "my-testing"
+```
+plugins/my-plugin/
+  skills/
+    my-linting/SKILL.md
+    my-testing/SKILL.md
 ```
 
-Or use `"*"` to include all discovered skills in the plugin.
+All plugin-local skills found under `plugins/<name>/skills/` are packaged into the plugin automatically — no per-plugin selector is needed or supported. Skill names must be globally unique across all plugins.
 
 ## Step 3: Build
 
@@ -264,7 +261,6 @@ claude:
       plugins:
         - name: my-plugin
           description: My plugin description
-          skills: "*"
       publish:
         github:
           repo: owner/repo          # GitHub repo to publish to
@@ -406,3 +402,13 @@ All `vat` commands in this skill work with these alternatives.
 ## 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.
+
+## Full-plugin authoring (commands, hooks, agents, MCP)
+
+VAT supports bundling any Claude Code plugin asset — not just skills. Drop the plugin
+under `plugins/<name>/` in the same native layout Claude expects. VAT tree-copies
+everything (minus `skills/` and `.claude-plugin/`), merges author `plugin.json` with
+VAT-owned identity fields, and applies any `files[]` mappings for artifacts built
+outside the plugin dir.
+
+See [docs/guides/marketplace-distribution.md](resources/marketplace-distribution.md) section "Full-plugin authoring".