@vibe-agent-toolkit/vat-development-agents 0.1.37 → 0.1.39-rc.1

package/dist/skills/vat-knowledge-resources/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: vat-knowledge-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.
+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.
 ---
 
 # VAT Resources: Collections & Frontmatter Validation
@@ -91,6 +93,24 @@ Absolute URLs in URI-reference fields feed into the existing external URL health
 
 Opt-out: `checkFrontmatterLinks: false` per collection, or `--no-check-frontmatter-links` on the CLI.
 
+## Per-code severity and allow (`resources.validation`)
+
+Every resources finding is a registry code (e.g. `LINK_BROKEN_FILE`, `FRONTMATTER_SCHEMA_ERROR`, `EXTERNAL_URL_DEAD`) with a default severity. Tune them per-code under `resources.validation`:
+
+```yaml
+resources:
+  validation:
+    severity:
+      EXTERNAL_URL_DEAD: ignore     # silence dead external links entirely
+      LINK_UNKNOWN: error           # promote unclassified links to build-failing
+    allow:
+      LINK_TO_GITIGNORED:           # keyed by code; value is a list of allow entries
+        - paths: ["docs/internal/**"]
+          reason: "internal-only notes, intentionally gitignored"
+```
+
+`severity` accepts `error | warning | info | ignore`. External-URL findings default to `warning` and never fail the build on their own — promote them to `error` here if you want network checks to gate CI. `allow` is keyed by code; each entry's `paths` (glob list, default `**/*`) and `reason` suppress that code for matching files rather than disabling it globally. Add `expires` (a date string) to flag the allowance for re-review.
+
 ## Annotating Frontmatter Schemas with Zod 4
 
 If your project generates JSON Schemas from Zod (via `z.toJSONSchema()`), annotate frontmatter fields that hold links with the appropriate `format` so VAT's link validator picks them up:
@@ -111,6 +131,46 @@ const PrdFrontmatter = z.object({
 
 **Tip:** `format` is advisory in JSON Schema; pair it with a `pattern` regex when you also need parse-time rejection of invalid inputs.
 
+## URI-references in frontmatter
+
+VAT validates frontmatter fields whose schema position has `format: uri-reference`
+(or `uri`, `iri-reference`, `iri`) against the same rules as body links:
+
+- Leading-`/` is RFC 3986 §4.2 absolute-path reference — resolved against
+  the project root. Same semantics as body links.
+- Anchor fragments and external URLs are accepted; broken local refs error.
+- Inline comments on URI-ref fields are **preserved** when any tool rewrites
+  the file via `openFrontmatter` (VAT packager, hand-rolled adopter scripts).
+
+Example:
+
+```yaml
+---
+parent_spec: /docs/specs/foo.md  # the spec this one supersedes
+adrs-cited:
+  - /docs/adrs/0007-storage.md  # primary reference
+  - /docs/adrs/0011-snapshot.md  # impacted by storage choice
+---
+```
+
+Schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "parent_spec": { "type": "string", "format": "uri-reference" },
+    "adrs-cited": {
+      "type": "array",
+      "items": { "type": "string", "format": "uri-reference" }
+    }
+  }
+}
+```
+
+For tools that **modify** frontmatter (not just validate it), see
+[[markdown-rewriting]].
+
 ## Validation Output
 
 ```yaml

package/dist/skills/vat-rag/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: vat-rag
-description: Use when running `vat rag index` / `vat rag query` or configuring RAG for agent context — covers the CLI commands, native embedding providers and vector store support, chunking, custom metadata, and extension points for adding new backends.
+description: Use when running `vat rag index` / `vat rag query` or configuring
+  RAG for agent context — covers the CLI commands, native embedding providers
+  and vector store support, chunking, custom metadata, and extension points for
+  adding new backends.
 ---
 
 # VAT RAG: Indexing and Querying Markdown with Native Providers

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

@@ -1,6 +1,9 @@
 ---
 name: vat-skill-authoring
-description: Use when authoring or revising a SKILL.md file — frontmatter, body structure, references, packagingOptions (linkFollowDepth, excludeReferencesFromBundle), and validation overrides. Paired with vat-skill-review for pre-publication checks.
+description: Use when authoring or revising a SKILL.md file — frontmatter, body
+  structure, references, packagingOptions (linkFollowDepth,
+  excludeReferencesFromBundle), and validation overrides. Paired with
+  vat-skill-review for pre-publication checks.
 ---
 
 # VAT Skill Authoring: SKILL.md Structure and Packaging
@@ -34,6 +37,29 @@ Best practices for `description`:
 - Write in third person. First-person ("I can...") and conversational second-person ("You can use...") fire `SKILL_DESCRIPTION_WRONG_PERSON`.
 - Keep under 250 characters so the Claude Code `/skills` listing doesn't truncate the tail (target ≤200 for safety, ≤130 if shipping a large skill collection). The hard schema limit is 1024.
 
+## Cross-document references in SKILL.md frontmatter
+
+When SKILL.md frontmatter references other documents (parent specs, ADRs,
+related skills), use **leading-`/`** URI-references:
+
+```yaml
+---
+parent_spec: /docs/specs/foo.md
+related-skills:
+  - /packages/foo/resources/skills/bar/SKILL.md
+---
+```
+
+These resolve against the project root per RFC 3986 §4.2 (same rule VAT
+applies to body links). Source-relative paths (`../../docs/foo.md`) also
+work but are fragile when skills move.
+
+If a tool needs to programmatically rewrite these references — e.g., when
+moving a file — load [[markdown-rewriting]] for the canonical pattern.
+Never use `gray-matter`, `front-matter`, or `js-yaml` directly for SKILL.md
+edits; they silently drop frontmatter comments. ESLint enforces this for
+VAT-internal code.
+
 ## Body Structure
 
 - Lead with a short orientation paragraph: what the skill owns and when to reach for it.

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

@@ -1,6 +1,9 @@
 ---
 name: vat-skill-distribution
-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.
+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.
 ---
 
 # VAT Distribution: Build, Publish & Install
@@ -304,9 +307,9 @@ Start a new Claude Code session to confirm skills load. See the [Marketplace Dis
 
 VAT supports two versioning models for a marketplace:
 
-**Single-version (default for skills-only marketplaces).** No `version` is declared on individual plugins. All plugins inherit the root `package.json:version`. This is the model used by `vibe-agent-toolkit` and `avonrisk-sdlc` — the marketplace is treated as one release artifact.
+**Single-version (default for skills-only marketplaces).** No `version` is declared on individual plugins. All plugins inherit the root `package.json:version`. This is the model used by `vibe-agent-toolkit` — the marketplace is treated as one release artifact.
 
-**Per-plugin versioning** (multi-plugin marketplaces with independent release cadences). Each plugin declares its own `version`. Recommended when topical plugins under one marketplace evolve on independent timelines (e.g., AvonRiskBuilders' `ai-digest`, `bank-reconciliation`).
+**Per-plugin versioning** (multi-plugin marketplaces with independent release cadences). Each plugin declares its own `version`. Recommended when topical plugins under one marketplace evolve on independent timelines.
 
 #### Where to declare a per-plugin version
 
@@ -334,7 +337,6 @@ If both declare a version, marketplace config wins and VAT logs a reconciliation
 For each plugin with a resolved version:
 
 - The published `.claude-plugin/marketplace.json` includes the per-plugin `version` field on each plugin entry.
-- After the publish-branch push succeeds, VAT pushes a `<plugin>-v<version>` tag to the **source repo** (not the marketplace branch) — e.g., `ai-digest-v0.2.0`. "Source repo" means the working directory where you invoke `vat claude marketplace publish` (i.e., `process.cwd()`); if you invoke from a subdirectory of a worktree, tags land in the containing repo, not the subdirectory. Tag-push failures log a warning but do not roll back the publish.
 - If `<plugin.source>/CHANGELOG.md` exists in source (or the marketplace plugin entry's `changelog` field points to a file), it is bundled into the published marketplace at `plugins/<name>/CHANGELOG.md`, alongside the marketplace-level CHANGELOG.
 
 The marketplace-level CHANGELOG (under `publish.changelog` in the config) continues to work unchanged.
@@ -355,7 +357,7 @@ plugins:
 
 #### Backwards compatibility
 
-Marketplaces with no per-plugin version anywhere are unaffected. The root `package.json` version flows through to every plugin, the published `marketplace.json` either omits per-plugin `version` or includes the same value for all plugins, and tag pushes use the inherited version (e.g., both plugins tagged `<plugin>-v1.0.0`).
+Marketplaces with no per-plugin version anywhere are unaffected. The root `package.json` version flows through to every plugin, and the published `marketplace.json` either omits per-plugin `version` or includes the same value for all plugins.
 
 ## Step 5: User Install
 
@@ -468,4 +470,4 @@ everything (minus `skills/` and `.claude-plugin/`), merges author `plugin.json`
 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".
+See [docs/guides/marketplace-distribution.md]() section "Full-plugin authoring".

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

@@ -1,6 +1,9 @@
 ---
 name: vat-skill-review
-description: Use when reviewing a skill before publication or running `vat skill review`. Pre-publication quality checklist grouped into general (all skills) and CLI-backed items, tied to VAT validation codes and Anthropic's skill-authoring best practices.
+description: Use when reviewing a skill before publication or running `vat skill
+  review`. Pre-publication quality checklist grouped into general (all skills)
+  and CLI-backed items, tied to VAT validation codes and Anthropic's
+  skill-authoring best practices.
 ---
 
 # Skill Quality Checklist (vat skill review)

package/dist/skills/vibe-agent-toolkit/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: vibe-agent-toolkit
-description: Use when starting VAT work or deciding which VAT sub-skill applies. Router that points at sub-skills for adoption, skill/agent authoring, audit, distribution, RAG, knowledge resources, skill review, and enterprise org admin.
+description: Use when starting VAT work or deciding which VAT sub-skill applies.
+  Router that points at sub-skills for adoption, skill/agent authoring, audit,
+  distribution, RAG, knowledge resources, skill review, and enterprise org
+  admin.
 ---
 
 # Vibe Agent Toolkit
@@ -38,6 +41,7 @@ Poor fits:
 | `vat rag index` / `vat rag query`, embedding providers, vector stores, chunking | `vibe-agent-toolkit:vat-rag` |
 | Pre-publication quality review, `vat skill review`, validation-code triage | `vibe-agent-toolkit:vat-skill-review` |
 | Anthropic Admin API: org users, cost/usage, workspace skills, `ANTHROPIC_ADMIN_API_KEY` | `vibe-agent-toolkit:vat-enterprise-org` |
+| Programmatic markdown/frontmatter edits — moving files, updating references, schema-evolution migrations; comment-preserving FrontmatterEditor + rewriteBodyLinks | `vibe-agent-toolkit:markdown-rewriting` |
 
 ## CLI Surface at a Glance
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/vat-development-agents",
-  "version": "0.1.37",
+  "version": "0.1.39-rc.1",
   "description": "VAT development agents - dogfooding the vibe-agent-toolkit",
   "type": "module",
   "keywords": [
@@ -67,13 +67,13 @@
     "postinstall": "vat claude plugin install --npm-postinstall || exit 0"
   },
   "dependencies": {
-    "@vibe-agent-toolkit/agent-schema": "0.1.37",
-    "@vibe-agent-toolkit/cli": "0.1.37",
+    "@vibe-agent-toolkit/agent-schema": "0.1.39-rc.1",
+    "@vibe-agent-toolkit/cli": "0.1.39-rc.1",
     "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
-    "@vibe-agent-toolkit/resource-compiler": "0.1.37",
+    "@vibe-agent-toolkit/resource-compiler": "0.1.39-rc.1",
     "ts-patch": "^3.2.1",
     "typescript": "^5.7.3"
   },

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

@@ -1,427 +0,0 @@
-# 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/`.