@vibe-agent-toolkit/vat-development-agents 0.1.29-rc.1 → 0.1.29-rc.3

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

@@ -9,8 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - **`vat verify --consistency-check`** — post-build verification that skill distribution config in `vibe-agent-toolkit.config.yaml` and `package.json` are consistent. Detects skills missing from `package.json`, orphaned entries, and publish opt-out mismatches. Runs automatically as part of `vat verify`.
+- **Post-build integrity checks for packaged skills** — `packageSkill()` now runs `PACKAGED_UNREFERENCED_FILE` and `PACKAGED_BROKEN_LINK` checks after copying files and rewriting links. Both are best-practice (overridable) errors surfaced via `PackageSkillResult.postBuildIssues`; the CLI logs them at info level (non-blocking). Suppress via `packagingOptions.ignoreValidationErrors`. Link extraction skips fenced code blocks and inline code spans so template strings aren't false-flagged.
+- **Skill quality checklist** — new `skill-quality-checklist.md` resource bundled with the agent-authoring skill. 21-item checklist covering general skill authoring (description triggering, length limits, third-person voice, time-sensitive content, references one-level-deep, TOCs on long files) plus CLI-backed skill specifics (env guards, auth checks, cross-platform commands, `files` config). Reviewed against external best practices (Anthropic docs, anthropics/skills, superpowers conventions, Claude Code release notes through 2026-04-15).
 
 ### Fixed
+- **`files` config in `skills.config.<name>.files` was parsed but not applied at build time** — `vat skills build` merged the `files` entries from `vibe-agent-toolkit.config.yaml` and validated them (`vat verify` correctly reported missing dests), but never passed them into `packageSkill()`, so declared files were silently skipped. Now CLI binaries and other build artifacts declared via `files` config are copied into skill output as intended.
+- **Skill bundler strips links to non-markdown bundled files** — links to YAML, JSON, and script files routed to `templates/`, `assets/`, or `scripts/` were rewritten to empty `()` because non-markdown assets weren't added to the output registry. Now all files in the path map are added to the output registry with their mapped output paths, including the duplicate-ID edge case for paired markdown/non-markdown files (e.g. `config.md` + `config.yaml`).
+- **Skill bundler strips depth-boundary links to already-bundled resources** — when resource D linked to resource C and C was already bundled via a shorter path from SKILL.md, the link from D→C was stripped because depth-exceeded exclusions were unconditionally added to `excludedIds`. Bundle membership now wins: `excludedIds` filters out resources already in `bundledResources`.
 - **Discovery scanner no longer traverses git worktrees** — `.worktrees/` and `.claude/worktrees/` added to `PERFORMANCE_POISON` exclusions, preventing the crawler from physically walking into worktree copies of the repo during scans.
 - **System tests no longer flaky from vitest worker timeout** — refactored `skills-list.system.test.ts` to run CLI spawns once in `beforeAll` instead of 5 redundant full-project scans. Same coverage, 70% faster (90s → 27s), eliminates the `onTaskUpdate` timeout.
 

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

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

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

@@ -368,6 +368,7 @@ const output2 = await agent.execute({
 
 ## References
 
-- [agent-authoring.md]() — Complete patterns guide
-- [orchestration.md]() — Multi-agent workflows
+- Skill Quality Checklist — Pre-publication checklist for all skills (general + CLI-backed)
+- agent-authoring.md — Complete patterns guide
+- orchestration.md — Multi-agent workflows
 - [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents)

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

@@ -79,7 +79,7 @@ Before changing VAT source code, write a test that reproduces the bug:
 - **CLI behavior** → add an integration test in `packages/cli/test/integration/`
 - **End-to-end workflow** → add a system test in `packages/cli/test/system/`
 
-See [docs/writing-tests.md]() for test patterns and
+See [docs/writing-tests.md](resources/writing-tests.md) for test patterns and
 the unit/integration/system classification guide.
 
 ## Step 5: Validate Before Committing
@@ -106,6 +106,6 @@ is safe to commit. Do not commit until `bun run validate` passes.
 
 ## See Also
 
-- [docs/debug-and-test-vat-fixes.md]() — Full reference
-- [docs/writing-tests.md]() — Test patterns and classification
-- [packages/cli/CLAUDE.md]() — CLI development guidelines
+- [docs/debug-and-test-vat-fixes.md](resources/debug-and-test-vat-fixes.md) — Full reference
+- [docs/writing-tests.md](resources/writing-tests.md) — Test patterns and classification
+- [packages/cli/CLAUDE.md](resources/CLAUDE.md) — CLI development guidelines

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

@@ -54,7 +54,7 @@ cd /path/to/adopter-project
 vat resources validate .   # now uses your local build
 ```
 
-Full debugging guide: [docs/debug-and-test-vat-fixes.md](../../docs/debug-and-test-vat-fixes.md)
+Full debugging guide: [docs/debug-and-test-vat-fixes.md](debug-and-test-vat-fixes.md)
 
 ## CLI Package Architecture Principles
 

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/debugging/resources/debug-and-test-vat-fixes.md

@@ -73,7 +73,7 @@ Reproduce the bug as a test before touching source code:
 | CLI command behavior | `packages/cli/test/integration/*.integration.test.ts` |
 | End-to-end workflow | `packages/cli/test/system/*.system.test.ts` |
 
-See [docs/writing-tests.md](./writing-tests.md) for patterns and classification guide.
+See [docs/writing-tests.md](writing-tests.md) for patterns and classification guide.
 
 Run just the test you added:
 ```bash
@@ -106,6 +106,6 @@ what changed. Do not commit until this passes.
 
 ## See Also
 
-- [docs/writing-tests.md](./writing-tests.md) — Full test classification and patterns
-- [packages/cli/CLAUDE.md](../packages/cli/CLAUDE.md) — CLI development guidelines
-- [docs/build-system.md](./build-system.md) — Build configuration reference
+- [docs/writing-tests.md](writing-tests.md) — Full test classification and patterns
+- [packages/cli/CLAUDE.md](CLAUDE.md) — CLI development guidelines
+- [docs/build-system.md]() — Build configuration reference

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

@@ -182,12 +182,12 @@ You've successfully adopted VAT when:
 
 ## Documentation Index
 
-- [Getting Started Guide]()
-- [Agent Authoring Guide]() — patterns and code examples
-- [Orchestration Guide]() — multi-agent workflows
-- [RAG Usage Guide]()
-- [Resource Compiler Guide]()
-- [Runtime Adapters]()
+- [Getting Started Guide](resources/getting-started.md)
+- [Agent Authoring Guide](resources/agent-authoring.md) — patterns and code examples
+- [Orchestration Guide](resources/orchestration.md) — multi-agent workflows
+- [RAG Usage Guide](resources/rag-usage-guide.md)
+- [Resource Compiler Guide](resources/compiling-markdown-to-typescript.md)
+- [Runtime Adapters](resources/adding-runtime-adapters.md)
 - Examples: `@vibe-agent-toolkit/vat-example-cat-agents`
 
 ## Running VAT

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

@@ -890,8 +890,8 @@ async execute(input, options = {}) {
 
 ## Related Documentation
 
-- [Orchestration Guide](./orchestration.md) - Composing agents into workflows
-- [Architecture Overview](./architecture/README.md) - Package structure
+- [Orchestration Guide](orchestration.md) - Composing agents into workflows
+- [Architecture Overview]() - Package structure
 
 ## Examples
 

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vibe-agent-toolkit/resources/compiling-markdown-to-typescript.md

@@ -473,29 +473,29 @@ import * as Doc from './doc.md';
 ## Next Steps
 
 ### For Package Publishers
-Read [Publishing TypeScript Resource Packages](./publishing-packages.md) to learn how to:
+Read [Publishing TypeScript Resource Packages]() to learn how to:
 - Set up package structure
 - Configure build scripts
 - Publish to npm
 - Include both compiled and original markdown
 
 ### For Package Consumers
-Read [Consuming TypeScript Resources](./consuming-packages.md) to learn how to:
+Read [Consuming TypeScript Resources]() to learn how to:
 - Install and import packages
 - Use type-safe compiled resources
 - Access original markdown for flexibility
 - Integrate with your project
 
 ### For Specific Use Cases
-- **Building AI agents?** → [Building Agent Prompt Libraries](./use-cases/agent-prompt-libraries.md)
-- **Creating RAG systems?** → [Creating RAG Knowledge Bases](./use-cases/rag-knowledge-bases.md)
-- **Building templates?** → [Template System Patterns](./use-cases/template-systems.md)
+- **Building AI agents?** → [Building Agent Prompt Libraries]()
+- **Creating RAG systems?** → [Creating RAG Knowledge Bases]()
+- **Building templates?** → [Template System Patterns]()
 
 ---
 
 ## See Also
 
-- [Resource Compiler README](../../../packages/resource-compiler/README.md) - Package documentation
-- [Publishing Packages](./publishing-packages.md) - Create and publish resource packages
-- [Consuming Packages](./consuming-packages.md) - Use published packages
-- [Guide Index](./README.md) - All resource compiler guides
+- [Resource Compiler README]() - Package documentation
+- [Publishing Packages]() - Create and publish resource packages
+- [Consuming Packages]() - Use published packages
+- [Guide Index]() - All resource compiler guides

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vibe-agent-toolkit/resources/getting-started.md

@@ -75,7 +75,7 @@ mkdir -p packages/my-package/src packages/my-package/test
 
 3. **Add package configuration**:
 
-Create `package.json`, `tsconfig.json` (with `composite: true`), and add to root `tsconfig.json` references. See [CLAUDE.md](../CLAUDE.md) Development Workflow section for complete details.
+Create `package.json`, `tsconfig.json` (with `composite: true`), and add to root `tsconfig.json` references. See [CLAUDE.md]() Development Workflow section for complete details.
 
 4. **Update root tsconfig.json**:
 
@@ -304,7 +304,7 @@ The audit command checks for:
 - Link integrity (broken links, invalid paths)
 - Console compatibility (tool availability)
 
-See [Audit Command Documentation](./cli/audit.md) for complete validation rules.
+See [Audit Command Documentation]() for complete validation rules.
 
 ### Importing Skills
 
@@ -339,13 +339,13 @@ vat test
 vat package
 ```
 
-See [Import Command Documentation](./cli/import.md) for more details.
+See [Import Command Documentation]() for more details.
 
 ## Next Steps
 
-- Read [CLAUDE.md](../CLAUDE.md) for detailed development guidelines
-- Review [Agent Skills Best Practices](./guides/agent-skills-best-practices.md)
-- Review the [utils package](../packages/utils/) for reference patterns
+- Read [CLAUDE.md]() for detailed development guidelines
+- Review [Agent Skills Best Practices]()
+- Review the [utils package]() for reference patterns
 - Check out [vibe-validate documentation](https://github.com/jdutton/vibe-validate)
 - Set up your CI/CD pipeline on GitHub
 - Enable Codecov for your repository (see README.md for setup instructions)

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vibe-agent-toolkit/resources/orchestration.md

@@ -839,8 +839,8 @@ interface BreedAdvisorMetadata {
 
 ## Related Documentation
 
-- [Agent Authoring Guide](./agent-authoring.md) - How to create agents with result envelopes
-- [Architecture Overview](./architecture/README.md) - Package structure and design principles
+- [Agent Authoring Guide](agent-authoring.md) - How to create agents with result envelopes
+- [Architecture Overview]() - Package structure and design principles
 
 ## Examples
 

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vibe-agent-toolkit/resources/rag-usage-guide.md

@@ -767,4 +767,4 @@ vat agent run doc-assistant "What's our code review process?"
 ---
 
 **See Also**:
-- [RAG Architecture](../architecture/rag.md)
+- [RAG Architecture]()

package/dist/generated/resources/skills/skill-quality-checklist.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Generated TypeScript declarations - DO NOT EDIT
+ */
+
+export interface Fragment {
+  readonly header: string;
+  readonly body: string;
+  readonly text: string;
+}
+
+export const meta: {};
+
+export const text: string;
+
+export const fragments: {
+  readonly general-AllSkills: Fragment;
+  readonly cliBackedSkills-AdditionalChecks: Fragment;
+  readonly usingThisChecklist: Fragment;
+};
+
+export type FragmentName = keyof typeof fragments;

package/dist/generated/resources/skills/skill-quality-checklist.js

@@ -0,0 +1,25 @@
+/**
+ * Generated from markdown file - DO NOT EDIT
+ */
+
+export const meta = {};
+
+export const text = "# Skill Quality Checklist\n\nWork through this checklist before publishing a skill. Items are grouped into general (all skills) and CLI-backed (skills that bundle and invoke scripts).\n\n## General — All Skills\n\n- [ ] **Name**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how.\n- [ ] **Description — trigger keywords first**: lead with the concepts that should trigger this skill. Claude truncates descriptions aggressively — the most important words must come first. \"Sprint analysis, velocity tracking, work item queries\" not \"This skill is used for when you need to analyze sprints.\"\n- [ ] **Description — no filler openers, third-person voice**: never start with \"This skill...\", \"A skill that...\", \"Used to...\", \"Use when you want to...\" — these waste the first tokens on zero-information words. Avoid first/second person (\"I can help...\", \"You can use...\") — Anthropic guidance is third person throughout.\n- [ ] **Description ≤250 characters**: Claude Code truncates descriptions at 250 characters in the \`/skills\` listing (since v2.1.86). Aim for ≤200 chars for safety; ≤130 chars if shipping a large skill collection (60+ skills) so the total budget fits.\n- [ ] **Purpose statement in first 3 lines**: an agent skimming the top of SKILL.md should understand what it does and when to use it without reading further.\n- [ ] **SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. Split detailed content into reference files when approaching the limit.\n- [ ] **Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- [ ] **Consistent terminology**: pick one term per concept and use it throughout. Switching between synonyms (\"artifact\" vs \"bundle\" vs \"package\") confuses agents.\n- [ ] **No time-sensitive content**: avoid \"as of November 2025\" or \"use the new API after July 2026\". Route deprecated guidance into a clearly labeled \"old patterns\" section so agents skip it.\n- [ ] **Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. Dead files confuse agents and waste context.\n- [ ] **References one level deep**: link reference files directly from SKILL.md, not via intermediate hubs. Claude does partial reads on nested references and may miss content several hops down.\n- [ ] **TOC on reference files >100 lines**: long reference files should include a table of contents at the top. Claude often previews with partial reads — a TOC ensures the full scope of available content is visible.\n- [ ] **All links resolve**: every \`[text](path)\` link points to a file that exists. Run \`vat verify\` to check.\n- [ ] **Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- [ ] **Test the trigger**: ask yourself \"if an agent sees only this name and description, will it know when to load this skill?\" If you need to read the SKILL.md to understand the description, the description is wrong.\n\n## CLI-Backed Skills — Additional Checks\n\nThese apply to skills that bundle executable scripts and instruct agents to run commands.\n\n- [ ] **Environment guard**: the skill checks that the CLI binary exists before running commands (e.g., verify \`scripts/cli.mjs\` is present). Agents should get a clear error, not a cryptic Node.js stack trace.\n- [ ] **Pre-flight auth check**: if the CLI requires credentials or tokens, the skill verifies them before operations. Fail fast with clear guidance on how to authenticate.\n- [ ] **CLI invocation section**: provide exact command patterns with placeholder arguments. Agents copy these verbatim — ambiguous prose gets misinterpreted.\n- [ ] **Error handling guidance**: document what to do when the CLI fails. Which errors are retryable? When should the agent stop and ask the user?\n- [ ] **No bare command names in prose or tables**: agents may try to execute anything that looks like a command. Wrap command references in context or use code blocks with clear framing.\n- [ ] **Cross-platform commands**: avoid \`timeout\` (not on macOS), platform-specific \`sed\` flags, \`grep -P\`, and other non-portable utilities. If platform-specific, document alternatives.\n- [ ] **\`files\` config declares CLI binaries**: use \`files\` entries in \`vibe-agent-toolkit.config.yaml\` so VAT copies scripts into the skill package at build time. Don\'t rely on external copy scripts.\n- [ ] **Document bundled assets and templates**: if scripts reference files programmatically (not via markdown links), explain what\'s bundled and why in the SKILL.md. The consuming agent should understand the full package contents.\n\n## Using This Checklist\n\nThis is a living document. When a new failure pattern is discovered in skill authoring, add a checklist item here. The goal is shift-left: catch issues before they ship rather than debugging them in production.\n\nItems marked as checks (not automated validation) are judgment calls that tooling can\'t fully enforce. An agent or human reviews them manually. Items that _can_ be automated are already enforced by \`vat verify\` — this checklist covers the gaps.\n\nReviewed against external best practices (Anthropic skills documentation, anthropics/skills repository, superpowers conventions, Claude Code release notes through 2026-04-15) before initial publication.\n";
+
+export const fragments = {
+  general-AllSkills: {
+    header: "## General — All Skills",
+    body: "- [ ] **Name**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how.\n- [ ] **Description — trigger keywords first**: lead with the concepts that should trigger this skill. Claude truncates descriptions aggressively — the most important words must come first. \"Sprint analysis, velocity tracking, work item queries\" not \"This skill is used for when you need to analyze sprints.\"\n- [ ] **Description — no filler openers, third-person voice**: never start with \"This skill...\", \"A skill that...\", \"Used to...\", \"Use when you want to...\" — these waste the first tokens on zero-information words. Avoid first/second person (\"I can help...\", \"You can use...\") — Anthropic guidance is third person throughout.\n- [ ] **Description ≤250 characters**: Claude Code truncates descriptions at 250 characters in the \`/skills\` listing (since v2.1.86). Aim for ≤200 chars for safety; ≤130 chars if shipping a large skill collection (60+ skills) so the total budget fits.\n- [ ] **Purpose statement in first 3 lines**: an agent skimming the top of SKILL.md should understand what it does and when to use it without reading further.\n- [ ] **SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. Split detailed content into reference files when approaching the limit.\n- [ ] **Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- [ ] **Consistent terminology**: pick one term per concept and use it throughout. Switching between synonyms (\"artifact\" vs \"bundle\" vs \"package\") confuses agents.\n- [ ] **No time-sensitive content**: avoid \"as of November 2025\" or \"use the new API after July 2026\". Route deprecated guidance into a clearly labeled \"old patterns\" section so agents skip it.\n- [ ] **Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. Dead files confuse agents and waste context.\n- [ ] **References one level deep**: link reference files directly from SKILL.md, not via intermediate hubs. Claude does partial reads on nested references and may miss content several hops down.\n- [ ] **TOC on reference files >100 lines**: long reference files should include a table of contents at the top. Claude often previews with partial reads — a TOC ensures the full scope of available content is visible.\n- [ ] **All links resolve**: every \`[text](path)\` link points to a file that exists. Run \`vat verify\` to check.\n- [ ] **Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- [ ] **Test the trigger**: ask yourself \"if an agent sees only this name and description, will it know when to load this skill?\" If you need to read the SKILL.md to understand the description, the description is wrong.",
+    text: "## General — All Skills\n\n- [ ] **Name**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how.\n- [ ] **Description — trigger keywords first**: lead with the concepts that should trigger this skill. Claude truncates descriptions aggressively — the most important words must come first. \"Sprint analysis, velocity tracking, work item queries\" not \"This skill is used for when you need to analyze sprints.\"\n- [ ] **Description — no filler openers, third-person voice**: never start with \"This skill...\", \"A skill that...\", \"Used to...\", \"Use when you want to...\" — these waste the first tokens on zero-information words. Avoid first/second person (\"I can help...\", \"You can use...\") — Anthropic guidance is third person throughout.\n- [ ] **Description ≤250 characters**: Claude Code truncates descriptions at 250 characters in the \`/skills\` listing (since v2.1.86). Aim for ≤200 chars for safety; ≤130 chars if shipping a large skill collection (60+ skills) so the total budget fits.\n- [ ] **Purpose statement in first 3 lines**: an agent skimming the top of SKILL.md should understand what it does and when to use it without reading further.\n- [ ] **SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. Split detailed content into reference files when approaching the limit.\n- [ ] **Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- [ ] **Consistent terminology**: pick one term per concept and use it throughout. Switching between synonyms (\"artifact\" vs \"bundle\" vs \"package\") confuses agents.\n- [ ] **No time-sensitive content**: avoid \"as of November 2025\" or \"use the new API after July 2026\". Route deprecated guidance into a clearly labeled \"old patterns\" section so agents skip it.\n- [ ] **Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. Dead files confuse agents and waste context.\n- [ ] **References one level deep**: link reference files directly from SKILL.md, not via intermediate hubs. Claude does partial reads on nested references and may miss content several hops down.\n- [ ] **TOC on reference files >100 lines**: long reference files should include a table of contents at the top. Claude often previews with partial reads — a TOC ensures the full scope of available content is visible.\n- [ ] **All links resolve**: every \`[text](path)\` link points to a file that exists. Run \`vat verify\` to check.\n- [ ] **Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- [ ] **Test the trigger**: ask yourself \"if an agent sees only this name and description, will it know when to load this skill?\" If you need to read the SKILL.md to understand the description, the description is wrong."
+  },
+  cliBackedSkills-AdditionalChecks: {
+    header: "## CLI-Backed Skills — Additional Checks",
+    body: "These apply to skills that bundle executable scripts and instruct agents to run commands.\n\n- [ ] **Environment guard**: the skill checks that the CLI binary exists before running commands (e.g., verify \`scripts/cli.mjs\` is present). Agents should get a clear error, not a cryptic Node.js stack trace.\n- [ ] **Pre-flight auth check**: if the CLI requires credentials or tokens, the skill verifies them before operations. Fail fast with clear guidance on how to authenticate.\n- [ ] **CLI invocation section**: provide exact command patterns with placeholder arguments. Agents copy these verbatim — ambiguous prose gets misinterpreted.\n- [ ] **Error handling guidance**: document what to do when the CLI fails. Which errors are retryable? When should the agent stop and ask the user?\n- [ ] **No bare command names in prose or tables**: agents may try to execute anything that looks like a command. Wrap command references in context or use code blocks with clear framing.\n- [ ] **Cross-platform commands**: avoid \`timeout\` (not on macOS), platform-specific \`sed\` flags, \`grep -P\`, and other non-portable utilities. If platform-specific, document alternatives.\n- [ ] **\`files\` config declares CLI binaries**: use \`files\` entries in \`vibe-agent-toolkit.config.yaml\` so VAT copies scripts into the skill package at build time. Don\'t rely on external copy scripts.\n- [ ] **Document bundled assets and templates**: if scripts reference files programmatically (not via markdown links), explain what\'s bundled and why in the SKILL.md. The consuming agent should understand the full package contents.",
+    text: "## CLI-Backed Skills — Additional Checks\n\nThese apply to skills that bundle executable scripts and instruct agents to run commands.\n\n- [ ] **Environment guard**: the skill checks that the CLI binary exists before running commands (e.g., verify \`scripts/cli.mjs\` is present). Agents should get a clear error, not a cryptic Node.js stack trace.\n- [ ] **Pre-flight auth check**: if the CLI requires credentials or tokens, the skill verifies them before operations. Fail fast with clear guidance on how to authenticate.\n- [ ] **CLI invocation section**: provide exact command patterns with placeholder arguments. Agents copy these verbatim — ambiguous prose gets misinterpreted.\n- [ ] **Error handling guidance**: document what to do when the CLI fails. Which errors are retryable? When should the agent stop and ask the user?\n- [ ] **No bare command names in prose or tables**: agents may try to execute anything that looks like a command. Wrap command references in context or use code blocks with clear framing.\n- [ ] **Cross-platform commands**: avoid \`timeout\` (not on macOS), platform-specific \`sed\` flags, \`grep -P\`, and other non-portable utilities. If platform-specific, document alternatives.\n- [ ] **\`files\` config declares CLI binaries**: use \`files\` entries in \`vibe-agent-toolkit.config.yaml\` so VAT copies scripts into the skill package at build time. Don\'t rely on external copy scripts.\n- [ ] **Document bundled assets and templates**: if scripts reference files programmatically (not via markdown links), explain what\'s bundled and why in the SKILL.md. The consuming agent should understand the full package contents."
+  },
+  usingThisChecklist: {
+    header: "## Using This Checklist",
+    body: "This is a living document. When a new failure pattern is discovered in skill authoring, add a checklist item here. The goal is shift-left: catch issues before they ship rather than debugging them in production.\n\nItems marked as checks (not automated validation) are judgment calls that tooling can\'t fully enforce. An agent or human reviews them manually. Items that _can_ be automated are already enforced by \`vat verify\` — this checklist covers the gaps.\n\nReviewed against external best practices (Anthropic skills documentation, anthropics/skills repository, superpowers conventions, Claude Code release notes through 2026-04-15) before initial publication.",
+    text: "## Using This Checklist\n\nThis is a living document. When a new failure pattern is discovered in skill authoring, add a checklist item here. The goal is shift-left: catch issues before they ship rather than debugging them in production.\n\nItems marked as checks (not automated validation) are judgment calls that tooling can\'t fully enforce. An agent or human reviews them manually. Items that _can_ be automated are already enforced by \`vat verify\` — this checklist covers the gaps.\n\nReviewed against external best practices (Anthropic skills documentation, anthropics/skills repository, superpowers conventions, Claude Code release notes through 2026-04-15) before initial publication."
+  }
+};

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

@@ -7,7 +7,7 @@ export const meta = {
   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."
 };
 
-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**\`ignoreValidationErrors\`** — Override specific validation rules when justified:\n\n\`\`\`json\n\"ignoreValidationErrors\": {\n  \"SKILL_LENGTH_EXCEEDS_RECOMMENDED\": \"Large domain requires detailed examples\",\n  \"NO_PROGRESSIVE_DISCLOSURE\": {\n    \"reason\": \"Temporary — refactoring planned\",\n    \"expires\": \"2026-06-30\"\n  }\n}\n\`\`\`\n\nUse sparingly. Prefer fixing the underlying issue over suppressing warnings.\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- [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: 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**\`ignoreValidationErrors\`** — Override specific validation rules when justified:\n\n\`\`\`json\n\"ignoreValidationErrors\": {\n  \"SKILL_LENGTH_EXCEEDS_RECOMMENDED\": \"Large domain requires detailed examples\",\n  \"NO_PROGRESSIVE_DISCLOSURE\": {\n    \"reason\": \"Temporary — refactoring planned\",\n    \"expires\": \"2026-06-30\"\n  }\n}\n\`\`\`\n\nUse sparingly. Prefer fixing the underlying issue over suppressing warnings.\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 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 fragments = {
   skillmdStructure: {
@@ -47,7 +47,7 @@ export const fragments = {
   },
   references: {
     header: "## References",
-    body: "- [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- [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: "- [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 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)"
   }
 };

package/dist/skills/authoring/SKILL.md

@@ -368,6 +368,7 @@ const output2 = await agent.execute({
 
 ## References
 
-- [agent-authoring.md]() — Complete patterns guide
-- [orchestration.md]() — Multi-agent workflows
+- Skill Quality Checklist — Pre-publication checklist for all skills (general + CLI-backed)
+- agent-authoring.md — Complete patterns guide
+- orchestration.md — Multi-agent workflows
 - [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents)

package/dist/skills/debugging/SKILL.md

@@ -79,7 +79,7 @@ Before changing VAT source code, write a test that reproduces the bug:
 - **CLI behavior** → add an integration test in `packages/cli/test/integration/`
 - **End-to-end workflow** → add a system test in `packages/cli/test/system/`
 
-See [docs/writing-tests.md]() for test patterns and
+See [docs/writing-tests.md](resources/writing-tests.md) for test patterns and
 the unit/integration/system classification guide.
 
 ## Step 5: Validate Before Committing
@@ -106,6 +106,6 @@ is safe to commit. Do not commit until `bun run validate` passes.
 
 ## See Also
 
-- [docs/debug-and-test-vat-fixes.md]() — Full reference
-- [docs/writing-tests.md]() — Test patterns and classification
-- [packages/cli/CLAUDE.md]() — CLI development guidelines
+- [docs/debug-and-test-vat-fixes.md](resources/debug-and-test-vat-fixes.md) — Full reference
+- [docs/writing-tests.md](resources/writing-tests.md) — Test patterns and classification
+- [packages/cli/CLAUDE.md](resources/CLAUDE.md) — CLI development guidelines

package/dist/skills/debugging/resources/CLAUDE.md

@@ -54,7 +54,7 @@ cd /path/to/adopter-project
 vat resources validate .   # now uses your local build
 ```
 
-Full debugging guide: [docs/debug-and-test-vat-fixes.md](../../docs/debug-and-test-vat-fixes.md)
+Full debugging guide: [docs/debug-and-test-vat-fixes.md](debug-and-test-vat-fixes.md)
 
 ## CLI Package Architecture Principles
 

package/dist/skills/debugging/resources/debug-and-test-vat-fixes.md

@@ -73,7 +73,7 @@ Reproduce the bug as a test before touching source code:
 | CLI command behavior | `packages/cli/test/integration/*.integration.test.ts` |
 | End-to-end workflow | `packages/cli/test/system/*.system.test.ts` |
 
-See [docs/writing-tests.md](./writing-tests.md) for patterns and classification guide.
+See [docs/writing-tests.md](writing-tests.md) for patterns and classification guide.
 
 Run just the test you added:
 ```bash
@@ -106,6 +106,6 @@ what changed. Do not commit until this passes.
 
 ## See Also
 
-- [docs/writing-tests.md](./writing-tests.md) — Full test classification and patterns
-- [packages/cli/CLAUDE.md](../packages/cli/CLAUDE.md) — CLI development guidelines
-- [docs/build-system.md](./build-system.md) — Build configuration reference
+- [docs/writing-tests.md](writing-tests.md) — Full test classification and patterns
+- [packages/cli/CLAUDE.md](CLAUDE.md) — CLI development guidelines
+- [docs/build-system.md]() — Build configuration reference

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

@@ -182,12 +182,12 @@ You've successfully adopted VAT when:
 
 ## Documentation Index
 
-- [Getting Started Guide]()
-- [Agent Authoring Guide]() — patterns and code examples
-- [Orchestration Guide]() — multi-agent workflows
-- [RAG Usage Guide]()
-- [Resource Compiler Guide]()
-- [Runtime Adapters]()
+- [Getting Started Guide](resources/getting-started.md)
+- [Agent Authoring Guide](resources/agent-authoring.md) — patterns and code examples
+- [Orchestration Guide](resources/orchestration.md) — multi-agent workflows
+- [RAG Usage Guide](resources/rag-usage-guide.md)
+- [Resource Compiler Guide](resources/compiling-markdown-to-typescript.md)
+- [Runtime Adapters](resources/adding-runtime-adapters.md)
 - Examples: `@vibe-agent-toolkit/vat-example-cat-agents`
 
 ## Running VAT

package/dist/skills/vibe-agent-toolkit/resources/agent-authoring.md

@@ -890,8 +890,8 @@ async execute(input, options = {}) {
 
 ## Related Documentation
 
-- [Orchestration Guide](./orchestration.md) - Composing agents into workflows
-- [Architecture Overview](./architecture/README.md) - Package structure
+- [Orchestration Guide](orchestration.md) - Composing agents into workflows
+- [Architecture Overview]() - Package structure
 
 ## Examples
 

package/dist/skills/vibe-agent-toolkit/resources/compiling-markdown-to-typescript.md

@@ -473,29 +473,29 @@ import * as Doc from './doc.md';
 ## Next Steps
 
 ### For Package Publishers
-Read [Publishing TypeScript Resource Packages](./publishing-packages.md) to learn how to:
+Read [Publishing TypeScript Resource Packages]() to learn how to:
 - Set up package structure
 - Configure build scripts
 - Publish to npm
 - Include both compiled and original markdown
 
 ### For Package Consumers
-Read [Consuming TypeScript Resources](./consuming-packages.md) to learn how to:
+Read [Consuming TypeScript Resources]() to learn how to:
 - Install and import packages
 - Use type-safe compiled resources
 - Access original markdown for flexibility
 - Integrate with your project
 
 ### For Specific Use Cases
-- **Building AI agents?** → [Building Agent Prompt Libraries](./use-cases/agent-prompt-libraries.md)
-- **Creating RAG systems?** → [Creating RAG Knowledge Bases](./use-cases/rag-knowledge-bases.md)
-- **Building templates?** → [Template System Patterns](./use-cases/template-systems.md)
+- **Building AI agents?** → [Building Agent Prompt Libraries]()
+- **Creating RAG systems?** → [Creating RAG Knowledge Bases]()
+- **Building templates?** → [Template System Patterns]()
 
 ---
 
 ## See Also
 
-- [Resource Compiler README](../../../packages/resource-compiler/README.md) - Package documentation
-- [Publishing Packages](./publishing-packages.md) - Create and publish resource packages
-- [Consuming Packages](./consuming-packages.md) - Use published packages
-- [Guide Index](./README.md) - All resource compiler guides
+- [Resource Compiler README]() - Package documentation
+- [Publishing Packages]() - Create and publish resource packages
+- [Consuming Packages]() - Use published packages
+- [Guide Index]() - All resource compiler guides

package/dist/skills/vibe-agent-toolkit/resources/getting-started.md

@@ -75,7 +75,7 @@ mkdir -p packages/my-package/src packages/my-package/test
 
 3. **Add package configuration**:
 
-Create `package.json`, `tsconfig.json` (with `composite: true`), and add to root `tsconfig.json` references. See [CLAUDE.md](../CLAUDE.md) Development Workflow section for complete details.
+Create `package.json`, `tsconfig.json` (with `composite: true`), and add to root `tsconfig.json` references. See [CLAUDE.md]() Development Workflow section for complete details.
 
 4. **Update root tsconfig.json**:
 
@@ -304,7 +304,7 @@ The audit command checks for:
 - Link integrity (broken links, invalid paths)
 - Console compatibility (tool availability)
 
-See [Audit Command Documentation](./cli/audit.md) for complete validation rules.
+See [Audit Command Documentation]() for complete validation rules.
 
 ### Importing Skills
 
@@ -339,13 +339,13 @@ vat test
 vat package
 ```
 
-See [Import Command Documentation](./cli/import.md) for more details.
+See [Import Command Documentation]() for more details.
 
 ## Next Steps
 
-- Read [CLAUDE.md](../CLAUDE.md) for detailed development guidelines
-- Review [Agent Skills Best Practices](./guides/agent-skills-best-practices.md)
-- Review the [utils package](../packages/utils/) for reference patterns
+- Read [CLAUDE.md]() for detailed development guidelines
+- Review [Agent Skills Best Practices]()
+- Review the [utils package]() for reference patterns
 - Check out [vibe-validate documentation](https://github.com/jdutton/vibe-validate)
 - Set up your CI/CD pipeline on GitHub
 - Enable Codecov for your repository (see README.md for setup instructions)

package/dist/skills/vibe-agent-toolkit/resources/orchestration.md

@@ -839,8 +839,8 @@ interface BreedAdvisorMetadata {
 
 ## Related Documentation
 
-- [Agent Authoring Guide](./agent-authoring.md) - How to create agents with result envelopes
-- [Architecture Overview](./architecture/README.md) - Package structure and design principles
+- [Agent Authoring Guide](agent-authoring.md) - How to create agents with result envelopes
+- [Architecture Overview]() - Package structure and design principles
 
 ## Examples
 

package/dist/skills/vibe-agent-toolkit/resources/rag-usage-guide.md

@@ -767,4 +767,4 @@ vat agent run doc-assistant "What's our code review process?"
 ---
 
 **See Also**:
-- [RAG Architecture](../architecture/rag.md)
+- [RAG Architecture]()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/vat-development-agents",
-  "version": "0.1.29-rc.1",
+  "version": "0.1.29-rc.3",
   "description": "VAT development agents - dogfooding the vibe-agent-toolkit",
   "type": "module",
   "keywords": [
@@ -65,13 +65,13 @@
     "postinstall": "vat claude plugin install --npm-postinstall || exit 0"
   },
   "dependencies": {
-    "@vibe-agent-toolkit/agent-schema": "0.1.29-rc.1",
-    "@vibe-agent-toolkit/cli": "0.1.29-rc.1",
+    "@vibe-agent-toolkit/agent-schema": "0.1.29-rc.3",
+    "@vibe-agent-toolkit/cli": "0.1.29-rc.3",
     "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
-    "@vibe-agent-toolkit/resource-compiler": "0.1.29-rc.1",
+    "@vibe-agent-toolkit/resource-compiler": "0.1.29-rc.3",
     "ts-patch": "^3.2.1",
     "typescript": "^5.7.3"
   },