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

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

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

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

@@ -7,37 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.35] - 2026-05-09
+
+### Added
+- **Multi-plugin marketplaces with independent versioning.** Each plugin in a marketplace can now declare its own version (in `plugins/<name>/.claude-plugin/plugin.json:version` or via the marketplace config's per-plugin `version` field), get its own per-plugin source-repo tag (`<plugin>-v<version>`) on `vat claude marketplace publish`, and ship its own CHANGELOG (default `<plugin.source>/CHANGELOG.md`, override via the per-plugin `changelog` field) bundled into the published marketplace at `plugins/<name>/CHANGELOG.md`. The published `marketplace.json` includes `version` per plugin entry when defined. Marketplaces with no per-plugin version inherit the root `package.json:version` (backwards compatible — exercised by integration test scenario 3 against the existing avonrisk-sdlc shape). Unblocks the AvonRiskBuilders marketplace where each topical plugin must version and release independently.
+
+### Changed
+- **Version precedence in `mergePluginJson` flipped.** When both a marketplace-config version and a `plugin.json:version` are present, config wins (with a reconciliation warning); when only `plugin.json:version` is present, it now wins over the root `package.json` version. Previously the root version always won. Single-version marketplaces (no per-plugin version anywhere) are unaffected.
+
+## [0.1.34] - 2026-05-06
+
 ### Added
-- **Skill-claude-plugin recognition in `vat audit`.** Introduces the **skill-claude-plugin** artifact shape — a skill that self-publishes as a Claude plugin by co-locating `.claude-plugin/plugin.json` alongside its root `SKILL.md`. Audit now emits independent `ValidationResult` entries for each surface (one `agent-skill`, one `claude-plugin`) instead of reporting only the plugin and silently ignoring the skill. The skill remains platform-agnostic; the graduation to skill-claude-plugin adds Claude-specific packaging only. See [`docs/architecture/skill-packaging.md`](docs/architecture/skill-packaging.md) for the full packaging-shape terminology (standalone skill / skill-claude-plugin / claude-plugin / claude-marketplace).
-- **`SKILL_CLAUDE_PLUGIN_NAME_MISMATCH`** validation code (default `warning`). Fires on the plugin result when a skill-claude-plugin's `plugin.json.name` disagrees with the co-located `SKILL.md` frontmatter `name`. The skill is authoritative; the plugin manifest is a distribution wrapper and should match unless the plugin is intentionally namespaced (in which case use `validation.severity` or `validation.allow`).
-- **Self-contained Claude Code plugin support in `vat claude plugin build`.**
-  Adopters can now bundle commands, hooks, agents, MCP servers, scripts, raw
-  plugin-local `SKILL.md` files, and author-supplied `plugin.json` metadata from a
-  per-plugin `plugins/<name>/` directory. The entire directory is tree-copied
-  verbatim (respecting `.gitignore`). Pre-existing pool-to-plugin skill selectors
-  (`marketplace.plugins[].skills`) are preserved — a plugin can still declare
-  `skills: "*"` or `skills: [names]` to import pool skills (built by
-  `vat skills build`) into its bundle. The skills stream is unchanged: `vat skills
-  build` continues to produce `dist/skills/<name>/` only. New schema fields on
-  marketplace plugin entries: `source` (path override, default `plugins/<name>`)
-  and `files[]` (compiled-artifact mappings). The 5-phase plugin build pipeline
-  is deterministically ordered (discovery → tree-copy → pool-skill import →
-  `files[]` → merged `plugin.json`). YAML summary adds `commandsCopied`,
-  `hooksCopied`, `agentsCopied`, `mcpCopied`, `treeFilesCopied`,
-  `explicitFilesCopied` per plugin. Case-sensitivity mismatches between declared
-  plugin names and on-disk dirs now fail the build to catch Linux-CI drift.
+- **`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` directory-entry detection uses a new `enumerateSurfaces()` helper that returns every manifest present at the directory root, replacing single-result detection in the multi-surface case. Single-surface directories retain their legacy single-validator dispatch, including the marketplace-with-co-located-plugin collapse.
-- `packages/cli/src/commands/audit/hierarchical-output.ts` comments standardized on the new terminology: the pattern previously documented as "standalone plugin skill (no skills subdir)" is now called **skill-claude-plugin**.
-- Upgraded `vibe-validate` and `@vibe-validate/cli` dev dependencies from `^0.19.1` to `^0.19.4`.
+- **`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 reference doc `docs/architecture/skill-packaging.md` enumerates the four packaging shapes with layouts and applicable validation.
-- `docs/README.md` gains a "Validation & Quality Framework" section indexing the three stance docs (`skill-quality-and-compatibility.md`, `validation-codes.md`, `skill-smell-philosophy.md`).
-- New `docs/CLAUDE.md` and `docs/architecture/CLAUDE.md` agent navigators pull in each directory's README via `@README.md` and add agent-only guidance for audit/validation work.
-- Root `/CLAUDE.md` "Questions?" section now links to directories rather than README files — child CLAUDE.md files auto-trigger and pull in their README once, avoiding the previous double-read pattern.
-- `packages/cli/CLAUDE.md` gains a "Validation Framework References" section.
+- 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
 
@@ -88,7 +89,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,6 +1,7 @@
 {
+  "license": "MIT",
   "name": "vibe-agent-toolkit",
-  "version": "0.1.34-rc.2",
+  "version": "0.1.35",
   "author": {
     "name": "vibe-agent-toolkit contributors"
   },

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

@@ -300,6 +300,63 @@ Start a new Claude Code session to confirm skills load. See the [Marketplace Dis
 
 **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.
 
+### Per-plugin versioning (multi-plugin marketplaces)
+
+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.
+
+**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`).
+
+#### Where to declare a per-plugin version
+
+Two options, in precedence order:
+
+1. **Marketplace config** (`vibe-agent-toolkit.config.yaml`) — most explicit:
+   ```yaml
+   claude:
+     marketplaces:
+       my-marketplace:
+         plugins:
+           - name: ai-digest
+             version: 0.2.0
+             skills: '*'
+   ```
+2. **Plugin source** (`plugins/<name>/.claude-plugin/plugin.json:version`) — most ergonomic for plugin authors:
+   ```json
+   { "name": "ai-digest", "version": "0.2.0", "description": "..." }
+   ```
+
+If both declare a version, marketplace config wins and VAT logs a reconciliation warning. If neither is declared, VAT falls back to the root `package.json:version` (single-version model).
+
+#### What `vat claude marketplace publish` does for multi-plugin marketplaces
+
+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.
+
+#### Default CHANGELOG location
+
+The default per-plugin CHANGELOG path is `<plugin.source>/CHANGELOG.md`, anchored to the entry's `source` field (default `plugins/<name>`). It is NOT assumed to be `plugins/<name>/CHANGELOG.md` — if you override `source`, the default CHANGELOG path follows.
+
+To use a non-default path, set the `changelog` field on the marketplace plugin entry (relative to the plugin source dir):
+
+```yaml
+plugins:
+  - name: ai-digest
+    source: plugins/ai-digest
+    changelog: docs/RELEASES.md
+    skills: '*'
+```
+
+#### 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`).
+
 ## Step 5: User Install
 
 ### Recommended: npm global install (postinstall runs automatically)

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
 

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

@@ -4,7 +4,7 @@
 
 export const meta = {};
 
-export const text = "# VAT Plugin Skills — Development Guide\n\nThis directory ships the \`vibe-agent-toolkit\` Claude Code plugin. When editing\nor creating skills here, follow the boundaries and rules below. The goal is\nthat each sub-skill has a single, sharp trigger and that they collectively\ncover VAT\'s user-facing surface without overlap.\n\n## Skill inventory and boundaries\n\n| Skill | Owns | Does NOT own | CLI |\n|---|---|---|---|\n| \`vibe-agent-toolkit\` (router, \`SKILL.md\`) | What VAT is, when to use it, routing to sub-skills | Any deep content — keep ≤150 lines, prose-only references to sub-skills | — |\n| \`vat-adoption-and-configuration\` | Project setup, \`vibe-agent-toolkit.config.yaml\` orientation, repo structure, vibe-validate integration, npm postinstall hook | Per-section config depth (each owning skill covers its own slice) | — |\n| \`vat-skill-authoring\` | \`SKILL.md\` files: frontmatter, body structure, references, packagingOptions (linkFollowDepth, excludeReferencesFromBundle), validation overrides | TypeScript agent functions, plugin packaging, RAG | — |\n| \`vat-agent-authoring\` | TypeScript portable agents: archetypes (Pure Function Tool, One-Shot LLM Analyzer, Conversational Assistant, External Event Integrator), \`agent.yaml\`, result envelopes, runtime adapters (Vercel/LangChain/OpenAI/Claude Agent SDK) | SKILL.md authoring, plugin/marketplace config | — |\n| \`vat-audit\` | \`vat audit\` on plugins/marketplaces/skills/settings; \`--compat\`, \`--exclude\`, \`--user\`, CI usage | What to fix (defer to other skills) | \`vat audit\` |\n| \`vat-knowledge-resources\` | Markdown collections, \`vibe-agent-toolkit.config.yaml\` \`resources\` section, frontmatter schemas, validation modes | RAG indexing (separate skill) | \`vat resources validate\` |\n| \`vat-skill-distribution\` | \`vat build\`, \`vat verify\`, plugin/marketplace config, npm publishing, postinstall hooks, \`vat.skills\` field | Authoring the SKILL.md itself | \`vat build\`, \`vat verify\` |\n| \`vat-rag\` | \`vat rag index\`, \`vat rag query\`, native embedding/vector store support, extension points, \"contributions welcome\" callout | Markdown collection authoring (knowledge-resources owns) | \`vat rag\` |\n| \`vat-skill-review\` | Pre-publication review rubric, validation-code reference, Anthropic best-practices integration, \`vat skill review\` command | The validators themselves (live in code) | \`vat skill review\` |\n| \`vat-enterprise-org\` | Anthropic Admin API: org users, cost/usage, workspace skills, \`ANTHROPIC_ADMIN_API_KEY\` | Per-user runtime auth | \`vat claude org\` |\n\n## Cross-cutting: \`vibe-agent-toolkit.config.yaml\`\n\nThis file is multi-skill. Each section is owned by one skill:\n\n| Config section | Owning skill |\n|---|---|\n| Top-level structure, version, multi-section orientation | \`vat-adoption-and-configuration\` |\n| \`skills:\` (include, defaults, per-skill config, packagingOptions) | \`vat-skill-authoring\` |\n| \`resources:\` (collections, schemas, validation modes) | \`vat-knowledge-resources\` |\n| \`claude:\` (marketplaces, plugins, publish, owner) | \`vat-skill-distribution\` |\n\nWhen a skill needs to mention a section it doesn\'t own, link to the owning skill rather than re-explaining the section.\n\n## Naming rules (programmatic + advisory)\n\n- **Forbidden words in \`name\`**: \`claude\`, \`anthropic\`. Claude Code rejects skills containing these words unless they are official certified skills. Enforced by validator code \`RESERVED_WORD_IN_NAME\` (warning severity).\n- **Prefer CLI-name alignment**: when a skill primarily covers a CLI command, use the same root word (\`vat-audit\` → \`vat audit\`, \`vat-skill-review\` → \`vat skill review\`). Discovery hook for users running \`--help\`.\n- **Kebab-case**, lowercase letters, digits, hyphens. Matches \`^[a-z][a-z0-9-]*$\`.\n- **No vague nouns**: \`vat-resources\` was renamed to \`vat-knowledge-resources\` because \"resources\" alone could mean anything. Each name should carry its subject.\n- **No platform names** unless certified: see forbidden words rule above. Say \"enterprise\" not \"claude\" / \"anthropic\".\n\n## Description quality\n\nA description must let Claude Code trigger correctly. Required elements:\n- **Action verb or \"Use when...\"** opener\n- **Subject** (what kind of work fires this skill)\n- **2-4 trigger keywords** (the words a user is likely to use)\n- **What it covers** (one short clause)\n- ≤250 chars total (Claude Code listing truncates at 250)\n\nExample (\`vat-audit\`):\n> Use when running \`vat audit\` to validate Claude plugins, marketplaces, or skills. Covers the audit command, \`--compat\` for surface compatibility, \`--exclude\` for noise filtering, and interpreting findings.\n\nTriggers on: \"audit my plugin\", \"validate plugin compatibility\", \"what does this audit warning mean\".\n\n## Router skill (\`SKILL.md\` / \`vibe-agent-toolkit\`) — special rules\n\nThe router exists for **discovery + routing**, not content. Strict rules:\n\n1. **≤150 lines total**\n2. **Prose references to sub-skills** — never markdown links: write \`vibe-agent-toolkit:vat-audit\`, not \`[vat-audit](./vat-audit.md)\`. Markdown links cause VAT\'s packager to transclude the sibling, bloating the bundle.\n3. **No code examples beyond a 5-line CLI overview** — depth lives in sub-skills\n4. **Description triggers entry questions** (\"what is VAT\", \"how do I get started\"), not specific tasks\n\nVerify after edits: \`vat skill review packages/vat-development-agents/resources/skills\` should report \`fileCount: 1\` (no transclusion).\n\n## Single-responsibility — when to split\n\nSplit a skill when its description must list two unrelated subjects to trigger correctly. Example: the original \`vat-authoring\` covered both SKILL.md files and TypeScript agent functions — two distinct mental models, hence the split into \`vat-skill-authoring\` and \`vat-agent-authoring\`.\n\n## Contributor vs user content\n\nThis plugin is for **users of VAT**. Contributor-facing material (debugging VAT internals, designing install architecture, working on the codebase) belongs in \`docs/contributing/\`, not in a SKILL.md here. The root CLAUDE.md routes contributors to those docs.\n\nIf a skill description says \"use when developing/contributing to VAT\", it doesn\'t belong in this directory.\n\n## This area moves fast — verify current standards\n\nSkill authoring, agent design, and Claude Code\'s own skill-loading semantics are evolving rapidly. Cached guidance under \`docs/external/\` (e.g. \`anthropic-skill-authoring-best-practices.md\`) ages quickly. Before making non-trivial changes:\n\n- Re-fetch the source URL named in the cached doc\'s preamble; diff against the cache; if material has changed, update the cache and propagate the delta into validators and \`vat-skill-review\`.\n- Web search for the latest Claude Code release notes when changing trigger semantics, frontmatter rules, or packaging behavior. Don\'t rely on training-data recall.\n- The \`vat-skill-review\` skill must carry this same instruction explicitly — it\'s the skill agents load when they\'re about to apply quality standards.\n\n## Shift left — every manual check is a future validator\n\nWhen a quality issue is caught manually (in code review, by the user noticing an error from Claude Code, or via a checklist walkthrough), treat it as a candidate for **promotion to a programmatic validator**. The bar is: if the issue has a clear pattern that can be detected from the file contents, it should not stay a manual check.\n\n**Canonical example**: the \`RESERVED_WORD_IN_NAME\` rule. The \`claude\`/\`anthropic\` naming restriction was discovered through an install-time rejection — the kind of failure a developer hits once, remembers forever, but new contributors keep re-hitting. Encoding it as a validator (warning severity, fires at \`vat audit\` / \`vat skills validate\` time) shifts the discovery left from \"Claude Code rejects my install\" to \"validator warns me before I commit.\"\n\nWhen you add a validator:\n1. Register the code in \`validation-rules.ts\` with severity, message template, fix hint, and a \`reference\` pointer to the rationale (often a section of \`vat-skill-review\` or external doc)\n2. Wire it into the appropriate validator pipeline (frontmatter, link, packaging) so it actually fires\n3. Add a checklist entry in \`vat-skill-review\` that references the same code (so the manual rubric and the automated check stay aligned)\n4. Default severity is **warning** unless the issue genuinely blocks distribution — even then, prefer warning + clear fix hint per the [skill-smell philosophy](../../../../docs/skill-smell-philosophy.md)\n\nWhen \`vat-skill-review\` lists a checklist item that is currently a \`[ ]\` manual judgment call, ask: *can this be detected programmatically?* If yes, file a follow-up to add the validator and convert the manual item to an automated reference.\n\n## Pre-commit checks\n\nBefore committing a skill change:\n\n\`\`\`bash\n# Review the specific skill you touched\nbun run vat skill review packages/vat-development-agents/resources/skills/<skill>.md\n\n# Audit the whole plugin\nbun run vat audit packages/vat-development-agents\n\n# Full validation\nbun run validate\n\`\`\`\n\nWatch for:\n- \`RESERVED_WORD_IN_NAME\` (warning) — naming policy violation\n- \`SKILL_DESCRIPTION_OVER_CLAUDE_CODE_LIMIT\` — trim to ≤250 chars\n- \`SKILL_DESCRIPTION_FILLER_OPENER\` — start with action verb or \"Use when\"\n- \`SKILL_NAME_MISMATCHES_DIR\` (should not fire — generic-container exemption applies here)\n- \`LINK_TO_NAVIGATION_FILE\` — link to specific files, not READMEs\n- \`LINK_TARGETS_DIRECTORY\` — link to specific files, not directories\n";
+export const text = "# VAT Plugin Skills — Development Guide\n\nThis directory ships the \`vibe-agent-toolkit\` Claude Code plugin. When editing\nor creating skills here, follow the boundaries and rules below. The goal is\nthat each sub-skill has a single, sharp trigger and that they collectively\ncover VAT\'s user-facing surface without overlap.\n\n## Skill inventory and boundaries\n\n| Skill | Owns | Does NOT own | CLI |\n|---|---|---|---|\n| \`vibe-agent-toolkit\` (router, \`SKILL.md\`) | What VAT is, when to use it, routing to sub-skills | Any deep content — keep ≤150 lines, prose-only references to sub-skills | — |\n| \`vat-adoption-and-configuration\` | Project setup, \`vibe-agent-toolkit.config.yaml\` orientation, repo structure, vibe-validate integration, npm postinstall hook | Per-section config depth (each owning skill covers its own slice) | — |\n| \`vat-skill-authoring\` | \`SKILL.md\` files: frontmatter, body structure, references, packagingOptions (linkFollowDepth, excludeReferencesFromBundle), validation overrides | TypeScript agent functions, plugin packaging, RAG | — |\n| \`vat-agent-authoring\` | TypeScript portable agents: archetypes (Pure Function Tool, One-Shot LLM Analyzer, Conversational Assistant, External Event Integrator), \`agent.yaml\`, result envelopes, runtime adapters (Vercel/LangChain/OpenAI/Claude Agent SDK) | SKILL.md authoring, plugin/marketplace config | — |\n| \`vat-audit\` | \`vat audit\` on plugins/marketplaces/skills/settings; \`--compat\`, \`--exclude\`, \`--user\`, CI usage | What to fix (defer to other skills) | \`vat audit\` |\n| \`vat-knowledge-resources\` | Markdown collections, \`vibe-agent-toolkit.config.yaml\` \`resources\` section, frontmatter schemas, validation modes | RAG indexing (separate skill) | \`vat resources validate\` |\n| \`vat-skill-distribution\` | \`vat build\`, \`vat verify\`, plugin/marketplace config, npm publishing, postinstall hooks, \`vat.skills\` field | Authoring the SKILL.md itself | \`vat build\`, \`vat verify\` |\n| \`vat-rag\` | \`vat rag index\`, \`vat rag query\`, native embedding/vector store support, extension points, \"contributions welcome\" callout | Markdown collection authoring (knowledge-resources owns) | \`vat rag\` |\n| \`vat-skill-review\` | Pre-publication review rubric, validation-code reference, Anthropic best-practices integration, \`vat skill review\` command | The validators themselves (live in code) | \`vat skill review\` |\n| \`vat-enterprise-org\` | Anthropic Admin API: org users, cost/usage, workspace skills, \`ANTHROPIC_ADMIN_API_KEY\` | Per-user runtime auth | \`vat claude org\` |\n\n## Cross-cutting: \`vibe-agent-toolkit.config.yaml\`\n\nThis file is multi-skill. Each section is owned by one skill:\n\n| Config section | Owning skill |\n|---|---|\n| Top-level structure, version, multi-section orientation | \`vat-adoption-and-configuration\` |\n| \`skills:\` (include, defaults, per-skill config, packagingOptions) | \`vat-skill-authoring\` |\n| \`resources:\` (collections, schemas, validation modes) | \`vat-knowledge-resources\` |\n| \`claude:\` (marketplaces, plugins, publish, owner) | \`vat-skill-distribution\` |\n\nWhen a skill needs to mention a section it doesn\'t own, link to the owning skill rather than re-explaining the section.\n\n## Naming rules (programmatic + advisory)\n\n- **Forbidden words in \`name\`**: \`claude\`, \`anthropic\`. Claude Code rejects skills containing these words unless they are official certified skills. Enforced by validator code \`RESERVED_WORD_IN_NAME\` (warning severity).\n- **Prefer CLI-name alignment**: when a skill primarily covers a CLI command, use the same root word (\`vat-audit\` → \`vat audit\`, \`vat-skill-review\` → \`vat skill review\`). Discovery hook for users running \`--help\`.\n- **Kebab-case**, lowercase letters, digits, hyphens. Matches \`^[a-z][a-z0-9-]*$\`.\n- **No vague nouns**: \`vat-resources\` was renamed to \`vat-knowledge-resources\` because \"resources\" alone could mean anything. Each name should carry its subject.\n- **No platform names** unless certified: see forbidden words rule above. Say \"enterprise\" not \"claude\" / \"anthropic\".\n\n## Description quality\n\nA description must let Claude Code trigger correctly. Required elements:\n- **Action verb or \"Use when...\"** opener\n- **Subject** (what kind of work fires this skill)\n- **2-4 trigger keywords** (the words a user is likely to use)\n- **What it covers** (one short clause)\n- ≤250 chars total (Claude Code listing truncates at 250)\n\nExample (\`vat-audit\`):\n> Use when running \`vat audit\` to validate Claude plugins, marketplaces, or skills. Covers the audit command, \`--compat\` for surface compatibility, \`--exclude\` for noise filtering, and interpreting findings.\n\nTriggers on: \"audit my plugin\", \"validate plugin compatibility\", \"what does this audit warning mean\".\n\n## Router skill (\`SKILL.md\` / \`vibe-agent-toolkit\`) — special rules\n\nThe router exists for **discovery + routing**, not content. Strict rules:\n\n1. **≤150 lines total**\n2. **Prose references to sub-skills** — never markdown links: write \`vibe-agent-toolkit:vat-audit\`, not \`[vat-audit](./vat-audit.md)\`. Markdown links cause VAT\'s packager to transclude the sibling, bloating the bundle.\n3. **No code examples beyond a 5-line CLI overview** — depth lives in sub-skills\n4. **Description triggers entry questions** (\"what is VAT\", \"how do I get started\"), not specific tasks\n\nVerify after edits: \`vat skill review packages/vat-development-agents/resources/skills\` should report \`fileCount: 1\` (no transclusion).\n\n## Single-responsibility — when to split\n\nSplit a skill when its description must list two unrelated subjects to trigger correctly. Example: the original \`vat-authoring\` covered both SKILL.md files and TypeScript agent functions — two distinct mental models, hence the split into \`vat-skill-authoring\` and \`vat-agent-authoring\`.\n\n## Contributor vs user content\n\nThis plugin is for **users of VAT**. Contributor-facing material (debugging VAT internals, designing install architecture, working on the codebase) belongs in \`docs/contributing/\`, not in a SKILL.md here. The root CLAUDE.md routes contributors to those docs.\n\nIf a skill description says \"use when developing/contributing to VAT\", it doesn\'t belong in this directory.\n\n## This area moves fast — verify current standards\n\nSkill authoring, agent design, and Claude Code\'s own skill-loading semantics are evolving rapidly. Cached guidance under \`docs/external/\` (e.g. \`anthropic-skill-authoring-best-practices.md\`) ages quickly. Before making non-trivial changes:\n\n- Re-fetch the source URL named in the cached doc\'s preamble; diff against the cache; if material has changed, update the cache and propagate the delta into validators and \`vat-skill-review\`.\n- Web search for the latest Claude Code release notes when changing trigger semantics, frontmatter rules, or packaging behavior. Don\'t rely on training-data recall.\n- The \`vat-skill-review\` skill must carry this same instruction explicitly — it\'s the skill agents load when they\'re about to apply quality standards.\n\n## Shift left — every manual check is a future validator\n\nWhen a quality issue is caught manually (in code review, by the user noticing an error from Claude Code, or via a checklist walkthrough), treat it as a candidate for **promotion to a programmatic validator**. The bar is: if the issue has a clear pattern that can be detected from the file contents, it should not stay a manual check.\n\n**Canonical example**: the \`RESERVED_WORD_IN_NAME\` rule. The \`claude\`/\`anthropic\` naming restriction was discovered through an install-time rejection — the kind of failure a developer hits once, remembers forever, but new contributors keep re-hitting. Encoding it as a validator (warning severity, fires at \`vat audit\` / \`vat skills validate\` time) shifts the discovery left from \"Claude Code rejects my install\" to \"validator warns me before I commit.\"\n\nWhen you add a validator:\n1. Register the code in \`validation-rules.ts\` with severity, message template, fix hint, and a \`reference\` pointer to the rationale (often a section of \`vat-skill-review\` or external doc)\n2. Wire it into the appropriate validator pipeline (frontmatter, link, packaging) so it actually fires\n3. Add a checklist entry in \`vat-skill-review\` that references the same code (so the manual rubric and the automated check stay aligned)\n4. Default severity is **warning** unless the issue genuinely blocks distribution — even then, prefer warning + clear fix hint per the [validation-rule-design policy](../../../../docs/validation-rule-design.md)\n\nWhen \`vat-skill-review\` lists a checklist item that is currently a \`[ ]\` manual judgment call, ask: *can this be detected programmatically?* If yes, file a follow-up to add the validator and convert the manual item to an automated reference.\n\n## Pre-commit checks\n\nBefore committing a skill change:\n\n\`\`\`bash\n# Review the specific skill you touched\nbun run vat skill review packages/vat-development-agents/resources/skills/<skill>.md\n\n# Audit the whole plugin\nbun run vat audit packages/vat-development-agents\n\n# Full validation\nbun run validate\n\`\`\`\n\nWatch for:\n- \`RESERVED_WORD_IN_NAME\` (warning) — naming policy violation\n- \`SKILL_DESCRIPTION_OVER_CLAUDE_CODE_LIMIT\` — trim to ≤250 chars\n- \`SKILL_DESCRIPTION_FILLER_OPENER\` — start with action verb or \"Use when\"\n- \`SKILL_NAME_MISMATCHES_DIR\` (should not fire — generic-container exemption applies here)\n- \`LINK_TO_NAVIGATION_FILE\` — link to specific files, not READMEs\n- \`LINK_TARGETS_DIRECTORY\` — link to specific files, not directories\n";
 
 export const fragments = {
   skillInventoryAndBoundaries: {
@@ -49,8 +49,8 @@ export const fragments = {
   },
   shiftLeft-EveryManualCheckIsAFutureValidator: {
     header: "## Shift left — every manual check is a future validator",
-    body: "When a quality issue is caught manually (in code review, by the user noticing an error from Claude Code, or via a checklist walkthrough), treat it as a candidate for **promotion to a programmatic validator**. The bar is: if the issue has a clear pattern that can be detected from the file contents, it should not stay a manual check.\n\n**Canonical example**: the \`RESERVED_WORD_IN_NAME\` rule. The \`claude\`/\`anthropic\` naming restriction was discovered through an install-time rejection — the kind of failure a developer hits once, remembers forever, but new contributors keep re-hitting. Encoding it as a validator (warning severity, fires at \`vat audit\` / \`vat skills validate\` time) shifts the discovery left from \"Claude Code rejects my install\" to \"validator warns me before I commit.\"\n\nWhen you add a validator:\n1. Register the code in \`validation-rules.ts\` with severity, message template, fix hint, and a \`reference\` pointer to the rationale (often a section of \`vat-skill-review\` or external doc)\n2. Wire it into the appropriate validator pipeline (frontmatter, link, packaging) so it actually fires\n3. Add a checklist entry in \`vat-skill-review\` that references the same code (so the manual rubric and the automated check stay aligned)\n4. Default severity is **warning** unless the issue genuinely blocks distribution — even then, prefer warning + clear fix hint per the [skill-smell philosophy](../../../../docs/skill-smell-philosophy.md)\n\nWhen \`vat-skill-review\` lists a checklist item that is currently a \`[ ]\` manual judgment call, ask: *can this be detected programmatically?* If yes, file a follow-up to add the validator and convert the manual item to an automated reference.",
-    text: "## Shift left — every manual check is a future validator\n\nWhen a quality issue is caught manually (in code review, by the user noticing an error from Claude Code, or via a checklist walkthrough), treat it as a candidate for **promotion to a programmatic validator**. The bar is: if the issue has a clear pattern that can be detected from the file contents, it should not stay a manual check.\n\n**Canonical example**: the \`RESERVED_WORD_IN_NAME\` rule. The \`claude\`/\`anthropic\` naming restriction was discovered through an install-time rejection — the kind of failure a developer hits once, remembers forever, but new contributors keep re-hitting. Encoding it as a validator (warning severity, fires at \`vat audit\` / \`vat skills validate\` time) shifts the discovery left from \"Claude Code rejects my install\" to \"validator warns me before I commit.\"\n\nWhen you add a validator:\n1. Register the code in \`validation-rules.ts\` with severity, message template, fix hint, and a \`reference\` pointer to the rationale (often a section of \`vat-skill-review\` or external doc)\n2. Wire it into the appropriate validator pipeline (frontmatter, link, packaging) so it actually fires\n3. Add a checklist entry in \`vat-skill-review\` that references the same code (so the manual rubric and the automated check stay aligned)\n4. Default severity is **warning** unless the issue genuinely blocks distribution — even then, prefer warning + clear fix hint per the [skill-smell philosophy](../../../../docs/skill-smell-philosophy.md)\n\nWhen \`vat-skill-review\` lists a checklist item that is currently a \`[ ]\` manual judgment call, ask: *can this be detected programmatically?* If yes, file a follow-up to add the validator and convert the manual item to an automated reference."
+    body: "When a quality issue is caught manually (in code review, by the user noticing an error from Claude Code, or via a checklist walkthrough), treat it as a candidate for **promotion to a programmatic validator**. The bar is: if the issue has a clear pattern that can be detected from the file contents, it should not stay a manual check.\n\n**Canonical example**: the \`RESERVED_WORD_IN_NAME\` rule. The \`claude\`/\`anthropic\` naming restriction was discovered through an install-time rejection — the kind of failure a developer hits once, remembers forever, but new contributors keep re-hitting. Encoding it as a validator (warning severity, fires at \`vat audit\` / \`vat skills validate\` time) shifts the discovery left from \"Claude Code rejects my install\" to \"validator warns me before I commit.\"\n\nWhen you add a validator:\n1. Register the code in \`validation-rules.ts\` with severity, message template, fix hint, and a \`reference\` pointer to the rationale (often a section of \`vat-skill-review\` or external doc)\n2. Wire it into the appropriate validator pipeline (frontmatter, link, packaging) so it actually fires\n3. Add a checklist entry in \`vat-skill-review\` that references the same code (so the manual rubric and the automated check stay aligned)\n4. Default severity is **warning** unless the issue genuinely blocks distribution — even then, prefer warning + clear fix hint per the [validation-rule-design policy](../../../../docs/validation-rule-design.md)\n\nWhen \`vat-skill-review\` lists a checklist item that is currently a \`[ ]\` manual judgment call, ask: *can this be detected programmatically?* If yes, file a follow-up to add the validator and convert the manual item to an automated reference.",
+    text: "## Shift left — every manual check is a future validator\n\nWhen a quality issue is caught manually (in code review, by the user noticing an error from Claude Code, or via a checklist walkthrough), treat it as a candidate for **promotion to a programmatic validator**. The bar is: if the issue has a clear pattern that can be detected from the file contents, it should not stay a manual check.\n\n**Canonical example**: the \`RESERVED_WORD_IN_NAME\` rule. The \`claude\`/\`anthropic\` naming restriction was discovered through an install-time rejection — the kind of failure a developer hits once, remembers forever, but new contributors keep re-hitting. Encoding it as a validator (warning severity, fires at \`vat audit\` / \`vat skills validate\` time) shifts the discovery left from \"Claude Code rejects my install\" to \"validator warns me before I commit.\"\n\nWhen you add a validator:\n1. Register the code in \`validation-rules.ts\` with severity, message template, fix hint, and a \`reference\` pointer to the rationale (often a section of \`vat-skill-review\` or external doc)\n2. Wire it into the appropriate validator pipeline (frontmatter, link, packaging) so it actually fires\n3. Add a checklist entry in \`vat-skill-review\` that references the same code (so the manual rubric and the automated check stay aligned)\n4. Default severity is **warning** unless the issue genuinely blocks distribution — even then, prefer warning + clear fix hint per the [validation-rule-design policy](../../../../docs/validation-rule-design.md)\n\nWhen \`vat-skill-review\` lists a checklist item that is currently a \`[ ]\` manual judgment call, ask: *can this be detected programmatically?* If yes, file a follow-up to add the validator and convert the manual item to an automated reference."
   },
   preCommitChecks: {
     header: "## Pre-commit checks",

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

@@ -18,6 +18,7 @@ export const text: string;
 export const fragments: {
   readonly runningTheAudit: Fragment;
   readonly whatGetsDetectedAutomatic: Fragment;
+  readonly auditingARemoteGitRepo: Fragment;
   readonly auditVsConfiguredVatProjects: Fragment;
   readonly compatibilityAnalysis--Compat: Fragment;
   readonly exitCodes: Fragment;

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

@@ -7,7 +7,7 @@ export const meta = {
   description: "Use when running vat audit to validate Claude plugins, agent skills, or marketplaces. Covers the audit command, --compat flag for surface compatibility analysis, --exclude for noise filtering, and interpreting audit output."
 };
 
-export const text = "\n# VAT Audit: Validating Plugins, Skills & Marketplaces\n\n## Running the Audit\n\n\`\`\`bash\n# Audit current directory (recursive by default)\nvat audit\n\n# Audit a specific directory\nvat audit ./plugins/\n\n# Audit your entire Claude installation\nvat audit --user\n\n# Exclude noisy directories\nvat audit --exclude \"dist/**\" --exclude \"node_modules/**\"\n\n# Verbose: show all resources, not just those with issues\nvat audit --verbose\n\n# Compatibility analysis: which Claude surfaces each plugin supports\nvat audit ./plugins/ --compat\n\`\`\`\n\n## What Gets Detected (Automatic)\n\nRunning \`vat audit <path>\` recursively walks the directory and auto-detects:\n\n| Found | Detected as |\n|---|---|\n| \`.claude-plugin/plugin.json\` in a dir | Claude Plugin |\n| \`.claude-plugin/marketplace.json\` in a dir | Claude Marketplace |\n| \`SKILL.md\` file | Agent Skill |\n| \`agent.yaml\` + \`SKILL.md\` | VAT Agent |\n| \`installed_plugins.json\` | Registry file |\n\nRecursion is the default — you do not need \`--recursive\`.\n\n## Audit vs configured VAT projects\n\nAudit 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.\n\n## Compatibility Analysis (\`--compat\`)\n\n\`\`\`bash\nvat audit ./plugins/ --compat\n\`\`\`\n\nOutput per plugin:\n\`\`\`yaml\nplugin: mission-control\ncompatibility:\n  claude-code:\n    compatible: true\n    evidence: []\n  cowork:\n    compatible: true\n    evidence: []\n  claude-desktop:\n    compatible: false\n    evidence:\n      - type: python-script\n        file: hooks-handlers/handler.py\n        detail: Python execution not available in claude-desktop\n\`\`\`\n\nUse this before a release to determine which surfaces each plugin supports.\n\n## Exit Codes\n\n\`vat audit\` is **advisory** — it reports every issue it detects but never blocks on validation severity:\n\n- \`0\` — always, when the audit completes, regardless of errors or warnings in the report.\n- \`2\` — system error (path not found, permission denied, etc.) — the audit could not run.\n\nFor gated checks that exit \`1\` on validation errors, use \`vat skills validate\` or \`vat skills build\` instead. Those commands apply \`validation.severity\` and honor \`validation.allow\` from config.\n\n## CI Usage\n\n\`\`\`yaml\n# vibe-validate.config.yaml\nsteps:\n  - name: Plugin and skill validation\n    command: vat audit plugins/ --exclude \"**/__pycache__/**\"\n\`\`\`\n\n## Interpreting Output\n\n\`\`\`yaml\nstatus: warning\nsummary:\n  filesScanned: 23\n  success: 21\n  warnings: 2\n  errors: 0\n\`\`\`\n\nSeverity taxonomy in audit output:\n- **Errors:** Missing required frontmatter, broken links, invalid plugin.json schema, link integrity violations\n- **Warnings:** Skill too long, description too short, best practice violations\n\nAudit always exits \`0\` regardless — surface-level severity drives display grouping only.\n\n**Hiding codes from audit output.** Audit ignores \`validation.allow\` by design (it is the read-only report), but it does honor \`validation.severity\`. Set a code to \`ignore\` in \`vibe-agent-toolkit.config.yaml\` to suppress it from the audit output:\n\n\`\`\`yaml\nskills:\n  config:\n    my-skill:\n      validation:\n        severity:\n          LINK_TO_NAVIGATION_FILE: ignore   # hidden from audit output\n\`\`\`\n\n**Per-instance allow entries.** For per-path suppression with an audit trail, use \`validation.allow\` and run \`vat skills validate\` or \`vat skills build\` — those commands apply \`allow\` and gate the build. See \`docs/validation-codes.md\` for the full code reference and the VAT agent-authoring skill for configuration patterns.\n";
+export const text = "\n# VAT Audit: Validating Plugins, Skills & Marketplaces\n\n## Running the Audit\n\n\`\`\`bash\n# Audit current directory (recursive by default)\nvat audit\n\n# Audit a specific directory\nvat audit ./plugins/\n\n# Audit your entire Claude installation\nvat audit --user\n\n# Exclude noisy directories\nvat audit --exclude \"dist/**\" --exclude \"node_modules/**\"\n\n# Verbose: show all resources, not just those with issues\nvat audit --verbose\n\n# Compatibility analysis: which Claude surfaces each plugin supports\nvat audit ./plugins/ --compat\n\`\`\`\n\n## What Gets Detected (Automatic)\n\nRunning \`vat audit <path>\` recursively walks the directory and auto-detects:\n\n| Found | Detected as |\n|---|---|\n| \`.claude-plugin/plugin.json\` in a dir | Claude Plugin |\n| \`.claude-plugin/marketplace.json\` in a dir | Claude Marketplace |\n| \`SKILL.md\` file | Agent Skill |\n| \`agent.yaml\` + \`SKILL.md\` | VAT Agent |\n| \`installed_plugins.json\` | Registry file |\n\nRecursion is the default — you do not need \`--recursive\`.\n\n## Auditing a remote git repo\n\n\`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.\n\n\`\`\`bash\n# Audit a public repo (HTTPS)\nvat audit https://github.com/foo/bar.git\n\n# GitHub shorthand\nvat audit foo/bar\n\n# Pin to a branch or tag\nvat audit foo/bar#main\nvat audit https://github.com/foo/bar.git#v1.2.3\n\n# Narrow to a monorepo subpath\nvat audit foo/bar#main:plugins/baz\n\n# A GitHub web URL also works\nvat audit https://github.com/foo/bar/tree/main/plugins/baz\n\`\`\`\n\nOutput 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.\n\n**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.\n\n**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.\n\nFor the full URL form table and edge cases, see \`packages/cli/docs/audit.md\` (the \"Auditing a remote git repo\" section).\n\n## Audit vs configured VAT projects\n\nAudit 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.\n\n## Compatibility Analysis (\`--compat\`)\n\n\`\`\`bash\nvat audit ./plugins/ --compat\n\`\`\`\n\nOutput per plugin:\n\`\`\`yaml\nplugin: mission-control\ncompatibility:\n  claude-code:\n    compatible: true\n    evidence: []\n  cowork:\n    compatible: true\n    evidence: []\n  claude-desktop:\n    compatible: false\n    evidence:\n      - type: python-script\n        file: hooks-handlers/handler.py\n        detail: Python execution not available in claude-desktop\n\`\`\`\n\nUse this before a release to determine which surfaces each plugin supports.\n\n## Exit Codes\n\n\`vat audit\` is **advisory** — it reports every issue it detects but never blocks on validation severity:\n\n- \`0\` — always, when the audit completes, regardless of errors or warnings in the report.\n- \`2\` — system error (path not found, permission denied, etc.) — the audit could not run.\n\nFor gated checks that exit \`1\` on validation errors, use \`vat skills validate\` or \`vat skills build\` instead. Those commands apply \`validation.severity\` and honor \`validation.allow\` from config.\n\n## CI Usage\n\n\`\`\`yaml\n# vibe-validate.config.yaml\nsteps:\n  - name: Plugin and skill validation\n    command: vat audit plugins/ --exclude \"**/__pycache__/**\"\n\`\`\`\n\n## Interpreting Output\n\n\`\`\`yaml\nstatus: warning\nsummary:\n  filesScanned: 23\n  success: 21\n  warnings: 2\n  errors: 0\n\`\`\`\n\nSeverity taxonomy in audit output:\n- **Errors:** Missing required frontmatter, broken links, invalid plugin.json schema, link integrity violations\n- **Warnings:** Skill too long, description too short, best practice violations\n\nAudit always exits \`0\` regardless — surface-level severity drives display grouping only.\n\n**Hiding codes from audit output.** Audit ignores \`validation.allow\` by design (it is the read-only report), but it does honor \`validation.severity\`. Set a code to \`ignore\` in \`vibe-agent-toolkit.config.yaml\` to suppress it from the audit output:\n\n\`\`\`yaml\nskills:\n  config:\n    my-skill:\n      validation:\n        severity:\n          LINK_TO_NAVIGATION_FILE: ignore   # hidden from audit output\n\`\`\`\n\n**Per-instance allow entries.** For per-path suppression with an audit trail, use \`validation.allow\` and run \`vat skills validate\` or \`vat skills build\` — those commands apply \`allow\` and gate the build. See \`docs/validation-codes.md\` for the full code reference and the VAT agent-authoring skill for configuration patterns.\n";
 
 export const fragments = {
   runningTheAudit: {
@@ -20,6 +20,11 @@ export const fragments = {
     body: "Running \`vat audit <path>\` recursively walks the directory and auto-detects:\n\n| Found | Detected as |\n|---|---|\n| \`.claude-plugin/plugin.json\` in a dir | Claude Plugin |\n| \`.claude-plugin/marketplace.json\` in a dir | Claude Marketplace |\n| \`SKILL.md\` file | Agent Skill |\n| \`agent.yaml\` + \`SKILL.md\` | VAT Agent |\n| \`installed_plugins.json\` | Registry file |\n\nRecursion is the default — you do not need \`--recursive\`.",
     text: "## What Gets Detected (Automatic)\n\nRunning \`vat audit <path>\` recursively walks the directory and auto-detects:\n\n| Found | Detected as |\n|---|---|\n| \`.claude-plugin/plugin.json\` in a dir | Claude Plugin |\n| \`.claude-plugin/marketplace.json\` in a dir | Claude Marketplace |\n| \`SKILL.md\` file | Agent Skill |\n| \`agent.yaml\` + \`SKILL.md\` | VAT Agent |\n| \`installed_plugins.json\` | Registry file |\n\nRecursion is the default — you do not need \`--recursive\`."
   },
+  auditingARemoteGitRepo: {
+    header: "## Auditing a remote git repo",
+    body: "\`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.\n\n\`\`\`bash\n# Audit a public repo (HTTPS)\nvat audit https://github.com/foo/bar.git\n\n# GitHub shorthand\nvat audit foo/bar\n\n# Pin to a branch or tag\nvat audit foo/bar#main\nvat audit https://github.com/foo/bar.git#v1.2.3\n\n# Narrow to a monorepo subpath\nvat audit foo/bar#main:plugins/baz\n\n# A GitHub web URL also works\nvat audit https://github.com/foo/bar/tree/main/plugins/baz\n\`\`\`\n\nOutput 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.\n\n**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.\n\n**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.\n\nFor the full URL form table and edge cases, see \`packages/cli/docs/audit.md\` (the \"Auditing a remote git repo\" section).",
+    text: "## Auditing a remote git repo\n\n\`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.\n\n\`\`\`bash\n# Audit a public repo (HTTPS)\nvat audit https://github.com/foo/bar.git\n\n# GitHub shorthand\nvat audit foo/bar\n\n# Pin to a branch or tag\nvat audit foo/bar#main\nvat audit https://github.com/foo/bar.git#v1.2.3\n\n# Narrow to a monorepo subpath\nvat audit foo/bar#main:plugins/baz\n\n# A GitHub web URL also works\nvat audit https://github.com/foo/bar/tree/main/plugins/baz\n\`\`\`\n\nOutput 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.\n\n**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.\n\n**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.\n\nFor the full URL form table and edge cases, see \`packages/cli/docs/audit.md\` (the \"Auditing a remote git repo\" section)."
+  },
   auditVsConfiguredVatProjects: {
     header: "## Audit vs configured VAT projects",
     body: "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/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\`\`\`\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 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### Per-plugin versioning (multi-plugin marketplaces)\n\nVAT supports two versioning models for a marketplace:\n\n**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.\n\n**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\`).\n\n#### Where to declare a per-plugin version\n\nTwo options, in precedence order:\n\n1. **Marketplace config** (\`vibe-agent-toolkit.config.yaml\`) — most explicit:\n   \`\`\`yaml\n   claude:\n     marketplaces:\n       my-marketplace:\n         plugins:\n           - name: ai-digest\n             version: 0.2.0\n             skills: \'*\'\n   \`\`\`\n2. **Plugin source** (\`plugins/<name>/.claude-plugin/plugin.json:version\`) — most ergonomic for plugin authors:\n   \`\`\`json\n   { \"name\": \"ai-digest\", \"version\": \"0.2.0\", \"description\": \"...\" }\n   \`\`\`\n\nIf both declare a version, marketplace config wins and VAT logs a reconciliation warning. If neither is declared, VAT falls back to the root \`package.json:version\` (single-version model).\n\n#### What \`vat claude marketplace publish\` does for multi-plugin marketplaces\n\nFor each plugin with a resolved version:\n\n- The published \`.claude-plugin/marketplace.json\` includes the per-plugin \`version\` field on each plugin entry.\n- 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.\n- 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.\n\nThe marketplace-level CHANGELOG (under \`publish.changelog\` in the config) continues to work unchanged.\n\n#### Default CHANGELOG location\n\nThe default per-plugin CHANGELOG path is \`<plugin.source>/CHANGELOG.md\`, anchored to the entry\'s \`source\` field (default \`plugins/<name>\`). It is NOT assumed to be \`plugins/<name>/CHANGELOG.md\` — if you override \`source\`, the default CHANGELOG path follows.\n\nTo use a non-default path, set the \`changelog\` field on the marketplace plugin entry (relative to the plugin source dir):\n\n\`\`\`yaml\nplugins:\n  - name: ai-digest\n    source: plugins/ai-digest\n    changelog: docs/RELEASES.md\n    skills: \'*\'\n\`\`\`\n\n#### Backwards compatibility\n\nMarketplaces 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\`).\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: {
@@ -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      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."
+    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.\n\n### Per-plugin versioning (multi-plugin marketplaces)\n\nVAT supports two versioning models for a marketplace:\n\n**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.\n\n**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\`).\n\n#### Where to declare a per-plugin version\n\nTwo options, in precedence order:\n\n1. **Marketplace config** (\`vibe-agent-toolkit.config.yaml\`) — most explicit:\n   \`\`\`yaml\n   claude:\n     marketplaces:\n       my-marketplace:\n         plugins:\n           - name: ai-digest\n             version: 0.2.0\n             skills: \'*\'\n   \`\`\`\n2. **Plugin source** (\`plugins/<name>/.claude-plugin/plugin.json:version\`) — most ergonomic for plugin authors:\n   \`\`\`json\n   { \"name\": \"ai-digest\", \"version\": \"0.2.0\", \"description\": \"...\" }\n   \`\`\`\n\nIf both declare a version, marketplace config wins and VAT logs a reconciliation warning. If neither is declared, VAT falls back to the root \`package.json:version\` (single-version model).\n\n#### What \`vat claude marketplace publish\` does for multi-plugin marketplaces\n\nFor each plugin with a resolved version:\n\n- The published \`.claude-plugin/marketplace.json\` includes the per-plugin \`version\` field on each plugin entry.\n- 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.\n- 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.\n\nThe marketplace-level CHANGELOG (under \`publish.changelog\` in the config) continues to work unchanged.\n\n#### Default CHANGELOG location\n\nThe default per-plugin CHANGELOG path is \`<plugin.source>/CHANGELOG.md\`, anchored to the entry\'s \`source\` field (default \`plugins/<name>\`). It is NOT assumed to be \`plugins/<name>/CHANGELOG.md\` — if you override \`source\`, the default CHANGELOG path follows.\n\nTo use a non-default path, set the \`changelog\` field on the marketplace plugin entry (relative to the plugin source dir):\n\n\`\`\`yaml\nplugins:\n  - name: ai-digest\n    source: plugins/ai-digest\n    changelog: docs/RELEASES.md\n    skills: \'*\'\n\`\`\`\n\n#### Backwards compatibility\n\nMarketplaces 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\`).",
+    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.\n\n### Per-plugin versioning (multi-plugin marketplaces)\n\nVAT supports two versioning models for a marketplace:\n\n**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.\n\n**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\`).\n\n#### Where to declare a per-plugin version\n\nTwo options, in precedence order:\n\n1. **Marketplace config** (\`vibe-agent-toolkit.config.yaml\`) — most explicit:\n   \`\`\`yaml\n   claude:\n     marketplaces:\n       my-marketplace:\n         plugins:\n           - name: ai-digest\n             version: 0.2.0\n             skills: \'*\'\n   \`\`\`\n2. **Plugin source** (\`plugins/<name>/.claude-plugin/plugin.json:version\`) — most ergonomic for plugin authors:\n   \`\`\`json\n   { \"name\": \"ai-digest\", \"version\": \"0.2.0\", \"description\": \"...\" }\n   \`\`\`\n\nIf both declare a version, marketplace config wins and VAT logs a reconciliation warning. If neither is declared, VAT falls back to the root \`package.json:version\` (single-version model).\n\n#### What \`vat claude marketplace publish\` does for multi-plugin marketplaces\n\nFor each plugin with a resolved version:\n\n- The published \`.claude-plugin/marketplace.json\` includes the per-plugin \`version\` field on each plugin entry.\n- 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.\n- 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.\n\nThe marketplace-level CHANGELOG (under \`publish.changelog\` in the config) continues to work unchanged.\n\n#### Default CHANGELOG location\n\nThe default per-plugin CHANGELOG path is \`<plugin.source>/CHANGELOG.md\`, anchored to the entry\'s \`source\` field (default \`plugins/<name>\`). It is NOT assumed to be \`plugins/<name>/CHANGELOG.md\` — if you override \`source\`, the default CHANGELOG path follows.\n\nTo use a non-default path, set the \`changelog\` field on the marketplace plugin entry (relative to the plugin source dir):\n\n\`\`\`yaml\nplugins:\n  - name: ai-digest\n    source: plugins/ai-digest\n    changelog: docs/RELEASES.md\n    skills: \'*\'\n\`\`\`\n\n#### Backwards compatibility\n\nMarketplaces 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\`)."
   },
   step5UserInstall: {
     header: "## Step 5: User Install",

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

@@ -7,7 +7,7 @@ export const meta = {
   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."
 };
 
-export const text = "\n# Skill Quality Checklist (vat skill review)\n\nWork through this checklist before publishing a skill. Items are grouped into general (all skills) and CLI-backed (skills that bundle and invoke scripts).\n\nThis content is also surfaced by the \`vat skill review\` CLI command, which formats the checklist around a specific skill\'s validation output.\n\n## Guidance freshness\n\nSkill authoring standards move fast. Before applying this checklist to a non-trivial change:\n\n- Re-fetch the source of \`docs/external/anthropic-skill-authoring-best-practices.md\` named in its preamble. If the content has shifted, update the cache and this checklist together.\n- Web search for the latest Claude Code release notes when trigger semantics, frontmatter rules, or packaging behavior may have changed. Don\'t rely on training-data recall.\n- Promote any manual item below to a programmatic validator when the pattern is detectable from file contents — see the shift-left notes in \`packages/vat-development-agents/resources/skills/CLAUDE.md\`.\n\n## About this checklist\n\nItems fall into two categories:\n\n- **[A]** items directly mirror Anthropic\'s official skill-authoring best practices (see the [cached guidance](../../../../docs/external/anthropic-skill-authoring-best-practices.md) or the [live doc](https://platform.claude.com/docs/en/docs/agents-and-tools/agent-skills/best-practices)). These are safe to treat as canonical.\n- **[VAT]** items are VAT-opinionated additions not explicitly in Anthropic\'s doc. They come from adopter experience, corpus observations, or Claude Code behavior changes. Individual teams can override any **[VAT]** item with \`validation.severity\` or \`validation.allow\` (with a \`reason\`).\n\nTooling enforcement: items marked with a bracketed code (e.g., \`[SKILL_DESCRIPTION_FILLER_OPENER]\`) are checked by \`vat skills validate\` / \`vat audit\`. The rest are judgment calls for a human or agent reviewer.\n\n## General — All Skills\n\n### Naming\n\n- **[A] Name format**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how. \`[SKILL_NAME_INVALID]\` enforces this.\n- **[A] Prefer gerund form** (\`processing-pdfs\`, \`analyzing-spreadsheets\`). Anthropic recommends gerund form as the primary pattern — \"clearly describes the activity or capability the Skill provides.\" Noun phrases (\`pdf-processing\`) and action-oriented forms (\`process-pdfs\`) are \"acceptable alternatives.\" Avoid vague names like \`helper\`, \`utils\`, \`tools\`.\n- **[VAT] Name matches built skill directory name**: \`[SKILL_NAME_MISMATCHES_DIR]\` fires when the \`name\` frontmatter field differs from the parent directory name after build. The schema allows inference from the directory, but explicit mismatches are usually bugs.\n\n### Description\n\n- **[A] Trigger keywords first**: lead with the concepts that should trigger this skill. Claude truncates descriptions aggressively — the most important words must come first. \`Sprint analysis, velocity tracking, work item queries. Use when ...\` beats \`This skill is used for when you need to analyze sprints\`.\n- **[A] Third-person voice**: Anthropic guidance is unambiguous — \"**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.\" Avoid first/second person: \`I can help...\`, \`You can use...\`. \`[SKILL_DESCRIPTION_WRONG_PERSON]\` flags these.\n- **[A] \`Use when <concrete trigger>\` is the recommended pattern** — every Anthropic example uses it after a verb phrase. What\'s banned is vague variants like \`Use when you want to...\` / \`Use when you need to...\` that don\'t name a concrete trigger.\n- **[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.\n- **[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.\n- **[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.\n\n### Body structure\n\n- **[A] SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. \`[SKILL_LENGTH_EXCEEDS_RECOMMENDED]\` warns as you approach the limit. Split detailed content into reference files.\n- **[A] Purpose statement in first 3 lines**: an agent skimming the top of SKILL.md should understand what it does and when to use it without reading further.\n- **[A] Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- **[A] Consistent terminology**: pick one term per concept and use it throughout. Mixing \`artifact\` / \`bundle\` / \`package\` confuses agents.\n- **[A] No time-sensitive content**: \`[SKILL_TIME_SENSITIVE_CONTENT]\` flags patterns like \`as of November 2025\` or \`after July 2026\`. Route deprecated guidance into a clearly labeled \`Old patterns\` section so agents skip it.\n\n### References and bundled files\n\n- **[A] Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. \`[PACKAGED_UNREFERENCED_FILE]\` enforces this at build time. Dead files confuse agents and waste context.\n- **[A] References one level deep**: link reference files directly from SKILL.md, not via intermediate hubs. Claude does partial reads on nested references and may miss content several hops down. \`[REFERENCE_TOO_DEEP]\` enforces.\n- **[A] TOC on reference files >100 lines**: long reference files should include a table of contents at the top. Claude often previews with partial reads — a TOC ensures the full scope of available content is visible.\n- **[A] All links resolve**: every \`[text](path)\` link points to a file that exists. \`[LINK_MISSING_TARGET]\` and siblings enforce.\n- **[A] Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- **[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.\n\n### Frontmatter hygiene\n\n- **[VAT] Frontmatter keys stay conservative**: use only the standard keys \`name\`, \`description\`, \`allowed-tools\` (plus \`argument-hint\` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific \`version:\` or \`metadata:\` fields will be rejected. If you need per-skill config, put it in \`vibe-agent-toolkit.config.yaml\`, not the frontmatter. \`[SKILL_FRONTMATTER_EXTRA_FIELDS]\` warns on non-standard keys.\n- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don\'t mix folded (\`description: >-\`) and inline (\`description: \"...\"\`) string forms. Pick one and apply it to every skill. \`[SKILL_DESCRIPTION_STYLE_MIXED_IN_PACKAGE]\` flags mixed styles across a package (detector implemented, pipeline wiring pending).\n\n### Cross-skill dependencies\n\n- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (\`Requires ado skill for auth\`). Agents may load one without the other; a silent dependency fails mysteriously at runtime. \`[SKILL_CROSS_SKILL_AUTH_UNDECLARED]\` flags body prose that requires a sibling skill or \`ANTHROPIC_*_KEY\` env var without naming it in the description.\n\n### Readability\n\n- **[VAT] Large tables move to reference files**: if a table exceeds ~15 rows, move it to a sibling reference file and link from SKILL.md. Long tables compete for context budget and push the main skill content further down.\n\n## CLI-Backed Skills — Additional Checks\n\nThese apply to skills that bundle executable scripts and instruct agents to run commands.\n\n- **[VAT] Environment guard**: the skill checks that the CLI binary exists before running commands (e.g., verify \`scripts/cli.mjs\` is present). Agents should get a clear error, not a cryptic Node.js stack trace.\n- **[VAT] Pre-flight auth check**: if the CLI requires credentials or tokens, the skill verifies them before operations. Fail fast with clear guidance on how to authenticate.\n- **[VAT] CLI invocation section**: provide exact command patterns with placeholder arguments. Agents copy these verbatim — ambiguous prose gets misinterpreted.\n- **[VAT] Error handling guidance**: document what to do when the CLI fails. Which errors are retryable? When should the agent stop and ask the user?\n- **[VAT] No bare command names in prose or tables**: agents may try to execute anything that looks like a command. Wrap command references in context or use code blocks with clear framing.\n- **[VAT] Cross-platform commands**: avoid \`timeout\` (not on macOS), platform-specific \`sed\` flags, \`grep -P\`, and other non-portable utilities. If platform-specific, document alternatives.\n- **[VAT] \`files\` config declares CLI binaries**: use \`files\` entries in \`vibe-agent-toolkit.config.yaml\` so VAT copies scripts into the skill package at build time. Don\'t rely on external copy scripts.\n- **[VAT] Document bundled assets and templates**: if scripts reference files programmatically (not via markdown links), explain what\'s bundled and why in the SKILL.md. The consuming agent should understand the full package contents.\n\n## Using This Checklist\n\nThis is a living document. When a new failure pattern is discovered in skill authoring, add a checklist item here. The goal is shift-left: catch issues before they ship rather than debugging them in production.\n\nItems marked as checks (not automated validation) are judgment calls that tooling can\'t fully enforce. An agent or human reviews them manually. Items that *can* be automated are enforced by \`vat skills validate\` / \`vat audit\` — their validation-code IDs are shown in brackets above.\n\nWhen a VAT validation code fires, its \`fix:\` field will suggest a concrete remediation; this checklist is the reference for the underlying principle. For a walkthrough that combines automated validation with this checklist, run \`vat skill review <path>\`.\n\n**Source of truth**: [Anthropic\'s skill-authoring best practices](https://platform.claude.com/docs/en/docs/agents-and-tools/agent-skills/best-practices). See [\`docs/external/anthropic-skill-authoring-best-practices.md\`](../../../../docs/external/anthropic-skill-authoring-best-practices.md) for a cached copy of the load-bearing portions with the VAT-vs-Anthropic delta called out.\n\nReviewed against external best practices (Anthropic skill-authoring docs, anthropics/skills repository, Claude Code release notes through 2026-04-18).\n";
+export const text = "\n# Skill Quality Checklist (vat skill review)\n\nWork through this checklist before publishing a skill. Items are grouped into general (all skills) and CLI-backed (skills that bundle and invoke scripts).\n\nThis content is also surfaced by the \`vat skill review\` CLI command, which formats the checklist around a specific skill\'s validation output.\n\n## Guidance freshness\n\nSkill authoring standards move fast. Before applying this checklist to a non-trivial change:\n\n- Re-fetch the source of \`docs/external/anthropic-skill-authoring-best-practices.md\` named in its preamble. If the content has shifted, update the cache and this checklist together.\n- Web search for the latest Claude Code release notes when trigger semantics, frontmatter rules, or packaging behavior may have changed. Don\'t rely on training-data recall.\n- Promote any manual item below to a programmatic validator when the pattern is detectable from file contents — see the shift-left notes in \`packages/vat-development-agents/resources/skills/CLAUDE.md\`.\n\n## About this checklist\n\nItems fall into two categories:\n\n- **[A]** items directly mirror Anthropic\'s official skill-authoring best practices (see the [cached guidance](../../../../docs/external/anthropic-skill-authoring-best-practices.md) or the [live doc](https://platform.claude.com/docs/en/docs/agents-and-tools/agent-skills/best-practices)). These are safe to treat as canonical.\n- **[VAT]** items are VAT-opinionated additions not explicitly in Anthropic\'s doc. They come from adopter experience, corpus observations, or Claude Code behavior changes. Individual teams can override any **[VAT]** item with \`validation.severity\` or \`validation.allow\` (with a \`reason\`).\n\nTooling enforcement: items marked with a bracketed code (e.g., \`[SKILL_DESCRIPTION_FILLER_OPENER]\`) are checked by \`vat skills validate\` / \`vat audit\`. The rest are judgment calls for a human or agent reviewer.\n\n## General — All Skills\n\n### Naming\n\n- **[A] Name format**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how. \`[SKILL_NAME_INVALID]\` enforces this.\n- **[A] Prefer gerund form** (\`processing-pdfs\`, \`analyzing-spreadsheets\`). Anthropic recommends gerund form as the primary pattern — \"clearly describes the activity or capability the Skill provides.\" Noun phrases (\`pdf-processing\`) and action-oriented forms (\`process-pdfs\`) are \"acceptable alternatives.\" Avoid vague names like \`helper\`, \`utils\`, \`tools\`.\n- **[VAT] Name matches built skill directory name**: \`[SKILL_NAME_MISMATCHES_DIR]\` fires when the \`name\` frontmatter field differs from the parent directory name after build. The schema allows inference from the directory, but explicit mismatches are usually bugs.\n\n### Description\n\n- **[A] Trigger keywords first**: lead with the concepts that should trigger this skill. Claude truncates descriptions aggressively — the most important words must come first. \`Sprint analysis, velocity tracking, work item queries. Use when ...\` beats \`This skill is used for when you need to analyze sprints\`.\n- **[A] Third-person voice**: Anthropic guidance is unambiguous — \"**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.\" Avoid first/second person: \`I can help...\`, \`You can use...\`. \`[SKILL_DESCRIPTION_WRONG_PERSON]\` flags these.\n- **[A] \`Use when <concrete trigger>\` is the recommended pattern** — every Anthropic example uses it after a verb phrase. What\'s banned is vague variants like \`Use when you want to...\` / \`Use when you need to...\` that don\'t name a concrete trigger.\n- **[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.\n- **[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.\n- **[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.\n- **[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.\n- **[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.\n\n### Body structure\n\n- **[A] SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. \`[SKILL_LENGTH_EXCEEDS_RECOMMENDED]\` warns as you approach the limit. Split detailed content into reference files.\n- **[A] Purpose statement in first 3 lines**: an agent skimming the top of SKILL.md should understand what it does and when to use it without reading further.\n- **[A] Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- **[A] Consistent terminology**: pick one term per concept and use it throughout. Mixing \`artifact\` / \`bundle\` / \`package\` confuses agents.\n- **[A] No time-sensitive content**: \`[SKILL_TIME_SENSITIVE_CONTENT]\` flags patterns like \`as of November 2025\` or \`after July 2026\`. Route deprecated guidance into a clearly labeled \`Old patterns\` section so agents skip it.\n\n### References and bundled files\n\n- **[A] Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. \`[PACKAGED_UNREFERENCED_FILE]\` enforces this at build time. Dead files confuse agents and waste context.\n- **[A] References one level deep**: link reference files directly from SKILL.md, not via intermediate hubs. Claude does partial reads on nested references and may miss content several hops down. \`[REFERENCE_TOO_DEEP]\` enforces.\n- **[A] TOC on reference files >100 lines**: long reference files should include a table of contents at the top. Claude often previews with partial reads — a TOC ensures the full scope of available content is visible.\n- **[A] All links resolve**: every \`[text](path)\` link points to a file that exists. \`[LINK_MISSING_TARGET]\` and siblings enforce.\n- **[A] Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- **[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.\n- **[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.\n\n### Frontmatter hygiene\n\n- **[VAT] Frontmatter keys stay conservative**: use only the standard keys \`name\`, \`description\`, \`allowed-tools\` (plus \`argument-hint\` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific \`version:\` or \`metadata:\` fields will be rejected. If you need per-skill config, put it in \`vibe-agent-toolkit.config.yaml\`, not the frontmatter. \`[SKILL_FRONTMATTER_EXTRA_FIELDS]\` warns on non-standard keys.\n- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don\'t mix folded (\`description: >-\`) and inline (\`description: \"...\"\`) string forms. Pick one and apply it to every skill. \`[SKILL_DESCRIPTION_STYLE_MIXED_IN_PACKAGE]\` flags mixed styles across a package (detector implemented, pipeline wiring pending).\n\n### Cross-skill dependencies\n\n- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (\`Requires ado skill for auth\`). Agents may load one without the other; a silent dependency fails mysteriously at runtime. \`[SKILL_CROSS_SKILL_AUTH_UNDECLARED]\` flags body prose that requires a sibling skill or \`ANTHROPIC_*_KEY\` env var without naming it in the description.\n\n### Readability\n\n- **[VAT] Large tables move to reference files**: if a table exceeds ~15 rows, move it to a sibling reference file and link from SKILL.md. Long tables compete for context budget and push the main skill content further down.\n\n## CLI-Backed Skills — Additional Checks\n\nThese apply to skills that bundle executable scripts and instruct agents to run commands.\n\n- **[VAT] Environment guard**: the skill checks that the CLI binary exists before running commands (e.g., verify \`scripts/cli.mjs\` is present). Agents should get a clear error, not a cryptic Node.js stack trace.\n- **[VAT] Pre-flight auth check**: if the CLI requires credentials or tokens, the skill verifies them before operations. Fail fast with clear guidance on how to authenticate.\n- **[VAT] CLI invocation section**: provide exact command patterns with placeholder arguments. Agents copy these verbatim — ambiguous prose gets misinterpreted.\n- **[VAT] Error handling guidance**: document what to do when the CLI fails. Which errors are retryable? When should the agent stop and ask the user?\n- **[VAT] No bare command names in prose or tables**: agents may try to execute anything that looks like a command. Wrap command references in context or use code blocks with clear framing.\n- **[VAT] Cross-platform commands**: avoid \`timeout\` (not on macOS), platform-specific \`sed\` flags, \`grep -P\`, and other non-portable utilities. If platform-specific, document alternatives.\n- **[VAT] \`files\` config declares CLI binaries**: use \`files\` entries in \`vibe-agent-toolkit.config.yaml\` so VAT copies scripts into the skill package at build time. Don\'t rely on external copy scripts.\n- **[VAT] Document bundled assets and templates**: if scripts reference files programmatically (not via markdown links), explain what\'s bundled and why in the SKILL.md. The consuming agent should understand the full package contents.\n\n## Using This Checklist\n\nThis is a living document. When a new failure pattern is discovered in skill authoring, add a checklist item here. The goal is shift-left: catch issues before they ship rather than debugging them in production.\n\nItems marked as checks (not automated validation) are judgment calls that tooling can\'t fully enforce. An agent or human reviews them manually. Items that *can* be automated are enforced by \`vat skills validate\` / \`vat audit\` — their validation-code IDs are shown in brackets above.\n\nWhen a VAT validation code fires, its \`fix:\` field will suggest a concrete remediation; this checklist is the reference for the underlying principle. For a walkthrough that combines automated validation with this checklist, run \`vat skill review <path>\`.\n\n**Source of truth**: [Anthropic\'s skill-authoring best practices](https://platform.claude.com/docs/en/docs/agents-and-tools/agent-skills/best-practices). See [\`docs/external/anthropic-skill-authoring-best-practices.md\`](../../../../docs/external/anthropic-skill-authoring-best-practices.md) for a cached copy of the load-bearing portions with the VAT-vs-Anthropic delta called out.\n\nReviewed against external best practices (Anthropic skill-authoring docs, anthropics/skills repository, Claude Code release notes through 2026-04-18).\n";
 
 export const fragments = {
   guidanceFreshness: {
@@ -22,8 +22,8 @@ export const fragments = {
   },
   general-AllSkills: {
     header: "## General — All Skills",
-    body: "### Naming\n\n- **[A] Name format**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how. \`[SKILL_NAME_INVALID]\` enforces this.\n- **[A] Prefer gerund form** (\`processing-pdfs\`, \`analyzing-spreadsheets\`). Anthropic recommends gerund form as the primary pattern — \"clearly describes the activity or capability the Skill provides.\" Noun phrases (\`pdf-processing\`) and action-oriented forms (\`process-pdfs\`) are \"acceptable alternatives.\" Avoid vague names like \`helper\`, \`utils\`, \`tools\`.\n- **[VAT] Name matches built skill directory name**: \`[SKILL_NAME_MISMATCHES_DIR]\` fires when the \`name\` frontmatter field differs from the parent directory name after build. The schema allows inference from the directory, but explicit mismatches are usually bugs.\n\n### Description\n\n- **[A] Trigger keywords first**: lead with the concepts that should trigger this skill. Claude truncates descriptions aggressively — the most important words must come first. \`Sprint analysis, velocity tracking, work item queries. Use when ...\` beats \`This skill is used for when you need to analyze sprints\`.\n- **[A] Third-person voice**: Anthropic guidance is unambiguous — \"**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.\" Avoid first/second person: \`I can help...\`, \`You can use...\`. \`[SKILL_DESCRIPTION_WRONG_PERSON]\` flags these.\n- **[A] \`Use when <concrete trigger>\` is the recommended pattern** — every Anthropic example uses it after a verb phrase. What\'s banned is vague variants like \`Use when you want to...\` / \`Use when you need to...\` that don\'t name a concrete trigger.\n- **[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.\n- **[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.\n- **[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.\n\n### Body structure\n\n- **[A] SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. \`[SKILL_LENGTH_EXCEEDS_RECOMMENDED]\` warns as you approach the limit. Split detailed content into reference files.\n- **[A] Purpose statement in first 3 lines**: an agent skimming the top of SKILL.md should understand what it does and when to use it without reading further.\n- **[A] Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- **[A] Consistent terminology**: pick one term per concept and use it throughout. Mixing \`artifact\` / \`bundle\` / \`package\` confuses agents.\n- **[A] No time-sensitive content**: \`[SKILL_TIME_SENSITIVE_CONTENT]\` flags patterns like \`as of November 2025\` or \`after July 2026\`. Route deprecated guidance into a clearly labeled \`Old patterns\` section so agents skip it.\n\n### References and bundled files\n\n- **[A] Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. \`[PACKAGED_UNREFERENCED_FILE]\` enforces this at build time. Dead files confuse agents and waste context.\n- **[A] References one level deep**: link reference files directly from SKILL.md, not via intermediate hubs. Claude does partial reads on nested references and may miss content several hops down. \`[REFERENCE_TOO_DEEP]\` enforces.\n- **[A] TOC on reference files >100 lines**: long reference files should include a table of contents at the top. Claude often previews with partial reads — a TOC ensures the full scope of available content is visible.\n- **[A] All links resolve**: every \`[text](path)\` link points to a file that exists. \`[LINK_MISSING_TARGET]\` and siblings enforce.\n- **[A] Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- **[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.\n\n### Frontmatter hygiene\n\n- **[VAT] Frontmatter keys stay conservative**: use only the standard keys \`name\`, \`description\`, \`allowed-tools\` (plus \`argument-hint\` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific \`version:\` or \`metadata:\` fields will be rejected. If you need per-skill config, put it in \`vibe-agent-toolkit.config.yaml\`, not the frontmatter. \`[SKILL_FRONTMATTER_EXTRA_FIELDS]\` warns on non-standard keys.\n- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don\'t mix folded (\`description: >-\`) and inline (\`description: \"...\"\`) string forms. Pick one and apply it to every skill. \`[SKILL_DESCRIPTION_STYLE_MIXED_IN_PACKAGE]\` flags mixed styles across a package (detector implemented, pipeline wiring pending).\n\n### Cross-skill dependencies\n\n- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (\`Requires ado skill for auth\`). Agents may load one without the other; a silent dependency fails mysteriously at runtime. \`[SKILL_CROSS_SKILL_AUTH_UNDECLARED]\` flags body prose that requires a sibling skill or \`ANTHROPIC_*_KEY\` env var without naming it in the description.\n\n### Readability\n\n- **[VAT] Large tables move to reference files**: if a table exceeds ~15 rows, move it to a sibling reference file and link from SKILL.md. Long tables compete for context budget and push the main skill content further down.",
-    text: "## General — All Skills\n\n### Naming\n\n- **[A] Name format**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how. \`[SKILL_NAME_INVALID]\` enforces this.\n- **[A] Prefer gerund form** (\`processing-pdfs\`, \`analyzing-spreadsheets\`). Anthropic recommends gerund form as the primary pattern — \"clearly describes the activity or capability the Skill provides.\" Noun phrases (\`pdf-processing\`) and action-oriented forms (\`process-pdfs\`) are \"acceptable alternatives.\" Avoid vague names like \`helper\`, \`utils\`, \`tools\`.\n- **[VAT] Name matches built skill directory name**: \`[SKILL_NAME_MISMATCHES_DIR]\` fires when the \`name\` frontmatter field differs from the parent directory name after build. The schema allows inference from the directory, but explicit mismatches are usually bugs.\n\n### Description\n\n- **[A] Trigger keywords first**: lead with the concepts that should trigger this skill. Claude truncates descriptions aggressively — the most important words must come first. \`Sprint analysis, velocity tracking, work item queries. Use when ...\` beats \`This skill is used for when you need to analyze sprints\`.\n- **[A] Third-person voice**: Anthropic guidance is unambiguous — \"**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.\" Avoid first/second person: \`I can help...\`, \`You can use...\`. \`[SKILL_DESCRIPTION_WRONG_PERSON]\` flags these.\n- **[A] \`Use when <concrete trigger>\` is the recommended pattern** — every Anthropic example uses it after a verb phrase. What\'s banned is vague variants like \`Use when you want to...\` / \`Use when you need to...\` that don\'t name a concrete trigger.\n- **[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.\n- **[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.\n- **[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.\n\n### Body structure\n\n- **[A] SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. \`[SKILL_LENGTH_EXCEEDS_RECOMMENDED]\` warns as you approach the limit. Split detailed content into reference files.\n- **[A] Purpose statement in first 3 lines**: an agent skimming the top of SKILL.md should understand what it does and when to use it without reading further.\n- **[A] Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- **[A] Consistent terminology**: pick one term per concept and use it throughout. Mixing \`artifact\` / \`bundle\` / \`package\` confuses agents.\n- **[A] No time-sensitive content**: \`[SKILL_TIME_SENSITIVE_CONTENT]\` flags patterns like \`as of November 2025\` or \`after July 2026\`. Route deprecated guidance into a clearly labeled \`Old patterns\` section so agents skip it.\n\n### References and bundled files\n\n- **[A] Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. \`[PACKAGED_UNREFERENCED_FILE]\` enforces this at build time. Dead files confuse agents and waste context.\n- **[A] References one level deep**: link reference files directly from SKILL.md, not via intermediate hubs. Claude does partial reads on nested references and may miss content several hops down. \`[REFERENCE_TOO_DEEP]\` enforces.\n- **[A] TOC on reference files >100 lines**: long reference files should include a table of contents at the top. Claude often previews with partial reads — a TOC ensures the full scope of available content is visible.\n- **[A] All links resolve**: every \`[text](path)\` link points to a file that exists. \`[LINK_MISSING_TARGET]\` and siblings enforce.\n- **[A] Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- **[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.\n\n### Frontmatter hygiene\n\n- **[VAT] Frontmatter keys stay conservative**: use only the standard keys \`name\`, \`description\`, \`allowed-tools\` (plus \`argument-hint\` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific \`version:\` or \`metadata:\` fields will be rejected. If you need per-skill config, put it in \`vibe-agent-toolkit.config.yaml\`, not the frontmatter. \`[SKILL_FRONTMATTER_EXTRA_FIELDS]\` warns on non-standard keys.\n- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don\'t mix folded (\`description: >-\`) and inline (\`description: \"...\"\`) string forms. Pick one and apply it to every skill. \`[SKILL_DESCRIPTION_STYLE_MIXED_IN_PACKAGE]\` flags mixed styles across a package (detector implemented, pipeline wiring pending).\n\n### Cross-skill dependencies\n\n- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (\`Requires ado skill for auth\`). Agents may load one without the other; a silent dependency fails mysteriously at runtime. \`[SKILL_CROSS_SKILL_AUTH_UNDECLARED]\` flags body prose that requires a sibling skill or \`ANTHROPIC_*_KEY\` env var without naming it in the description.\n\n### Readability\n\n- **[VAT] Large tables move to reference files**: if a table exceeds ~15 rows, move it to a sibling reference file and link from SKILL.md. Long tables compete for context budget and push the main skill content further down."
+    body: "### Naming\n\n- **[A] Name format**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how. \`[SKILL_NAME_INVALID]\` enforces this.\n- **[A] Prefer gerund form** (\`processing-pdfs\`, \`analyzing-spreadsheets\`). Anthropic recommends gerund form as the primary pattern — \"clearly describes the activity or capability the Skill provides.\" Noun phrases (\`pdf-processing\`) and action-oriented forms (\`process-pdfs\`) are \"acceptable alternatives.\" Avoid vague names like \`helper\`, \`utils\`, \`tools\`.\n- **[VAT] Name matches built skill directory name**: \`[SKILL_NAME_MISMATCHES_DIR]\` fires when the \`name\` frontmatter field differs from the parent directory name after build. The schema allows inference from the directory, but explicit mismatches are usually bugs.\n\n### Description\n\n- **[A] Trigger keywords first**: lead with the concepts that should trigger this skill. Claude truncates descriptions aggressively — the most important words must come first. \`Sprint analysis, velocity tracking, work item queries. Use when ...\` beats \`This skill is used for when you need to analyze sprints\`.\n- **[A] Third-person voice**: Anthropic guidance is unambiguous — \"**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.\" Avoid first/second person: \`I can help...\`, \`You can use...\`. \`[SKILL_DESCRIPTION_WRONG_PERSON]\` flags these.\n- **[A] \`Use when <concrete trigger>\` is the recommended pattern** — every Anthropic example uses it after a verb phrase. What\'s banned is vague variants like \`Use when you want to...\` / \`Use when you need to...\` that don\'t name a concrete trigger.\n- **[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.\n- **[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.\n- **[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.\n- **[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.\n- **[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.\n\n### Body structure\n\n- **[A] SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. \`[SKILL_LENGTH_EXCEEDS_RECOMMENDED]\` warns as you approach the limit. Split detailed content into reference files.\n- **[A] Purpose statement in first 3 lines**: an agent skimming the top of SKILL.md should understand what it does and when to use it without reading further.\n- **[A] Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- **[A] Consistent terminology**: pick one term per concept and use it throughout. Mixing \`artifact\` / \`bundle\` / \`package\` confuses agents.\n- **[A] No time-sensitive content**: \`[SKILL_TIME_SENSITIVE_CONTENT]\` flags patterns like \`as of November 2025\` or \`after July 2026\`. Route deprecated guidance into a clearly labeled \`Old patterns\` section so agents skip it.\n\n### References and bundled files\n\n- **[A] Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. \`[PACKAGED_UNREFERENCED_FILE]\` enforces this at build time. Dead files confuse agents and waste context.\n- **[A] References one level deep**: link reference files directly from SKILL.md, not via intermediate hubs. Claude does partial reads on nested references and may miss content several hops down. \`[REFERENCE_TOO_DEEP]\` enforces.\n- **[A] TOC on reference files >100 lines**: long reference files should include a table of contents at the top. Claude often previews with partial reads — a TOC ensures the full scope of available content is visible.\n- **[A] All links resolve**: every \`[text](path)\` link points to a file that exists. \`[LINK_MISSING_TARGET]\` and siblings enforce.\n- **[A] Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- **[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.\n- **[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.\n\n### Frontmatter hygiene\n\n- **[VAT] Frontmatter keys stay conservative**: use only the standard keys \`name\`, \`description\`, \`allowed-tools\` (plus \`argument-hint\` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific \`version:\` or \`metadata:\` fields will be rejected. If you need per-skill config, put it in \`vibe-agent-toolkit.config.yaml\`, not the frontmatter. \`[SKILL_FRONTMATTER_EXTRA_FIELDS]\` warns on non-standard keys.\n- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don\'t mix folded (\`description: >-\`) and inline (\`description: \"...\"\`) string forms. Pick one and apply it to every skill. \`[SKILL_DESCRIPTION_STYLE_MIXED_IN_PACKAGE]\` flags mixed styles across a package (detector implemented, pipeline wiring pending).\n\n### Cross-skill dependencies\n\n- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (\`Requires ado skill for auth\`). Agents may load one without the other; a silent dependency fails mysteriously at runtime. \`[SKILL_CROSS_SKILL_AUTH_UNDECLARED]\` flags body prose that requires a sibling skill or \`ANTHROPIC_*_KEY\` env var without naming it in the description.\n\n### Readability\n\n- **[VAT] Large tables move to reference files**: if a table exceeds ~15 rows, move it to a sibling reference file and link from SKILL.md. Long tables compete for context budget and push the main skill content further down.",
+    text: "## General — All Skills\n\n### Naming\n\n- **[A] Name format**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how. \`[SKILL_NAME_INVALID]\` enforces this.\n- **[A] Prefer gerund form** (\`processing-pdfs\`, \`analyzing-spreadsheets\`). Anthropic recommends gerund form as the primary pattern — \"clearly describes the activity or capability the Skill provides.\" Noun phrases (\`pdf-processing\`) and action-oriented forms (\`process-pdfs\`) are \"acceptable alternatives.\" Avoid vague names like \`helper\`, \`utils\`, \`tools\`.\n- **[VAT] Name matches built skill directory name**: \`[SKILL_NAME_MISMATCHES_DIR]\` fires when the \`name\` frontmatter field differs from the parent directory name after build. The schema allows inference from the directory, but explicit mismatches are usually bugs.\n\n### Description\n\n- **[A] Trigger keywords first**: lead with the concepts that should trigger this skill. Claude truncates descriptions aggressively — the most important words must come first. \`Sprint analysis, velocity tracking, work item queries. Use when ...\` beats \`This skill is used for when you need to analyze sprints\`.\n- **[A] Third-person voice**: Anthropic guidance is unambiguous — \"**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.\" Avoid first/second person: \`I can help...\`, \`You can use...\`. \`[SKILL_DESCRIPTION_WRONG_PERSON]\` flags these.\n- **[A] \`Use when <concrete trigger>\` is the recommended pattern** — every Anthropic example uses it after a verb phrase. What\'s banned is vague variants like \`Use when you want to...\` / \`Use when you need to...\` that don\'t name a concrete trigger.\n- **[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.\n- **[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.\n- **[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.\n- **[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.\n- **[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.\n\n### Body structure\n\n- **[A] SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. \`[SKILL_LENGTH_EXCEEDS_RECOMMENDED]\` warns as you approach the limit. Split detailed content into reference files.\n- **[A] Purpose statement in first 3 lines**: an agent skimming the top of SKILL.md should understand what it does and when to use it without reading further.\n- **[A] Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- **[A] Consistent terminology**: pick one term per concept and use it throughout. Mixing \`artifact\` / \`bundle\` / \`package\` confuses agents.\n- **[A] No time-sensitive content**: \`[SKILL_TIME_SENSITIVE_CONTENT]\` flags patterns like \`as of November 2025\` or \`after July 2026\`. Route deprecated guidance into a clearly labeled \`Old patterns\` section so agents skip it.\n\n### References and bundled files\n\n- **[A] Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. \`[PACKAGED_UNREFERENCED_FILE]\` enforces this at build time. Dead files confuse agents and waste context.\n- **[A] References one level deep**: link reference files directly from SKILL.md, not via intermediate hubs. Claude does partial reads on nested references and may miss content several hops down. \`[REFERENCE_TOO_DEEP]\` enforces.\n- **[A] TOC on reference files >100 lines**: long reference files should include a table of contents at the top. Claude often previews with partial reads — a TOC ensures the full scope of available content is visible.\n- **[A] All links resolve**: every \`[text](path)\` link points to a file that exists. \`[LINK_MISSING_TARGET]\` and siblings enforce.\n- **[A] Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- **[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.\n- **[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.\n\n### Frontmatter hygiene\n\n- **[VAT] Frontmatter keys stay conservative**: use only the standard keys \`name\`, \`description\`, \`allowed-tools\` (plus \`argument-hint\` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific \`version:\` or \`metadata:\` fields will be rejected. If you need per-skill config, put it in \`vibe-agent-toolkit.config.yaml\`, not the frontmatter. \`[SKILL_FRONTMATTER_EXTRA_FIELDS]\` warns on non-standard keys.\n- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don\'t mix folded (\`description: >-\`) and inline (\`description: \"...\"\`) string forms. Pick one and apply it to every skill. \`[SKILL_DESCRIPTION_STYLE_MIXED_IN_PACKAGE]\` flags mixed styles across a package (detector implemented, pipeline wiring pending).\n\n### Cross-skill dependencies\n\n- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (\`Requires ado skill for auth\`). Agents may load one without the other; a silent dependency fails mysteriously at runtime. \`[SKILL_CROSS_SKILL_AUTH_UNDECLARED]\` flags body prose that requires a sibling skill or \`ANTHROPIC_*_KEY\` env var without naming it in the description.\n\n### Readability\n\n- **[VAT] Large tables move to reference files**: if a table exceeds ~15 rows, move it to a sibling reference file and link from SKILL.md. Long tables compete for context budget and push the main skill content further down."
   },
   cliBackedSkills-AdditionalChecks: {
     header: "## CLI-Backed Skills — Additional Checks",

package/dist/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/skills/vat-skill-distribution/SKILL.md

@@ -300,6 +300,63 @@ Start a new Claude Code session to confirm skills load. See the [Marketplace Dis
 
 **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.
 
+### Per-plugin versioning (multi-plugin marketplaces)
+
+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.
+
+**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`).
+
+#### Where to declare a per-plugin version
+
+Two options, in precedence order:
+
+1. **Marketplace config** (`vibe-agent-toolkit.config.yaml`) — most explicit:
+   ```yaml
+   claude:
+     marketplaces:
+       my-marketplace:
+         plugins:
+           - name: ai-digest
+             version: 0.2.0
+             skills: '*'
+   ```
+2. **Plugin source** (`plugins/<name>/.claude-plugin/plugin.json:version`) — most ergonomic for plugin authors:
+   ```json
+   { "name": "ai-digest", "version": "0.2.0", "description": "..." }
+   ```
+
+If both declare a version, marketplace config wins and VAT logs a reconciliation warning. If neither is declared, VAT falls back to the root `package.json:version` (single-version model).
+
+#### What `vat claude marketplace publish` does for multi-plugin marketplaces
+
+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.
+
+#### Default CHANGELOG location
+
+The default per-plugin CHANGELOG path is `<plugin.source>/CHANGELOG.md`, anchored to the entry's `source` field (default `plugins/<name>`). It is NOT assumed to be `plugins/<name>/CHANGELOG.md` — if you override `source`, the default CHANGELOG path follows.
+
+To use a non-default path, set the `changelog` field on the marketplace plugin entry (relative to the plugin source dir):
+
+```yaml
+plugins:
+  - name: ai-digest
+    source: plugins/ai-digest
+    changelog: docs/RELEASES.md
+    skills: '*'
+```
+
+#### 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`).
+
 ## Step 5: User Install
 
 ### Recommended: npm global install (postinstall runs automatically)

package/dist/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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/vat-development-agents",
-  "version": "0.1.34-rc.2",
+  "version": "0.1.35",
   "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.34-rc.2",
-    "@vibe-agent-toolkit/cli": "0.1.34-rc.2",
+    "@vibe-agent-toolkit/agent-schema": "0.1.35",
+    "@vibe-agent-toolkit/cli": "0.1.35",
     "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
-    "@vibe-agent-toolkit/resource-compiler": "0.1.34-rc.2",
+    "@vibe-agent-toolkit/resource-compiler": "0.1.35",
     "ts-patch": "^3.2.1",
     "typescript": "^5.7.3"
   },