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

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

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Three new skill-smell validation codes (all default `warning`, per skill-smell philosophy):
+  - `SKILL_FRONTMATTER_EXTRA_FIELDS`: frontmatter contains keys beyond the standard agentskills.io + Claude Code set. Allowed keys derive from `AgentSkillFrontmatterSchema` at module load, so the rule tracks the schema. Actionable when adopters put project-specific fields (`version:`, `tools:`, `permissions:`) at top level — `metadata.*` is the right home for custom data.
+  - `SKILL_CROSS_SKILL_AUTH_UNDECLARED`: body prose declares a sibling-skill or `ANTHROPIC_*_KEY` dependency (e.g., "Requires `vibe-agent-toolkit:vat-enterprise-org`", "Requires `ANTHROPIC_ADMIN_API_KEY`") but the description omits it. Narrow heuristic to keep false-positive rate low; bare `ANTHROPIC_API_KEY` (the universal Claude-API default) is explicitly excluded.
+  - `SKILL_DESCRIPTION_STYLE_MIXED_IN_PACKAGE`: detects mixed YAML scalar styles across sibling skills' `description` frontmatter in the same package. Detector registered and documented; pipeline wiring deferred to a follow-up RC (requires a package-level aggregation pass that the current single-file validator pipeline does not provide).
+
+### Changed
+- `actions/checkout` and `actions/setup-node` bumped from `@v4` to `@v6` across `.github/workflows/*.yml`. Runs on Node 24; removes the Sept-2026 deprecation warning on `v4` runners.
+
+### Fixed
+- `packages/cli/test/system/audit-dogfooding.system.test.ts` test 1 (`should successfully audit vibe-agent-toolkit project root`) now runs on Windows. The `skipIf(process.platform === 'win32')` was added in 0.1.32 when the test timed out at 120s; the narrow `gitCheckIgnoredBatch` fallback fix that landed alongside it dropped audit wall time ~4x, so the smoke test fits in budget again. Windows CI will confirm.
+- Stale JSDoc examples referencing `vibe-agent-toolkit:resources` (renamed to `vibe-agent-toolkit:vat-knowledge-resources` during the 0.1.32 plugin restructure) replaced with `vibe-agent-toolkit:vat-audit` in `packages/cli/src/commands/claude/plugin/build.ts`, `packages/cli/src/commands/skills/build.ts`, `packages/agent-schema/src/package-metadata.ts`, and the companion test constant.
+
+### Performance
+- **Walker unification on `GitTracker`.** Every `vat audit` / `vat skills validate` / `vat verify` scan now shares one pre-populated `GitTracker` per repo. The tracker pre-loads the full active file set (tracked + untracked-not-ignored) via `git ls-files --cached --others --exclude-standard`, precomputes the ancestor directory set, and answers every ignore check from an in-memory `Set` instead of spawning `git check-ignore`. Per-directory `gitCheckIgnoredBatch` calls and per-link `isGitIgnored` calls are gone from the hot paths in `packages/cli/src/commands/audit.ts`, `packages/agent-skills/src/walk-link-graph.ts`, `packages/agent-skills/src/validators/packaging-validator.ts`, and `packages/discovery/src/scanners/local-scanner.ts`. The legacy `isGitIgnored` / `gitCheckIgnoredBatch` exports on `@vibe-agent-toolkit/utils` are preserved for one-off and cross-repo consumers.
+- **Shared `ResourceRegistry` across skills in `vat skills validate`.** When a single `vat skills validate` invocation covers multiple skills that share one project root, the command now builds one crawled/link-resolved `ResourceRegistry` once and reuses it for every skill's validation instead of re-parsing the same markdown per skill. Heterogeneous scans (mixed project roots) transparently fall back to per-skill registries.
+- **Measured wall-time (median of 3 runs on the VAT monorepo, M-series laptop):**
+  - `vat audit .`: 6.85s → 2.50s (~2.7x, under the 3s target set in the rc.1 plan)
+  - `vat verify --cwd packages/vat-development-agents`: 12.68s → 2.85s (~4.4x)
+  - `vat skills validate packages/vat-development-agents`: 10.05s → 1.44s (~7x)
+- Pure perf — no behavior changes. YAML output diffs clean pre/post across all three commands except wall-time fields. New `GitTracker` APIs (`hasActiveDescendant`, `isIgnoredByActiveSet`) are non-breaking additions; `initialize()` accepts an options bag with `includeUntracked` defaulting to `true`.
+
 ## [0.1.32] - 2026-04-19
 
 ### Added

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.32",
+  "version": "0.1.33-rc.2",
   "author": {
     "name": "vibe-agent-toolkit contributors"
   }

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

@@ -62,12 +62,12 @@ Tooling enforcement: items marked with a bracketed code (e.g., `[SKILL_DESCRIPTI
 
 ### Frontmatter hygiene
 
-- **[VAT] Frontmatter keys stay conservative**: use only the standard keys `name`, `description`, `allowed-tools` (plus `argument-hint` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific `version:` or `metadata:` fields will be rejected. If you need per-skill config, put it in `vibe-agent-toolkit.config.yaml`, not the frontmatter.
-- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don't mix folded (`description: >-`) and inline (`description: "..."`) string forms. Pick one and apply it to every skill.
+- **[VAT] Frontmatter keys stay conservative**: use only the standard keys `name`, `description`, `allowed-tools` (plus `argument-hint` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific `version:` or `metadata:` fields will be rejected. If you need per-skill config, put it in `vibe-agent-toolkit.config.yaml`, not the frontmatter. `[SKILL_FRONTMATTER_EXTRA_FIELDS]` warns on non-standard keys.
+- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don't mix folded (`description: >-`) and inline (`description: "..."`) string forms. Pick one and apply it to every skill. `[SKILL_DESCRIPTION_STYLE_MIXED_IN_PACKAGE]` flags mixed styles across a package (detector implemented, pipeline wiring pending).
 
 ### Cross-skill dependencies
 
-- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (`Requires ado skill for auth`). Agents may load one without the other; a silent dependency fails mysteriously at runtime.
+- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (`Requires ado skill for auth`). Agents may load one without the other; a silent dependency fails mysteriously at runtime. `[SKILL_CROSS_SKILL_AUTH_UNDECLARED]` flags body prose that requires a sibling skill or `ANTHROPIC_*_KEY` env var without naming it in the description.
 
 ### Readability
 

package/dist/generated/resources/skills/vat-skill-review.js

@@ -7,7 +7,7 @@ export const meta = {
   description: "Use when reviewing a skill before publication or running \`vat skill review\`. Pre-publication quality checklist grouped into general (all skills) and CLI-backed items, tied to VAT validation codes and Anthropic\'s skill-authoring best practices."
 };
 
-export const text = "\n# Skill Quality Checklist (vat skill review)\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\nThis content is also surfaced by the \`vat skill review\` CLI command, which formats the checklist around a specific skill\'s validation output.\n\n## Guidance freshness\n\nSkill authoring standards move fast. Before applying this checklist to a non-trivial change:\n\n- Re-fetch the source of \`docs/external/anthropic-skill-authoring-best-practices.md\` named in its preamble. If the content has shifted, update the cache and this checklist together.\n- Web search for the latest Claude Code release notes when trigger semantics, frontmatter rules, or packaging behavior may have changed. Don\'t rely on training-data recall.\n- Promote any manual item below to a programmatic validator when the pattern is detectable from file contents — see the shift-left notes in \`packages/vat-development-agents/resources/skills/CLAUDE.md\`.\n\n## About this checklist\n\nItems fall into two categories:\n\n- **[A]** items directly mirror Anthropic\'s official skill-authoring best practices (see the [cached guidance](../../../../docs/external/anthropic-skill-authoring-best-practices.md) or the [live doc](https://platform.claude.com/docs/en/docs/agents-and-tools/agent-skills/best-practices)). These are safe to treat as canonical.\n- **[VAT]** items are VAT-opinionated additions not explicitly in Anthropic\'s doc. They come from adopter experience, corpus observations, or Claude Code behavior changes. Individual teams can override any **[VAT]** item with \`validation.severity\` or \`validation.allow\` (with a \`reason\`).\n\nTooling enforcement: items marked with a bracketed code (e.g., \`[SKILL_DESCRIPTION_FILLER_OPENER]\`) are checked by \`vat skills validate\` / \`vat audit\`. The rest are judgment calls for a human or agent reviewer.\n\n## General — All Skills\n\n### Naming\n\n- **[A] Name format**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how. \`[SKILL_NAME_INVALID]\` enforces this.\n- **[A] Prefer gerund form** (\`processing-pdfs\`, \`analyzing-spreadsheets\`). Anthropic recommends gerund form as the primary pattern — \"clearly describes the activity or capability the Skill provides.\" Noun phrases (\`pdf-processing\`) and action-oriented forms (\`process-pdfs\`) are \"acceptable alternatives.\" Avoid vague names like \`helper\`, \`utils\`, \`tools\`.\n- **[VAT] Name matches built skill directory name**: \`[SKILL_NAME_MISMATCHES_DIR]\` fires when the \`name\` frontmatter field differs from the parent directory name after build. The schema allows inference from the directory, but explicit mismatches are usually bugs.\n\n### Description\n\n- **[A] 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. Use when ...\` beats \`This skill is used for when you need to analyze sprints\`.\n- **[A] Third-person voice**: Anthropic guidance is unambiguous — \"**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.\" Avoid first/second person: \`I can help...\`, \`You can use...\`. \`[SKILL_DESCRIPTION_WRONG_PERSON]\` flags these.\n- **[A] \`Use when <concrete trigger>\` is the recommended pattern** — every Anthropic example uses it after a verb phrase. What\'s banned is vague variants like \`Use when you want to...\` / \`Use when you need to...\` that don\'t name a concrete trigger.\n- **[VAT] Prefer a verb phrase or \`Use when ...\` opener** — not a meta-description of the skill-as-object. \`[SKILL_DESCRIPTION_FILLER_OPENER]\` warns on \`This skill...\`, \`A skill that...\`, \`Used to...\` — these waste the first tokens describing the wrapper rather than the behavior. Anthropic doesn\'t ban these explicitly, but their own examples never use them; VAT is stricter here.\n- **[A] Be specific**: include both what the skill does and when to use it. \`[DESCRIPTION_TOO_VAGUE]\` fires below 50 chars. Anthropic\'s bad examples — \`Helps with documents\`, \`Processes data\`, \`Does stuff with files\` — are rejected for vagueness, not length.\n- **[VAT] Description ≤250 characters**: Claude Code truncates descriptions at 250 characters in the \`/skills\` listing (since v2.1.86). \`[SKILL_DESCRIPTION_OVER_CLAUDE_CODE_LIMIT]\` warns at 250; \`[SKILL_DESCRIPTION_TOO_LONG]\` errors at the 1024-char schema hard max. Aim for ≤200 chars for safety; ≤130 chars if shipping a large skill collection (60+ skills) so the total budget fits.\n\n### Body structure\n\n- **[A] SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. \`[SKILL_LENGTH_EXCEEDS_RECOMMENDED]\` warns as you approach the limit. Split detailed content into reference files.\n- **[A] 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- **[A] Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- **[A] Consistent terminology**: pick one term per concept and use it throughout. Mixing \`artifact\` / \`bundle\` / \`package\` confuses agents.\n- **[A] No time-sensitive content**: \`[SKILL_TIME_SENSITIVE_CONTENT]\` flags patterns like \`as of November 2025\` or \`after July 2026\`. Route deprecated guidance into a clearly labeled \`Old patterns\` section so agents skip it.\n\n### References and bundled files\n\n- **[A] Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. \`[PACKAGED_UNREFERENCED_FILE]\` enforces this at build time. Dead files confuse agents and waste context.\n- **[A] 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. \`[REFERENCE_TOO_DEEP]\` enforces.\n- **[A] 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- **[A] All links resolve**: every \`[text](path)\` link points to a file that exists. \`[LINK_MISSING_TARGET]\` and siblings enforce.\n- **[A] Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- **[A] Test the trigger**: ask \"if an agent sees only this name and description, will it know when to load this skill?\" If understanding the description requires reading the SKILL.md, the description is wrong.\n\n### Frontmatter hygiene\n\n- **[VAT] Frontmatter keys stay conservative**: use only the standard keys \`name\`, \`description\`, \`allowed-tools\` (plus \`argument-hint\` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific \`version:\` or \`metadata:\` fields will be rejected. If you need per-skill config, put it in \`vibe-agent-toolkit.config.yaml\`, not the frontmatter.\n- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don\'t mix folded (\`description: >-\`) and inline (\`description: \"...\"\`) string forms. Pick one and apply it to every skill.\n\n### Cross-skill dependencies\n\n- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (\`Requires ado skill for auth\`). Agents may load one without the other; a silent dependency fails mysteriously at runtime.\n\n### Readability\n\n- **[VAT] Large tables move to reference files**: if a table exceeds ~15 rows, move it to a sibling reference file and link from SKILL.md. Long tables compete for context budget and push the main skill content further down.\n\n## CLI-Backed Skills — Additional Checks\n\nThese apply to skills that bundle executable scripts and instruct agents to run commands.\n\n- **[VAT] 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- **[VAT] 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- **[VAT] CLI invocation section**: provide exact command patterns with placeholder arguments. Agents copy these verbatim — ambiguous prose gets misinterpreted.\n- **[VAT] 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- **[VAT] 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- **[VAT] 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- **[VAT] \`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- **[VAT] 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 enforced by \`vat skills validate\` / \`vat audit\` — their validation-code IDs are shown in brackets above.\n\nWhen a VAT validation code fires, its \`fix:\` field will suggest a concrete remediation; this checklist is the reference for the underlying principle. For a walkthrough that combines automated validation with this checklist, run \`vat skill review <path>\`.\n\n**Source of truth**: [Anthropic\'s skill-authoring best practices](https://platform.claude.com/docs/en/docs/agents-and-tools/agent-skills/best-practices). See [\`docs/external/anthropic-skill-authoring-best-practices.md\`](../../../../docs/external/anthropic-skill-authoring-best-practices.md) for a cached copy of the load-bearing portions with the VAT-vs-Anthropic delta called out.\n\nReviewed against external best practices (Anthropic skill-authoring docs, anthropics/skills repository, Claude Code release notes through 2026-04-18).\n";
+export const text = "\n# Skill Quality Checklist (vat skill review)\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\nThis content is also surfaced by the \`vat skill review\` CLI command, which formats the checklist around a specific skill\'s validation output.\n\n## Guidance freshness\n\nSkill authoring standards move fast. Before applying this checklist to a non-trivial change:\n\n- Re-fetch the source of \`docs/external/anthropic-skill-authoring-best-practices.md\` named in its preamble. If the content has shifted, update the cache and this checklist together.\n- Web search for the latest Claude Code release notes when trigger semantics, frontmatter rules, or packaging behavior may have changed. Don\'t rely on training-data recall.\n- Promote any manual item below to a programmatic validator when the pattern is detectable from file contents — see the shift-left notes in \`packages/vat-development-agents/resources/skills/CLAUDE.md\`.\n\n## About this checklist\n\nItems fall into two categories:\n\n- **[A]** items directly mirror Anthropic\'s official skill-authoring best practices (see the [cached guidance](../../../../docs/external/anthropic-skill-authoring-best-practices.md) or the [live doc](https://platform.claude.com/docs/en/docs/agents-and-tools/agent-skills/best-practices)). These are safe to treat as canonical.\n- **[VAT]** items are VAT-opinionated additions not explicitly in Anthropic\'s doc. They come from adopter experience, corpus observations, or Claude Code behavior changes. Individual teams can override any **[VAT]** item with \`validation.severity\` or \`validation.allow\` (with a \`reason\`).\n\nTooling enforcement: items marked with a bracketed code (e.g., \`[SKILL_DESCRIPTION_FILLER_OPENER]\`) are checked by \`vat skills validate\` / \`vat audit\`. The rest are judgment calls for a human or agent reviewer.\n\n## General — All Skills\n\n### Naming\n\n- **[A] Name format**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how. \`[SKILL_NAME_INVALID]\` enforces this.\n- **[A] Prefer gerund form** (\`processing-pdfs\`, \`analyzing-spreadsheets\`). Anthropic recommends gerund form as the primary pattern — \"clearly describes the activity or capability the Skill provides.\" Noun phrases (\`pdf-processing\`) and action-oriented forms (\`process-pdfs\`) are \"acceptable alternatives.\" Avoid vague names like \`helper\`, \`utils\`, \`tools\`.\n- **[VAT] Name matches built skill directory name**: \`[SKILL_NAME_MISMATCHES_DIR]\` fires when the \`name\` frontmatter field differs from the parent directory name after build. The schema allows inference from the directory, but explicit mismatches are usually bugs.\n\n### Description\n\n- **[A] 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. Use when ...\` beats \`This skill is used for when you need to analyze sprints\`.\n- **[A] Third-person voice**: Anthropic guidance is unambiguous — \"**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.\" Avoid first/second person: \`I can help...\`, \`You can use...\`. \`[SKILL_DESCRIPTION_WRONG_PERSON]\` flags these.\n- **[A] \`Use when <concrete trigger>\` is the recommended pattern** — every Anthropic example uses it after a verb phrase. What\'s banned is vague variants like \`Use when you want to...\` / \`Use when you need to...\` that don\'t name a concrete trigger.\n- **[VAT] Prefer a verb phrase or \`Use when ...\` opener** — not a meta-description of the skill-as-object. \`[SKILL_DESCRIPTION_FILLER_OPENER]\` warns on \`This skill...\`, \`A skill that...\`, \`Used to...\` — these waste the first tokens describing the wrapper rather than the behavior. Anthropic doesn\'t ban these explicitly, but their own examples never use them; VAT is stricter here.\n- **[A] Be specific**: include both what the skill does and when to use it. \`[DESCRIPTION_TOO_VAGUE]\` fires below 50 chars. Anthropic\'s bad examples — \`Helps with documents\`, \`Processes data\`, \`Does stuff with files\` — are rejected for vagueness, not length.\n- **[VAT] Description ≤250 characters**: Claude Code truncates descriptions at 250 characters in the \`/skills\` listing (since v2.1.86). \`[SKILL_DESCRIPTION_OVER_CLAUDE_CODE_LIMIT]\` warns at 250; \`[SKILL_DESCRIPTION_TOO_LONG]\` errors at the 1024-char schema hard max. Aim for ≤200 chars for safety; ≤130 chars if shipping a large skill collection (60+ skills) so the total budget fits.\n\n### Body structure\n\n- **[A] SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. \`[SKILL_LENGTH_EXCEEDS_RECOMMENDED]\` warns as you approach the limit. Split detailed content into reference files.\n- **[A] 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- **[A] Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- **[A] Consistent terminology**: pick one term per concept and use it throughout. Mixing \`artifact\` / \`bundle\` / \`package\` confuses agents.\n- **[A] No time-sensitive content**: \`[SKILL_TIME_SENSITIVE_CONTENT]\` flags patterns like \`as of November 2025\` or \`after July 2026\`. Route deprecated guidance into a clearly labeled \`Old patterns\` section so agents skip it.\n\n### References and bundled files\n\n- **[A] Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. \`[PACKAGED_UNREFERENCED_FILE]\` enforces this at build time. Dead files confuse agents and waste context.\n- **[A] 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. \`[REFERENCE_TOO_DEEP]\` enforces.\n- **[A] 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- **[A] All links resolve**: every \`[text](path)\` link points to a file that exists. \`[LINK_MISSING_TARGET]\` and siblings enforce.\n- **[A] Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- **[A] Test the trigger**: ask \"if an agent sees only this name and description, will it know when to load this skill?\" If understanding the description requires reading the SKILL.md, the description is wrong.\n\n### Frontmatter hygiene\n\n- **[VAT] Frontmatter keys stay conservative**: use only the standard keys \`name\`, \`description\`, \`allowed-tools\` (plus \`argument-hint\` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific \`version:\` or \`metadata:\` fields will be rejected. If you need per-skill config, put it in \`vibe-agent-toolkit.config.yaml\`, not the frontmatter. \`[SKILL_FRONTMATTER_EXTRA_FIELDS]\` warns on non-standard keys.\n- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don\'t mix folded (\`description: >-\`) and inline (\`description: \"...\"\`) string forms. Pick one and apply it to every skill. \`[SKILL_DESCRIPTION_STYLE_MIXED_IN_PACKAGE]\` flags mixed styles across a package (detector implemented, pipeline wiring pending).\n\n### Cross-skill dependencies\n\n- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (\`Requires ado skill for auth\`). Agents may load one without the other; a silent dependency fails mysteriously at runtime. \`[SKILL_CROSS_SKILL_AUTH_UNDECLARED]\` flags body prose that requires a sibling skill or \`ANTHROPIC_*_KEY\` env var without naming it in the description.\n\n### Readability\n\n- **[VAT] Large tables move to reference files**: if a table exceeds ~15 rows, move it to a sibling reference file and link from SKILL.md. Long tables compete for context budget and push the main skill content further down.\n\n## CLI-Backed Skills — Additional Checks\n\nThese apply to skills that bundle executable scripts and instruct agents to run commands.\n\n- **[VAT] 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- **[VAT] 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- **[VAT] CLI invocation section**: provide exact command patterns with placeholder arguments. Agents copy these verbatim — ambiguous prose gets misinterpreted.\n- **[VAT] 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- **[VAT] 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- **[VAT] 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- **[VAT] \`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- **[VAT] 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 enforced by \`vat skills validate\` / \`vat audit\` — their validation-code IDs are shown in brackets above.\n\nWhen a VAT validation code fires, its \`fix:\` field will suggest a concrete remediation; this checklist is the reference for the underlying principle. For a walkthrough that combines automated validation with this checklist, run \`vat skill review <path>\`.\n\n**Source of truth**: [Anthropic\'s skill-authoring best practices](https://platform.claude.com/docs/en/docs/agents-and-tools/agent-skills/best-practices). See [\`docs/external/anthropic-skill-authoring-best-practices.md\`](../../../../docs/external/anthropic-skill-authoring-best-practices.md) for a cached copy of the load-bearing portions with the VAT-vs-Anthropic delta called out.\n\nReviewed against external best practices (Anthropic skill-authoring docs, anthropics/skills repository, Claude Code release notes through 2026-04-18).\n";
 
 export const fragments = {
   guidanceFreshness: {
@@ -22,8 +22,8 @@ export const fragments = {
   },
   general-AllSkills: {
     header: "## General — All Skills",
-    body: "### Naming\n\n- **[A] Name format**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how. \`[SKILL_NAME_INVALID]\` enforces this.\n- **[A] Prefer gerund form** (\`processing-pdfs\`, \`analyzing-spreadsheets\`). Anthropic recommends gerund form as the primary pattern — \"clearly describes the activity or capability the Skill provides.\" Noun phrases (\`pdf-processing\`) and action-oriented forms (\`process-pdfs\`) are \"acceptable alternatives.\" Avoid vague names like \`helper\`, \`utils\`, \`tools\`.\n- **[VAT] Name matches built skill directory name**: \`[SKILL_NAME_MISMATCHES_DIR]\` fires when the \`name\` frontmatter field differs from the parent directory name after build. The schema allows inference from the directory, but explicit mismatches are usually bugs.\n\n### Description\n\n- **[A] 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. Use when ...\` beats \`This skill is used for when you need to analyze sprints\`.\n- **[A] Third-person voice**: Anthropic guidance is unambiguous — \"**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.\" Avoid first/second person: \`I can help...\`, \`You can use...\`. \`[SKILL_DESCRIPTION_WRONG_PERSON]\` flags these.\n- **[A] \`Use when <concrete trigger>\` is the recommended pattern** — every Anthropic example uses it after a verb phrase. What\'s banned is vague variants like \`Use when you want to...\` / \`Use when you need to...\` that don\'t name a concrete trigger.\n- **[VAT] Prefer a verb phrase or \`Use when ...\` opener** — not a meta-description of the skill-as-object. \`[SKILL_DESCRIPTION_FILLER_OPENER]\` warns on \`This skill...\`, \`A skill that...\`, \`Used to...\` — these waste the first tokens describing the wrapper rather than the behavior. Anthropic doesn\'t ban these explicitly, but their own examples never use them; VAT is stricter here.\n- **[A] Be specific**: include both what the skill does and when to use it. \`[DESCRIPTION_TOO_VAGUE]\` fires below 50 chars. Anthropic\'s bad examples — \`Helps with documents\`, \`Processes data\`, \`Does stuff with files\` — are rejected for vagueness, not length.\n- **[VAT] Description ≤250 characters**: Claude Code truncates descriptions at 250 characters in the \`/skills\` listing (since v2.1.86). \`[SKILL_DESCRIPTION_OVER_CLAUDE_CODE_LIMIT]\` warns at 250; \`[SKILL_DESCRIPTION_TOO_LONG]\` errors at the 1024-char schema hard max. Aim for ≤200 chars for safety; ≤130 chars if shipping a large skill collection (60+ skills) so the total budget fits.\n\n### Body structure\n\n- **[A] SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. \`[SKILL_LENGTH_EXCEEDS_RECOMMENDED]\` warns as you approach the limit. Split detailed content into reference files.\n- **[A] 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- **[A] Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- **[A] Consistent terminology**: pick one term per concept and use it throughout. Mixing \`artifact\` / \`bundle\` / \`package\` confuses agents.\n- **[A] No time-sensitive content**: \`[SKILL_TIME_SENSITIVE_CONTENT]\` flags patterns like \`as of November 2025\` or \`after July 2026\`. Route deprecated guidance into a clearly labeled \`Old patterns\` section so agents skip it.\n\n### References and bundled files\n\n- **[A] Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. \`[PACKAGED_UNREFERENCED_FILE]\` enforces this at build time. Dead files confuse agents and waste context.\n- **[A] 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. \`[REFERENCE_TOO_DEEP]\` enforces.\n- **[A] 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- **[A] All links resolve**: every \`[text](path)\` link points to a file that exists. \`[LINK_MISSING_TARGET]\` and siblings enforce.\n- **[A] Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- **[A] Test the trigger**: ask \"if an agent sees only this name and description, will it know when to load this skill?\" If understanding the description requires reading the SKILL.md, the description is wrong.\n\n### Frontmatter hygiene\n\n- **[VAT] Frontmatter keys stay conservative**: use only the standard keys \`name\`, \`description\`, \`allowed-tools\` (plus \`argument-hint\` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific \`version:\` or \`metadata:\` fields will be rejected. If you need per-skill config, put it in \`vibe-agent-toolkit.config.yaml\`, not the frontmatter.\n- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don\'t mix folded (\`description: >-\`) and inline (\`description: \"...\"\`) string forms. Pick one and apply it to every skill.\n\n### Cross-skill dependencies\n\n- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (\`Requires ado skill for auth\`). Agents may load one without the other; a silent dependency fails mysteriously at runtime.\n\n### Readability\n\n- **[VAT] Large tables move to reference files**: if a table exceeds ~15 rows, move it to a sibling reference file and link from SKILL.md. Long tables compete for context budget and push the main skill content further down.",
-    text: "## General — All Skills\n\n### Naming\n\n- **[A] Name format**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how. \`[SKILL_NAME_INVALID]\` enforces this.\n- **[A] Prefer gerund form** (\`processing-pdfs\`, \`analyzing-spreadsheets\`). Anthropic recommends gerund form as the primary pattern — \"clearly describes the activity or capability the Skill provides.\" Noun phrases (\`pdf-processing\`) and action-oriented forms (\`process-pdfs\`) are \"acceptable alternatives.\" Avoid vague names like \`helper\`, \`utils\`, \`tools\`.\n- **[VAT] Name matches built skill directory name**: \`[SKILL_NAME_MISMATCHES_DIR]\` fires when the \`name\` frontmatter field differs from the parent directory name after build. The schema allows inference from the directory, but explicit mismatches are usually bugs.\n\n### Description\n\n- **[A] 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. Use when ...\` beats \`This skill is used for when you need to analyze sprints\`.\n- **[A] Third-person voice**: Anthropic guidance is unambiguous — \"**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.\" Avoid first/second person: \`I can help...\`, \`You can use...\`. \`[SKILL_DESCRIPTION_WRONG_PERSON]\` flags these.\n- **[A] \`Use when <concrete trigger>\` is the recommended pattern** — every Anthropic example uses it after a verb phrase. What\'s banned is vague variants like \`Use when you want to...\` / \`Use when you need to...\` that don\'t name a concrete trigger.\n- **[VAT] Prefer a verb phrase or \`Use when ...\` opener** — not a meta-description of the skill-as-object. \`[SKILL_DESCRIPTION_FILLER_OPENER]\` warns on \`This skill...\`, \`A skill that...\`, \`Used to...\` — these waste the first tokens describing the wrapper rather than the behavior. Anthropic doesn\'t ban these explicitly, but their own examples never use them; VAT is stricter here.\n- **[A] Be specific**: include both what the skill does and when to use it. \`[DESCRIPTION_TOO_VAGUE]\` fires below 50 chars. Anthropic\'s bad examples — \`Helps with documents\`, \`Processes data\`, \`Does stuff with files\` — are rejected for vagueness, not length.\n- **[VAT] Description ≤250 characters**: Claude Code truncates descriptions at 250 characters in the \`/skills\` listing (since v2.1.86). \`[SKILL_DESCRIPTION_OVER_CLAUDE_CODE_LIMIT]\` warns at 250; \`[SKILL_DESCRIPTION_TOO_LONG]\` errors at the 1024-char schema hard max. Aim for ≤200 chars for safety; ≤130 chars if shipping a large skill collection (60+ skills) so the total budget fits.\n\n### Body structure\n\n- **[A] SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. \`[SKILL_LENGTH_EXCEEDS_RECOMMENDED]\` warns as you approach the limit. Split detailed content into reference files.\n- **[A] 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- **[A] Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- **[A] Consistent terminology**: pick one term per concept and use it throughout. Mixing \`artifact\` / \`bundle\` / \`package\` confuses agents.\n- **[A] No time-sensitive content**: \`[SKILL_TIME_SENSITIVE_CONTENT]\` flags patterns like \`as of November 2025\` or \`after July 2026\`. Route deprecated guidance into a clearly labeled \`Old patterns\` section so agents skip it.\n\n### References and bundled files\n\n- **[A] Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. \`[PACKAGED_UNREFERENCED_FILE]\` enforces this at build time. Dead files confuse agents and waste context.\n- **[A] 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. \`[REFERENCE_TOO_DEEP]\` enforces.\n- **[A] 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- **[A] All links resolve**: every \`[text](path)\` link points to a file that exists. \`[LINK_MISSING_TARGET]\` and siblings enforce.\n- **[A] Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- **[A] Test the trigger**: ask \"if an agent sees only this name and description, will it know when to load this skill?\" If understanding the description requires reading the SKILL.md, the description is wrong.\n\n### Frontmatter hygiene\n\n- **[VAT] Frontmatter keys stay conservative**: use only the standard keys \`name\`, \`description\`, \`allowed-tools\` (plus \`argument-hint\` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific \`version:\` or \`metadata:\` fields will be rejected. If you need per-skill config, put it in \`vibe-agent-toolkit.config.yaml\`, not the frontmatter.\n- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don\'t mix folded (\`description: >-\`) and inline (\`description: \"...\"\`) string forms. Pick one and apply it to every skill.\n\n### Cross-skill dependencies\n\n- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (\`Requires ado skill for auth\`). Agents may load one without the other; a silent dependency fails mysteriously at runtime.\n\n### Readability\n\n- **[VAT] Large tables move to reference files**: if a table exceeds ~15 rows, move it to a sibling reference file and link from SKILL.md. Long tables compete for context budget and push the main skill content further down."
+    body: "### Naming\n\n- **[A] Name format**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how. \`[SKILL_NAME_INVALID]\` enforces this.\n- **[A] Prefer gerund form** (\`processing-pdfs\`, \`analyzing-spreadsheets\`). Anthropic recommends gerund form as the primary pattern — \"clearly describes the activity or capability the Skill provides.\" Noun phrases (\`pdf-processing\`) and action-oriented forms (\`process-pdfs\`) are \"acceptable alternatives.\" Avoid vague names like \`helper\`, \`utils\`, \`tools\`.\n- **[VAT] Name matches built skill directory name**: \`[SKILL_NAME_MISMATCHES_DIR]\` fires when the \`name\` frontmatter field differs from the parent directory name after build. The schema allows inference from the directory, but explicit mismatches are usually bugs.\n\n### Description\n\n- **[A] 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. Use when ...\` beats \`This skill is used for when you need to analyze sprints\`.\n- **[A] Third-person voice**: Anthropic guidance is unambiguous — \"**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.\" Avoid first/second person: \`I can help...\`, \`You can use...\`. \`[SKILL_DESCRIPTION_WRONG_PERSON]\` flags these.\n- **[A] \`Use when <concrete trigger>\` is the recommended pattern** — every Anthropic example uses it after a verb phrase. What\'s banned is vague variants like \`Use when you want to...\` / \`Use when you need to...\` that don\'t name a concrete trigger.\n- **[VAT] Prefer a verb phrase or \`Use when ...\` opener** — not a meta-description of the skill-as-object. \`[SKILL_DESCRIPTION_FILLER_OPENER]\` warns on \`This skill...\`, \`A skill that...\`, \`Used to...\` — these waste the first tokens describing the wrapper rather than the behavior. Anthropic doesn\'t ban these explicitly, but their own examples never use them; VAT is stricter here.\n- **[A] Be specific**: include both what the skill does and when to use it. \`[DESCRIPTION_TOO_VAGUE]\` fires below 50 chars. Anthropic\'s bad examples — \`Helps with documents\`, \`Processes data\`, \`Does stuff with files\` — are rejected for vagueness, not length.\n- **[VAT] Description ≤250 characters**: Claude Code truncates descriptions at 250 characters in the \`/skills\` listing (since v2.1.86). \`[SKILL_DESCRIPTION_OVER_CLAUDE_CODE_LIMIT]\` warns at 250; \`[SKILL_DESCRIPTION_TOO_LONG]\` errors at the 1024-char schema hard max. Aim for ≤200 chars for safety; ≤130 chars if shipping a large skill collection (60+ skills) so the total budget fits.\n\n### Body structure\n\n- **[A] SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. \`[SKILL_LENGTH_EXCEEDS_RECOMMENDED]\` warns as you approach the limit. Split detailed content into reference files.\n- **[A] 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- **[A] Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- **[A] Consistent terminology**: pick one term per concept and use it throughout. Mixing \`artifact\` / \`bundle\` / \`package\` confuses agents.\n- **[A] No time-sensitive content**: \`[SKILL_TIME_SENSITIVE_CONTENT]\` flags patterns like \`as of November 2025\` or \`after July 2026\`. Route deprecated guidance into a clearly labeled \`Old patterns\` section so agents skip it.\n\n### References and bundled files\n\n- **[A] Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. \`[PACKAGED_UNREFERENCED_FILE]\` enforces this at build time. Dead files confuse agents and waste context.\n- **[A] 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. \`[REFERENCE_TOO_DEEP]\` enforces.\n- **[A] 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- **[A] All links resolve**: every \`[text](path)\` link points to a file that exists. \`[LINK_MISSING_TARGET]\` and siblings enforce.\n- **[A] Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- **[A] Test the trigger**: ask \"if an agent sees only this name and description, will it know when to load this skill?\" If understanding the description requires reading the SKILL.md, the description is wrong.\n\n### Frontmatter hygiene\n\n- **[VAT] Frontmatter keys stay conservative**: use only the standard keys \`name\`, \`description\`, \`allowed-tools\` (plus \`argument-hint\` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific \`version:\` or \`metadata:\` fields will be rejected. If you need per-skill config, put it in \`vibe-agent-toolkit.config.yaml\`, not the frontmatter. \`[SKILL_FRONTMATTER_EXTRA_FIELDS]\` warns on non-standard keys.\n- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don\'t mix folded (\`description: >-\`) and inline (\`description: \"...\"\`) string forms. Pick one and apply it to every skill. \`[SKILL_DESCRIPTION_STYLE_MIXED_IN_PACKAGE]\` flags mixed styles across a package (detector implemented, pipeline wiring pending).\n\n### Cross-skill dependencies\n\n- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (\`Requires ado skill for auth\`). Agents may load one without the other; a silent dependency fails mysteriously at runtime. \`[SKILL_CROSS_SKILL_AUTH_UNDECLARED]\` flags body prose that requires a sibling skill or \`ANTHROPIC_*_KEY\` env var without naming it in the description.\n\n### Readability\n\n- **[VAT] Large tables move to reference files**: if a table exceeds ~15 rows, move it to a sibling reference file and link from SKILL.md. Long tables compete for context budget and push the main skill content further down.",
+    text: "## General — All Skills\n\n### Naming\n\n- **[A] Name format**: short, specific, lowercase-with-hyphens. Matches what the skill does, not how. \`[SKILL_NAME_INVALID]\` enforces this.\n- **[A] Prefer gerund form** (\`processing-pdfs\`, \`analyzing-spreadsheets\`). Anthropic recommends gerund form as the primary pattern — \"clearly describes the activity or capability the Skill provides.\" Noun phrases (\`pdf-processing\`) and action-oriented forms (\`process-pdfs\`) are \"acceptable alternatives.\" Avoid vague names like \`helper\`, \`utils\`, \`tools\`.\n- **[VAT] Name matches built skill directory name**: \`[SKILL_NAME_MISMATCHES_DIR]\` fires when the \`name\` frontmatter field differs from the parent directory name after build. The schema allows inference from the directory, but explicit mismatches are usually bugs.\n\n### Description\n\n- **[A] 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. Use when ...\` beats \`This skill is used for when you need to analyze sprints\`.\n- **[A] Third-person voice**: Anthropic guidance is unambiguous — \"**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.\" Avoid first/second person: \`I can help...\`, \`You can use...\`. \`[SKILL_DESCRIPTION_WRONG_PERSON]\` flags these.\n- **[A] \`Use when <concrete trigger>\` is the recommended pattern** — every Anthropic example uses it after a verb phrase. What\'s banned is vague variants like \`Use when you want to...\` / \`Use when you need to...\` that don\'t name a concrete trigger.\n- **[VAT] Prefer a verb phrase or \`Use when ...\` opener** — not a meta-description of the skill-as-object. \`[SKILL_DESCRIPTION_FILLER_OPENER]\` warns on \`This skill...\`, \`A skill that...\`, \`Used to...\` — these waste the first tokens describing the wrapper rather than the behavior. Anthropic doesn\'t ban these explicitly, but their own examples never use them; VAT is stricter here.\n- **[A] Be specific**: include both what the skill does and when to use it. \`[DESCRIPTION_TOO_VAGUE]\` fires below 50 chars. Anthropic\'s bad examples — \`Helps with documents\`, \`Processes data\`, \`Does stuff with files\` — are rejected for vagueness, not length.\n- **[VAT] Description ≤250 characters**: Claude Code truncates descriptions at 250 characters in the \`/skills\` listing (since v2.1.86). \`[SKILL_DESCRIPTION_OVER_CLAUDE_CODE_LIMIT]\` warns at 250; \`[SKILL_DESCRIPTION_TOO_LONG]\` errors at the 1024-char schema hard max. Aim for ≤200 chars for safety; ≤130 chars if shipping a large skill collection (60+ skills) so the total budget fits.\n\n### Body structure\n\n- **[A] SKILL.md body ≤500 lines**: Anthropic recommends keeping SKILL.md under 500 lines. \`[SKILL_LENGTH_EXCEEDS_RECOMMENDED]\` warns as you approach the limit. Split detailed content into reference files.\n- **[A] 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- **[A] Single responsibility**: the skill does one thing well. If it has multiple unrelated sections, consider splitting into separate skills.\n- **[A] Consistent terminology**: pick one term per concept and use it throughout. Mixing \`artifact\` / \`bundle\` / \`package\` confuses agents.\n- **[A] No time-sensitive content**: \`[SKILL_TIME_SENSITIVE_CONTENT]\` flags patterns like \`as of November 2025\` or \`after July 2026\`. Route deprecated guidance into a clearly labeled \`Old patterns\` section so agents skip it.\n\n### References and bundled files\n\n- **[A] Every bundled file is referenced**: if a file is in the package, some markdown file should link to it or explain what it is. \`[PACKAGED_UNREFERENCED_FILE]\` enforces this at build time. Dead files confuse agents and waste context.\n- **[A] 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. \`[REFERENCE_TOO_DEEP]\` enforces.\n- **[A] 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- **[A] All links resolve**: every \`[text](path)\` link points to a file that exists. \`[LINK_MISSING_TARGET]\` and siblings enforce.\n- **[A] Build clean**: \`vat skills build\` succeeds and \`vat verify\` passes with zero errors.\n- **[A] Test the trigger**: ask \"if an agent sees only this name and description, will it know when to load this skill?\" If understanding the description requires reading the SKILL.md, the description is wrong.\n\n### Frontmatter hygiene\n\n- **[VAT] Frontmatter keys stay conservative**: use only the standard keys \`name\`, \`description\`, \`allowed-tools\` (plus \`argument-hint\` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific \`version:\` or \`metadata:\` fields will be rejected. If you need per-skill config, put it in \`vibe-agent-toolkit.config.yaml\`, not the frontmatter. \`[SKILL_FRONTMATTER_EXTRA_FIELDS]\` warns on non-standard keys.\n- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don\'t mix folded (\`description: >-\`) and inline (\`description: \"...\"\`) string forms. Pick one and apply it to every skill. \`[SKILL_DESCRIPTION_STYLE_MIXED_IN_PACKAGE]\` flags mixed styles across a package (detector implemented, pipeline wiring pending).\n\n### Cross-skill dependencies\n\n- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (\`Requires ado skill for auth\`). Agents may load one without the other; a silent dependency fails mysteriously at runtime. \`[SKILL_CROSS_SKILL_AUTH_UNDECLARED]\` flags body prose that requires a sibling skill or \`ANTHROPIC_*_KEY\` env var without naming it in the description.\n\n### Readability\n\n- **[VAT] Large tables move to reference files**: if a table exceeds ~15 rows, move it to a sibling reference file and link from SKILL.md. Long tables compete for context budget and push the main skill content further down."
   },
   cliBackedSkills-AdditionalChecks: {
     header: "## CLI-Backed Skills — Additional Checks",

package/dist/skills/vat-skill-review/SKILL.md

@@ -62,12 +62,12 @@ Tooling enforcement: items marked with a bracketed code (e.g., `[SKILL_DESCRIPTI
 
 ### Frontmatter hygiene
 
-- **[VAT] Frontmatter keys stay conservative**: use only the standard keys `name`, `description`, `allowed-tools` (plus `argument-hint` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific `version:` or `metadata:` fields will be rejected. If you need per-skill config, put it in `vibe-agent-toolkit.config.yaml`, not the frontmatter.
-- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don't mix folded (`description: >-`) and inline (`description: "..."`) string forms. Pick one and apply it to every skill.
+- **[VAT] Frontmatter keys stay conservative**: use only the standard keys `name`, `description`, `allowed-tools` (plus `argument-hint` for slash-command-shaped skills). VAT generates SKILL.md under strict schema — novel keys like project-specific `version:` or `metadata:` fields will be rejected. If you need per-skill config, put it in `vibe-agent-toolkit.config.yaml`, not the frontmatter. `[SKILL_FRONTMATTER_EXTRA_FIELDS]` warns on non-standard keys.
+- **[VAT] Sibling skills use consistent YAML styling**: within a single skill package, don't mix folded (`description: >-`) and inline (`description: "..."`) string forms. Pick one and apply it to every skill. `[SKILL_DESCRIPTION_STYLE_MIXED_IN_PACKAGE]` flags mixed styles across a package (detector implemented, pipeline wiring pending).
 
 ### Cross-skill dependencies
 
-- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (`Requires ado skill for auth`). Agents may load one without the other; a silent dependency fails mysteriously at runtime.
+- **[VAT] State cross-skill dependencies in the description**: if this skill delegates auth, pre-flight, or setup to a sibling skill, say so in the description (`Requires ado skill for auth`). Agents may load one without the other; a silent dependency fails mysteriously at runtime. `[SKILL_CROSS_SKILL_AUTH_UNDECLARED]` flags body prose that requires a sibling skill or `ANTHROPIC_*_KEY` env var without naming it in the description.
 
 ### Readability
 

package/package.json

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