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

package/dist/.claude/plugins/marketplaces/vat-skills/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.34] - 2026-05-06
+
+### Added
+- **`vat inventory <path>`** — new top-level command emitting structural YAML/JSON for plugins, marketplaces, skills, and installs (`schema: vat.inventory/v1alpha`). Runs no validators; pure structural enumeration. Supports `--user`, `--shallow`, and `--format json|yaml`. The same inventory model is now the single substrate for `vat audit` — adopters who want to script structural questions about their plugins (declared vs. discovered components, parse errors, cross-references) can do so without re-walking the filesystem.
+- **`vat corpus scan [seed-file] --out <dir>`** — audit and (with `--with-review`) review multiple plugins in one run. Reads a YAML seed of tracked plugins, audits each, and aggregates per-plugin output. Per-entry `validation:` overrides silence findings on a per-plugin basis. Ships with a starter `corpus/seed.yaml` of 11 plugins.
+- **`vat audit` accepts a git URL.** Pass HTTPS, SSH, GitHub-shorthand (`owner/repo`), GitHub web URL, or `file://`, optionally with `#ref:subpath`. Shallow-clones, audits, cleans up. Auth is passthrough to your local `git` — VAT reads no tokens. `--debug` preserves the cloned tempdir.
+- **`vat claude plugin build`** — bundle commands, hooks, agents, MCP servers, scripts, plugin-local `SKILL.md` files, and `plugin.json` from a `plugins/<name>/` directory into a self-contained Claude Code plugin (tree-copied verbatim, `.gitignore`-respecting). Pool-skill import via `marketplace.plugins[].skills` (`"*"` or `[names]`) preserved. New marketplace fields: `source` (path override) and `files[]` (compiled-artifact mappings). Case mismatches between declared plugin names and on-disk dirs fail the build.
+- **`skill-claude-plugin` recognized as a distinct artifact shape.** A skill that self-publishes as a Claude plugin by co-locating `.claude-plugin/plugin.json` alongside its root `SKILL.md` now produces independent `agent-skill` and `claude-plugin` validation results. New `SKILL_CLAUDE_PLUGIN_NAME_MISMATCH` warning fires when the manifest name disagrees with the SKILL.md `name`.
+- **Eleven new validation codes.**
+  - Seven cross-walked from Anthropic's `plugin-dev` skill, all `info` severity per the rule-addition policy: `PLUGIN_MISSING_DESCRIPTION`, `PLUGIN_MISSING_AUTHOR`, `PLUGIN_MISSING_LICENSE`, `PLUGIN_NAME_NOT_KEBAB_CASE`, `SKILL_NAME_NOT_KEBAB_CASE`, `SKILL_REFERENCES_BUT_NO_LINKS`, `SKILL_BODY_NOT_IMPERATIVE`. Additive observability — no existing audit will newly fail.
+  - Four structural codes derived from the inventory model:
+    - `COMPONENT_DECLARED_BUT_MISSING` (warning) — manifest declares a component path that's absent on disk.
+    - `COMPONENT_PRESENT_BUT_UNDECLARED` (info) — component exists under canonical layout but the manifest's explicit list omits it; the runtime will silently skip it. Fires only when `declared !== null`; auto-discovery (a missing field) is intentional and not flagged.
+    - `REFERENCE_TARGET_MISSING` (error) — a manifest-resolved cross-component reference (hook script, MCP path) points at a missing file.
+    - `MARKETPLACE_PLUGIN_SOURCE_MISSING` (error) — a marketplace declares a path-source plugin that doesn't exist.
+- **Three `[VAT]` manual checklist items in `vat-skill-review.md`** for judgment calls automation can't make: description names concrete trigger phrases, description disambiguates from sibling skills, body avoids duplicating reference content.
+
+### Changed
+- **`vat audit <marketplace-dir>` now recurses into co-located, path-source plugins.** Previously a marketplace audit scanned only the manifest; plugins declared via `./plugins/<name>` were silently skipped. Each path-source plugin in `discovered.plugins[]` is now audited via the same plugin pipeline. Adopters who run `vat audit` against a marketplace directory in CI will see findings for the contained plugins and their skills (e.g., `vibe-validate.git#claude-marketplace`: 1 file scanned → 10). Git/npm sources stay out of scope.
+- **Breaking (pre-1.0):** `ClaudePluginSchema`, `ClaudePlugin`, `ClaudePluginJsonSchema`, and `validatePlugin` moved from `@vibe-agent-toolkit/agent-skills` to `@vibe-agent-toolkit/claude-marketplace`. `agent-skills` is now vendor-neutral. Update imports.
+
+### Documentation
+- New `docs/architecture/skill-packaging.md` enumerates the four packaging shapes (standalone skill / skill-claude-plugin / claude-plugin / claude-marketplace) and the inventory model.
+- New "Plugin Inventory Codes" section in `docs/validation-codes.md` and a "Declared vs discovered components" subsection in `docs/skill-quality-and-compatibility.md` document the tri-state declared/discovered model and the empirical Claude Code loader behavior behind it.
+
 ## [0.1.33] - 2026-04-21
 
 ### Added
@@ -56,7 +81,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Post-build validation**: `vat skills build` runs the full validation suite against built `dist/skills/*/SKILL.md` (skipping source-only codes like `LINK_OUTSIDE_PROJECT`). Build failures surface identically to source failures.
 - **`info` severity** in the validation framework. `CAPABILITY_*` and `COMPAT_TARGET_UNDECLARED` emit as info; they appear in output and respect `validation.severity` overrides but do not contribute to build failure status.
 - New validation codes: `CAPABILITY_LOCAL_SHELL`, `CAPABILITY_EXTERNAL_CLI`, `CAPABILITY_BROWSER_AUTH` (info); `COMPAT_TARGET_INCOMPATIBLE`, `COMPAT_TARGET_NEEDS_REVIEW` (warning); `COMPAT_TARGET_UNDECLARED` (info).
-- Skill-smell philosophy doc at `docs/skill-smell-philosophy.md` articulating rule-addition bar, default severity posture, graduation path, and data-driven evolution. Referenced from `docs/validation-codes.md`.
+- Validation-rule-design doc at `docs/validation-rule-design.md` articulating rule-addition bar, default severity posture, graduation path, and data-driven evolution. Referenced from `docs/validation-codes.md`.
 - Cached Anthropic skill-authoring best-practices doc at `docs/external/anthropic-skill-authoring-best-practices.md` with attribution, source URL, and fetch date. Provides a diffable reference so VAT's tooling stays aligned with upstream Anthropic guidance. CLAUDE.md documents the periodic-refresh policy.
 - `vat-skill-review.md` (formerly `skill-quality-checklist.md`) rewritten with `[A]` / `[VAT]` tags distinguishing Anthropic-aligned items from VAT-opinionated additions. Added gerund-form naming guidance (Anthropic's preferred pattern), frontmatter-key conservatism, cross-skill dependency disclosure, in-package YAML-styling consistency, and large-tables-to-reference-files guidance — all from dogfood findings across 17 real skills (8 avonrisk-sdlc + 1 vibe-validate + 8 VAT dev-agents).
 - Five new skill-quality validation codes, all non-blocking:

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/.claude-plugin/plugin.json

@@ -1,8 +1,9 @@
 {
+  "license": "MIT",
   "name": "vibe-agent-toolkit",
-  "description": "Development agents and skills for building with vibe-agent-toolkit",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "author": {
     "name": "vibe-agent-toolkit contributors"
-  }
+  },
+  "description": "Development agents and skills for building with vibe-agent-toolkit"
 }

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

@@ -41,6 +41,36 @@ Running `vat audit <path>` recursively walks the directory and auto-detects:
 
 Recursion is the default — you do not need `--recursive`.
 
+## Auditing a remote git repo
+
+`vat audit` accepts a git URL in addition to a local path. VAT shallow-clones into a temp directory, audits the clone, and **always cleans up on exit** — including on errors and SIGINT.
+
+```bash
+# Audit a public repo (HTTPS)
+vat audit https://github.com/foo/bar.git
+
+# GitHub shorthand
+vat audit foo/bar
+
+# Pin to a branch or tag
+vat audit foo/bar#main
+vat audit https://github.com/foo/bar.git#v1.2.3
+
+# Narrow to a monorepo subpath
+vat audit foo/bar#main:plugins/baz
+
+# A GitHub web URL also works
+vat audit https://github.com/foo/bar/tree/main/plugins/baz
+```
+
+Output is preceded by a provenance header — `# Audited: <url> @ <ref> (commit <sha>)` — emitted as YAML comments so `vat audit <url> | yq` parses cleanly. Audited paths are repo-relative, never tempdir-relative.
+
+**Authentication is pure passthrough to your local `git`.** SSH URLs use your SSH agent / keys; HTTPS URLs use whatever credential helper your `git` is configured with. VAT itself reads no tokens. If `git clone <url>` works on your machine, `vat audit <url>` works.
+
+**Inspection.** Pass `--debug` to preserve the cloned tempdir for post-mortem inspection (its location is printed to stderr at exit). You are responsible for cleanup when using this flag.
+
+For the full URL form table and edge cases, see `packages/cli/docs/audit.md` (the "Auditing a remote git repo" section).
+
 ## Audit vs configured VAT projects
 
 Audit is the general-purpose command — you may point it at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill's nearest-ancestor `vibe-agent-toolkit.config.yaml` and respects the skill's per-skill packaging rules (`excludeReferencesFromBundle`, `linkFollowDepth`, `files`) to avoid false flags — but it never composes configs across project boundaries. Per-skill rules from one project do not bleed into skills in another project. For gated, configured-project-level validation, use the lifecycle commands (`vat skills validate`, `vat verify`) and run them from within the project directory.

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

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

@@ -0,0 +1,427 @@
+# Marketplace Distribution
+
+**Guide for building, validating, and publishing Claude plugin marketplaces.**
+
+## Overview
+
+A Claude plugin marketplace is a Git repository containing `.claude-plugin/marketplace.json` and plugin directories. Marketplaces are the distribution unit for Claude Code (via `/plugin marketplace add`) and Cowork (via GitHub App sync). VAT supports three modes of marketplace management.
+
+## Three Marketplace Modes
+
+| Mode | Description | VAT commands |
+|------|-------------|-------------|
+| **Built** | Source repo with skills → `vat build` → publish to `claude-marketplace` branch | `vat build`, `vat validate`, `vat claude marketplace publish` |
+| **Separate repo** | Source repo → `vat build` → publish to a different Git repo | Same as Built (remote configured in YAML) |
+| **Manual/native** | The repo IS the marketplace — no build step | `vat validate` (with config) or `vat claude marketplace validate` (without config) |
+
+## Distribution Surfaces
+
+Custom skills and plugins **do not sync across Claude surfaces**. Each surface is independent:
+
+| Surface | Source | Scope | Marketplace format? |
+|---------|--------|-------|---------------------|
+| **Claude Code** | Git repo with `marketplace.json` | Self-service install | Yes |
+| **Cowork (claude.ai)** | Admin UI → GitHub App sync from private repo | Org-wide, admin-controlled | Yes (same format) |
+| **Skills API** | `POST /v1/skills` multipart upload | Workspace-wide | No (direct API upload) |
+| **Claude Code (managed)** | `managed-settings.json` via MDM | Per-machine, IT-managed | Yes (marketplace ref in settings) |
+
+Public and private GitHub marketplaces use the **same format**. The only difference is authentication (private repos require `GITHUB_TOKEN` or `GH_TOKEN` for auto-updates).
+
+## Marketplace Structure
+
+```
+marketplace-repo/           # or claude-marketplace branch
+├── .claude-plugin/
+│   └── marketplace.json    # marketplace manifest (required)
+├── plugins/
+│   └── plugin-name/
+│       ├── .claude-plugin/
+│       │   └── plugin.json # plugin manifest (required)
+│       ├── skills/
+│       │   └── skill-name/
+│       │       ├── SKILL.md
+│       │       └── references/
+│       ├── commands/       # slash commands (*.md)
+│       ├── agents/         # agent definitions (*.md)
+│       └── hooks/          # hooks.json
+├── CHANGELOG.md            # marketplace changelog
+├── README.md               # marketplace "storefront" for GitHub
+└── LICENSE                  # required for distribution
+```
+
+## Versioning Strategy
+
+**Marketplace version is the distribution version.** One version for the whole marketplace.
+
+| Artifact | Versioned? | Required? | Source |
+|----------|-----------|-----------|--------|
+| Marketplace | Yes | Yes (error if missing) | `package.json` or config |
+| Plugin | Yes | Yes (error if missing) | Defaults to marketplace version |
+| Skill | No | N/A | Tracked by marketplace version |
+
+Skills are not independently versioned by VAT. The SKILL.md frontmatter spec has no version field. Skill changes are tracked at the marketplace level.
+
+Plugin version defaults to the marketplace version when not explicitly set. The top-level version defaults to `package.json` when available.
+
+## Branch Convention
+
+**Default publish branch: `claude-marketplace`** — analogous to GitHub Pages' `gh-pages`.
+
+- Source code and SDLC on `main` (tests, lint, CI, PRs)
+- Built marketplace artifacts on `claude-marketplace` (clean, generated)
+- Extensible: `claude-marketplace-beta`, `claude-marketplace-next` for staging channels
+- Configurable via `publish.branch` in config or `--branch` flag
+
+**Default-branch-only surfaces:** Both Cowork (claude.ai) and Claude Enterprise GitHub sync read from the repository's **default branch only** — they cannot target a specific branch. This means the branch-based publish pattern (`claude-marketplace` / `claude-marketplace-next`) does not work for these surfaces.
+
+**Workaround: dedicated marketplace repo.** Create a separate repository where the default branch (`main`) IS the marketplace. Configure `publish.remote` to point to this repo:
+
+```yaml
+publish:
+  remote: https://github.com/org/my-marketplace-repo.git
+  branch: main
+```
+
+This keeps your source code and SDLC on the original repo while the marketplace repo contains only the published artifacts.
+
+**Enterprise lockdown:** `managed-settings.json` supports `ref` on marketplace sources:
+
+```json
+{
+  "strictKnownMarketplaces": [
+    { "source": "github", "repo": "acme/plugins", "ref": "claude-marketplace" }
+  ]
+}
+```
+
+## Configuration
+
+In `vibe-agent-toolkit.config.yaml`:
+
+```yaml
+version: 1
+
+claude:
+  marketplaces:
+    my-marketplace:
+      owner:
+        name: Your Name or Org
+      publish:
+        branch: claude-marketplace          # default
+        remote: origin                      # git remote name, or full URL for cross-repo publish
+        changelog: docs/marketplace-changelog.md
+        readme: docs/marketplace-readme.md
+        license: mit                        # SPDX identifier or file path
+        sourceRepo: false                   # optional linkback in commit metadata
+      plugins:
+        - name: my-plugin
+          description: What this plugin does
+          skills: "*"                       # or list: ["skill-a", "skill-b"]
+```
+
+### License field
+
+The `license` field accepts:
+- **SPDX identifier string** (e.g., `mit`, `apache-2.0`, `gpl-3.0`) — generates standard license text with owner name and current year
+- **File path** (e.g., `./LICENSE` or `docs/LICENSE-ENTERPRISE`) — copies the file as-is
+
+Strings are validated against known SPDX identifiers. Paths are distinguished by containing `/` or `.` characters.
+
+## Changelog
+
+Each marketplace maintains its own `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/) format. The marketplace release cadence may differ from source package releases.
+
+- Author maintains the changelog source file in the repo (path configured in YAML)
+- On publish, it's copied to `CHANGELOG.md` in the published tree
+- The `[Unreleased]` section is required for publish — the command refuses if empty
+- On publish, `[Unreleased]` is stamped with version + date
+- The changelog delta becomes the Git commit message body
+
+Categories: `Added`, `Changed`, `Removed`, `Fixed`, `Security`.
+
+## Publish Flow
+
+```bash
+# 1. Build marketplace artifacts
+vat build
+
+# 2. Validate everything
+vat validate
+
+# 3. Publish to claude-marketplace branch
+vat claude marketplace publish
+
+# Or dry-run first
+vat claude marketplace publish --dry-run
+```
+
+**What publish does:**
+
+1. Verifies `vat build` output exists
+2. Checks marketplace changelog has `[Unreleased]` content
+3. Composes the publish tree (marketplace artifacts + CHANGELOG.md + README.md + LICENSE)
+4. Creates a single squashed commit: `publish v{version}` with changelog delta as body
+5. Pushes to the configured branch/remote
+
+**Flags:**
+- `--dry-run` — compose and show diff, don't push
+- `--branch <name>` — override configured branch
+- `--force` — force-push (first publish or recovery only)
+
+**Commit history:** Each publish adds one commit. The `claude-marketplace` branch accumulates a clean release timeline — `git log` shows the version history of the marketplace.
+
+## CI/CD: Cross-Repo Publishing
+
+When publishing to a **separate repository** (via `publish.remote`), the default `GITHUB_TOKEN` in GitHub Actions is scoped to the source repo and cannot push to the target. You need a Personal Access Token (PAT) or fine-grained token with write access to the marketplace repo.
+
+**Setup:**
+
+1. Create a PAT with `contents: write` permission on the marketplace repo
+2. Store it as a repository secret (e.g., `MARKETPLACE_GITHUB_PUSH_TOKEN`)
+3. Expose it as `GH_TOKEN` in your workflow — `vat claude marketplace publish` uses `GH_TOKEN` (or `GITHUB_TOKEN`) to authenticate pushes
+
+```yaml
+# .github/workflows/marketplace-publish.yml
+- name: Publish marketplace
+  env:
+    GH_TOKEN: ${{ secrets.MARKETPLACE_GITHUB_PUSH_TOKEN }}
+  run: |
+    vat build
+    vat claude marketplace publish --branch main
+```
+
+**Why a separate token?** GitHub Actions' built-in `GITHUB_TOKEN` has repo-scoped permissions and cannot push to other repositories. This is a standard pattern for any cross-repo CI operation.
+
+## Validation
+
+### With config (`vat validate`)
+
+When marketplace config exists, `vat validate` orchestrates in dependency order:
+
+1. `resources validate` — links, frontmatter, schemas
+2. `skills validate` — SKILL.md structure, frontmatter
+3. `marketplace validate` — marketplace.json, plugin.json, structure
+
+Each layer fails fast — bad links block skill validation, bad skills block marketplace validation.
+
+### Without config (`vat claude marketplace validate`)
+
+Standalone validation for manual/native marketplaces. Uses the same discovery logic as `vat audit` but with **strict expectations** — this must be a valid marketplace:
+
+| Check | `vat audit` (liberal) | `marketplace validate` (strict) |
+|-------|----------------------|--------------------------------|
+| Missing version | Warning | Error |
+| Missing LICENSE | Ignored | Error |
+| Bad plugin.json | Warning | Error |
+| Missing README | Ignored | Warning |
+| Missing CHANGELOG | Ignored | Warning |
+| Bad SKILL.md | Warning | Error |
+
+```bash
+# Validate a marketplace directory or repo
+vat claude marketplace validate .
+vat claude marketplace validate path/to/marketplace
+```
+
+## Examples
+
+### Built mode: monorepo publishes to same repo
+
+```yaml
+# vibe-agent-toolkit.config.yaml
+claude:
+  marketplaces:
+    vat-skills:
+      owner:
+        name: vibe-agent-toolkit contributors
+      publish:
+        changelog: docs/marketplace-changelog.md
+        readme: docs/marketplace-readme.md
+        license: mit
+      plugins:
+        - name: vibe-agent-toolkit
+          description: Development agents and skills
+          skills: "*"
+```
+
+```bash
+vat build && vat validate && vat claude marketplace publish
+```
+
+Consumers install via:
+```
+/plugin marketplace add owner/repo#claude-marketplace
+```
+
+### Separate repo: private source, public marketplace
+
+```yaml
+# vibe-agent-toolkit.config.yaml in private source repo
+claude:
+  marketplaces:
+    acme-skills:
+      owner:
+        name: Acme Corp
+      publish:
+        remote: git@github.com:acme/acme-skills-marketplace.git
+        changelog: docs/marketplace-changelog.md
+        readme: docs/marketplace-readme.md
+        license: apache-2.0
+      plugins:
+        - name: acme-tools
+          description: Acme engineering tools
+          skills: "*"
+```
+
+### Manual/native: repo IS the marketplace
+
+No `vat build`, no publish. Author maintains `marketplace.json` and plugin directories directly. Validate with:
+
+```bash
+# With vibe-agent-toolkit.config.yaml
+vat validate
+
+# Without config
+vat claude marketplace validate .
+```
+
+## Testing Your Marketplace
+
+After publishing, test the marketplace locally before sharing with users. This flow validates the full consumer experience — clone, install, and skill loading.
+
+### Test flow
+
+```bash
+# 1. Add the marketplace (uses the published branch)
+claude plugin marketplace add owner/repo#claude-marketplace
+
+# 2. Install the plugin from the marketplace
+claude plugin install my-plugin@my-marketplace
+
+# 3. Validate the installed plugin
+claude plugin validate ~/.claude/plugins/cache/my-marketplace/my-plugin/<version>
+
+# 4. List plugins and verify status
+claude plugin list
+
+# 5. Start a new Claude Code session — skills should appear in /skill-name
+```
+
+### What to verify
+
+- **Marketplace add** succeeds and `known_marketplaces.json` shows the correct source
+- **Plugin install** resolves the correct version from plugin.json
+- **All skills** are present in the cache directory
+- **`claude plugin validate`** passes on the installed plugin
+- **`claude plugin list`** shows the plugin as enabled
+- **Skills load** in a new session (check the system reminder for skill names)
+
+### Updating after changes
+
+After publishing a new version:
+
+```bash
+# Update the marketplace cache
+claude plugin marketplace update my-marketplace
+
+# Update the installed plugin
+claude plugin update my-plugin@my-marketplace
+```
+
+### Known issues
+
+**Name collision on marketplace add (Claude Code v2.1.81):** If a marketplace with the same `name` field already exists (e.g., previously registered via npm), `claude plugin marketplace add` reports success but silently reuses the old source in `known_marketplaces.json`. The workaround is to remove the old marketplace first, then add:
+
+```bash
+claude plugin marketplace remove my-marketplace
+claude plugin marketplace add owner/repo#branch
+```
+
+Verify by checking `~/.claude/plugins/known_marketplaces.json` to confirm the source switched to `github`.
+
+**`claude plugin validate` rejects `$schema` key (Claude Code v2.1.81):** The marketplace validator treats `$schema` as an unrecognized key, even though Anthropic's own official marketplace uses it. This does not affect runtime behavior — the marketplace installs and works correctly. This is a Claude Code validation bug, not a marketplace authoring issue.
+
+
+## Full-plugin authoring
+
+`vat claude plugin build` ships any Claude Code plugin asset — not just skills. Drop the plugin under `plugins/<name>/` in the same native layout Claude Code expects, declare it in `vibe-agent-toolkit.config.yaml`, and `vat claude plugin build` assembles the output from that plugin's own directory. Pool skills (from the top-level `skills:` discovery) are still imported into the plugin via the `skills:` selector — the plugin directory and the pool skills are both sources, composed into one bundle.
+
+### Layout
+
+```
+plugins/<name>/
+  .claude-plugin/
+    plugin.json       # author-supplied metadata; VAT merges on top
+  commands/           # slash commands (*.md)
+  hooks/
+    hooks.json        # hook registry (JSON; parse-only validated)
+  agents/             # subagent definitions (*.md)
+  .mcp.json           # MCP server config (JSON; parse-only validated)
+  scripts/            # arbitrary scripts (tree-copied verbatim)
+  skills/             # plugin-local SKILL.md files — tree-copied verbatim
+```
+
+Everything under `plugins/<name>/` is tree-copied to `dist/.claude/plugins/marketplaces/<mp>/plugins/<name>/`, except:
+
+- `.claude-plugin/` — owned by the `plugin.json` merge-write (see "plugin.json merge")
+
+Tree-copy respects `.gitignore` (safe: `node_modules/`, build detritus never ship). `plugins/<name>/skills/` is just a regular tree-copied directory — drop raw `SKILL.md` files there and they ship as-is.
+
+### Minimum content — empty-plugin guard
+
+Every declared plugin must supply at least one of:
+
+- a `plugins/<name>/` directory on disk (or an alternate `source:` override pointing at one), **or**
+- a non-empty `files: [{ source, dest }, ...]` mapping, **or**
+- a non-empty `skills:` selector that matches at least one pool skill.
+
+A plugin with none of these is rejected with the empty-plugin guard.
+
+### `source` override
+
+```yaml
+claude:
+  marketplaces:
+    mp1:
+      owner: { name: Example }
+      plugins:
+        - name: my-plugin
+          skills: []
+          source: custom/path/to/my-plugin   # default: plugins/my-plugin
+```
+
+### `files[]` — compiled artifacts outside the plugin dir
+
+Use `files: [{ source, dest }]` to inject build artifacts (compiled hooks, generated configs) into the plugin output:
+
+```yaml
+plugins:
+  - name: my-plugin
+    skills: []
+    files:
+      - source: dist/hooks/compiled-hook.mjs   # relative to project root
+        dest: hooks/compiled-hook.mjs         # relative to plugin output dir
+```
+
+`dest` cannot escape the plugin output dir and cannot target `.claude-plugin/plugin.json` (owned by merge-write). Overwrites are allowed and logged at info level.
+
+### `plugin.json` merge rules
+
+VAT writes `.claude-plugin/plugin.json` last, merging the author's `.claude-plugin/plugin.json` (if present) with VAT-owned identity fields:
+
+- **VAT wins** on `name`, `version`, `author` (shallow replace — mismatches produce warnings, never errors).
+- **Author wins** on all other keys (`keywords`, `repository`, `homepage`, `license`, …).
+- **Description chain:** `config.description ?? author.description ?? "${name} plugin"`.
+- `version` falls back to the author's value when VAT has no version (no `package.json`).
+
+### Ordering contract
+
+`vat claude plugin build` runs per plugin in this order:
+
+1. Discovery + validators (case-match, `hooks.json`/`.mcp.json` parse, empty-plugin guard)
+2. Tree-copy `plugins/<name>/` verbatim (skips `.claude-plugin/`, respects `.gitignore`)
+3. Pool-skill import via the plugin's `skills:` selector (from `dist/skills/`)
+4. `files[]` mapping (may overwrite tree-copied files; logged at info)
+5. `.claude-plugin/plugin.json` merge-write (always last, always wins)
+
+**Run order:** `vat skills build && vat claude plugin build`. The plugin build reads pre-built pool skills from `dist/skills/` and raw plugin-local skills directly from `plugins/<name>/skills/`.

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-skill-review/SKILL.md

@@ -42,6 +42,8 @@ Tooling enforcement: items marked with a bracketed code (e.g., `[SKILL_DESCRIPTI
 - **[VAT] Prefer a verb phrase or `Use when ...` opener** — not a meta-description of the skill-as-object. `[SKILL_DESCRIPTION_FILLER_OPENER]` warns on `This skill...`, `A skill that...`, `Used to...` — these waste the first tokens describing the wrapper rather than the behavior. Anthropic doesn't ban these explicitly, but their own examples never use them; VAT is stricter here.
 - **[A] Be specific**: include both what the skill does and when to use it. `[DESCRIPTION_TOO_VAGUE]` fires below 50 chars. Anthropic's bad examples — `Helps with documents`, `Processes data`, `Does stuff with files` — are rejected for vagueness, not length.
 - **[VAT] Description ≤250 characters**: Claude Code truncates descriptions at 250 characters in the `/skills` listing (since v2.1.86). `[SKILL_DESCRIPTION_OVER_CLAUDE_CODE_LIMIT]` warns at 250; `[SKILL_DESCRIPTION_TOO_LONG]` errors at the 1024-char schema hard max. Aim for ≤200 chars for safety; ≤130 chars if shipping a large skill collection (60+ skills) so the total budget fits.
+- **[VAT] Description names concrete trigger phrases** — does the description list specific user-said trigger phrases (in quotes) or at least one concrete scenario? `SKILL_DESCRIPTION_NO_CONCRETE_SCENARIO` is intentionally a checklist line: "concrete enough" is judgment, not a regex. Refer to plugin-dev's "Triggering" section for examples.
+- **[VAT] Description disambiguates from sibling skills** — if a reviewer only saw this skill's name+description and the names+descriptions of siblings in the same plugin, could an agent reliably pick the right one? Cross-skill semantic comparison is judgment-only — no automated detector for it.
 
 ### Body structure
 
@@ -59,6 +61,7 @@ Tooling enforcement: items marked with a bracketed code (e.g., `[SKILL_DESCRIPTI
 - **[A] All links resolve**: every `[text](path)` link points to a file that exists. `[LINK_MISSING_TARGET]` and siblings enforce.
 - **[A] Build clean**: `vat skills build` succeeds and `vat verify` passes with zero errors.
 - **[A] Test the trigger**: ask "if an agent sees only this name and description, will it know when to load this skill?" If understanding the description requires reading the SKILL.md, the description is wrong.
+- **[VAT] Body avoids duplicating reference content** — when the skill bundles `references/`, does SKILL.md teach the agent *when to load each reference*, without repeating the reference's own content? Information should live in either SKILL.md or `references/`, not both. Semantic duplication is judgment, not regex.
 
 ### Frontmatter hygiene