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

package/dist/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/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/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 → skills/vat-enterprise-org}/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: org-admin
-description: Anthropic org admin (Enterprise/Team). Use for user management, API-key auditing, cost/usage reporting, workspace admin, and enterprise skill distribution via the Admin API. Requires ANTHROPIC_ADMIN_API_KEY.
+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
 
 **For Anthropic org admins only.** Requires `ANTHROPIC_ADMIN_API_KEY` (Enterprise/Team plan).
-If you don't have an admin key, this skill is not for you — use `vibe-agent-toolkit:distribution`
+If you don't have an admin key, this skill is not for you — use `vibe-agent-toolkit:vat-skill-distribution`
 for local plugin management instead.
 
 ## Two Ways to Use It

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

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