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

package/README.md

@@ -71,7 +71,7 @@ vat skills install ./packages/vat-development-agents
 vat skills list --installed
 ```
 
-The `vibe-agent-toolkit` skill will be installed to `~/.claude/plugins/vibe-agent-toolkit/` and will appear in Claude Code after restarting or running `/reload-skills`.
+The `vibe-agent-toolkit` skill will be installed to `~/.claude/plugins/vibe-agent-toolkit/` and will appear in Claude Code after restarting or running `/reload-plugins`.
 
 **What the skill includes:**
 - VAT overview and use cases

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

@@ -9,7 +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.37",
+      "version": "0.1.39-rc.1",
       "author": {
         "name": "vibe-agent-toolkit contributors"
       }

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

@@ -7,6 +7,210 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Internal
+
+- **Empirical compatibility harness (`packages/dev-tools/src/compat-empirical/`).** Per-#100 research scaffold: a CLI (`predict`/`run`/`judge`/`report`/`all`) that runs candidate skills against claude-code, claude-cowork, and claude-chat, then joins VAT's static predictions with deterministic runtime observations and an LLM-judge semantic read into a reality-vs-prediction matrix. The output is an evidence artifact a follow-up PR will draw on to propose detector improvements, each citing specific (skill, runtime) cells. No detector code or `RUNTIME_PROFILES` changes here. Lives in the private `@vibe-agent-toolkit/dev-tools` package no adopter-facing surface.
+- **Empirical compat harness v2 (`packages/dev-tools/src/compat-empirical/`).** Foundations PR per [the v2 design](./docs/research/2026-05-23-compat-empirical-harness-v2-design.md). Probe coverage: multi-prompt + repeat-N with adaptive N=3→N=5 extension, mandatory positive+negative prompt pairing per corpus entry, and negative-prompt agreement inversion so false-positive triggers surface as `vat-optimistic`. Evidence quality: deterministic class widened from 6 to 9 values (splitting `error` into `install-failed`/`runtime-error`, `not-invoked` into `not-invoked-engaged`/`not-invoked-empty`, adding `refused`), judge prompt rewritten to v2 with a `refused` verdict. Report fidelity: coverage stats, per-bucket headline (own/official/community × ran/agree/optimistic/pessimistic/gray-zone), gray-zone (mixed-signal) and high-variance subsections, per-attempt variance rendered inline (`runtime-error (2/3) / failed (3/3)`). Judge replay: persisted `judge-calls/<skillId>-<promptId>-<target>-<attemptIdx>.json` artifacts plus a new `re-judge` subcommand that re-executes them against an optionally different model or freshly-edited system prompt without re-spending operator hours on the runtime side. Two PR-#108 deferred bug fixes also landed: `git fetch --tags --force` before named-ref fetch (annotated tag refresh) and `setup()` teardown-first idempotency for the manual driver. Still private to `@vibe-agent-toolkit/dev-tools`; corpus authoring, first real run, and the docs deliverable are the downstream work.
+- **Cowork driver spike.** Added [`docs/contributing/cowork-driver-spike.md`](docs/contributing/cowork-driver-spike.md) — a time-boxed investigation (per §4a of the harness v2 design) of whether `claude-cowork` can be driven programmatically by the empirical compat harness today. Verdict: **not feasible**; cowork is a Claude Desktop app product with no public API/CLI surface. The `claude-cowork` runtime stays on `scripted-assisted` until Anthropic ships a Cowork CLI mode, Sessions API, or documented filesystem-import path. Adjacent finding (not a cowork replacement): the public-beta Skills API (`POST /v1/skills` + `container.skills[]` on `/v1/messages`) supports a fully-automatable *new* runtime — captured in the spike doc as a potential follow-up, gated on a separate design decision.
+- **Subscription-only compat harness billing.** The harness now bills a Claude Pro/Max subscription instead of the API: both token-consuming surfaces (the `claude-code` runtime driver and the LLM judge) route through one shared `claude` CLI invoker (`runtimes/shared/claude-cli.ts`) that injects the operator's `CLAUDE_CODE_OAUTH_TOKEN` and deletes every API credential from the child env, so the CLI cannot fall back to API billing. The operator's own token is sourced at preflight — env var if set, otherwise an interactive prompt — so a run only ever spends the operator's personal plan. The judge was migrated off `@anthropic-ai/sdk` (dependency removed) onto the CLI, parsing a strict JSON verdict with one retry instead of the SDK's forced-tool call (`judge-system.md` now asks for a JSON object). `RunMetadata` gains `authMode` and the report methodology discloses subscription auth + parsed-not-forced verdicts. Premise (zero API billing under the OAuth token) still pending the manual smoke test.
+
+### Changed (breaking, pre-1.0)
+
+- **`vat resources validate` gains per-code severity configuration, and external-URL findings no longer fail the build by default.** Resource findings now use the same configurable severity framework as `vat skills`: each is a documented code (e.g. `LINK_BROKEN_FILE`, `EXTERNAL_URL_DEAD`) with a default severity, overridable per project under `resources.validation.severity` / `resources.validation.allow`. External-URL findings now default to `warning` and no longer flip the exit code (fixing a bug where they always failed the command); set their severity to `error` to restore failing. Severity now also accepts an `info` level. The never-implemented `resources.validation.checkLinks`/`checkAnchors`/`allowExternal` keys are removed.
+- **`validation.severity` / `validation.allow` keys are validated against real codes.** A mistyped code key (e.g. `LNIK_OUTSIDE_PROJECT`) is now a config-load error instead of a silent no-op.
+- **Corpus seed entries now require `bucket`, `confidence`, and `maturity` metadata fields.** `PluginEntrySchema` in `vat corpus scan`'s seed loader gains three required enum fields: `bucket: 'official' | 'community'`, `confidence: 'first-party' | 'curated' | 'listed'`, and `maturity: 'production' | 'experimental' | 'example'`. The bundled `corpus/seed.yaml` is updated; downstream callers running custom seeds must add the fields to every entry. `bucket` is the load-bearing discriminator (`official` entries report named findings; `community` entries are aggregate-only in follow-up work). The other two are descriptive metadata used by triage tooling.
+- **`vat claude marketplace publish` no longer reports the project root `package.json` version in the CLI banner, commit message, status YAML, or CHANGELOG section lookup.** The label is now derived from the staged `marketplace.json`. Single-plugin marketplaces use the plugin's version — banner reads `Publishing marketplace "X" v0.0.4`, commit subject reads `publish v0.0.4`. Multi-plugin marketplaces drop the `v<X>` entirely — banner reads `Publishing marketplace "X"`, commit subject reads `publish X` — since the per-plugin `version` fields in the published `marketplace.json` are the source of truth for which plugin moved to which version. Two visible side-effects follow: (1) the status YAML's `published[*].version` field is now absent for multi-plugin marketplaces (previously it carried the misleading project version) — automation should read per-plugin versions from the published `marketplace.json` instead; (2) the stamped `## [X.Y.Z]` CHANGELOG lookup now uses the plugin's version rather than the project's, so a previously-ignored matching section will now be picked up as the commit body for single-plugin marketplaces. The `marketplace.json` schema's optional top-level `version` field is not yet consumed — that is a separate follow-up.
+- **`vat claude marketplace publish` no longer pushes per-plugin `<name>-v<version>` source-repo tags.** The post-publish tagging step (introduced alongside multi-plugin versioning) is removed entirely — no tags are created or pushed, and the misleading `Repository not found` / "tag already exists at a different commit" warnings it emitted on every cross-repo publish are gone ([#121](https://github.com/jdutton/vibe-agent-toolkit/issues/121)). The tags were pushed to the marketplace remote rather than a source remote, never landed anywhere useful, and there was no opt-in demand. Which plugin moved to which version is now determined solely by the per-plugin `version` fields in the published `marketplace.json`. No config key or flag is involved; if you relied on these tags, create them in your own release workflow.
+
+### Fixed
+
+- **Transformers.js integration tests now skip on Windows CI instead of flaking.** `transformers-embedding-provider.integration.test.ts` and the Transformers.js block of `comparison.integration.test.ts` skip on Windows (in addition to skipping when the optional `@xenova/transformers` dependency is absent), matching the existing `onnx-embedding-provider` test. These tests download a model over the network and load the `onnxruntime-node` native backend — both flaky in Windows CI. Such a failure was previously mislabeled `@xenova/transformers is not installed` by an over-broad `catch` in the provider's `loadPipeline` (the package was installed; the model download/inference is what failed), which is also why an availability-only guard did not prevent it.
+- **Config-first skill discovery now honors `..` in `skills.include` patterns.** `vat build`, `vat verify`, and `vat skills validate` all funnel through `discoverSkillsFromConfig`, which previously passed every include pattern to a single downward-only crawl rooted at `projectRoot` — so an include like `"../../docs/skills/*/SKILL.md"` (common in monorepos where SKILL.md sources live alongside, not inside, the package) silently matched zero skills. `vat audit` accepted the same config only because it has a separate filesystem-first walker. Each include pattern is now split into a literal base + glob remainder via `picomatch.scan`, patterns are grouped by their resolved absolute base, and the crawler runs once per base — making config-first discovery agree with audit. User-supplied excludes stay anchored to `projectRoot` so patterns like `docs/private/**` keep their original meaning, and a pattern resolving to a nonexistent base now silently produces zero matches.
+
+## [0.1.38] - 2026-05-18
+
+### Changed (breaking, pre-1.0)
+
+- **`findProjectRoot` from `@vibe-agent-toolkit/utils` has new semantics.** It
+  now walks `vibe-agent-toolkit.config.yaml` → `.git/` and returns
+  `string | null` with no fallback to `cwd`. The previous workspace-anchored
+  behavior (workspace `package.json` → git → `cwd`, returning `string`) moved
+  to a new function: `findNodeWorkspaceRoot`, scoped to workspace `package.json`
+  lookup only and also returning `string | null`. Migration: use
+  `findNodeWorkspaceRoot` if you wanted Node-monorepo binary discovery; use
+  `findProjectRoot` if you wanted the VAT authoring boundary. Either way,
+  handle the `null` return — there is no more silent `cwd` fallback.
+
+- **`resolveLocalHref` returns a discriminated union.** From
+  `{ resolvedPath; anchor } | null` to one of `anchor_only | resolved |
+  absolute_no_root | absolute_escapes_root`. The function exported from
+  `@vibe-agent-toolkit/resources` now also accepts an optional `projectRoot`
+  parameter. Leading-`/` markdown links and frontmatter URI-references now
+  resolve against `projectRoot` per RFC 3986 §4.2 absolute-path-reference
+  semantics — matching GitHub, MkDocs, Sphinx, Docusaurus, VuePress, Jekyll,
+  Astro Starlight, Nextra, and MDN. Previously `safePath.resolve(sourceDir,
+  '/docs/foo.md')` resolved to filesystem-absolute `/docs/foo.md`. The two
+  new union kinds (`absolute_no_root`, `absolute_escapes_root`) surface to
+  consumers as the existing `broken_file` issue with distinct messages — no
+  new validation-code names. External callers destructuring the old return
+  shape must update to switch on `kind`.
+
+- **`ValidateLinkOptions.projectRoot` semantic narrowing.** In monorepos, the
+  effective root for link validation is now the nearest
+  `vibe-agent-toolkit.config.yaml` ancestor (or `.git/` ancestor), not the
+  workspace root. Cross-package relative links (`../sibling-pkg/foo.md`) are
+  still validated for file existence, case mismatches, and anchor resolution
+  — path-based logic is unaffected. **The gitignore-safety gate, however,
+  scopes to the sub-package's `projectRoot` only.** Adopters who own per-package
+  `vibe-agent-toolkit.config.yaml` files in a monorepo and rely on
+  workspace-wide gitignore checking for cross-package doc links must either
+  move the config up to the workspace root or accept the narrower scope. In
+  practice, the file-existence + anchor checks are what catch broken links;
+  the narrower gitignore gate matches how VAT already treats links to
+  truly-external files.
+
+- **Some adopter configs may need `validation.allow.LINK_OUTSIDE_PROJECT`.**
+  Because the effective `projectRoot` narrows in monorepos with per-package
+  configs, cross-package links that previously passed under workspace-wide
+  scope may now emit `LINK_OUTSIDE_PROJECT`. Add a `validation.allow` entry
+  for the affected paths or `validation.severity` override at the config that
+  governs the linking skill.
+
+- **`Logger.warn` added to the CLI `Logger` interface.** The interface widened
+  with a `warn(message: string): void` method that writes to stderr. If you
+  implement the `Logger` interface directly (custom embedders, test doubles),
+  add the method.
+
+- **`excludeReferencesFromBundle` no longer masks cross-package links flagged
+  as outside-project.** Under the new `projectRoot` model, `outside-project`
+  fires before bundle-exclusion pattern match. If you used
+  `excludeReferencesFromBundle` to hide cross-package links from audit, those
+  links will now surface — switch to `validation.severity` or `validation.allow`
+  on `LINK_OUTSIDE_PROJECT` for the relevant skill.
+
+- **Skill packager rewrites frontmatter URI-references during packaging.**
+  When a markdown file's collection has a `frontmatterSchema` configured, the
+  packager now walks every schema-annotated URI-reference field (`format:
+  uri-reference`, `uri`, `iri-reference`, `iri`) and rewrites the value with
+  the same target-path lookup that drives body-link rewriting. Body and
+  frontmatter URI-refs now agree on packaged paths, and inline comments on
+  rewritten fields survive. Previously, packaged artifacts could ship with
+  rewritten body links but stale source-path frontmatter pointers — a silent
+  half-correct rewrite.
+
+- **`@vibe-agent-toolkit/resource-compiler` now depends on
+  `@vibe-agent-toolkit/resources`.** The markdown parser there goes through
+  `openFrontmatter` so frontmatter comments survive into compiled output.
+  Pure transitive consumers see no API change; embedders who installed
+  `resource-compiler` standalone now pull `resources` too.
+
+### Added
+
+- **Canonical comment-preserving primitive for frontmatter edits:
+  `openFrontmatter` from `@vibe-agent-toolkit/resources`.** Wraps `yaml`
+  (eemeli) in a round-trip-safe editor with `get` / `set` / `setArrayItem` /
+  `appendArrayItem` / `delete` / `toString` and a settable `body`. Comments,
+  blank lines, key order, quoting style, anchors, and EOL survive on
+  mutation. `openFrontmatter(x).toString()` is byte-identical to `x` until
+  you mutate. Malformed YAML throws `FrontmatterParseError` with the
+  underlying error on `.cause`. Use this instead of `gray-matter`,
+  `front-matter`, or raw `yaml.parse` for any write path — those drop
+  comments silently.
+
+- **`createAjvWithUriFormats(options?)` from `@vibe-agent-toolkit/resources`** —
+  Ajv factory pre-registered with the URI-family formats (`uri`,
+  `uri-reference`, `iri`, `iri-reference`) plus the rest of the
+  `ajv-formats` standard vocabulary. Use this anywhere downstream code
+  compiles a schema that may reference those formats: vanilla
+  `new Ajv({ allErrors: true })` throws `unknown format "uri-reference"
+  ignored` under default strict mode, and adopters had to invent the
+  workaround themselves. `iri` / `iri-reference` are registered as no-op
+  validators (semantic validation is the caller's job — VAT uses
+  `resolveLocalHref` for that). Ajv options pass through unchanged so
+  callers control `allErrors`, `strict`, `verbose`, etc.
+
+- **Three rewriter helpers sharing one `(href: string) => string` callback
+  shape**, exported from `@vibe-agent-toolkit/resources`:
+  - `rewriteBodyLinks(body, rewriteHref)` — inline links + reference
+    definitions in the markdown body.
+  - `rewriteFrontmatterFieldsAtPaths(editor, paths, rewriteHref)` — when you
+    know the field paths by convention (`'meta.parent'`, `'adrs-cited[]'`).
+  - `rewriteFrontmatterUriReferencesFromSchema(editor, schema, rewriteHref)`
+    — when you have a JSON Schema and want every `format: uri-reference`
+    field walked automatically. Compose with `rewriteBodyLinks` for the
+    common file/folder-rename case.
+
+- **New `markdown-rewriting` skill in the `vibe-agent-toolkit` Claude Code
+  plugin** — steers any session about to programmatically edit markdown or
+  frontmatter toward the comment-preserving primitives above. Includes the
+  canonical file-move recipe (body + frontmatter together) and the
+  schema-driven variant. Triggers on prompts like "rewrite references
+  across these docs", "rename `/docs/specs/` to `/docs/architecture/`",
+  "batch-update parent_spec".
+
+- **URI-references in frontmatter are now a documented affordance.** Updates
+  to two existing skills:
+  - `vat-knowledge-resources` — explains the leading-`/` resolution
+    + comment-preservation story for schema-annotated URI-ref fields.
+  - `vat-skill-authoring` — recommends leading-`/` URI-refs for cross-document
+    references in SKILL.md frontmatter and cross-links `markdown-rewriting`
+    for programmatic edits.
+
+- **Per-command `projectRoot` and config policies, documented and enforced.**
+  Every `vat` command now declares its `projectRoot` policy (`required` /
+  `tolerate null` / `loud-cwd` / `N/A`) and config policy (`required file` /
+  `required fields` / `accept defaults` / `not used`) in `--help` output and
+  in its CLI reference doc under `packages/cli/docs/` or `docs/cli/`. The
+  canonical source is the new [Roots and Config — Canonical
+  Concepts](docs/concepts/roots-and-config.md) doc. Run `vat <cmd> --help` to
+  see the `Requirements:` block for any command.
+
+- **Loud-cwd fallback for `vat resources scan` and `vat resources validate`.**
+  When invoked without an explicit path and no `vibe-agent-toolkit.config.yaml`
+  or `.git/` ancestor is found, these commands now fall back to `cwd` and emit
+  a single stderr warning (`warn: no vibe-agent-toolkit.config.yaml or .git/
+  ancestor; using <cwd> as projectRoot`) instead of failing silently or
+  surprising the user. With an explicit path argument the path is used and no
+  warning fires.
+
+- **`docs/concepts/roots-and-config.md`** — single source of truth for the
+  three-root model (`projectRoot` / `gitRoot` / `nodeWorkspaceRoot`), the
+  config-then-git discovery ladder, the CLI-boundary discovery rule, the
+  per-command policy matrix, and the loud-cwd fallback contract. Every
+  command's `Requirements:` help block links to this doc.
+
+### Removed
+
+- `findConfigPath`, `findConfigFile` (from `packages/resources/src/config-parser.ts`),
+  `findGoverningConfig`, `resetGoverningConfigCache`. Use `findConfigFile`
+  from `@vibe-agent-toolkit/utils` for config discovery, and `findProjectRoot`
+  + `loadConfigCached` for root + config loading at CLI boundaries. Cache
+  resets: `resetGoverningConfigCache()` → `resetProjectRootCaches() +
+  resetLoadedConfigCache()`.
+
+### Performance
+
+- **`vat audit` is faster on large scan targets.** Per-skill `projectRoot`
+  lookup now hits a module-level cache pre-warmed during the scan descent, so
+  large multi-skill audits no longer repeat filesystem walk-ups per skill.
+
+### Fixed
+
+- **Markdown links to directories now surface as `broken_file`.** Previously, links resolving to an existing directory (e.g., `/docs/`, `../`, or any href whose resolved path is a directory rather than a file) silently passed validation. They now emit `broken_file` with `Link target is a directory: <path>` and a suggestion to link to a file inside the directory.
+
+- **Leading-`/` links no longer false-flag as path-traversal escapes when the project root traverses a symlink.** `isWithinProject` now canonicalizes both sides of the within-check symmetrically (via `realpathSync`). Previously, when `projectRoot` was a symlinked path — common on macOS (`/tmp` → `/private/tmp`), bind mounts, and CI containers — a legitimate `/foo.md` resolution to `projectRoot/foo.md` was incorrectly reported as `absolute_escapes_root` because only the file side was realpath'd. The same fix also corrects the latent identical bug in the pre-existing gitignore-safety gate of `validateLocalFile`.
+
+- **`vat claude plugin install` post-install hints now point to the correct Claude Code slash command.** Both the standard and `--dev` install paths previously suggested `/reload-skills`, which is not a registered Claude Code CLI command — the real one is `/reload-plugins`. Docs (`packages/cli/docs/skills.md`, `docs/guides/distributing-vat-skills.md`, plugin READMEs, `vat-example-cat-agents` distribution doc) updated to match.
+
+- **`vat resources validate` no longer floods stderr with `unknown format
+  "uri-reference" ignored` warnings.** Ajv's default vocabulary doesn't
+  include URI-family formats; with `format: uri-reference` first-class in
+  frontmatter, the validator used to log one warning per occurrence (often 20+
+  per validate run). The validator now registers `ajv-formats` against its
+  Ajv instance, which silences the warnings without changing semantics — VAT's
+  own walker validates URI-ref hrefs against `resolveLocalHref`, not Ajv's
+  format definitions. Adopter-surfaced cleanup.
+
 ## [0.1.37] - 2026-05-16
 
 ### Fixed

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

@@ -1,7 +1,7 @@
 {
   "license": "MIT",
   "name": "vibe-agent-toolkit",
-  "version": "0.1.37",
+  "version": "0.1.39-rc.1",
   "author": {
     "name": "vibe-agent-toolkit contributors"
   },

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-adoption-and-configuration/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: vat-adoption-and-configuration
-description: Use when starting a new VAT project, adding VAT to an existing repo, or orienting to `vibe-agent-toolkit.config.yaml`. Covers project setup, repo structure, package.json wiring, vibe-validate integration, and the npm postinstall hook.
+description: Use when starting a new VAT project, adding VAT to an existing
+  repo, or orienting to `vibe-agent-toolkit.config.yaml`. Covers project setup,
+  repo structure, package.json wiring, vibe-validate integration, and the npm
+  postinstall hook.
 ---
 
 # VAT Adoption and Configuration

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

@@ -1,6 +1,9 @@
 ---
 name: vat-agent-authoring
-description: Use when authoring TypeScript portable agents — agent archetypes, agent.yaml, result envelopes, orchestration patterns, and runtime adapters (Vercel/LangChain/OpenAI/Claude Agent SDK). Paired with vat-skill-authoring for the SKILL.md side.
+description: Use when authoring TypeScript portable agents — agent archetypes,
+  agent.yaml, result envelopes, orchestration patterns, and runtime adapters
+  (Vercel/LangChain/OpenAI/Claude Agent SDK). Paired with vat-skill-authoring
+  for the SKILL.md side.
 ---
 
 # VAT Agent Authoring: Archetypes, Envelopes, Orchestration

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

@@ -1,6 +1,9 @@
 ---
 name: vat-audit
-description: Use when running vat audit to validate Claude plugins, agent skills, or marketplaces. Covers the audit command, --compat flag for surface compatibility analysis, --exclude for noise filtering, and interpreting audit output.
+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.
 ---
 
 # VAT Audit: Validating Plugins, Skills & Marketplaces

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-enterprise-org/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: vat-enterprise-org
-description: Use for Anthropic Enterprise/Team org administration via the Admin API — user management, API-key auditing, cost/usage reporting, workspace admin, and enterprise skill distribution. Requires ANTHROPIC_ADMIN_API_KEY.
+description: Use for Anthropic Enterprise/Team org administration via the Admin
+  API — user management, API-key auditing, cost/usage reporting, workspace
+  admin, and enterprise skill distribution. Requires ANTHROPIC_ADMIN_API_KEY.
 ---
 
 # Claude Org Administration

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-knowledge-resources/SKILL.md

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

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

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

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

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

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

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

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

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

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

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

package/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 [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 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 \`packages/agent-schema/src/validation-codes.ts\` (the \`CODE_REGISTRY\`) with default severity, description, fix hint, and a \`reference\` anchor into \`docs/validation-codes.md\`\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 [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."
+    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 \`packages/agent-schema/src/validation-codes.ts\` (the \`CODE_REGISTRY\`) with default severity, description, fix hint, and a \`reference\` anchor into \`docs/validation-codes.md\`\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 \`packages/agent-schema/src/validation-codes.ts\` (the \`CODE_REGISTRY\`) with default severity, description, fix hint, and a \`reference\` anchor into \`docs/validation-codes.md\`\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",