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

package/dist/skills/{distribution → vat-skill-distribution}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: distribution
+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.
 ---
 
@@ -12,7 +12,8 @@ This is the only install method VAT currently supports.
 
 For the full install landscape — Claude Desktop paths, enterprise CI deployment,
 Anthropic Cloud org management, MDM integration, and the `vat plugins uninstall`
-design — see [Install & Uninstall Architecture](resources/vat-install-architecture.md).
+design — see the contributor reference at `docs/contributing/vat-install-architecture.md`
+in the `vibe-agent-toolkit` repo (contributor material, not bundled with this skill).
 
 ## Overview
 

package/dist/{.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/authoring/resources/skill-quality-checklist.md → skills/vat-skill-review/SKILL.md}

@@ -1,7 +1,22 @@
-# Skill Quality Checklist
+---
+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.
+---
+
+# Skill Quality Checklist (vat skill review)
 
 Work through this checklist before publishing a skill. Items are grouped into general (all skills) and CLI-backed (skills that bundle and invoke scripts).
 
+This content is also surfaced by the `vat skill review` CLI command, which formats the checklist around a specific skill's validation output.
+
+## Guidance freshness
+
+Skill authoring standards move fast. Before applying this checklist to a non-trivial change:
+
+- Re-fetch the source of `docs/external/anthropic-skill-authoring-best-practices.md` named in its preamble. If the content has shifted, update the cache and this checklist together.
+- Web search for the latest Claude Code release notes when trigger semantics, frontmatter rules, or packaging behavior may have changed. Don't rely on training-data recall.
+- Promote any manual item below to a programmatic validator when the pattern is detectable from file contents — see the shift-left notes in `packages/vat-development-agents/resources/skills/CLAUDE.md`.
+
 ## About this checklist
 
 Items fall into two categories:

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

@@ -1,211 +1,62 @@
 ---
 name: vibe-agent-toolkit
-description: Use when building, adopting, or learning vibe-agent-toolkit (VAT). Covers agent creation, CLI commands (vat skills, vat resources, vat audit, vat rag), runtime adapters, skill packaging, and resource validation. Routes to specialized sub-skills.
+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 Skill
+# Vibe Agent Toolkit
 
-**Vibe Agent Toolkit (VAT)** is a modular toolkit for building portable AI agents that work across
-multiple LLM frameworks and deployment targets. Write your agent logic once as plain TypeScript,
-then deploy it to Vercel AI SDK, LangChain, OpenAI, Claude Agent SDK, or any other runtime using
-framework adapters. No vendor lock-in.
+**Vibe Agent Toolkit (VAT)** is a modular toolkit for building, packaging, and distributing portable AI agents and skills that work across multiple Claude surfaces and adjacent frameworks. Write skill or agent content once; VAT handles validation, packaging, plugin/marketplace layout, and npm publishing.
 
-## Purpose: For Users, Not Contributors
-
-- **This skill** = How to USE VAT to build agents
-- **`vibe-agent-toolkit:debugging`** = When VAT itself behaves unexpectedly or you need to test a fix
-- **Root CLAUDE.md** = How to DEVELOP the VAT codebase itself
+This is a router skill. Load the sibling sub-skill that matches the work you're doing — each sub-skill owns one slice of VAT's surface and is designed to be pulled in on demand.
 
 ## When to Use VAT
 
-**VAT is great for:** Multi-framework projects, reusable agent libraries, testing across LLM
-providers, complex multi-agent orchestration, human-in-the-loop workflows.
-
-**VAT may not be needed for:** Simple one-off scripts where the framework is already decided,
-non-TypeScript/JavaScript projects, or cases where you need deep framework-specific features.
+Good fits:
 
-## Skill Routing Table
+- Publishing a Claude skill or plugin to npm with a proper marketplace layout
+- Multi-runtime agent projects (Vercel AI SDK, LangChain, OpenAI, Claude Agent SDK)
+- Validating plugins / skills / marketplaces with `vat audit` before shipping
+- Enforcing frontmatter schemas across large markdown corpora
+- Wiring RAG indexing into an agent project
 
-| If you're working on... | Use this skill |
-|---|---|
-| Writing or structuring a `SKILL.md` file | `vibe-agent-toolkit:authoring` |
-| Agent archetypes, orchestration patterns, result envelopes | `vibe-agent-toolkit:authoring` |
-| `packagingOptions` (linkFollowDepth, excludeReferencesFromBundle) | `vibe-agent-toolkit:authoring` |
-| Resource collections, frontmatter schema validation | `vibe-agent-toolkit:resources` |
-| `vat resources validate`, collection config | `vibe-agent-toolkit:resources` |
-| Setting up `vat build` + `vat claude build` for a project | `vibe-agent-toolkit:distribution` |
-| Configuring `claude:` section in vibe-agent-toolkit.config.yaml | `vibe-agent-toolkit:distribution` |
-| npm publishing with plugin postinstall | `vibe-agent-toolkit:distribution` |
-| `vat build` / `vat verify` orchestration | `vibe-agent-toolkit:distribution` |
-| `--target claude-web` ZIP format | `vibe-agent-toolkit:distribution` |
-| Install/uninstall methods, enterprise deployment, Desktop vs CLI paths | `vibe-agent-toolkit:install` |
-| `vat audit`, `--compat`, CI validation | `vibe-agent-toolkit:audit` |
-| `vat claude org`, Admin API, org users/cost/usage/skills, ANTHROPIC_ADMIN_API_KEY | `vibe-agent-toolkit:org-admin` |
-| VAT behaves unexpectedly, debugging VAT, testing local VAT changes, VAT_ROOT_DIR | `vibe-agent-toolkit:debugging` |
+Poor fits:
 
-## Agent Archetypes (Quick Reference)
+- Simple one-off scripts where the framework is already decided
+- Non-TypeScript/JavaScript projects
+- Cases where you need deep framework-specific features with no reuse goal
 
-Four patterns cover most use cases. For full code examples, see `vibe-agent-toolkit:authoring`.
+## Picking a Sub-skill
 
-| Archetype | When to Use |
+| If you're working on... | Load |
 |---|---|
-| **Pure Function Tool** | Stateless validation, transformation, computation — no LLM needed |
-| **One-Shot LLM Analyzer** | Single LLM call for analysis, classification, or generation |
-| **Conversational Assistant** | Multi-turn dialogue with session state across turns |
-| **External Event Integrator** | Waiting for human approval, webhooks, or third-party APIs |
-
-## Core CLI Commands
-
-```bash
-# Install VAT CLI globally
-npm install -g vibe-agent-toolkit
-
-# Or run without installing (works anywhere vat commands appear below)
-npx vibe-agent-toolkit <command>    # npm/Node.js
-bunx vibe-agent-toolkit <command>   # Bun
-
-# Top-level orchestration
-vat build                                # build all artifacts (skills then claude plugins)
-vat verify                               # verify all artifacts (resources, skills, claude)
-
-# Claude plugin commands
-vat claude build                         # generate plugin artifacts from built skills
-vat claude verify                        # validate plugin artifacts
-
-# Skills
-vat skills list                          # list skills in current project
-vat skills list --user                   # list user-installed skills
-vat skills install npm:@org/my-skills    # install from npm (routes through plugin system)
-vat skills build                         # build portable skills only
-vat skills validate                      # validate skill quality
-
-# Resources
-vat resources validate                   # validate collections (reads config)
-vat resources validate docs/ --frontmatter-schema schema.json
-
-# Audit
-vat audit                                # audit current directory recursively
-vat audit --user                         # audit entire Claude installation
-vat audit ./plugins/ --compat            # check surface compatibility
-
-# RAG
-vat rag index docs/                      # index markdown into vector DB
-vat rag query "my question" --limit 5    # semantic search
-
-# Get help for any command
-vat --help
-vat skills --help
-```
-
-## agent-generator: Creating New Agents
-
-The **agent-generator** is a built-in meta-agent that guides you through designing
-high-quality agents via a 4-phase workflow:
-
-1. **GATHER** — Understand your intent and goals
-2. **ANALYZE** — Identify agent pattern and requirements
-3. **DESIGN** — Make architecture decisions (LLM, tools, prompts)
-4. **GENERATE** — Create validated agent package
-
-Minimum input needed:
-```json
-{
-  "agentPurpose": "Review PRs for security issues",
-  "successCriteria": "Catches 100% of critical vulnerabilities"
-}
-```
-
-The generator produces: `agent.yaml`, `prompts/system.md`, `prompts/user.md`,
-`schemas/input.schema.json`, `schemas/output.schema.json`, and `README.md`.
-
-**Tips for better results:**
-- Be specific about success criteria ("Under 30s, zero false negatives") not vague ("fast enough")
-- Name the tools the agent needs upfront (file readers, APIs, etc.)
-- Describe domain context (OWASP Top 10, company coding standards, etc.)
-
-## Packaging Markdown for Reuse
-
-VAT's resource compiler transforms markdown files into type-safe TypeScript modules,
-enabling prompt libraries, RAG knowledge bases, and shared content across projects.
+| New project setup, `vibe-agent-toolkit.config.yaml` orientation, repo structure, vibe-validate integration, npm postinstall | `vibe-agent-toolkit:vat-adoption-and-configuration` |
+| Writing or revising a SKILL.md — frontmatter, body, references, packagingOptions, validation overrides | `vibe-agent-toolkit:vat-skill-authoring` |
+| TypeScript agent archetypes, `agent.yaml`, result envelopes, orchestration, runtime adapters | `vibe-agent-toolkit:vat-agent-authoring` |
+| `vat audit` on plugins, marketplaces, skills, or settings — including `--compat`, `--exclude`, `--user`, CI use | `vibe-agent-toolkit:vat-audit` |
+| Markdown collections, `resources:` config, frontmatter schema validation, `vat resources validate` | `vibe-agent-toolkit:vat-knowledge-resources` |
+| `vat build`, `vat verify`, plugin/marketplace layout, npm publishing, postinstall | `vibe-agent-toolkit:vat-skill-distribution` |
+| `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` |
+
+## CLI Surface at a Glance
 
 ```bash
-npm install -D @vibe-agent-toolkit/resource-compiler
-npx vat-compile-resources compile resources/ generated/resources/
+vat --help                 # top-level help
+vat build                  # build all artifacts (skills → claude plugins)
+vat verify                 # validate all artifacts
+vat skills validate        # validate skill quality
+vat resources validate     # validate markdown collections
+vat audit                  # audit plugins/skills/marketplaces/settings
+vat rag index docs/        # index markdown for RAG
+vat skill review <path>    # pre-publication review
+vat claude org --help      # enterprise admin surface
 ```
 
-```typescript
-import * as Doc from './generated/resources/doc.js';
-
-Doc.meta.title;                        // type-safe frontmatter
-Doc.fragments.introduction.text;       // H2 section content
-Doc.text;                              // full markdown
-```
-
-Use cases: agent prompt libraries, RAG knowledge bases packaged as npm modules,
-multi-project content sharing with versioning.
-
-## Common Workflows
-
-**Create a new agent:**
-```bash
-# Use agent-generator interactively, then:
-vat agent import my-skill/SKILL.md   # import to VAT format
-vat skills validate                   # check quality
-vat skills build                      # package for distribution
-```
-
-**Install and use a community skill:**
-```bash
-vat skills install npm:@vibe-agent-toolkit/vat-cat-agents
-vat skills list --user
-# Plugin-aware packages register in Claude's plugin system
-# Skills are invoked as /plugin-name:skill-name in Claude Code
-```
-
-**Build and publish your own skill package:**
-```bash
-# Configure vat.skills in package.json + claude: in vibe-agent-toolkit.config.yaml, then:
-vat build                 # builds skills + claude plugin artifacts
-vat verify                # validates everything
-npm publish               # publishes to npm (postinstall registers the plugin)
-# Users install with: vat skills install npm:@myorg/my-skills
-```
-
-## Success Criteria
-
-You've successfully adopted VAT when:
-- Agents have clear input/output schemas (Zod-validated)
-- Errors are handled as data (result envelopes), never thrown
-- Tests cover success and error paths without real API calls (mock mode)
-- Agents work across multiple runtimes via adapters
-- Multi-agent pipelines compose via `andThen()` / `match()` helpers
-
-## Documentation Index
-
-- Getting Started Guide
-- Agent Authoring Guide — patterns and code examples
-- Orchestration Guide — multi-agent workflows
-- RAG Usage Guide
-- Resource Compiler Guide
-- Runtime Adapters
-- Examples: `@vibe-agent-toolkit/vat-example-cat-agents`
-
-## Running VAT
-
-VAT can be run without a global install:
-
-```bash
-vat <command>                     # If installed globally
-npx vibe-agent-toolkit <command>  # npm (downloads on demand)
-bunx vibe-agent-toolkit <command> # Bun (downloads on demand)
-```
-
-All `vat` commands in this skill and sub-skills accept these alternatives.
+Each sub-skill covers its slice of the CLI in depth — don't memorize this table, load the sub-skill when you need detail.
 
 ## Getting Help
 
-- **CLI Help:** `vat --help`, `vat skills --help`, etc.
-- **Examples:** `packages/vat-example-cat-agents/`
-- **GitHub Issues:** Report bugs or ask questions
-
-Happy agent building!
+- `vat --help` and `vat <group> --help --verbose` for CLI depth
+- Repo docs: the VAT repository's `docs/` directory carries the full setup guide, architecture notes, and design references (not bundled with this plugin)
+- Contributor reference docs (debugging VAT, install architecture) live under `docs/contributing/` in the VAT repo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/vat-development-agents",
-  "version": "0.1.32-rc.4",
+  "version": "0.1.32",
   "description": "VAT development agents - dogfooding the vibe-agent-toolkit",
   "type": "module",
   "keywords": [
@@ -13,13 +13,15 @@
     "version": "1.0",
     "skills": [
       "vibe-agent-toolkit",
-      "resources",
-      "distribution",
-      "authoring",
-      "audit",
-      "debugging",
-      "install",
-      "org-admin"
+      "vat-adoption-and-configuration",
+      "vat-knowledge-resources",
+      "vat-skill-distribution",
+      "vat-agent-authoring",
+      "vat-skill-authoring",
+      "vat-audit",
+      "vat-rag",
+      "vat-skill-review",
+      "vat-enterprise-org"
     ],
     "replaces": {
       "plugins": [
@@ -65,13 +67,13 @@
     "postinstall": "vat claude plugin install --npm-postinstall || exit 0"
   },
   "dependencies": {
-    "@vibe-agent-toolkit/agent-schema": "0.1.32-rc.4",
-    "@vibe-agent-toolkit/cli": "0.1.32-rc.4",
+    "@vibe-agent-toolkit/agent-schema": "0.1.32",
+    "@vibe-agent-toolkit/cli": "0.1.32",
     "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
-    "@vibe-agent-toolkit/resource-compiler": "0.1.32-rc.4",
+    "@vibe-agent-toolkit/resource-compiler": "0.1.32",
     "ts-patch": "^3.2.1",
     "typescript": "^5.7.3"
   },

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

@@ -1,111 +0,0 @@
----
-name: debugging
-description: >-
-  Debug unexpected VAT behavior, reproduce bugs, test local vibe-agent-toolkit
-  changes in adopter projects (VAT_ROOT_DIR), write failing tests before fixing,
-  and validate fixes with the full build pipeline before publishing
----
-
-# Debugging & Testing VAT Fixes
-
-Use this skill when VAT itself is behaving unexpectedly, you suspect a VAT bug,
-or you need to test a local code change to vibe-agent-toolkit in another project.
-
-## Step 1: Confirm the Version
-
-First, confirm which version of VAT is running:
-
-```bash
-# In the adopter project
-cat node_modules/@vibe-agent-toolkit/cli/package.json | grep '"version"'
-
-# Or check the binary directly
-vat --version
-```
-
-If the installed version is behind the monorepo, you may need `VAT_ROOT_DIR` (see below)
-to test with the local build instead.
-
-## Step 2: Enable Debug Output
-
-```bash
-VAT_DEBUG=1 vat <command>
-```
-
-`VAT_DEBUG=1` prints context detection info, binary path resolution, and config loading
-details. Use it to confirm which config file and which binary are actually being used.
-
-Other useful env vars:
-- `VAT_TEST_ROOT=/path` — Override the project root VAT uses (skips `.git` detection)
-- `VAT_TEST_CONFIG=/path/to/config.yaml` — Override the config file path
-
-## Step 3: Reproduce With the Local Monorepo Build
-
-To test a fix from your local vibe-agent-toolkit checkout in an adopter project
-(e.g. lfa-cc-marketplace) **without publishing to npm**:
-
-### Option A: VAT_ROOT_DIR (recommended)
-
-```bash
-# In your shell (or .env.local in the adopter project)
-export VAT_ROOT_DIR=/path/to/vibe-agent-toolkit
-
-# Build the monorepo first — always required
-cd /path/to/vibe-agent-toolkit && bun run build
-
-# Now any vat command in the adopter project uses your local build
-cd /path/to/adopter-project
-vat resources validate .
-```
-
-The globally-installed `vat` wrapper detects `VAT_ROOT_DIR` and re-dispatches
-to `$VAT_ROOT_DIR/packages/cli/dist/bin.js`.
-
-### Option B: Direct path (no global install needed)
-
-```bash
-# Build first
-cd /path/to/vibe-agent-toolkit && bun run build
-
-# Then invoke directly
-node /path/to/vibe-agent-toolkit/packages/cli/dist/bin/vat.js resources validate .
-```
-
-## Step 4: Write a Failing Test Before Fixing
-
-Before changing VAT source code, write a test that reproduces the bug:
-
-- **Unit bug** → add a test in `packages/<package>/test/`
-- **CLI behavior** → add an integration test in `packages/cli/test/integration/`
-- **End-to-end workflow** → add a system test in `packages/cli/test/system/`
-
-See docs/writing-tests.md for test patterns and
-the unit/integration/system classification guide.
-
-## Step 5: Validate Before Committing
-
-After fixing, run the full pipeline from the monorepo root:
-
-```bash
-bun run validate
-```
-
-This runs unit → integration → system tests with caching. If tests pass, the fix
-is safe to commit. Do not commit until `bun run validate` passes.
-
-## Quick Diagnosis Checklist
-
-| Symptom | First thing to check |
-|---|---|
-| `vat` command not found | `npm install -g vibe-agent-toolkit` |
-| Wrong results in adopter project | Confirm installed version matches expected RC |
-| Fix applied but adopter still wrong | Did you `bun run build` after the change? |
-| Validation slow every time | `git rev-parse --git-dir` — are you in a git repo? |
-| Config not loading | `VAT_DEBUG=1 vat <command>` to see which config is found |
-| Test passes locally, fails CI | Windows path separator? Use `toForwardSlash()` from `@vibe-agent-toolkit/utils` |
-
-## See Also
-
-- docs/debug-and-test-vat-fixes.md — Full reference
-- docs/writing-tests.md — Test patterns and classification
-- [packages/cli/CLAUDE.md]() — CLI development guidelines