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

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

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

package/dist/generated/resources/skills/vat-adoption-and-configuration.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Generated TypeScript declarations - DO NOT EDIT
+ */
+
+export interface Fragment {
+  readonly header: string;
+  readonly body: string;
+  readonly text: string;
+}
+
+export const meta: {
+  readonly name: string;
+  readonly description: string;
+};
+
+export const text: string;
+
+export const fragments: {
+  readonly installingVat: Fragment;
+  readonly recommendedRepoStructure: Fragment;
+  readonly vibeAgentToolkitconfigyamlShape: Fragment;
+  readonly packagejsonWiring: Fragment;
+  readonly vibeValidateIntegration: Fragment;
+  readonly firstTimeSetupChecklist: Fragment;
+  readonly whenThingsAreOff: Fragment;
+  readonly references: Fragment;
+};
+
+export type FragmentName = keyof typeof fragments;

package/dist/generated/resources/skills/vat-adoption-and-configuration.js

@@ -0,0 +1,53 @@
+/**
+ * Generated from markdown file - DO NOT EDIT
+ */
+
+export const meta = {
+  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."
+};
+
+export const text = "\n# VAT Adoption and Configuration\n\nThis 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.\n\n## Installing VAT\n\nVAT ships as the \`vibe-agent-toolkit\` npm package with a \`vat\` CLI:\n\n\`\`\`bash\n# Global install (most common during development)\nnpm install -g vibe-agent-toolkit\n\n# Or run without installing\nnpx vibe-agent-toolkit <command>\nbunx vibe-agent-toolkit <command>\n\n# As a runtime dependency (recommended for published packages that ship skills)\nnpm install --save vibe-agent-toolkit\n\`\`\`\n\nOnce installed, \`vat --help\` lists the top-level command groups. \`vat <group> --help\` and \`vat <group> <cmd> --help --verbose\` cover the rest.\n\n## Recommended Repo Structure\n\n\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT walks upward from the invocation directory to find it.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored.\n\n## \`vibe-agent-toolkit.config.yaml\` Shape\n\n\`\`\`yaml\nversion: 1\n\nskills:\n  include: [\"resources/skills/SKILL.md\", \"resources/skills/*.md\"]\n  defaults:\n    linkFollowDepth: 2\n    excludeNavigationFiles: true\n    targets: [\'claude-code\']\n  config:\n    my-skill:\n      linkFollowDepth: 1\n\nresources:\n  collections:\n    docs:\n      include: [\"docs/**/*.md\"]\n      validation:\n        frontmatterSchema: \"schemas/doc.schema.json\"\n        mode: permissive\n\nclaude:\n  marketplaces:\n    my-marketplace:\n      owner: { name: \"my-org\" }\n      publish:\n        changelog: CHANGELOG.md\n        readme: README.md\n      plugins:\n        - name: my-plugin\n          description: \"What this plugin does\"\n          skills: \"*\"\n\nrag:\n  stores:\n    default:\n      db: .rag-db/\n      include: [\"docs/**/*.md\"]\n\`\`\`\n\nSections and the skills that own their details:\n\n| Section | Owning skill |\n|---|---|\n| Top-level structure, \`version\`, section orientation | this skill (\`vat-adoption-and-configuration\`) |\n| \`skills:\` (include, defaults, per-skill config, packagingOptions) | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| \`resources:\` (collections, schemas, validation modes) | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`claude:\` (marketplaces, plugins, publish, owner) | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`rag:\` (stores, embedding providers) | \`vibe-agent-toolkit:vat-rag\` |\n\nWhen adding to a section, load the owning skill rather than re-deriving the shape from this file.\n\n## \`package.json\` Wiring\n\nFor projects that publish skills via npm, three fields tie VAT into the npm lifecycle:\n\n\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"dependencies\": {\n    \"vibe-agent-toolkit\": \"latest\"\n  },\n  \"scripts\": {\n    \"build\": \"vat build\",\n    \"postinstall\": \"vat claude plugin install --npm-postinstall || exit 0\"\n  },\n  \"vat\": {\n    \"skills\": [\"my-skill-one\", \"my-skill-two\"]\n  }\n}\n\`\`\`\n\n- **\`dependencies.vibe-agent-toolkit\`** — runtime dep, not dev. Needed so the postinstall hook can find \`vat\`.\n- **\`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).\n- **\`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.\n\nThe full distribution pipeline (build, verify, npm publish, marketplace layout, managed settings) lives in \`vibe-agent-toolkit:vat-skill-distribution\`.\n\n## vibe-validate Integration\n\nIf the project uses vibe-validate (recommended), wire VAT into the validation config:\n\n\`\`\`yaml\n# vibe-validate.config.yaml (or relevant section)\nphases:\n  - name: vat-build-and-verify\n    parallel: false\n    commands:\n      - name: vat build\n        run: vat build\n      - name: vat verify\n        run: vat verify\n\`\`\`\n\n\`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.\n\n## First-Time Setup Checklist\n\n1. \`npm install -g vibe-agent-toolkit\` (or add to local deps)\n2. \`vat --help\` — confirm the CLI resolves\n3. Create \`vibe-agent-toolkit.config.yaml\` with the minimal \`version: 1\` plus the sections you need\n4. 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)\n5. \`vat skills validate\` — report any issues before building\n6. \`vat build\` — produces \`dist/\` artifacts\n7. \`vat verify\` — full consistency check; should be a no-op when clean\n8. If publishing: add the \`vat.skills\`, \`scripts.postinstall\`, and \`dependencies.vibe-agent-toolkit\` entries in \`package.json\` before \`npm publish\`\n\n## When Things Are Off\n\n- **\"No skills section in config yaml\"** — either the file isn\'t at the project root, or \`skills.include\` is missing.\n- **\"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\`).\n- **\`PACKAGE_JSON_LISTS_UNKNOWN_SKILL\`** — \`vat.skills\` mentions a name not produced by \`skills.include\` discovery. Either add the file or remove the name.\n- **\`vat audit\` fires unexpected warnings** — load \`vibe-agent-toolkit:vat-audit\` for the full audit surface, including \`--compat\` and \`--exclude\` flags.\n\n## References\n\n- \`vibe-agent-toolkit:vat-skill-authoring\` — SKILL.md frontmatter, body structure, references, packagingOptions\n- \`vibe-agent-toolkit:vat-agent-authoring\` — TypeScript agent archetypes and runtime adapters\n- \`vibe-agent-toolkit:vat-skill-distribution\` — \`vat build\` / \`vat verify\` / marketplace / npm publish\n- \`vibe-agent-toolkit:vat-knowledge-resources\` — \`resources:\` collections and frontmatter schemas\n- \`vibe-agent-toolkit:vat-rag\` — \`rag:\` stores, embedding providers, \`vat rag index/query\`\n- \`vibe-agent-toolkit:vat-audit\` — \`vat audit\` for plugins, marketplaces, and installed skills\n- \`vibe-agent-toolkit:vat-skill-review\` — pre-publication quality checklist\n- [Getting Started Guide](../../../../docs/getting-started.md) — full setup walkthrough\n";
+
+export const fragments = {
+  installingVat: {
+    header: "## Installing VAT",
+    body: "VAT ships as the \`vibe-agent-toolkit\` npm package with a \`vat\` CLI:\n\n\`\`\`bash\n# Global install (most common during development)\nnpm install -g vibe-agent-toolkit\n\n# Or run without installing\nnpx vibe-agent-toolkit <command>\nbunx vibe-agent-toolkit <command>\n\n# As a runtime dependency (recommended for published packages that ship skills)\nnpm install --save vibe-agent-toolkit\n\`\`\`\n\nOnce installed, \`vat --help\` lists the top-level command groups. \`vat <group> --help\` and \`vat <group> <cmd> --help --verbose\` cover the rest.",
+    text: "## Installing VAT\n\nVAT ships as the \`vibe-agent-toolkit\` npm package with a \`vat\` CLI:\n\n\`\`\`bash\n# Global install (most common during development)\nnpm install -g vibe-agent-toolkit\n\n# Or run without installing\nnpx vibe-agent-toolkit <command>\nbunx vibe-agent-toolkit <command>\n\n# As a runtime dependency (recommended for published packages that ship skills)\nnpm install --save vibe-agent-toolkit\n\`\`\`\n\nOnce installed, \`vat --help\` lists the top-level command groups. \`vat <group> --help\` and \`vat <group> <cmd> --help --verbose\` cover the rest."
+  },
+  recommendedRepoStructure: {
+    header: "## Recommended Repo Structure",
+    body: "\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT walks upward from the invocation directory to find it.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored.",
+    text: "## Recommended Repo Structure\n\n\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT walks upward from the invocation directory to find it.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored."
+  },
+  vibeAgentToolkitconfigyamlShape: {
+    header: "## \`vibe-agent-toolkit.config.yaml\` Shape",
+    body: "\`\`\`yaml\nversion: 1\n\nskills:\n  include: [\"resources/skills/SKILL.md\", \"resources/skills/*.md\"]\n  defaults:\n    linkFollowDepth: 2\n    excludeNavigationFiles: true\n    targets: [\'claude-code\']\n  config:\n    my-skill:\n      linkFollowDepth: 1\n\nresources:\n  collections:\n    docs:\n      include: [\"docs/**/*.md\"]\n      validation:\n        frontmatterSchema: \"schemas/doc.schema.json\"\n        mode: permissive\n\nclaude:\n  marketplaces:\n    my-marketplace:\n      owner: { name: \"my-org\" }\n      publish:\n        changelog: CHANGELOG.md\n        readme: README.md\n      plugins:\n        - name: my-plugin\n          description: \"What this plugin does\"\n          skills: \"*\"\n\nrag:\n  stores:\n    default:\n      db: .rag-db/\n      include: [\"docs/**/*.md\"]\n\`\`\`\n\nSections and the skills that own their details:\n\n| Section | Owning skill |\n|---|---|\n| Top-level structure, \`version\`, section orientation | this skill (\`vat-adoption-and-configuration\`) |\n| \`skills:\` (include, defaults, per-skill config, packagingOptions) | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| \`resources:\` (collections, schemas, validation modes) | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`claude:\` (marketplaces, plugins, publish, owner) | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`rag:\` (stores, embedding providers) | \`vibe-agent-toolkit:vat-rag\` |\n\nWhen adding to a section, load the owning skill rather than re-deriving the shape from this file.",
+    text: "## \`vibe-agent-toolkit.config.yaml\` Shape\n\n\`\`\`yaml\nversion: 1\n\nskills:\n  include: [\"resources/skills/SKILL.md\", \"resources/skills/*.md\"]\n  defaults:\n    linkFollowDepth: 2\n    excludeNavigationFiles: true\n    targets: [\'claude-code\']\n  config:\n    my-skill:\n      linkFollowDepth: 1\n\nresources:\n  collections:\n    docs:\n      include: [\"docs/**/*.md\"]\n      validation:\n        frontmatterSchema: \"schemas/doc.schema.json\"\n        mode: permissive\n\nclaude:\n  marketplaces:\n    my-marketplace:\n      owner: { name: \"my-org\" }\n      publish:\n        changelog: CHANGELOG.md\n        readme: README.md\n      plugins:\n        - name: my-plugin\n          description: \"What this plugin does\"\n          skills: \"*\"\n\nrag:\n  stores:\n    default:\n      db: .rag-db/\n      include: [\"docs/**/*.md\"]\n\`\`\`\n\nSections and the skills that own their details:\n\n| Section | Owning skill |\n|---|---|\n| Top-level structure, \`version\`, section orientation | this skill (\`vat-adoption-and-configuration\`) |\n| \`skills:\` (include, defaults, per-skill config, packagingOptions) | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| \`resources:\` (collections, schemas, validation modes) | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`claude:\` (marketplaces, plugins, publish, owner) | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`rag:\` (stores, embedding providers) | \`vibe-agent-toolkit:vat-rag\` |\n\nWhen adding to a section, load the owning skill rather than re-deriving the shape from this file."
+  },
+  packagejsonWiring: {
+    header: "## \`package.json\` Wiring",
+    body: "For projects that publish skills via npm, three fields tie VAT into the npm lifecycle:\n\n\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"dependencies\": {\n    \"vibe-agent-toolkit\": \"latest\"\n  },\n  \"scripts\": {\n    \"build\": \"vat build\",\n    \"postinstall\": \"vat claude plugin install --npm-postinstall || exit 0\"\n  },\n  \"vat\": {\n    \"skills\": [\"my-skill-one\", \"my-skill-two\"]\n  }\n}\n\`\`\`\n\n- **\`dependencies.vibe-agent-toolkit\`** — runtime dep, not dev. Needed so the postinstall hook can find \`vat\`.\n- **\`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).\n- **\`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.\n\nThe full distribution pipeline (build, verify, npm publish, marketplace layout, managed settings) lives in \`vibe-agent-toolkit:vat-skill-distribution\`.",
+    text: "## \`package.json\` Wiring\n\nFor projects that publish skills via npm, three fields tie VAT into the npm lifecycle:\n\n\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"dependencies\": {\n    \"vibe-agent-toolkit\": \"latest\"\n  },\n  \"scripts\": {\n    \"build\": \"vat build\",\n    \"postinstall\": \"vat claude plugin install --npm-postinstall || exit 0\"\n  },\n  \"vat\": {\n    \"skills\": [\"my-skill-one\", \"my-skill-two\"]\n  }\n}\n\`\`\`\n\n- **\`dependencies.vibe-agent-toolkit\`** — runtime dep, not dev. Needed so the postinstall hook can find \`vat\`.\n- **\`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).\n- **\`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.\n\nThe full distribution pipeline (build, verify, npm publish, marketplace layout, managed settings) lives in \`vibe-agent-toolkit:vat-skill-distribution\`."
+  },
+  vibeValidateIntegration: {
+    header: "## vibe-validate Integration",
+    body: "If the project uses vibe-validate (recommended), wire VAT into the validation config:\n\n\`\`\`yaml\n# vibe-validate.config.yaml (or relevant section)\nphases:\n  - name: vat-build-and-verify\n    parallel: false\n    commands:\n      - name: vat build\n        run: vat build\n      - name: vat verify\n        run: vat verify\n\`\`\`\n\n\`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.",
+    text: "## vibe-validate Integration\n\nIf the project uses vibe-validate (recommended), wire VAT into the validation config:\n\n\`\`\`yaml\n# vibe-validate.config.yaml (or relevant section)\nphases:\n  - name: vat-build-and-verify\n    parallel: false\n    commands:\n      - name: vat build\n        run: vat build\n      - name: vat verify\n        run: vat verify\n\`\`\`\n\n\`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."
+  },
+  firstTimeSetupChecklist: {
+    header: "## First-Time Setup Checklist",
+    body: "1. \`npm install -g vibe-agent-toolkit\` (or add to local deps)\n2. \`vat --help\` — confirm the CLI resolves\n3. Create \`vibe-agent-toolkit.config.yaml\` with the minimal \`version: 1\` plus the sections you need\n4. 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)\n5. \`vat skills validate\` — report any issues before building\n6. \`vat build\` — produces \`dist/\` artifacts\n7. \`vat verify\` — full consistency check; should be a no-op when clean\n8. If publishing: add the \`vat.skills\`, \`scripts.postinstall\`, and \`dependencies.vibe-agent-toolkit\` entries in \`package.json\` before \`npm publish\`",
+    text: "## First-Time Setup Checklist\n\n1. \`npm install -g vibe-agent-toolkit\` (or add to local deps)\n2. \`vat --help\` — confirm the CLI resolves\n3. Create \`vibe-agent-toolkit.config.yaml\` with the minimal \`version: 1\` plus the sections you need\n4. 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)\n5. \`vat skills validate\` — report any issues before building\n6. \`vat build\` — produces \`dist/\` artifacts\n7. \`vat verify\` — full consistency check; should be a no-op when clean\n8. If publishing: add the \`vat.skills\`, \`scripts.postinstall\`, and \`dependencies.vibe-agent-toolkit\` entries in \`package.json\` before \`npm publish\`"
+  },
+  whenThingsAreOff: {
+    header: "## When Things Are Off",
+    body: "- **\"No skills section in config yaml\"** — either the file isn\'t at the project root, or \`skills.include\` is missing.\n- **\"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\`).\n- **\`PACKAGE_JSON_LISTS_UNKNOWN_SKILL\`** — \`vat.skills\` mentions a name not produced by \`skills.include\` discovery. Either add the file or remove the name.\n- **\`vat audit\` fires unexpected warnings** — load \`vibe-agent-toolkit:vat-audit\` for the full audit surface, including \`--compat\` and \`--exclude\` flags.",
+    text: "## When Things Are Off\n\n- **\"No skills section in config yaml\"** — either the file isn\'t at the project root, or \`skills.include\` is missing.\n- **\"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\`).\n- **\`PACKAGE_JSON_LISTS_UNKNOWN_SKILL\`** — \`vat.skills\` mentions a name not produced by \`skills.include\` discovery. Either add the file or remove the name.\n- **\`vat audit\` fires unexpected warnings** — load \`vibe-agent-toolkit:vat-audit\` for the full audit surface, including \`--compat\` and \`--exclude\` flags."
+  },
+  references: {
+    header: "## References",
+    body: "- \`vibe-agent-toolkit:vat-skill-authoring\` — SKILL.md frontmatter, body structure, references, packagingOptions\n- \`vibe-agent-toolkit:vat-agent-authoring\` — TypeScript agent archetypes and runtime adapters\n- \`vibe-agent-toolkit:vat-skill-distribution\` — \`vat build\` / \`vat verify\` / marketplace / npm publish\n- \`vibe-agent-toolkit:vat-knowledge-resources\` — \`resources:\` collections and frontmatter schemas\n- \`vibe-agent-toolkit:vat-rag\` — \`rag:\` stores, embedding providers, \`vat rag index/query\`\n- \`vibe-agent-toolkit:vat-audit\` — \`vat audit\` for plugins, marketplaces, and installed skills\n- \`vibe-agent-toolkit:vat-skill-review\` — pre-publication quality checklist\n- [Getting Started Guide](../../../../docs/getting-started.md) — full setup walkthrough",
+    text: "## References\n\n- \`vibe-agent-toolkit:vat-skill-authoring\` — SKILL.md frontmatter, body structure, references, packagingOptions\n- \`vibe-agent-toolkit:vat-agent-authoring\` — TypeScript agent archetypes and runtime adapters\n- \`vibe-agent-toolkit:vat-skill-distribution\` — \`vat build\` / \`vat verify\` / marketplace / npm publish\n- \`vibe-agent-toolkit:vat-knowledge-resources\` — \`resources:\` collections and frontmatter schemas\n- \`vibe-agent-toolkit:vat-rag\` — \`rag:\` stores, embedding providers, \`vat rag index/query\`\n- \`vibe-agent-toolkit:vat-audit\` — \`vat audit\` for plugins, marketplaces, and installed skills\n- \`vibe-agent-toolkit:vat-skill-review\` — pre-publication quality checklist\n- [Getting Started Guide](../../../../docs/getting-started.md) — full setup walkthrough"
+  }
+};

package/dist/generated/resources/skills/vat-agent-authoring.d.ts

@@ -16,11 +16,9 @@ export const meta: {
 export const text: string;
 
 export const fragments: {
-  readonly skillmdStructure: Fragment;
   readonly agentArchetypes: Fragment;
   readonly resultEnvelopes: Fragment;
   readonly orchestrationPatterns: Fragment;
-  readonly packagingoptionsReference: Fragment;
   readonly testingAgents: Fragment;
   readonly bestPractices: Fragment;
   readonly references: Fragment;

package/dist/generated/resources/skills/vat-agent-authoring.js

@@ -3,18 +3,13 @@
  */
 
 export const meta = {
-  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."
 };
 
-export const text = "\n# VAT Agent Authoring: SKILL.md, Archetypes & Patterns\n\n## SKILL.md Structure\n\nA SKILL.md file is the definition file for a VAT agent skill. It tells Claude what the skill\ndoes and how to use it. All SKILL.md files must have YAML frontmatter:\n\n\`\`\`markdown\n---\nname: my-skill\ndescription: One sentence: what this skill does and when to use it (max 200 chars)\n---\n\n# My Skill\n\nRest of the skill documentation...\n\`\`\`\n\nRequired frontmatter fields:\n- \`name\` — unique identifier, kebab-case, matches the skill\'s directory name\n- \`description\` — trigger description used for skill routing; be specific about activation conditions\n\nBest practices for \`description\`:\n- Start with \"Use when...\" to make activation conditions explicit\n- Include the key commands or concepts the skill covers\n- Keep under 200 characters\n\n## Agent Archetypes\n\nVAT supports four agent archetypes for different use cases.\n\n### Archetype 1: Pure Function Tool\n\n**When to use:** Stateless validation, transformation, computation — no LLM needed.\n\n**Characteristics:** Deterministic output, fast execution, easy to test.\n\n**Example use cases:** Input validation, data transformation, format conversion, rules-based logic.\n\n\`\`\`typescript\nexport async function validateInput(input: MyInput): Promise<ValidationResult> {\n  if (input.text.length < 5) {\n    return { status: \'error\', error: \'too-short\' };\n  }\n  return { status: \'success\', data: { valid: true } };\n}\n\`\`\`\n\n### Archetype 2: One-Shot LLM Analyzer\n\n**When to use:** Single LLM call for analysis, classification, or generation.\n\n**Characteristics:** One LLM call per execution, stateless, handles LLM errors.\n\n**Example use cases:** Sentiment analysis, text classification, entity extraction, creative generation.\n\n\`\`\`typescript\nexport async function analyzeSentiment(text: string, context: AgentContext) {\n  const response = await context.callLLM([\n    { role: \'user\', content: \`Analyze sentiment: \"${text}\"\` }\n  ]);\n\n  const parsed = JSON.parse(response);\n  return { status: \'success\', data: parsed };\n}\n\`\`\`\n\n### Archetype 3: Conversational Assistant\n\n**When to use:** Multi-turn dialogue, progressive data collection across sessions.\n\n**Characteristics:** Multiple LLM calls, maintains session state, phases (gathering → ready → complete).\n\n**Example use cases:** Customer support chatbots, product advisors, interview agents, multi-step forms.\n\n\`\`\`typescript\nexport async function conversationalAgent(\n  message: string,\n  sessionState: SessionState\n) {\n  if (sessionState.phase === \'gathering\') {\n    return {\n      reply: \"Can you tell me more about X?\",\n      sessionState: { ...sessionState },\n      result: { status: \'in-progress\' }\n    };\n  }\n\n  return {\n    reply: \"Here\'s your result!\",\n    sessionState: { ...sessionState, phase: \'complete\' },\n    result: { status: \'success\', data: finalResult }\n  };\n}\n\`\`\`\n\n### Archetype 4: External Event Integrator\n\n**When to use:** Waiting for external events (approvals, webhooks, third-party APIs).\n\n**Characteristics:** Emits event, blocks waiting for response, timeout handling, mockable for testing.\n\n**Example use cases:** Human-in-the-loop approval, webhook integrations, external API polling.\n\n\`\`\`typescript\nexport async function humanApproval(\n  request: ApprovalRequest,\n  options = { mockable: true, timeout: 30000 }\n) {\n  if (options.mockable) {\n    return { status: \'success\', data: { approved: true } };\n  }\n\n  const response = await emitEvent(request, options.timeout);\n  return { status: \'success\', data: response };\n}\n\`\`\`\n\n## Result Envelopes\n\nAlways return result envelopes — never throw exceptions for expected errors.\n\n\`\`\`typescript\n// AgentResult<TData, TError> — for single-execution agents\ntype AgentResult<TData, TError> =\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\n// StatefulAgentResult — for conversational agents\ntype StatefulAgentResult<TData, TError, TMetadata> =\n  | { status: \'in-progress\'; metadata?: TMetadata }\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\`\`\`\n\nStandard LLM error literals: \`\'llm-refusal\'\`, \`\'llm-invalid-output\'\`, \`\'llm-timeout\'\`,\n\`\'llm-rate-limit\'\`, \`\'llm-token-limit\'\`, \`\'llm-unavailable\'\`.\n\nAlways check status before accessing data:\n\`\`\`typescript\nconst output = await myAgent.execute(input);\nif (output.result.status === \'success\') {\n  console.log(output.result.data);\n} else if (output.result.status === \'error\') {\n  console.error(\'Failed:\', output.result.error);\n}\n\`\`\`\n\n## Orchestration Patterns\n\n### Sequential Pipeline\n\n\`\`\`typescript\nconst analysisOutput = await analyzer.execute(input);\nconst processedOutput = await andThen(\n  analysisOutput.result,\n  async (data) => {\n    const out = await processor.execute(data);\n    return out.result;\n  }\n);\n\`\`\`\n\n### Parallel Execution\n\n\`\`\`typescript\nconst [output1, output2, output3] = await Promise.all([\n  agent1.execute(input),\n  agent2.execute(input),\n  agent3.execute(input),\n]);\n\`\`\`\n\n### Validation Loop (Generate + Validate with Retry)\n\n\`\`\`typescript\nasync function generateValidOutput(input: MyInput, maxAttempts = 5) {\n  for (let attempt = 0; attempt < maxAttempts; attempt++) {\n    const generatorOutput = await generator.execute(input);\n    if (generatorOutput.result.status === \'error\') continue;\n\n    const validatorOutput = await validator.execute(generatorOutput.result.data);\n    if (validatorOutput.result.status === \'success\' &&\n        validatorOutput.result.data.valid) {\n      return generatorOutput.result.data;\n    }\n  }\n  throw new Error(\'Max attempts exceeded\');\n}\n\`\`\`\n\n### Human-in-the-Loop\n\n\`\`\`typescript\nconst generatorOutput = await generator.execute(input);\nif (generatorOutput.result.status === \'success\') {\n  const approvalOutput = await humanApproval.execute({\n    content: generatorOutput.result.data,\n    context: input,\n  });\n  if (approvalOutput.result.data.approved) {\n    return generatorOutput.result.data;\n  }\n}\n\`\`\`\n\n### Conversational Multi-Turn\n\n\`\`\`typescript\nlet session = { state: { phase: \'gathering\' }, history: [] };\n\nwhile (true) {\n  const userMessage = await getUserInput();\n  const output = await conversationalAgent.execute({\n    message: userMessage,\n    sessionState: session.state,\n  });\n\n  console.log(\'Agent:\', output.reply);\n  session = {\n    state: output.sessionState,\n    history: [...session.history,\n      { role: \'user\', content: userMessage },\n      { role: \'assistant\', content: output.reply }\n    ],\n  };\n\n  if (output.result.status === \'success\') break;\n  if (output.result.status === \'error\') break;\n  // status === \'in-progress\': continue\n}\n\`\`\`\n\n## packagingOptions Reference\n\nConfigure in your skill\'s \`vat.skills[]\` entry in \`package.json\`:\n\n\`\`\`json\n{\n  \"vat\": {\n    \"skills\": [{\n      \"name\": \"my-skill\",\n      \"source\": \"./SKILL.md\",\n      \"path\": \"./dist/skills/my-skill\",\n      \"packagingOptions\": {\n        \"linkFollowDepth\": 1,\n        \"resourceNaming\": \"resource-id\",\n        \"stripPrefix\": \"knowledge-base\",\n        \"excludeReferencesFromBundle\": {\n          \"rules\": [\n            { \"patterns\": [\"**/concepts/**\"], \"template\": \"Use search to find: {{link.text}}\" }\n          ],\n          \"defaultTemplate\": \"{{link.text}} (search knowledge base)\"\n        }\n      }\n    }]\n  }\n}\n\`\`\`\n\n**\`linkFollowDepth\`** — How deep to follow links from SKILL.md:\n\n| Value | Behavior |\n|-------|----------|\n| \`0\` | Skill file only (no links followed) |\n| \`1\` | Direct links only |\n| \`2\` | Direct + one transitive level **(default)** |\n| \`\"full\"\` | Complete transitive closure |\n\n**\`resourceNaming\`** — How bundled files are named:\n\n| Strategy | Example | Use When |\n|----------|---------|----------|\n| \`basename\` | \`overview.md\` | Few files, unique names **(default)** |\n| \`resource-id\` | \`topics-quickstart-overview.md\` | Many files, flat output |\n| \`preserve-path\` | \`topics/quickstart/overview.md\` | Preserve structure |\n\nUse \`stripPrefix\` to remove a common directory prefix (e.g., \`\"knowledge-base\"\`).\n\n**\`excludeReferencesFromBundle\`** — Rules for excluding files and rewriting their links:\n- \`rules[]\` — Ordered glob patterns (first match wins), each with optional Handlebars template\n- \`defaultTemplate\` — Applied to depth-exceeded links not matching any rule\n\n**Template variables:**\n\n| Variable | Description |\n|----------|-------------|\n| \`{{link.text}}\` | Link display text |\n| \`{{link.href}}\` | Original href (without fragment) |\n| \`{{link.fragment}}\` | Fragment including \`#\` prefix, or empty |\n| \`{{link.type}}\` | Link type (\`\"local_file\"\`, etc.) |\n| \`{{link.resource.id}}\` | Target resource ID (if resolved) |\n| \`{{link.resource.fileName}}\` | Target filename (if resolved) |\n| \`{{skill.name}}\` | Skill name from frontmatter |\n\n**\`validation\`** — Unified framework for overriding default severity and allowing specific issue instances:\n\n\`\`\`yaml\n# In vibe-agent-toolkit.config.yaml under skills.defaults or skills.config.<name>\nvalidation:\n  severity:\n    LINK_DROPPED_BY_DEPTH: error           # upgrade: block on depth-dropped links\n    LINK_TO_NAVIGATION_FILE: ignore        # silence: this skill intentionally links to READMEs\n  allow:\n    PACKAGED_UNREFERENCED_FILE:\n      - paths: [\"templates/runtime.json\"]\n        reason: \"consumed programmatically at runtime\"\n        expires: \"2026-09-30\"\n    SKILL_LENGTH_EXCEEDS_RECOMMENDED:\n      - reason: \"whole-skill concern; paths defaults to [\'**/*\']\"\n\`\`\`\n\nTwo sub-keys, each covering a different override granularity:\n\n- **\`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.\n- **\`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.\n\nThings adopters typically adjust:\n\n- Downgrade \`LINK_DROPPED_BY_DEPTH\` to \`ignore\` when intentionally linking out to external docs.\n- Allow specific files under \`PACKAGED_UNREFERENCED_FILE\` when they\'re consumed programmatically by CLI scripts at runtime.\n- Raise \`ALLOW_EXPIRED\` to \`error\` for zero-tolerance expiry policies.\n\nExpired \`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).\n\nFull 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.\n\n## Testing Agents\n\n### Unit Testing Pure Functions\n\n\`\`\`typescript\nimport { describe, expect, it } from \'vitest\';\nimport { resultMatchers } from \'@vibe-agent-toolkit/agent-runtime\';\n\ndescribe(\'myValidator\', () => {\n  it(\'should validate correct input\', async () => {\n    const output = await myValidator.execute({ text: \'valid\' });\n    resultMatchers.expectSuccess(output.result);\n    expect(output.result.data.valid).toBe(true);\n  });\n});\n\`\`\`\n\n### Integration Testing with Mock LLM\n\n\`\`\`typescript\nimport { createMockContext } from \'@vibe-agent-toolkit/agent-runtime\';\n\nconst mockContext = createMockContext(\n  JSON.stringify({ sentiment: \'positive\', confidence: 0.9 })\n);\nconst output = await myAnalyzer.execute({ text: \'Great!\' }, mockContext);\nresultMatchers.expectSuccess(output.result);\n\`\`\`\n\n### Testing Conversational Flows\n\n\`\`\`typescript\n// Turn 1\nconst output1 = await agent.execute({ message: \'Hello\' });\nexpect(output1.reply).toContain(\'name?\');\nresultMatchers.expectInProgress(output1.result);\n\n// Turn 2 — pass session state forward\nconst output2 = await agent.execute({\n  message: \'My name is Alice\',\n  sessionState: output1.sessionState,\n});\n\`\`\`\n\n## Best Practices\n\n1. **Return result envelopes, never throw** for expected errors\n2. **Define error types as literal unions** (\`\'invalid-format\' | \'timeout\'\`) not \`string\`\n3. **Use Zod schemas** for all input/output validation\n4. **Test all paths** — success, each error type, edge cases\n5. **Use mock mode** for external dependencies to enable offline testing\n6. **Document with JSDoc** — purpose, params, return type, example, \`@throws Never throws\`\n7. **Keep SKILL.md focused** — if it exceeds ~300 lines, split into action skills\n\n## References\n\n- [Skill Quality and Compatibility — VAT\'s Stance](../../../../docs/skill-quality-and-compatibility.md) — 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.\n- [Validation Codes Reference](../../../../docs/validation-codes.md) — full list of codes VAT emits, their default severity, and override recipes.\n- [Skill Quality Checklist](skill-quality-checklist.md) — Pre-publication checklist for all skills (general + CLI-backed)\n- [agent-authoring.md](../../../../docs/agent-authoring.md) — Complete patterns guide\n- [orchestration.md](../../../../docs/orchestration.md) — Multi-agent workflows\n- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents)\n";
+export const text = "\n# VAT Agent Authoring: Archetypes, Envelopes, Orchestration\n\nThis 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\`.\n\n## Agent Archetypes\n\nVAT supports four agent archetypes for different use cases.\n\n### Archetype 1: Pure Function Tool\n\n**When to use:** Stateless validation, transformation, computation — no LLM needed.\n\n**Characteristics:** Deterministic output, fast execution, easy to test.\n\n**Example use cases:** Input validation, data transformation, format conversion, rules-based logic.\n\n\`\`\`typescript\nexport async function validateInput(input: MyInput): Promise<ValidationResult> {\n  if (input.text.length < 5) {\n    return { status: \'error\', error: \'too-short\' };\n  }\n  return { status: \'success\', data: { valid: true } };\n}\n\`\`\`\n\n### Archetype 2: One-Shot LLM Analyzer\n\n**When to use:** Single LLM call for analysis, classification, or generation.\n\n**Characteristics:** One LLM call per execution, stateless, handles LLM errors.\n\n**Example use cases:** Sentiment analysis, text classification, entity extraction, creative generation.\n\n\`\`\`typescript\nexport async function analyzeSentiment(text: string, context: AgentContext) {\n  const response = await context.callLLM([\n    { role: \'user\', content: \`Analyze sentiment: \"${text}\"\` }\n  ]);\n\n  const parsed = JSON.parse(response);\n  return { status: \'success\', data: parsed };\n}\n\`\`\`\n\n### Archetype 3: Conversational Assistant\n\n**When to use:** Multi-turn dialogue, progressive data collection across sessions.\n\n**Characteristics:** Multiple LLM calls, maintains session state, phases (gathering → ready → complete).\n\n**Example use cases:** Customer support chatbots, product advisors, interview agents, multi-step forms.\n\n\`\`\`typescript\nexport async function conversationalAgent(\n  message: string,\n  sessionState: SessionState\n) {\n  if (sessionState.phase === \'gathering\') {\n    return {\n      reply: \"Can you tell me more about X?\",\n      sessionState: { ...sessionState },\n      result: { status: \'in-progress\' }\n    };\n  }\n\n  return {\n    reply: \"Here\'s your result!\",\n    sessionState: { ...sessionState, phase: \'complete\' },\n    result: { status: \'success\', data: finalResult }\n  };\n}\n\`\`\`\n\n### Archetype 4: External Event Integrator\n\n**When to use:** Waiting for external events (approvals, webhooks, third-party APIs).\n\n**Characteristics:** Emits event, blocks waiting for response, timeout handling, mockable for testing.\n\n**Example use cases:** Human-in-the-loop approval, webhook integrations, external API polling.\n\n\`\`\`typescript\nexport async function humanApproval(\n  request: ApprovalRequest,\n  options = { mockable: true, timeout: 30000 }\n) {\n  if (options.mockable) {\n    return { status: \'success\', data: { approved: true } };\n  }\n\n  const response = await emitEvent(request, options.timeout);\n  return { status: \'success\', data: response };\n}\n\`\`\`\n\n## Result Envelopes\n\nAlways return result envelopes — never throw exceptions for expected errors.\n\n\`\`\`typescript\n// AgentResult<TData, TError> — for single-execution agents\ntype AgentResult<TData, TError> =\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\n// StatefulAgentResult — for conversational agents\ntype StatefulAgentResult<TData, TError, TMetadata> =\n  | { status: \'in-progress\'; metadata?: TMetadata }\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\`\`\`\n\nStandard LLM error literals: \`\'llm-refusal\'\`, \`\'llm-invalid-output\'\`, \`\'llm-timeout\'\`, \`\'llm-rate-limit\'\`, \`\'llm-token-limit\'\`, \`\'llm-unavailable\'\`.\n\nAlways check status before accessing data:\n\n\`\`\`typescript\nconst output = await myAgent.execute(input);\nif (output.result.status === \'success\') {\n  console.log(output.result.data);\n} else if (output.result.status === \'error\') {\n  console.error(\'Failed:\', output.result.error);\n}\n\`\`\`\n\n## Orchestration Patterns\n\n### Sequential Pipeline\n\n\`\`\`typescript\nconst analysisOutput = await analyzer.execute(input);\nconst processedOutput = await andThen(\n  analysisOutput.result,\n  async (data) => {\n    const out = await processor.execute(data);\n    return out.result;\n  }\n);\n\`\`\`\n\n### Parallel Execution\n\n\`\`\`typescript\nconst [output1, output2, output3] = await Promise.all([\n  agent1.execute(input),\n  agent2.execute(input),\n  agent3.execute(input),\n]);\n\`\`\`\n\n### Validation Loop (Generate + Validate with Retry)\n\n\`\`\`typescript\nasync function generateValidOutput(input: MyInput, maxAttempts = 5) {\n  for (let attempt = 0; attempt < maxAttempts; attempt++) {\n    const generatorOutput = await generator.execute(input);\n    if (generatorOutput.result.status === \'error\') continue;\n\n    const validatorOutput = await validator.execute(generatorOutput.result.data);\n    if (validatorOutput.result.status === \'success\' &&\n        validatorOutput.result.data.valid) {\n      return generatorOutput.result.data;\n    }\n  }\n  throw new Error(\'Max attempts exceeded\');\n}\n\`\`\`\n\n### Human-in-the-Loop\n\n\`\`\`typescript\nconst generatorOutput = await generator.execute(input);\nif (generatorOutput.result.status === \'success\') {\n  const approvalOutput = await humanApproval.execute({\n    content: generatorOutput.result.data,\n    context: input,\n  });\n  if (approvalOutput.result.data.approved) {\n    return generatorOutput.result.data;\n  }\n}\n\`\`\`\n\n### Conversational Multi-Turn\n\n\`\`\`typescript\nlet session = { state: { phase: \'gathering\' }, history: [] };\n\nwhile (true) {\n  const userMessage = await getUserInput();\n  const output = await conversationalAgent.execute({\n    message: userMessage,\n    sessionState: session.state,\n  });\n\n  console.log(\'Agent:\', output.reply);\n  session = {\n    state: output.sessionState,\n    history: [...session.history,\n      { role: \'user\', content: userMessage },\n      { role: \'assistant\', content: output.reply }\n    ],\n  };\n\n  if (output.result.status === \'success\') break;\n  if (output.result.status === \'error\') break;\n  // status === \'in-progress\': continue\n}\n\`\`\`\n\n## Testing Agents\n\n### Unit Testing Pure Functions\n\n\`\`\`typescript\nimport { describe, expect, it } from \'vitest\';\nimport { resultMatchers } from \'@vibe-agent-toolkit/agent-runtime\';\n\ndescribe(\'myValidator\', () => {\n  it(\'should validate correct input\', async () => {\n    const output = await myValidator.execute({ text: \'valid\' });\n    resultMatchers.expectSuccess(output.result);\n    expect(output.result.data.valid).toBe(true);\n  });\n});\n\`\`\`\n\n### Integration Testing with Mock LLM\n\n\`\`\`typescript\nimport { createMockContext } from \'@vibe-agent-toolkit/agent-runtime\';\n\nconst mockContext = createMockContext(\n  JSON.stringify({ sentiment: \'positive\', confidence: 0.9 })\n);\nconst output = await myAnalyzer.execute({ text: \'Great!\' }, mockContext);\nresultMatchers.expectSuccess(output.result);\n\`\`\`\n\n### Testing Conversational Flows\n\n\`\`\`typescript\n// Turn 1\nconst output1 = await agent.execute({ message: \'Hello\' });\nexpect(output1.reply).toContain(\'name?\');\nresultMatchers.expectInProgress(output1.result);\n\n// Turn 2 — pass session state forward\nconst output2 = await agent.execute({\n  message: \'My name is Alice\',\n  sessionState: output1.sessionState,\n});\n\`\`\`\n\n## Best Practices\n\n1. **Return result envelopes, never throw** for expected errors.\n2. **Define error types as literal unions** (\`\'invalid-format\' | \'timeout\'\`), not \`string\`.\n3. **Use Zod schemas** for all input/output validation.\n4. **Test all paths** — success, each error type, edge cases.\n5. **Use mock mode** for external dependencies to enable offline testing.\n6. **Document with JSDoc** — purpose, params, return type, example, \`@throws Never throws\`.\n7. **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\`).\n\n## References\n\n- \`vibe-agent-toolkit:vat-skill-authoring\` — sibling skill covering SKILL.md frontmatter, body structure, references, packagingOptions, and validation overrides\n- \`vibe-agent-toolkit:vat-skill-review\` — pre-publication quality checklist\n- [agent-authoring.md](../../../../docs/agent-authoring.md) — Complete patterns guide\n- [orchestration.md](../../../../docs/orchestration.md) — Multi-agent workflows\n- [Building Effective Agents — Anthropic](https://www.anthropic.com/research/building-effective-agents)\n";
 
 export const fragments = {
-  skillmdStructure: {
-    header: "## SKILL.md Structure",
-    body: "A SKILL.md file is the definition file for a VAT agent skill. It tells Claude what the skill\ndoes and how to use it. All SKILL.md files must have YAML frontmatter:\n\n\`\`\`markdown\n---\nname: my-skill\ndescription: One sentence: what this skill does and when to use it (max 200 chars)\n---\n\n# My Skill\n\nRest of the skill documentation...\n\`\`\`\n\nRequired frontmatter fields:\n- \`name\` — unique identifier, kebab-case, matches the skill\'s directory name\n- \`description\` — trigger description used for skill routing; be specific about activation conditions\n\nBest practices for \`description\`:\n- Start with \"Use when...\" to make activation conditions explicit\n- Include the key commands or concepts the skill covers\n- Keep under 200 characters",
-    text: "## SKILL.md Structure\n\nA SKILL.md file is the definition file for a VAT agent skill. It tells Claude what the skill\ndoes and how to use it. All SKILL.md files must have YAML frontmatter:\n\n\`\`\`markdown\n---\nname: my-skill\ndescription: One sentence: what this skill does and when to use it (max 200 chars)\n---\n\n# My Skill\n\nRest of the skill documentation...\n\`\`\`\n\nRequired frontmatter fields:\n- \`name\` — unique identifier, kebab-case, matches the skill\'s directory name\n- \`description\` — trigger description used for skill routing; be specific about activation conditions\n\nBest practices for \`description\`:\n- Start with \"Use when...\" to make activation conditions explicit\n- Include the key commands or concepts the skill covers\n- Keep under 200 characters"
-  },
   agentArchetypes: {
     header: "## Agent Archetypes",
     body: "VAT supports four agent archetypes for different use cases.\n\n### Archetype 1: Pure Function Tool\n\n**When to use:** Stateless validation, transformation, computation — no LLM needed.\n\n**Characteristics:** Deterministic output, fast execution, easy to test.\n\n**Example use cases:** Input validation, data transformation, format conversion, rules-based logic.\n\n\`\`\`typescript\nexport async function validateInput(input: MyInput): Promise<ValidationResult> {\n  if (input.text.length < 5) {\n    return { status: \'error\', error: \'too-short\' };\n  }\n  return { status: \'success\', data: { valid: true } };\n}\n\`\`\`\n\n### Archetype 2: One-Shot LLM Analyzer\n\n**When to use:** Single LLM call for analysis, classification, or generation.\n\n**Characteristics:** One LLM call per execution, stateless, handles LLM errors.\n\n**Example use cases:** Sentiment analysis, text classification, entity extraction, creative generation.\n\n\`\`\`typescript\nexport async function analyzeSentiment(text: string, context: AgentContext) {\n  const response = await context.callLLM([\n    { role: \'user\', content: \`Analyze sentiment: \"${text}\"\` }\n  ]);\n\n  const parsed = JSON.parse(response);\n  return { status: \'success\', data: parsed };\n}\n\`\`\`\n\n### Archetype 3: Conversational Assistant\n\n**When to use:** Multi-turn dialogue, progressive data collection across sessions.\n\n**Characteristics:** Multiple LLM calls, maintains session state, phases (gathering → ready → complete).\n\n**Example use cases:** Customer support chatbots, product advisors, interview agents, multi-step forms.\n\n\`\`\`typescript\nexport async function conversationalAgent(\n  message: string,\n  sessionState: SessionState\n) {\n  if (sessionState.phase === \'gathering\') {\n    return {\n      reply: \"Can you tell me more about X?\",\n      sessionState: { ...sessionState },\n      result: { status: \'in-progress\' }\n    };\n  }\n\n  return {\n    reply: \"Here\'s your result!\",\n    sessionState: { ...sessionState, phase: \'complete\' },\n    result: { status: \'success\', data: finalResult }\n  };\n}\n\`\`\`\n\n### Archetype 4: External Event Integrator\n\n**When to use:** Waiting for external events (approvals, webhooks, third-party APIs).\n\n**Characteristics:** Emits event, blocks waiting for response, timeout handling, mockable for testing.\n\n**Example use cases:** Human-in-the-loop approval, webhook integrations, external API polling.\n\n\`\`\`typescript\nexport async function humanApproval(\n  request: ApprovalRequest,\n  options = { mockable: true, timeout: 30000 }\n) {\n  if (options.mockable) {\n    return { status: \'success\', data: { approved: true } };\n  }\n\n  const response = await emitEvent(request, options.timeout);\n  return { status: \'success\', data: response };\n}\n\`\`\`",
@@ -22,19 +17,14 @@ export const fragments = {
   },
   resultEnvelopes: {
     header: "## Result Envelopes",
-    body: "Always return result envelopes — never throw exceptions for expected errors.\n\n\`\`\`typescript\n// AgentResult<TData, TError> — for single-execution agents\ntype AgentResult<TData, TError> =\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\n// StatefulAgentResult — for conversational agents\ntype StatefulAgentResult<TData, TError, TMetadata> =\n  | { status: \'in-progress\'; metadata?: TMetadata }\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\`\`\`\n\nStandard LLM error literals: \`\'llm-refusal\'\`, \`\'llm-invalid-output\'\`, \`\'llm-timeout\'\`,\n\`\'llm-rate-limit\'\`, \`\'llm-token-limit\'\`, \`\'llm-unavailable\'\`.\n\nAlways check status before accessing data:\n\`\`\`typescript\nconst output = await myAgent.execute(input);\nif (output.result.status === \'success\') {\n  console.log(output.result.data);\n} else if (output.result.status === \'error\') {\n  console.error(\'Failed:\', output.result.error);\n}\n\`\`\`",
-    text: "## Result Envelopes\n\nAlways return result envelopes — never throw exceptions for expected errors.\n\n\`\`\`typescript\n// AgentResult<TData, TError> — for single-execution agents\ntype AgentResult<TData, TError> =\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\n// StatefulAgentResult — for conversational agents\ntype StatefulAgentResult<TData, TError, TMetadata> =\n  | { status: \'in-progress\'; metadata?: TMetadata }\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\`\`\`\n\nStandard LLM error literals: \`\'llm-refusal\'\`, \`\'llm-invalid-output\'\`, \`\'llm-timeout\'\`,\n\`\'llm-rate-limit\'\`, \`\'llm-token-limit\'\`, \`\'llm-unavailable\'\`.\n\nAlways check status before accessing data:\n\`\`\`typescript\nconst output = await myAgent.execute(input);\nif (output.result.status === \'success\') {\n  console.log(output.result.data);\n} else if (output.result.status === \'error\') {\n  console.error(\'Failed:\', output.result.error);\n}\n\`\`\`"
+    body: "Always return result envelopes — never throw exceptions for expected errors.\n\n\`\`\`typescript\n// AgentResult<TData, TError> — for single-execution agents\ntype AgentResult<TData, TError> =\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\n// StatefulAgentResult — for conversational agents\ntype StatefulAgentResult<TData, TError, TMetadata> =\n  | { status: \'in-progress\'; metadata?: TMetadata }\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\`\`\`\n\nStandard LLM error literals: \`\'llm-refusal\'\`, \`\'llm-invalid-output\'\`, \`\'llm-timeout\'\`, \`\'llm-rate-limit\'\`, \`\'llm-token-limit\'\`, \`\'llm-unavailable\'\`.\n\nAlways check status before accessing data:\n\n\`\`\`typescript\nconst output = await myAgent.execute(input);\nif (output.result.status === \'success\') {\n  console.log(output.result.data);\n} else if (output.result.status === \'error\') {\n  console.error(\'Failed:\', output.result.error);\n}\n\`\`\`",
+    text: "## Result Envelopes\n\nAlways return result envelopes — never throw exceptions for expected errors.\n\n\`\`\`typescript\n// AgentResult<TData, TError> — for single-execution agents\ntype AgentResult<TData, TError> =\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\n// StatefulAgentResult — for conversational agents\ntype StatefulAgentResult<TData, TError, TMetadata> =\n  | { status: \'in-progress\'; metadata?: TMetadata }\n  | { status: \'success\'; data: TData }\n  | { status: \'error\'; error: TError };\n\`\`\`\n\nStandard LLM error literals: \`\'llm-refusal\'\`, \`\'llm-invalid-output\'\`, \`\'llm-timeout\'\`, \`\'llm-rate-limit\'\`, \`\'llm-token-limit\'\`, \`\'llm-unavailable\'\`.\n\nAlways check status before accessing data:\n\n\`\`\`typescript\nconst output = await myAgent.execute(input);\nif (output.result.status === \'success\') {\n  console.log(output.result.data);\n} else if (output.result.status === \'error\') {\n  console.error(\'Failed:\', output.result.error);\n}\n\`\`\`"
   },
   orchestrationPatterns: {
     header: "## Orchestration Patterns",
     body: "### Sequential Pipeline\n\n\`\`\`typescript\nconst analysisOutput = await analyzer.execute(input);\nconst processedOutput = await andThen(\n  analysisOutput.result,\n  async (data) => {\n    const out = await processor.execute(data);\n    return out.result;\n  }\n);\n\`\`\`\n\n### Parallel Execution\n\n\`\`\`typescript\nconst [output1, output2, output3] = await Promise.all([\n  agent1.execute(input),\n  agent2.execute(input),\n  agent3.execute(input),\n]);\n\`\`\`\n\n### Validation Loop (Generate + Validate with Retry)\n\n\`\`\`typescript\nasync function generateValidOutput(input: MyInput, maxAttempts = 5) {\n  for (let attempt = 0; attempt < maxAttempts; attempt++) {\n    const generatorOutput = await generator.execute(input);\n    if (generatorOutput.result.status === \'error\') continue;\n\n    const validatorOutput = await validator.execute(generatorOutput.result.data);\n    if (validatorOutput.result.status === \'success\' &&\n        validatorOutput.result.data.valid) {\n      return generatorOutput.result.data;\n    }\n  }\n  throw new Error(\'Max attempts exceeded\');\n}\n\`\`\`\n\n### Human-in-the-Loop\n\n\`\`\`typescript\nconst generatorOutput = await generator.execute(input);\nif (generatorOutput.result.status === \'success\') {\n  const approvalOutput = await humanApproval.execute({\n    content: generatorOutput.result.data,\n    context: input,\n  });\n  if (approvalOutput.result.data.approved) {\n    return generatorOutput.result.data;\n  }\n}\n\`\`\`\n\n### Conversational Multi-Turn\n\n\`\`\`typescript\nlet session = { state: { phase: \'gathering\' }, history: [] };\n\nwhile (true) {\n  const userMessage = await getUserInput();\n  const output = await conversationalAgent.execute({\n    message: userMessage,\n    sessionState: session.state,\n  });\n\n  console.log(\'Agent:\', output.reply);\n  session = {\n    state: output.sessionState,\n    history: [...session.history,\n      { role: \'user\', content: userMessage },\n      { role: \'assistant\', content: output.reply }\n    ],\n  };\n\n  if (output.result.status === \'success\') break;\n  if (output.result.status === \'error\') break;\n  // status === \'in-progress\': continue\n}\n\`\`\`",
     text: "## Orchestration Patterns\n\n### Sequential Pipeline\n\n\`\`\`typescript\nconst analysisOutput = await analyzer.execute(input);\nconst processedOutput = await andThen(\n  analysisOutput.result,\n  async (data) => {\n    const out = await processor.execute(data);\n    return out.result;\n  }\n);\n\`\`\`\n\n### Parallel Execution\n\n\`\`\`typescript\nconst [output1, output2, output3] = await Promise.all([\n  agent1.execute(input),\n  agent2.execute(input),\n  agent3.execute(input),\n]);\n\`\`\`\n\n### Validation Loop (Generate + Validate with Retry)\n\n\`\`\`typescript\nasync function generateValidOutput(input: MyInput, maxAttempts = 5) {\n  for (let attempt = 0; attempt < maxAttempts; attempt++) {\n    const generatorOutput = await generator.execute(input);\n    if (generatorOutput.result.status === \'error\') continue;\n\n    const validatorOutput = await validator.execute(generatorOutput.result.data);\n    if (validatorOutput.result.status === \'success\' &&\n        validatorOutput.result.data.valid) {\n      return generatorOutput.result.data;\n    }\n  }\n  throw new Error(\'Max attempts exceeded\');\n}\n\`\`\`\n\n### Human-in-the-Loop\n\n\`\`\`typescript\nconst generatorOutput = await generator.execute(input);\nif (generatorOutput.result.status === \'success\') {\n  const approvalOutput = await humanApproval.execute({\n    content: generatorOutput.result.data,\n    context: input,\n  });\n  if (approvalOutput.result.data.approved) {\n    return generatorOutput.result.data;\n  }\n}\n\`\`\`\n\n### Conversational Multi-Turn\n\n\`\`\`typescript\nlet session = { state: { phase: \'gathering\' }, history: [] };\n\nwhile (true) {\n  const userMessage = await getUserInput();\n  const output = await conversationalAgent.execute({\n    message: userMessage,\n    sessionState: session.state,\n  });\n\n  console.log(\'Agent:\', output.reply);\n  session = {\n    state: output.sessionState,\n    history: [...session.history,\n      { role: \'user\', content: userMessage },\n      { role: \'assistant\', content: output.reply }\n    ],\n  };\n\n  if (output.result.status === \'success\') break;\n  if (output.result.status === \'error\') break;\n  // status === \'in-progress\': continue\n}\n\`\`\`"
   },
-  packagingoptionsReference: {
-    header: "## packagingOptions Reference",
-    body: "Configure in your skill\'s \`vat.skills[]\` entry in \`package.json\`:\n\n\`\`\`json\n{\n  \"vat\": {\n    \"skills\": [{\n      \"name\": \"my-skill\",\n      \"source\": \"./SKILL.md\",\n      \"path\": \"./dist/skills/my-skill\",\n      \"packagingOptions\": {\n        \"linkFollowDepth\": 1,\n        \"resourceNaming\": \"resource-id\",\n        \"stripPrefix\": \"knowledge-base\",\n        \"excludeReferencesFromBundle\": {\n          \"rules\": [\n            { \"patterns\": [\"**/concepts/**\"], \"template\": \"Use search to find: {{link.text}}\" }\n          ],\n          \"defaultTemplate\": \"{{link.text}} (search knowledge base)\"\n        }\n      }\n    }]\n  }\n}\n\`\`\`\n\n**\`linkFollowDepth\`** — How deep to follow links from SKILL.md:\n\n| Value | Behavior |\n|-------|----------|\n| \`0\` | Skill file only (no links followed) |\n| \`1\` | Direct links only |\n| \`2\` | Direct + one transitive level **(default)** |\n| \`\"full\"\` | Complete transitive closure |\n\n**\`resourceNaming\`** — How bundled files are named:\n\n| Strategy | Example | Use When |\n|----------|---------|----------|\n| \`basename\` | \`overview.md\` | Few files, unique names **(default)** |\n| \`resource-id\` | \`topics-quickstart-overview.md\` | Many files, flat output |\n| \`preserve-path\` | \`topics/quickstart/overview.md\` | Preserve structure |\n\nUse \`stripPrefix\` to remove a common directory prefix (e.g., \`\"knowledge-base\"\`).\n\n**\`excludeReferencesFromBundle\`** — Rules for excluding files and rewriting their links:\n- \`rules[]\` — Ordered glob patterns (first match wins), each with optional Handlebars template\n- \`defaultTemplate\` — Applied to depth-exceeded links not matching any rule\n\n**Template variables:**\n\n| Variable | Description |\n|----------|-------------|\n| \`{{link.text}}\` | Link display text |\n| \`{{link.href}}\` | Original href (without fragment) |\n| \`{{link.fragment}}\` | Fragment including \`#\` prefix, or empty |\n| \`{{link.type}}\` | Link type (\`\"local_file\"\`, etc.) |\n| \`{{link.resource.id}}\` | Target resource ID (if resolved) |\n| \`{{link.resource.fileName}}\` | Target filename (if resolved) |\n| \`{{skill.name}}\` | Skill name from frontmatter |\n\n**\`validation\`** — Unified framework for overriding default severity and allowing specific issue instances:\n\n\`\`\`yaml\n# In vibe-agent-toolkit.config.yaml under skills.defaults or skills.config.<name>\nvalidation:\n  severity:\n    LINK_DROPPED_BY_DEPTH: error           # upgrade: block on depth-dropped links\n    LINK_TO_NAVIGATION_FILE: ignore        # silence: this skill intentionally links to READMEs\n  allow:\n    PACKAGED_UNREFERENCED_FILE:\n      - paths: [\"templates/runtime.json\"]\n        reason: \"consumed programmatically at runtime\"\n        expires: \"2026-09-30\"\n    SKILL_LENGTH_EXCEEDS_RECOMMENDED:\n      - reason: \"whole-skill concern; paths defaults to [\'**/*\']\"\n\`\`\`\n\nTwo sub-keys, each covering a different override granularity:\n\n- **\`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.\n- **\`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.\n\nThings adopters typically adjust:\n\n- Downgrade \`LINK_DROPPED_BY_DEPTH\` to \`ignore\` when intentionally linking out to external docs.\n- Allow specific files under \`PACKAGED_UNREFERENCED_FILE\` when they\'re consumed programmatically by CLI scripts at runtime.\n- Raise \`ALLOW_EXPIRED\` to \`error\` for zero-tolerance expiry policies.\n\nExpired \`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).\n\nFull 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.",
-    text: "## packagingOptions Reference\n\nConfigure in your skill\'s \`vat.skills[]\` entry in \`package.json\`:\n\n\`\`\`json\n{\n  \"vat\": {\n    \"skills\": [{\n      \"name\": \"my-skill\",\n      \"source\": \"./SKILL.md\",\n      \"path\": \"./dist/skills/my-skill\",\n      \"packagingOptions\": {\n        \"linkFollowDepth\": 1,\n        \"resourceNaming\": \"resource-id\",\n        \"stripPrefix\": \"knowledge-base\",\n        \"excludeReferencesFromBundle\": {\n          \"rules\": [\n            { \"patterns\": [\"**/concepts/**\"], \"template\": \"Use search to find: {{link.text}}\" }\n          ],\n          \"defaultTemplate\": \"{{link.text}} (search knowledge base)\"\n        }\n      }\n    }]\n  }\n}\n\`\`\`\n\n**\`linkFollowDepth\`** — How deep to follow links from SKILL.md:\n\n| Value | Behavior |\n|-------|----------|\n| \`0\` | Skill file only (no links followed) |\n| \`1\` | Direct links only |\n| \`2\` | Direct + one transitive level **(default)** |\n| \`\"full\"\` | Complete transitive closure |\n\n**\`resourceNaming\`** — How bundled files are named:\n\n| Strategy | Example | Use When |\n|----------|---------|----------|\n| \`basename\` | \`overview.md\` | Few files, unique names **(default)** |\n| \`resource-id\` | \`topics-quickstart-overview.md\` | Many files, flat output |\n| \`preserve-path\` | \`topics/quickstart/overview.md\` | Preserve structure |\n\nUse \`stripPrefix\` to remove a common directory prefix (e.g., \`\"knowledge-base\"\`).\n\n**\`excludeReferencesFromBundle\`** — Rules for excluding files and rewriting their links:\n- \`rules[]\` — Ordered glob patterns (first match wins), each with optional Handlebars template\n- \`defaultTemplate\` — Applied to depth-exceeded links not matching any rule\n\n**Template variables:**\n\n| Variable | Description |\n|----------|-------------|\n| \`{{link.text}}\` | Link display text |\n| \`{{link.href}}\` | Original href (without fragment) |\n| \`{{link.fragment}}\` | Fragment including \`#\` prefix, or empty |\n| \`{{link.type}}\` | Link type (\`\"local_file\"\`, etc.) |\n| \`{{link.resource.id}}\` | Target resource ID (if resolved) |\n| \`{{link.resource.fileName}}\` | Target filename (if resolved) |\n| \`{{skill.name}}\` | Skill name from frontmatter |\n\n**\`validation\`** — Unified framework for overriding default severity and allowing specific issue instances:\n\n\`\`\`yaml\n# In vibe-agent-toolkit.config.yaml under skills.defaults or skills.config.<name>\nvalidation:\n  severity:\n    LINK_DROPPED_BY_DEPTH: error           # upgrade: block on depth-dropped links\n    LINK_TO_NAVIGATION_FILE: ignore        # silence: this skill intentionally links to READMEs\n  allow:\n    PACKAGED_UNREFERENCED_FILE:\n      - paths: [\"templates/runtime.json\"]\n        reason: \"consumed programmatically at runtime\"\n        expires: \"2026-09-30\"\n    SKILL_LENGTH_EXCEEDS_RECOMMENDED:\n      - reason: \"whole-skill concern; paths defaults to [\'**/*\']\"\n\`\`\`\n\nTwo sub-keys, each covering a different override granularity:\n\n- **\`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.\n- **\`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.\n\nThings adopters typically adjust:\n\n- Downgrade \`LINK_DROPPED_BY_DEPTH\` to \`ignore\` when intentionally linking out to external docs.\n- Allow specific files under \`PACKAGED_UNREFERENCED_FILE\` when they\'re consumed programmatically by CLI scripts at runtime.\n- Raise \`ALLOW_EXPIRED\` to \`error\` for zero-tolerance expiry policies.\n\nExpired \`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).\n\nFull 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."
-  },
   testingAgents: {
     header: "## Testing Agents",
     body: "### Unit Testing Pure Functions\n\n\`\`\`typescript\nimport { describe, expect, it } from \'vitest\';\nimport { resultMatchers } from \'@vibe-agent-toolkit/agent-runtime\';\n\ndescribe(\'myValidator\', () => {\n  it(\'should validate correct input\', async () => {\n    const output = await myValidator.execute({ text: \'valid\' });\n    resultMatchers.expectSuccess(output.result);\n    expect(output.result.data.valid).toBe(true);\n  });\n});\n\`\`\`\n\n### Integration Testing with Mock LLM\n\n\`\`\`typescript\nimport { createMockContext } from \'@vibe-agent-toolkit/agent-runtime\';\n\nconst mockContext = createMockContext(\n  JSON.stringify({ sentiment: \'positive\', confidence: 0.9 })\n);\nconst output = await myAnalyzer.execute({ text: \'Great!\' }, mockContext);\nresultMatchers.expectSuccess(output.result);\n\`\`\`\n\n### Testing Conversational Flows\n\n\`\`\`typescript\n// Turn 1\nconst output1 = await agent.execute({ message: \'Hello\' });\nexpect(output1.reply).toContain(\'name?\');\nresultMatchers.expectInProgress(output1.result);\n\n// Turn 2 — pass session state forward\nconst output2 = await agent.execute({\n  message: \'My name is Alice\',\n  sessionState: output1.sessionState,\n});\n\`\`\`",
@@ -42,12 +32,12 @@ export const fragments = {
   },
   bestPractices: {
     header: "## Best Practices",
-    body: "1. **Return result envelopes, never throw** for expected errors\n2. **Define error types as literal unions** (\`\'invalid-format\' | \'timeout\'\`) not \`string\`\n3. **Use Zod schemas** for all input/output validation\n4. **Test all paths** — success, each error type, edge cases\n5. **Use mock mode** for external dependencies to enable offline testing\n6. **Document with JSDoc** — purpose, params, return type, example, \`@throws Never throws\`\n7. **Keep SKILL.md focused** — if it exceeds ~300 lines, split into action skills",
-    text: "## Best Practices\n\n1. **Return result envelopes, never throw** for expected errors\n2. **Define error types as literal unions** (\`\'invalid-format\' | \'timeout\'\`) not \`string\`\n3. **Use Zod schemas** for all input/output validation\n4. **Test all paths** — success, each error type, edge cases\n5. **Use mock mode** for external dependencies to enable offline testing\n6. **Document with JSDoc** — purpose, params, return type, example, \`@throws Never throws\`\n7. **Keep SKILL.md focused** — if it exceeds ~300 lines, split into action skills"
+    body: "1. **Return result envelopes, never throw** for expected errors.\n2. **Define error types as literal unions** (\`\'invalid-format\' | \'timeout\'\`), not \`string\`.\n3. **Use Zod schemas** for all input/output validation.\n4. **Test all paths** — success, each error type, edge cases.\n5. **Use mock mode** for external dependencies to enable offline testing.\n6. **Document with JSDoc** — purpose, params, return type, example, \`@throws Never throws\`.\n7. **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\`).",
+    text: "## Best Practices\n\n1. **Return result envelopes, never throw** for expected errors.\n2. **Define error types as literal unions** (\`\'invalid-format\' | \'timeout\'\`), not \`string\`.\n3. **Use Zod schemas** for all input/output validation.\n4. **Test all paths** — success, each error type, edge cases.\n5. **Use mock mode** for external dependencies to enable offline testing.\n6. **Document with JSDoc** — purpose, params, return type, example, \`@throws Never throws\`.\n7. **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: {
     header: "## References",
-    body: "- [Skill Quality and Compatibility — VAT\'s Stance](../../../../docs/skill-quality-and-compatibility.md) — 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.\n- [Validation Codes Reference](../../../../docs/validation-codes.md) — full list of codes VAT emits, their default severity, and override recipes.\n- [Skill Quality Checklist](skill-quality-checklist.md) — Pre-publication checklist for all skills (general + CLI-backed)\n- [agent-authoring.md](../../../../docs/agent-authoring.md) — Complete patterns guide\n- [orchestration.md](../../../../docs/orchestration.md) — Multi-agent workflows\n- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents)",
-    text: "## References\n\n- [Skill Quality and Compatibility — VAT\'s Stance](../../../../docs/skill-quality-and-compatibility.md) — 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.\n- [Validation Codes Reference](../../../../docs/validation-codes.md) — full list of codes VAT emits, their default severity, and override recipes.\n- [Skill Quality Checklist](skill-quality-checklist.md) — Pre-publication checklist for all skills (general + CLI-backed)\n- [agent-authoring.md](../../../../docs/agent-authoring.md) — Complete patterns guide\n- [orchestration.md](../../../../docs/orchestration.md) — Multi-agent workflows\n- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents)"
+    body: "- \`vibe-agent-toolkit:vat-skill-authoring\` — sibling skill covering SKILL.md frontmatter, body structure, references, packagingOptions, and validation overrides\n- \`vibe-agent-toolkit:vat-skill-review\` — pre-publication quality checklist\n- [agent-authoring.md](../../../../docs/agent-authoring.md) — Complete patterns guide\n- [orchestration.md](../../../../docs/orchestration.md) — Multi-agent workflows\n- [Building Effective Agents — Anthropic](https://www.anthropic.com/research/building-effective-agents)",
+    text: "## References\n\n- \`vibe-agent-toolkit:vat-skill-authoring\` — sibling skill covering SKILL.md frontmatter, body structure, references, packagingOptions, and validation overrides\n- \`vibe-agent-toolkit:vat-skill-review\` — pre-publication quality checklist\n- [agent-authoring.md](../../../../docs/agent-authoring.md) — Complete patterns guide\n- [orchestration.md](../../../../docs/orchestration.md) — Multi-agent workflows\n- [Building Effective Agents — Anthropic](https://www.anthropic.com/research/building-effective-agents)"
   }
 };

package/dist/generated/resources/skills/vat-audit.js

@@ -3,7 +3,7 @@
  */
 
 export const meta = {
-  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."
 };