@vibe-agent-toolkit/vat-development-agents 0.1.32-rc.3 → 0.1.32-rc.5

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

@@ -18,8 +18,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`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`.
+- 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:
+  - `SKILL_DESCRIPTION_OVER_CLAUDE_CODE_LIMIT` (warning): description > 250 chars — Claude Code's `/skills` listing truncation limit since v2.1.86.
+  - `SKILL_DESCRIPTION_FILLER_OPENER` (warning): description opens with `This skill...`, `A skill that...`, `Used to...`, `Use when you want to...`, or `Use when you need to...`.
+  - `SKILL_DESCRIPTION_WRONG_PERSON` (warning): description uses first- or second-person voice (Anthropic: "Always write in third person").
+  - `SKILL_NAME_MISMATCHES_DIR` (warning): frontmatter `name` differs from the parent directory name.
+  - `SKILL_TIME_SENSITIVE_CONTENT` (info): body contains `as of <month> <year>`, `after <month> <year>`, etc. — will go stale.
+- `vat audit` and `vat skills validate` now print a checklist-discovery footer when skill-level findings are present, pointing at the `vat-skill-review` skill for rationale and judgment-call items.
+- **`vat skill review <path>` command**: deep-review a single skill. Combines `validateSkillForPackaging` output, config-aware compat verdicts (when inside a VAT project), and a manual-checklist walkthrough into one report. Groups automated findings by checklist section (Naming / Description / Body structure / References / Frontmatter hygiene / Compatibility). Supports `--yaml` for machine-readable output. Designed as a thin composition over existing primitives, not a new validation pipeline.
+- **MCP interpreter observations**: the `.mcp.json` scanner's `MCP_SERVER_COMMAND` evidence now rolls up into a `CAPABILITY_EXTERNAL_CLI` observation when the command is a python interpreter (`python`, `python3`, `python3.11`, absolute paths) or a node interpreter (`node`, `nodejs`, absolute paths). Closes the gap where python3-MCP plugins produced no capability signal and verdicts couldn't fire against them. Bespoke commands (e.g. `./scripts/my-server.sh`) remain un-rolled-up by design.
+- **`RESERVED_WORD_IN_NAME` (warning)** — code-registry-framework replacement for the legacy non-overridable error `SKILL_NAME_RESERVED_WORD`. Fires when a skill frontmatter `name` contains `anthropic` or `claude` (reserved for Anthropic's certified skills). Overridable via `validation.severity` / `validation.allow` like any other framework code. Per the skill-smell philosophy, reserved-word naming is a fix-before-publish smell, not a genuine build breaker, so default severity is `warning`.
 
 ### Changed
+- **`vibe-agent-toolkit` plugin restructured into 10 sub-skills + a router.** Each sub-skill now has a sharp single responsibility and a name that aligns with its CLI command. Published skill names changed:
+  - `resources` → `vat-knowledge-resources`
+  - `distribution` → `vat-skill-distribution`
+  - `authoring` → split into `vat-skill-authoring` (SKILL.md authoring) and `vat-agent-authoring` (TypeScript agents)
+  - `org-admin` → `vat-enterprise-org` (also avoids the reserved word `claude` in the previous filename)
+  - `audit` → `vat-audit`
+  - `skill-quality-checklist` → `vat-skill-review` (now a first-class skill, no longer transcluded)
+  - New: `vat-adoption-and-configuration`, `vat-skill-authoring`, `vat-rag`
+  - Root `SKILL.md` (`vibe-agent-toolkit`) is now a thin discovery router (~60 lines, prose references to sub-skills only, no transclusion).
+  - Pre-1.0: no backwards-compatibility shims for the old skill names. Adopters with pinned references to the old names should update to the new ones.
+- **Contributor-only reference docs moved out of the plugin** to `docs/contributing/` (`vat-debugging.md`, `vat-install-architecture.md`). These are not installed with the plugin — they're for people working on VAT itself.
+- Shortened over-limit descriptions on three VAT development-agent skills (renamed above: `vat-enterprise-org`, `vat-skill-distribution`) to stay under Claude Code's 250-character truncation limit.
 - **BREAKING: Runtime target rename.** `claude-desktop` → `claude-chat`, `cowork` → `claude-cowork`. Update `plugin.json`, `marketplace.json`, and any config references. The `claude-desktop` name was architecturally wrong — Claude Desktop is a host application, not a runtime.
 - **BREAKING: `runCompatDetectors` returns `DetectorOutput { evidence, observations }`** instead of `ValidationIssue[]`. The skill-validator converts observations to issues via `observationToIssue`; external callers must do the same or consume observations directly.
 - **BREAKING: `CompatibilityResult` restructured.** Old shape: `{ declared, analyzed: Record<Target, Verdict>, evidence: CompatibilityEvidence[] }`. New: `{ declaredTargets, evidence: EvidenceRecord[], observations: Observation[], verdicts: Verdict[] }`.
@@ -27,7 +51,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 - `vat audit --compat` now honors config-layer `targets` declared in `vibe-agent-toolkit.config.yaml`, matching `vat skills validate` verdicts inside a VAT project. Previously only `plugin.json` / `marketplace.json` targets flowed into plugin-level compat analysis. Multi-skill plugins use the union of every in-plugin skill's targets.
-- `skill-quality-checklist.md`: description-opener rule no longer contradicts Anthropic's official skill-description guidance. `Use when <concrete trigger>` is now explicitly allowed (it's the recommended pattern); only vague filler like `Use when you want to...` / `Use when you need to...` is banned. Prior wording banned all `Use when...` openers, which contradicted VAT's own authoring guidance.
+- `vat-skill-review.md` (formerly `skill-quality-checklist.md`): description-opener rule no longer contradicts Anthropic's official skill-description guidance. `Use when <concrete trigger>` is now explicitly allowed (it's the recommended pattern); only vague filler like `Use when you want to...` / `Use when you need to...` is banned. Prior wording banned all `Use when...` openers, which contradicted VAT's own authoring guidance.
+- `readMarketplaceDefaultTargets()` now walks upward from the starting directory to find the enclosing `.claude-plugin/marketplace.json`, instead of only checking the parent directory. Canonical layouts (`~/.claude/plugins/marketplaces/<m>/<p>/`) still work identically; deeper nested layouts now resolve correctly. Safeguarded against runaway walks by max depth (10 levels) and `node_modules` / `.git` boundaries. Closes limitation #1 from the 0.1.32-rc.1 plan Outcome.
+- **`vat audit` now walks to the nearest config per SKILL.md** instead of loading a single top-level config. In monorepos with per-package `vibe-agent-toolkit.config.yaml` files (e.g. `packages/<pkg>/vibe-agent-toolkit.config.yaml`), each skill's validation now honors its own package's config — eliminating cross-package config bleed where a root config was silently applied to skills owned by other packages.
+- **`vat audit` now honors `resources.exclude` from the config.** Previously the `exclude` list in the `resources` section only affected `vat resources validate`; audit ignored it and reported findings against files the author had explicitly opted out of validation for.
+- **`vat skill review <path>` accepts single-file skills** (any `.md` file), not just `SKILL.md` inside a directory. Useful when reviewing loose skill drafts or checklist-style skills that don't live in a dedicated directory.
+- **`SKILL_NAME_MISMATCHES_DIR` false positive:** the mismatch check no longer fires when `SKILL.md` lives directly inside a generic container directory (`skills/`, `resources/`). The parent directory name in those layouts carries no signal about what the skill is named.
+- Three directory-targeted markdown links in VAT docs (`CLAUDE.md`, `docs/README.md`, `docs/getting-started.md`) now point at specific files, silencing the corresponding `LINK_TARGETS_DIRECTORY` errors on VAT's own docs.
 
 ### Removed
 - **BREAKING:** `COMPAT_REQUIRES_BROWSER_AUTH`, `COMPAT_REQUIRES_LOCAL_SHELL`, `COMPAT_REQUIRES_EXTERNAL_CLI` codes (replaced by `CAPABILITY_*` + `COMPAT_TARGET_*`).

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

@@ -1,7 +1,7 @@
 {
   "name": "vibe-agent-toolkit",
   "description": "Development agents and skills for building with vibe-agent-toolkit",
-  "version": "0.1.32-rc.3",
+  "version": "0.1.32-rc.5",
   "author": {
     "name": "vibe-agent-toolkit contributors"
   }

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

@@ -0,0 +1,179 @@
+---
+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.
+---
+
+# VAT Adoption and Configuration
+
+This skill covers the top-level orientation for adopting VAT in a project: installing the CLI, the overall shape of `vibe-agent-toolkit.config.yaml`, repo structure conventions, vibe-validate integration, and how npm postinstall wires plugin registration. Per-section deep-dives live in the sibling skills listed below.
+
+## Installing VAT
+
+VAT ships as the `vibe-agent-toolkit` npm package with a `vat` CLI:
+
+```bash
+# Global install (most common during development)
+npm install -g vibe-agent-toolkit
+
+# Or run without installing
+npx vibe-agent-toolkit <command>
+bunx vibe-agent-toolkit <command>
+
+# As a runtime dependency (recommended for published packages that ship skills)
+npm install --save vibe-agent-toolkit
+```
+
+Once installed, `vat --help` lists the top-level command groups. `vat <group> --help` and `vat <group> <cmd> --help --verbose` cover the rest.
+
+## Recommended Repo Structure
+
+```
+my-skills-project/
+├── package.json                        # includes "vat" block (see below)
+├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT
+├── resources/
+│   ├── skills/                         # SKILL.md sources
+│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)
+│   │   └── my-skill.md
+│   └── content/                        # non-skill markdown (RAG, collections)
+├── agents/                             # TypeScript portable agents (optional)
+│   └── my-agent/
+│       ├── agent.yaml
+│       └── src/
+├── schemas/                            # JSON Schemas for resource collections
+├── docs/                               # project documentation
+└── dist/                               # generated (gitignored): vat build output
+```
+
+Three conventions are load-bearing:
+
+1. **`vibe-agent-toolkit.config.yaml` at the project root** — VAT walks upward from the invocation directory to find it.
+2. **SKILL.md files live under `resources/skills/`** — any path works, but this one is what `vat build` and `vat audit` expect by default.
+3. **`dist/` is the only write target** — everything VAT generates goes there, and it's gitignored.
+
+## `vibe-agent-toolkit.config.yaml` Shape
+
+```yaml
+version: 1
+
+skills:
+  include: ["resources/skills/SKILL.md", "resources/skills/*.md"]
+  defaults:
+    linkFollowDepth: 2
+    excludeNavigationFiles: true
+    targets: ['claude-code']
+  config:
+    my-skill:
+      linkFollowDepth: 1
+
+resources:
+  collections:
+    docs:
+      include: ["docs/**/*.md"]
+      validation:
+        frontmatterSchema: "schemas/doc.schema.json"
+        mode: permissive
+
+claude:
+  marketplaces:
+    my-marketplace:
+      owner: { name: "my-org" }
+      publish:
+        changelog: CHANGELOG.md
+        readme: README.md
+      plugins:
+        - name: my-plugin
+          description: "What this plugin does"
+          skills: "*"
+
+rag:
+  stores:
+    default:
+      db: .rag-db/
+      include: ["docs/**/*.md"]
+```
+
+Sections and the skills that own their details:
+
+| Section | Owning skill |
+|---|---|
+| Top-level structure, `version`, section orientation | this skill (`vat-adoption-and-configuration`) |
+| `skills:` (include, defaults, per-skill config, packagingOptions) | `vibe-agent-toolkit:vat-skill-authoring` |
+| `resources:` (collections, schemas, validation modes) | `vibe-agent-toolkit:vat-knowledge-resources` |
+| `claude:` (marketplaces, plugins, publish, owner) | `vibe-agent-toolkit:vat-skill-distribution` |
+| `rag:` (stores, embedding providers) | `vibe-agent-toolkit:vat-rag` |
+
+When adding to a section, load the owning skill rather than re-deriving the shape from this file.
+
+## `package.json` Wiring
+
+For projects that publish skills via npm, three fields tie VAT into the npm lifecycle:
+
+```json
+{
+  "name": "@myorg/my-skills",
+  "dependencies": {
+    "vibe-agent-toolkit": "latest"
+  },
+  "scripts": {
+    "build": "vat build",
+    "postinstall": "vat claude plugin install --npm-postinstall || exit 0"
+  },
+  "vat": {
+    "skills": ["my-skill-one", "my-skill-two"]
+  }
+}
+```
+
+- **`dependencies.vibe-agent-toolkit`** — runtime dep, not dev. Needed so the postinstall hook can find `vat`.
+- **`scripts.postinstall`** — registers the built plugin into the user's `~/.claude/plugins/` tree after `npm install -g` or any install that runs lifecycle scripts. The `|| exit 0` keeps `npm install` from aborting if the hook can't run (unusual but defensive).
+- **`vat.skills`** — declares which skill names this package ships. `vat verify` cross-checks this list against `skills.include` in `vibe-agent-toolkit.config.yaml`; mismatches fire `PACKAGE_JSON_LISTS_UNKNOWN_SKILL` / `PACKAGE_JSON_MISSING_SKILL`. The list is a packaging contract with npm, not a build input — `vat build` discovers skills from the config globs.
+
+The full distribution pipeline (build, verify, npm publish, marketplace layout, managed settings) lives in `vibe-agent-toolkit:vat-skill-distribution`.
+
+## vibe-validate Integration
+
+If the project uses vibe-validate (recommended), wire VAT into the validation config:
+
+```yaml
+# vibe-validate.config.yaml (or relevant section)
+phases:
+  - name: vat-build-and-verify
+    parallel: false
+    commands:
+      - name: vat build
+        run: vat build
+      - name: vat verify
+        run: vat verify
+```
+
+`vat verify` runs the full artifact check (resources → skills → marketplace → consistency); it's the authoritative gate before `npm publish`. In this repo's own config, `bun run validate` already does this — adopters typically mirror the pattern.
+
+## First-Time Setup Checklist
+
+1. `npm install -g vibe-agent-toolkit` (or add to local deps)
+2. `vat --help` — confirm the CLI resolves
+3. Create `vibe-agent-toolkit.config.yaml` with the minimal `version: 1` plus the sections you need
+4. Add `resources/skills/SKILL.md` or a kebab-case SKILL.md file and stage it in git (the skill discovery crawler uses `git ls-files` by default — untracked new files are skipped)
+5. `vat skills validate` — report any issues before building
+6. `vat build` — produces `dist/` artifacts
+7. `vat verify` — full consistency check; should be a no-op when clean
+8. If publishing: add the `vat.skills`, `scripts.postinstall`, and `dependencies.vibe-agent-toolkit` entries in `package.json` before `npm publish`
+
+## When Things Are Off
+
+- **"No skills section in config yaml"** — either the file isn't at the project root, or `skills.include` is missing.
+- **"Found 0 skills"** — glob doesn't match any SKILL.md files. Confirm the path and that the files are tracked by git (VAT's discovery respects `.gitignore` and `git ls-files`).
+- **`PACKAGE_JSON_LISTS_UNKNOWN_SKILL`** — `vat.skills` mentions a name not produced by `skills.include` discovery. Either add the file or remove the name.
+- **`vat audit` fires unexpected warnings** — load `vibe-agent-toolkit:vat-audit` for the full audit surface, including `--compat` and `--exclude` flags.
+
+## References
+
+- `vibe-agent-toolkit:vat-skill-authoring` — SKILL.md frontmatter, body structure, references, packagingOptions
+- `vibe-agent-toolkit:vat-agent-authoring` — TypeScript agent archetypes and runtime adapters
+- `vibe-agent-toolkit:vat-skill-distribution` — `vat build` / `vat verify` / marketplace / npm publish
+- `vibe-agent-toolkit:vat-knowledge-resources` — `resources:` collections and frontmatter schemas
+- `vibe-agent-toolkit:vat-rag` — `rag:` stores, embedding providers, `vat rag index/query`
+- `vibe-agent-toolkit:vat-audit` — `vat audit` for plugins, marketplaces, and installed skills
+- `vibe-agent-toolkit:vat-skill-review` — pre-publication quality checklist
+- Getting Started Guide — full setup walkthrough

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

@@ -1,34 +1,11 @@
 ---
-name: authoring
-description: Use when authoring SKILL.md files, designing agent architectures, or configuring packaging options. Covers SKILL.md structure, agent archetypes, orchestration patterns, and validation override patterns.
+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.
 ---
 
-# VAT Agent Authoring: SKILL.md, Archetypes & Patterns
+# VAT Agent Authoring: Archetypes, Envelopes, Orchestration
 
-## SKILL.md Structure
-
-A SKILL.md file is the definition file for a VAT agent skill. It tells Claude what the skill
-does and how to use it. All SKILL.md files must have YAML frontmatter:
-
-```markdown
----
-name: my-skill
-description: One sentence: what this skill does and when to use it (max 200 chars)
----
-
-# My Skill
-
-Rest of the skill documentation...
-```
-
-Required frontmatter fields:
-- `name` — unique identifier, kebab-case, matches the skill's directory name
-- `description` — trigger description used for skill routing; be specific about activation conditions
-
-Best practices for `description`:
-- Start with "Use when..." to make activation conditions explicit
-- Include the key commands or concepts the skill covers
-- Keep under 200 characters
+This skill covers authoring TypeScript portable agents — the runtime side of a VAT agent package. For SKILL.md authoring (frontmatter, body structure, references, packagingOptions, validation overrides) use `vibe-agent-toolkit:vat-skill-authoring`.
 
 ## Agent Archetypes
 
@@ -138,10 +115,10 @@ type StatefulAgentResult<TData, TError, TMetadata> =
   | { status: 'error'; error: TError };
 ```
 
-Standard LLM error literals: `'llm-refusal'`, `'llm-invalid-output'`, `'llm-timeout'`,
-`'llm-rate-limit'`, `'llm-token-limit'`, `'llm-unavailable'`.
+Standard LLM error literals: `'llm-refusal'`, `'llm-invalid-output'`, `'llm-timeout'`, `'llm-rate-limit'`, `'llm-token-limit'`, `'llm-unavailable'`.
 
 Always check status before accessing data:
+
 ```typescript
 const output = await myAgent.execute(input);
 if (output.result.status === 'success') {
@@ -236,100 +213,6 @@ while (true) {
 }
 ```
 
-## packagingOptions Reference
-
-Configure in your skill's `vat.skills[]` entry in `package.json`:
-
-```json
-{
-  "vat": {
-    "skills": [{
-      "name": "my-skill",
-      "source": "./SKILL.md",
-      "path": "./dist/skills/my-skill",
-      "packagingOptions": {
-        "linkFollowDepth": 1,
-        "resourceNaming": "resource-id",
-        "stripPrefix": "knowledge-base",
-        "excludeReferencesFromBundle": {
-          "rules": [
-            { "patterns": ["**/concepts/**"], "template": "Use search to find: {{link.text}}" }
-          ],
-          "defaultTemplate": "{{link.text}} (search knowledge base)"
-        }
-      }
-    }]
-  }
-}
-```
-
-**`linkFollowDepth`** — How deep to follow links from SKILL.md:
-
-| Value | Behavior |
-|-------|----------|
-| `0` | Skill file only (no links followed) |
-| `1` | Direct links only |
-| `2` | Direct + one transitive level **(default)** |
-| `"full"` | Complete transitive closure |
-
-**`resourceNaming`** — How bundled files are named:
-
-| Strategy | Example | Use When |
-|----------|---------|----------|
-| `basename` | `overview.md` | Few files, unique names **(default)** |
-| `resource-id` | `topics-quickstart-overview.md` | Many files, flat output |
-| `preserve-path` | `topics/quickstart/overview.md` | Preserve structure |
-
-Use `stripPrefix` to remove a common directory prefix (e.g., `"knowledge-base"`).
-
-**`excludeReferencesFromBundle`** — Rules for excluding files and rewriting their links:
-- `rules[]` — Ordered glob patterns (first match wins), each with optional Handlebars template
-- `defaultTemplate` — Applied to depth-exceeded links not matching any rule
-
-**Template variables:**
-
-| Variable | Description |
-|----------|-------------|
-| `{{link.text}}` | Link display text |
-| `{{link.href}}` | Original href (without fragment) |
-| `{{link.fragment}}` | Fragment including `#` prefix, or empty |
-| `{{link.type}}` | Link type (`"local_file"`, etc.) |
-| `{{link.resource.id}}` | Target resource ID (if resolved) |
-| `{{link.resource.fileName}}` | Target filename (if resolved) |
-| `{{skill.name}}` | Skill name from frontmatter |
-
-**`validation`** — Unified framework for overriding default severity and allowing specific issue instances:
-
-```yaml
-# In vibe-agent-toolkit.config.yaml under skills.defaults or skills.config.<name>
-validation:
-  severity:
-    LINK_DROPPED_BY_DEPTH: error           # upgrade: block on depth-dropped links
-    LINK_TO_NAVIGATION_FILE: ignore        # silence: this skill intentionally links to READMEs
-  allow:
-    PACKAGED_UNREFERENCED_FILE:
-      - paths: ["templates/runtime.json"]
-        reason: "consumed programmatically at runtime"
-        expires: "2026-09-30"
-    SKILL_LENGTH_EXCEEDS_RECOMMENDED:
-      - reason: "whole-skill concern; paths defaults to ['**/*']"
-```
-
-Two sub-keys, each covering a different override granularity:
-
-- **`severity`** — Class-level. Raise any code to `error` (blocks build), lower to `warning` (emits, non-blocking), or `ignore` (fully suppressed). Applies to every instance of that code.
-- **`allow`** — Per-instance. Suppress specific `(code, path)` matches with a required `reason` and optional `expires` date. `paths` is optional (defaults to `["**/*"]` — the whole skill). Use for legitimate exceptions that don't warrant code-wide silencing.
-
-Things adopters typically adjust:
-
-- Downgrade `LINK_DROPPED_BY_DEPTH` to `ignore` when intentionally linking out to external docs.
-- Allow specific files under `PACKAGED_UNREFERENCED_FILE` when they're consumed programmatically by CLI scripts at runtime.
-- Raise `ALLOW_EXPIRED` to `error` for zero-tolerance expiry policies.
-
-Expired `allow` entries still apply — VAT emits `ALLOW_EXPIRED` as a reminder rather than silently re-surfacing the underlying issue (no surprise build breaks when a date passes). Unused `allow` entries surface as `ALLOW_UNUSED` (analogous to ESLint's unused-disable).
-
-Full code reference at `docs/validation-codes.md`. `vat audit` is advisory: it applies `severity` for display grouping only, ignores `allow`, and always exits 0. Use `vat skills validate` or `vat skills build` for gated checks.
-
 ## Testing Agents
 
 ### Unit Testing Pure Functions
@@ -376,19 +259,18 @@ const output2 = await agent.execute({
 
 ## Best Practices
 
-1. **Return result envelopes, never throw** for expected errors
-2. **Define error types as literal unions** (`'invalid-format' | 'timeout'`) not `string`
-3. **Use Zod schemas** for all input/output validation
-4. **Test all paths** — success, each error type, edge cases
-5. **Use mock mode** for external dependencies to enable offline testing
-6. **Document with JSDoc** — purpose, params, return type, example, `@throws Never throws`
-7. **Keep SKILL.md focused** — if it exceeds ~300 lines, split into action skills
+1. **Return result envelopes, never throw** for expected errors.
+2. **Define error types as literal unions** (`'invalid-format' | 'timeout'`), not `string`.
+3. **Use Zod schemas** for all input/output validation.
+4. **Test all paths** — success, each error type, edge cases.
+5. **Use mock mode** for external dependencies to enable offline testing.
+6. **Document with JSDoc** — purpose, params, return type, example, `@throws Never throws`.
+7. **Keep SKILL.md focused** — if the skill documentation exceeds ~300 lines, split the skill or use progressive disclosure (see `vibe-agent-toolkit:vat-skill-authoring`).
 
 ## References
 
-- Skill Quality and Compatibility — VAT's Stance — what VAT believes makes a skill good and compatible, and how those beliefs turn into validation codes. Read this before overriding severity defaults or adding allow entries.
-- Validation Codes Reference — full list of codes VAT emits, their default severity, and override recipes.
-- [Skill Quality Checklist](resources/skill-quality-checklist.md) — Pre-publication checklist for all skills (general + CLI-backed)
+- `vibe-agent-toolkit:vat-skill-authoring` — sibling skill covering SKILL.md frontmatter, body structure, references, packagingOptions, and validation overrides
+- `vibe-agent-toolkit:vat-skill-review` — pre-publication quality checklist
 - agent-authoring.md — Complete patterns guide
 - orchestration.md — Multi-agent workflows
-- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents)
+- [Building Effective Agents — Anthropic](https://www.anthropic.com/research/building-effective-agents)

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

@@ -1,5 +1,5 @@
 ---
-name: audit
+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.
 ---
 

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

@@ -1,6 +1,6 @@
 ---
-name: org-admin
-description: Anthropic org administration for Enterprise/Team admins. Requires ANTHROPIC_ADMIN_API_KEY. Use for org user management, API key auditing, cost/usage reporting, workspace administration, and enterprise skill distribution via the Anthropic Admin API. Not for regular users — admin access required.
+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.
 ---
 
 # Claude Org Administration

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

@@ -1,5 +1,5 @@
 ---
-name: resources
+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.
 ---
 

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

@@ -0,0 +1,104 @@
+---
+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.
+---
+
+# VAT RAG: Indexing and Querying Markdown with Native Providers
+
+This skill covers VAT's RAG (retrieval-augmented generation) surface: the `vat rag` CLI commands, the embedding and vector-store providers that ship natively, and how to extend either side. For authoring the markdown that gets indexed (frontmatter schemas, collections) use `vibe-agent-toolkit:vat-knowledge-resources`.
+
+## CLI Commands
+
+```bash
+# Index markdown into a local vector DB (default: .rag-db/)
+vat rag index docs/
+
+# Ask a natural-language question; returns the top chunks with file paths and heading context
+vat rag query "How do I configure agent tools?"
+
+# Inspect the current index
+vat rag stats
+```
+
+`vat rag index` reads `vibe-agent-toolkit.config.yaml` when no path argument is given and respects the `rag` section for per-store configuration (multiple indices, content transforms, metadata schemas).
+
+```bash
+# Multi-store: index separate databases for different corpora
+vat rag index --db ./dist/rag-en docs/en/
+vat rag index --db ./dist/rag-fr docs/fr/
+
+# Query a specific database
+vat rag query "installation" --db ./dist/rag-en
+```
+
+See `vat rag --help` for the full flag surface and `docs/guides/rag-usage-guide.md` for end-to-end configuration examples.
+
+## What Ships Natively
+
+VAT's `@vibe-agent-toolkit/rag` package provides the core interfaces and a small set of ready-to-use providers. The goal is "works out of the box" for common cases, with clean extension points for everything else.
+
+### Embedding providers
+
+| Provider | Model | Where it runs |
+|---|---|---|
+| `TransformersEmbeddingProvider` | `Xenova/all-MiniLM-L6-v2` (default) | Local, via `transformers.js` — no API key, CPU inference |
+| `OpenAIEmbeddingProvider` | `text-embedding-3-small` (default) | OpenAI API — requires `OPENAI_API_KEY` |
+
+Both implement the `EmbeddingProvider` interface (`name`, `model`, `dimensions`, `embed(text)`, `embedBatch(texts)`), so the rest of the RAG pipeline doesn't care which one is wired in.
+
+### Vector store
+
+- `@vibe-agent-toolkit/rag-lancedb` — native LanceDB-backed store, lives on disk under `.rag-db/` by default. Supports approximate-nearest-neighbor search, metadata filtering, and incremental re-indexing.
+
+### Chunking and metadata
+
+- Hybrid heading-based + token-aware chunking via `chunkMarkdown`, integrated with `ResourceRegistry` so chunks inherit file-level metadata.
+- `DefaultRAGMetadata` — sensible defaults for markdown docs (filePath, tags, type, headingPath, sourceUrl, etc.).
+- Custom metadata — extend `DefaultRAGMetadataSchema` or replace it entirely. Use `createCustomRAGChunkSchema(MySchema)` to get type-safe chunks through the whole pipeline.
+
+### Token counters
+
+- `FastTokenCounter` — bytes/4 heuristic, zero-cost.
+- `ApproximateTokenCounter` — `gpt-tokenizer`-backed, closer to reality for OpenAI-style models.
+
+## Extension Points
+
+The RAG interfaces are small on purpose. If something isn't supported natively, implement the interface in your own package:
+
+- **Embedding provider** — implement `EmbeddingProvider` (cohere, Voyage, local LLM endpoints, etc.). Register via config or pass directly to `RAG.open({ embedding: myProvider })`.
+- **Vector store** — implement `RAGQueryProvider` + `RAGAdminProvider` (pgvector, Pinecone, Qdrant, ChromaDB, etc.). The `@vibe-agent-toolkit/rag-lancedb` package is the reference implementation; mirror its shape.
+- **Content transform** — hook into the chunking pipeline to rewrite markdown (e.g. strip HTML comments, expand templates) before it hits the embedder.
+- **Custom metadata** — ship your own Zod schema and thread it through the CLI via config.
+
+**Contributions welcome**: native support for additional embedding providers and vector stores is on the roadmap. If you've written a clean implementation of the RAG interfaces for another backend, open a PR — the target is a small, curated set of "we ship and test these" providers, with everything else available as community packages.
+
+## Configuration
+
+```yaml
+version: 1
+
+rag:
+  stores:
+    default:
+      db: .rag-db/
+      include: ["docs/**/*.md"]
+      exclude: ["docs/drafts/**"]
+      embedding:
+        provider: transformers-js          # or: openai
+        model: Xenova/all-MiniLM-L6-v2     # embedding-specific
+```
+
+Per-store configuration keeps multi-corpus projects (multilingual docs, product-vs-support splits) legible.
+
+## Troubleshooting
+
+- `vat rag query` returns empty: confirm `vat rag stats` shows non-zero chunks; re-run `vat rag index` after adding content.
+- Slow first index with `transformers-js`: the model downloads on first use and caches under `~/.cache/transformers`.
+- Drift between indexed content and live docs: re-index. LanceDB supports delete-by-filter, so `vat rag index --rebuild` for the specific store is safe.
+
+## References
+
+- `vibe-agent-toolkit:vat-knowledge-resources` — markdown collections and frontmatter schema validation (the content side)
+- RAG Usage Guide — configuration walkthroughs for single-store, multi-store, and custom metadata
+- Embedding Providers — provider deep-dive and how to write new ones
+- @vibe-agent-toolkit/rag — package README with the full interface reference