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

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

@@ -0,0 +1,156 @@
+---
+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.
+---
+
+# VAT Skill Authoring: SKILL.md Structure and Packaging
+
+This skill covers authoring SKILL.md files for portable Claude skills: frontmatter shape, body structure, reference links, and the packaging options that control how the skill is bundled for distribution. For the TypeScript agent side (archetypes, result envelopes, orchestration, runtime adapters) use `vibe-agent-toolkit:vat-agent-authoring`.
+
+## SKILL.md Structure
+
+A SKILL.md file is the definition file for a portable 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 (≤250 chars)
+---
+
+# My Skill
+
+Rest of the skill documentation...
+```
+
+Required frontmatter fields:
+
+- `name` — unique identifier, kebab-case (`^[a-z][a-z0-9-]*$`), matches the skill's directory name after build. Avoid the reserved words `claude` and `anthropic` (Claude Code rejects non-certified skills using those words — surfaced as `RESERVED_WORD_IN_NAME`).
+- `description` — trigger description used for Claude's skill routing; be specific about activation conditions.
+
+Best practices for `description`:
+
+- Lead with an action verb or `Use when <concrete trigger>` — filler openers like "This skill...", "A skill that...", "Use when you want to..." fire `SKILL_DESCRIPTION_FILLER_OPENER`.
+- Include 2–4 trigger keywords a user is likely to type.
+- 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.
+
+## Body Structure
+
+- Lead with a short orientation paragraph: what the skill owns and when to reach for it.
+- Use H2 sections for major content blocks; avoid deeply nested H3/H4 trees — they hurt Claude's ability to route attention inside the file.
+- Keep SKILL.md under ~500 lines. Longer than that fires `SKILL_LENGTH_EXCEEDS_RECOMMENDED` and is a strong signal to split via progressive disclosure (linked reference files) or to spin the content into a sibling skill.
+- Avoid time-sensitive phrasing like "as of April 2026" in the body — it ages the skill quickly (`SKILL_TIME_SENSITIVE_CONTENT`).
+
+## References Section
+
+A short `## References` section at the bottom is the canonical place to list linked resources. Two patterns:
+
+- **Progressive disclosure** — link to `.md` files inside the skill directory that get bundled. Keep reference depth ≤ 2 hops; deeper chains fire `REFERENCE_TOO_DEEP`.
+- **Prose references to sibling skills** — write `vibe-agent-toolkit:vat-audit`, not `[vat-audit](./vat-audit.md)`. Markdown links to sibling SKILL.md files cause the packager to transclude the other skill (and fire `LINK_TO_SKILL_DEFINITION`).
+
+Avoid linking to navigation files (`README.md`, `index.md`) — they're excluded from the bundle and the link resolves to nothing (`LINK_TO_NAVIGATION_FILE`).
+
+## packagingOptions Reference
+
+Packaging options are configured per skill in `vibe-agent-toolkit.config.yaml` under `skills.config.<name>`:
+
+```yaml
+skills:
+  include: ["resources/skills/SKILL.md", "resources/skills/*.md"]
+  defaults:
+    linkFollowDepth: 2
+  config:
+    my-skill:
+      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 Overrides
+
+The `validation` sub-key in a skill's config provides the unified override framework for VAT validation codes:
+
+```yaml
+skills:
+  config:
+    my-skill:
+      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.
+
+Common adjustments:
+
+- 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).
+
+`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.
+
+## Pre-publication Check
+
+Before shipping a skill, walk through the `vibe-agent-toolkit:vat-skill-review` checklist — it covers naming, description quality, structure, validation-code triage, and Anthropic's skill-authoring best practices. The `vat skill review <skill>` CLI command renders a skill-specific view of the same checklist.
+
+## References
+
+- `vibe-agent-toolkit:vat-skill-review` — pre-publication quality checklist (general + CLI-backed items, tied to VAT validation codes)
+- `vibe-agent-toolkit:vat-skill-distribution` — plugin/marketplace config, `vat build`, `vat verify`, npm publishing
+- `vibe-agent-toolkit:vat-knowledge-resources` — the `resources:` config section for multi-collection frontmatter schema validation
+- Validation Codes Reference — full list of codes VAT emits, their default severity, and override recipes.
+- Skill Quality and Compatibility — VAT's Stance — what VAT believes makes a skill good and compatible.

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/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/{skills/authoring/resources/skill-quality-checklist.md → .claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/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/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/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/dist/generated/resources/skills/CLAUDE.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Generated TypeScript declarations - DO NOT EDIT
+ */
+
+export interface Fragment {
+  readonly header: string;
+  readonly body: string;
+  readonly text: string;
+}
+
+export const meta: {};
+
+export const text: string;
+
+export const fragments: {
+  readonly skillInventoryAndBoundaries: Fragment;
+  readonly crossCuttingVibeAgentToolkitconfigyaml: Fragment;
+  readonly namingRulesProgrammatic-Advisory: Fragment;
+  readonly descriptionQuality: Fragment;
+  readonly routerSkillSkillmd-VibeAgentToolkit-SpecialRules: Fragment;
+  readonly singleResponsibility-WhenToSplit: Fragment;
+  readonly contributorVsUserContent: Fragment;
+  readonly thisAreaMovesFast-VerifyCurrentStandards: Fragment;
+  readonly shiftLeft-EveryManualCheckIsAFutureValidator: Fragment;
+  readonly preCommitChecks: Fragment;
+};
+
+export type FragmentName = keyof typeof fragments;

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

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

package/dist/generated/resources/skills/SKILL.d.ts

@@ -16,17 +16,9 @@ export const meta: {
 export const text: string;
 
 export const fragments: {
-  readonly purposeForUsersNotContributors: Fragment;
   readonly whenToUseVat: Fragment;
-  readonly skillRoutingTable: Fragment;
-  readonly agentArchetypesQuickReference: Fragment;
-  readonly coreCliCommands: Fragment;
-  readonly agentGeneratorCreatingNewAgents: Fragment;
-  readonly packagingMarkdownForReuse: Fragment;
-  readonly commonWorkflows: Fragment;
-  readonly successCriteria: Fragment;
-  readonly documentationIndex: Fragment;
-  readonly runningVat: Fragment;
+  readonly pickingASubSkill: Fragment;
+  readonly cliSurfaceAtAGlance: Fragment;
   readonly gettingHelp: Fragment;
 };