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

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

@@ -11,15 +11,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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_STALE_IN_PACKAGE`: detector registered and documented; pipeline wiring deferred to a follow-up RC so adopters aren't surprised by an unexpected warning until the name is settled (the code detects mixed YAML scalar styles across sibling skills — not staleness — and is a rename candidate before it ships observable output).
+  - `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
+- **Config model clarified: one `vibe-agent-toolkit.config.yaml` per VAT project; no composition across projects.** `vat audit` no longer walks the filesystem looking for every nested config under the scan path. Instead, for each SKILL.md it discovers, it walks up to the skill's nearest-ancestor config (if any) and applies only that skill's `skills.config.<name>` packaging rules to the finding. This removes the federated-skill-discovery behavior that was never a documented or intended feature. Lifecycle commands (`vat build`, `vat verify`, `vat skills validate`, `vat skills build`) continue to use exactly one config — the one at their cwd — as they have all along. Adopters who ran `vat audit <ancestor-path>` against monorepos with multiple per-package configs should now run `vat audit` inside each project directory (or use `--cwd`) for per-project validation. When audit encounters a non-scan-root `vibe-agent-toolkit.config.yaml`, it emits a one-time info breadcrumb so operators see which configs were observed. Performance: `vat audit .` on the VAT monorepo drops into the sub-second range because the tree walk is bounded to skill discovery, not to config discovery.
 - `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.33-rc.1",
+  "version": "0.1.33-rc.3",
   "author": {
     "name": "vibe-agent-toolkit contributors"
   }

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

@@ -47,7 +47,7 @@ my-skills-project/
 
 Three conventions are load-bearing:
 
-1. **`vibe-agent-toolkit.config.yaml` at the project root** — VAT walks upward from the invocation directory to find it.
+1. **`vibe-agent-toolkit.config.yaml` at the project root** — VAT commands pick up this file when run from the project root or a subdirectory.
 2. **SKILL.md files live under `resources/skills/`** — any path works, but this one is what `vat build` and `vat audit` expect by default.
 3. **`dist/` is the only write target** — everything VAT generates goes there, and it's gitignored.
 
@@ -105,6 +105,25 @@ Sections and the skills that own their details:
 
 When adding to a section, load the owning skill rather than re-deriving the shape from this file.
 
+## Config lives at the VAT project root
+
+A VAT project is a directory that contains a `vibe-agent-toolkit.config.yaml`. That file is authoritative for the project: it defines `resources`, `skills`, `claude`, and (optionally) `rag`. Nothing outside the config contributes to its behavior — there is no ambient configuration, no inheritance from parent directories, and no merge with sibling configs.
+
+VAT commands (`vat build`, `vat verify`, `vat skills validate`, `vat skills build`) read the config at the directory they are invoked from. Run them from the project root or from a subdirectory, or pass `--cwd <path>` to point them at a specific project. If you run a lifecycle command from somewhere that has no config, it will not find one — there is no upward walk here.
+
+**Multiple `vibe-agent-toolkit.config.yaml` files in one git repository mean multiple distinct VAT projects.** Each project is independent: configs do not compose, do not merge, and do not inherit from one another. Running VAT from outside any project directory operates on a union of whatever projects it discovers, but each project's rules are applied only to its own skills — per-skill packaging overrides in `project-a/vibe-agent-toolkit.config.yaml` never affect skills under `project-b/`.
+
+`vat audit` is the one command that knowingly spans projects, and even there it does not compose: audit is a general-purpose read-only scan that you may point at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill's nearest-ancestor `vibe-agent-toolkit.config.yaml` and applies **only** that skill's packaging rules (from its own project's `skills.config.<name>`) to the finding. This is display sanity, not federation — audit never merges config data across project boundaries.
+
+In practice, prefer one `vibe-agent-toolkit.config.yaml` per git repository. Multiple configs in a single repo are reasonable only for:
+
+- Committed test harnesses or fixtures that define their own toy VAT projects (for VAT's own tests, or for an adopter's integration tests).
+- Genuinely unrelated projects that happen to share a monorepo and each ship their own skills.
+
+If you are tempted to use nested configs to "share" or "override" settings across related skills, fold everything into one project-level config instead — that's what `skills.defaults` and `skills.config.<name>` are for.
+
+(Note: `agent.yaml`, the manifest for TypeScript portable agents, is a separate surface with its own rules and is out of scope for this guidance — see `vibe-agent-toolkit:vat-agent-authoring`.)
+
 ## `package.json` Wiring
 
 For projects that publish skills via npm, three fields tie VAT into the npm lifecycle:

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

@@ -41,6 +41,10 @@ Running `vat audit <path>` recursively walks the directory and auto-detects:
 
 Recursion is the default — you do not need `--recursive`.
 
+## Audit vs configured VAT projects
+
+Audit is the general-purpose command — you may point it at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill's nearest-ancestor `vibe-agent-toolkit.config.yaml` and respects the skill's per-skill packaging rules (`excludeReferencesFromBundle`, `linkFollowDepth`, `files`) to avoid false flags — but it never composes configs across project boundaries. Per-skill rules from one project do not bleed into skills in another project. For gated, configured-project-level validation, use the lifecycle commands (`vat skills validate`, `vat verify`) and run them from within the project directory.
+
 ## Compatibility Analysis (`--compat`)
 
 ```bash

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

@@ -63,7 +63,7 @@ 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. `[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_STALE_IN_PACKAGE]` flags mixed styles across a package (detector implemented, pipeline wiring pending).
+- **[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
 

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

@@ -19,6 +19,7 @@ export const fragments: {
   readonly installingVat: Fragment;
   readonly recommendedRepoStructure: Fragment;
   readonly vibeAgentToolkitconfigyamlShape: Fragment;
+  readonly configLivesAtTheVatProjectRoot: Fragment;
   readonly packagejsonWiring: Fragment;
   readonly vibeValidateIntegration: Fragment;
   readonly firstTimeSetupChecklist: Fragment;

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

@@ -7,7 +7,7 @@ export const meta = {
   description: "Use when starting a new VAT project, adding VAT to an existing repo, or orienting to \`vibe-agent-toolkit.config.yaml\`. Covers project setup, repo structure, package.json wiring, vibe-validate integration, and the npm postinstall hook."
 };
 
-export const text = "\n# VAT Adoption and Configuration\n\nThis skill covers the top-level orientation for adopting VAT in a project: installing the CLI, the overall shape of \`vibe-agent-toolkit.config.yaml\`, repo structure conventions, vibe-validate integration, and how npm postinstall wires plugin registration. Per-section deep-dives live in the sibling skills listed below.\n\n## Installing VAT\n\nVAT ships as the \`vibe-agent-toolkit\` npm package with a \`vat\` CLI:\n\n\`\`\`bash\n# Global install (most common during development)\nnpm install -g vibe-agent-toolkit\n\n# Or run without installing\nnpx vibe-agent-toolkit <command>\nbunx vibe-agent-toolkit <command>\n\n# As a runtime dependency (recommended for published packages that ship skills)\nnpm install --save vibe-agent-toolkit\n\`\`\`\n\nOnce installed, \`vat --help\` lists the top-level command groups. \`vat <group> --help\` and \`vat <group> <cmd> --help --verbose\` cover the rest.\n\n## Recommended Repo Structure\n\n\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT walks upward from the invocation directory to find it.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored.\n\n## \`vibe-agent-toolkit.config.yaml\` Shape\n\n\`\`\`yaml\nversion: 1\n\nskills:\n  include: [\"resources/skills/SKILL.md\", \"resources/skills/*.md\"]\n  defaults:\n    linkFollowDepth: 2\n    excludeNavigationFiles: true\n    targets: [\'claude-code\']\n  config:\n    my-skill:\n      linkFollowDepth: 1\n\nresources:\n  collections:\n    docs:\n      include: [\"docs/**/*.md\"]\n      validation:\n        frontmatterSchema: \"schemas/doc.schema.json\"\n        mode: permissive\n\nclaude:\n  marketplaces:\n    my-marketplace:\n      owner: { name: \"my-org\" }\n      publish:\n        changelog: CHANGELOG.md\n        readme: README.md\n      plugins:\n        - name: my-plugin\n          description: \"What this plugin does\"\n          skills: \"*\"\n\nrag:\n  stores:\n    default:\n      db: .rag-db/\n      include: [\"docs/**/*.md\"]\n\`\`\`\n\nSections and the skills that own their details:\n\n| Section | Owning skill |\n|---|---|\n| Top-level structure, \`version\`, section orientation | this skill (\`vat-adoption-and-configuration\`) |\n| \`skills:\` (include, defaults, per-skill config, packagingOptions) | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| \`resources:\` (collections, schemas, validation modes) | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`claude:\` (marketplaces, plugins, publish, owner) | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`rag:\` (stores, embedding providers) | \`vibe-agent-toolkit:vat-rag\` |\n\nWhen adding to a section, load the owning skill rather than re-deriving the shape from this file.\n\n## \`package.json\` Wiring\n\nFor projects that publish skills via npm, three fields tie VAT into the npm lifecycle:\n\n\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"dependencies\": {\n    \"vibe-agent-toolkit\": \"latest\"\n  },\n  \"scripts\": {\n    \"build\": \"vat build\",\n    \"postinstall\": \"vat claude plugin install --npm-postinstall || exit 0\"\n  },\n  \"vat\": {\n    \"skills\": [\"my-skill-one\", \"my-skill-two\"]\n  }\n}\n\`\`\`\n\n- **\`dependencies.vibe-agent-toolkit\`** — runtime dep, not dev. Needed so the postinstall hook can find \`vat\`.\n- **\`scripts.postinstall\`** — registers the built plugin into the user\'s \`~/.claude/plugins/\` tree after \`npm install -g\` or any install that runs lifecycle scripts. The \`|| exit 0\` keeps \`npm install\` from aborting if the hook can\'t run (unusual but defensive).\n- **\`vat.skills\`** — declares which skill names this package ships. \`vat verify\` cross-checks this list against \`skills.include\` in \`vibe-agent-toolkit.config.yaml\`; mismatches fire \`PACKAGE_JSON_LISTS_UNKNOWN_SKILL\` / \`PACKAGE_JSON_MISSING_SKILL\`. The list is a packaging contract with npm, not a build input — \`vat build\` discovers skills from the config globs.\n\nThe full distribution pipeline (build, verify, npm publish, marketplace layout, managed settings) lives in \`vibe-agent-toolkit:vat-skill-distribution\`.\n\n## vibe-validate Integration\n\nIf the project uses vibe-validate (recommended), wire VAT into the validation config:\n\n\`\`\`yaml\n# vibe-validate.config.yaml (or relevant section)\nphases:\n  - name: vat-build-and-verify\n    parallel: false\n    commands:\n      - name: vat build\n        run: vat build\n      - name: vat verify\n        run: vat verify\n\`\`\`\n\n\`vat verify\` runs the full artifact check (resources → skills → marketplace → consistency); it\'s the authoritative gate before \`npm publish\`. In this repo\'s own config, \`bun run validate\` already does this — adopters typically mirror the pattern.\n\n## First-Time Setup Checklist\n\n1. \`npm install -g vibe-agent-toolkit\` (or add to local deps)\n2. \`vat --help\` — confirm the CLI resolves\n3. Create \`vibe-agent-toolkit.config.yaml\` with the minimal \`version: 1\` plus the sections you need\n4. Add \`resources/skills/SKILL.md\` or a kebab-case SKILL.md file and stage it in git (the skill discovery crawler uses \`git ls-files\` by default — untracked new files are skipped)\n5. \`vat skills validate\` — report any issues before building\n6. \`vat build\` — produces \`dist/\` artifacts\n7. \`vat verify\` — full consistency check; should be a no-op when clean\n8. If publishing: add the \`vat.skills\`, \`scripts.postinstall\`, and \`dependencies.vibe-agent-toolkit\` entries in \`package.json\` before \`npm publish\`\n\n## When Things Are Off\n\n- **\"No skills section in config yaml\"** — either the file isn\'t at the project root, or \`skills.include\` is missing.\n- **\"Found 0 skills\"** — glob doesn\'t match any SKILL.md files. Confirm the path and that the files are tracked by git (VAT\'s discovery respects \`.gitignore\` and \`git ls-files\`).\n- **\`PACKAGE_JSON_LISTS_UNKNOWN_SKILL\`** — \`vat.skills\` mentions a name not produced by \`skills.include\` discovery. Either add the file or remove the name.\n- **\`vat audit\` fires unexpected warnings** — load \`vibe-agent-toolkit:vat-audit\` for the full audit surface, including \`--compat\` and \`--exclude\` flags.\n\n## References\n\n- \`vibe-agent-toolkit:vat-skill-authoring\` — SKILL.md frontmatter, body structure, references, packagingOptions\n- \`vibe-agent-toolkit:vat-agent-authoring\` — TypeScript agent archetypes and runtime adapters\n- \`vibe-agent-toolkit:vat-skill-distribution\` — \`vat build\` / \`vat verify\` / marketplace / npm publish\n- \`vibe-agent-toolkit:vat-knowledge-resources\` — \`resources:\` collections and frontmatter schemas\n- \`vibe-agent-toolkit:vat-rag\` — \`rag:\` stores, embedding providers, \`vat rag index/query\`\n- \`vibe-agent-toolkit:vat-audit\` — \`vat audit\` for plugins, marketplaces, and installed skills\n- \`vibe-agent-toolkit:vat-skill-review\` — pre-publication quality checklist\n- [Getting Started Guide](../../../../docs/getting-started.md) — full setup walkthrough\n";
+export const text = "\n# VAT Adoption and Configuration\n\nThis skill covers the top-level orientation for adopting VAT in a project: installing the CLI, the overall shape of \`vibe-agent-toolkit.config.yaml\`, repo structure conventions, vibe-validate integration, and how npm postinstall wires plugin registration. Per-section deep-dives live in the sibling skills listed below.\n\n## Installing VAT\n\nVAT ships as the \`vibe-agent-toolkit\` npm package with a \`vat\` CLI:\n\n\`\`\`bash\n# Global install (most common during development)\nnpm install -g vibe-agent-toolkit\n\n# Or run without installing\nnpx vibe-agent-toolkit <command>\nbunx vibe-agent-toolkit <command>\n\n# As a runtime dependency (recommended for published packages that ship skills)\nnpm install --save vibe-agent-toolkit\n\`\`\`\n\nOnce installed, \`vat --help\` lists the top-level command groups. \`vat <group> --help\` and \`vat <group> <cmd> --help --verbose\` cover the rest.\n\n## Recommended Repo Structure\n\n\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT commands pick up this file when run from the project root or a subdirectory.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored.\n\n## \`vibe-agent-toolkit.config.yaml\` Shape\n\n\`\`\`yaml\nversion: 1\n\nskills:\n  include: [\"resources/skills/SKILL.md\", \"resources/skills/*.md\"]\n  defaults:\n    linkFollowDepth: 2\n    excludeNavigationFiles: true\n    targets: [\'claude-code\']\n  config:\n    my-skill:\n      linkFollowDepth: 1\n\nresources:\n  collections:\n    docs:\n      include: [\"docs/**/*.md\"]\n      validation:\n        frontmatterSchema: \"schemas/doc.schema.json\"\n        mode: permissive\n\nclaude:\n  marketplaces:\n    my-marketplace:\n      owner: { name: \"my-org\" }\n      publish:\n        changelog: CHANGELOG.md\n        readme: README.md\n      plugins:\n        - name: my-plugin\n          description: \"What this plugin does\"\n          skills: \"*\"\n\nrag:\n  stores:\n    default:\n      db: .rag-db/\n      include: [\"docs/**/*.md\"]\n\`\`\`\n\nSections and the skills that own their details:\n\n| Section | Owning skill |\n|---|---|\n| Top-level structure, \`version\`, section orientation | this skill (\`vat-adoption-and-configuration\`) |\n| \`skills:\` (include, defaults, per-skill config, packagingOptions) | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| \`resources:\` (collections, schemas, validation modes) | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`claude:\` (marketplaces, plugins, publish, owner) | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`rag:\` (stores, embedding providers) | \`vibe-agent-toolkit:vat-rag\` |\n\nWhen adding to a section, load the owning skill rather than re-deriving the shape from this file.\n\n## Config lives at the VAT project root\n\nA VAT project is a directory that contains a \`vibe-agent-toolkit.config.yaml\`. That file is authoritative for the project: it defines \`resources\`, \`skills\`, \`claude\`, and (optionally) \`rag\`. Nothing outside the config contributes to its behavior — there is no ambient configuration, no inheritance from parent directories, and no merge with sibling configs.\n\nVAT commands (\`vat build\`, \`vat verify\`, \`vat skills validate\`, \`vat skills build\`) read the config at the directory they are invoked from. Run them from the project root or from a subdirectory, or pass \`--cwd <path>\` to point them at a specific project. If you run a lifecycle command from somewhere that has no config, it will not find one — there is no upward walk here.\n\n**Multiple \`vibe-agent-toolkit.config.yaml\` files in one git repository mean multiple distinct VAT projects.** Each project is independent: configs do not compose, do not merge, and do not inherit from one another. Running VAT from outside any project directory operates on a union of whatever projects it discovers, but each project\'s rules are applied only to its own skills — per-skill packaging overrides in \`project-a/vibe-agent-toolkit.config.yaml\` never affect skills under \`project-b/\`.\n\n\`vat audit\` is the one command that knowingly spans projects, and even there it does not compose: audit is a general-purpose read-only scan that you may point at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill\'s nearest-ancestor \`vibe-agent-toolkit.config.yaml\` and applies **only** that skill\'s packaging rules (from its own project\'s \`skills.config.<name>\`) to the finding. This is display sanity, not federation — audit never merges config data across project boundaries.\n\nIn practice, prefer one \`vibe-agent-toolkit.config.yaml\` per git repository. Multiple configs in a single repo are reasonable only for:\n\n- Committed test harnesses or fixtures that define their own toy VAT projects (for VAT\'s own tests, or for an adopter\'s integration tests).\n- Genuinely unrelated projects that happen to share a monorepo and each ship their own skills.\n\nIf you are tempted to use nested configs to \"share\" or \"override\" settings across related skills, fold everything into one project-level config instead — that\'s what \`skills.defaults\` and \`skills.config.<name>\` are for.\n\n(Note: \`agent.yaml\`, the manifest for TypeScript portable agents, is a separate surface with its own rules and is out of scope for this guidance — see \`vibe-agent-toolkit:vat-agent-authoring\`.)\n\n## \`package.json\` Wiring\n\nFor projects that publish skills via npm, three fields tie VAT into the npm lifecycle:\n\n\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"dependencies\": {\n    \"vibe-agent-toolkit\": \"latest\"\n  },\n  \"scripts\": {\n    \"build\": \"vat build\",\n    \"postinstall\": \"vat claude plugin install --npm-postinstall || exit 0\"\n  },\n  \"vat\": {\n    \"skills\": [\"my-skill-one\", \"my-skill-two\"]\n  }\n}\n\`\`\`\n\n- **\`dependencies.vibe-agent-toolkit\`** — runtime dep, not dev. Needed so the postinstall hook can find \`vat\`.\n- **\`scripts.postinstall\`** — registers the built plugin into the user\'s \`~/.claude/plugins/\` tree after \`npm install -g\` or any install that runs lifecycle scripts. The \`|| exit 0\` keeps \`npm install\` from aborting if the hook can\'t run (unusual but defensive).\n- **\`vat.skills\`** — declares which skill names this package ships. \`vat verify\` cross-checks this list against \`skills.include\` in \`vibe-agent-toolkit.config.yaml\`; mismatches fire \`PACKAGE_JSON_LISTS_UNKNOWN_SKILL\` / \`PACKAGE_JSON_MISSING_SKILL\`. The list is a packaging contract with npm, not a build input — \`vat build\` discovers skills from the config globs.\n\nThe full distribution pipeline (build, verify, npm publish, marketplace layout, managed settings) lives in \`vibe-agent-toolkit:vat-skill-distribution\`.\n\n## vibe-validate Integration\n\nIf the project uses vibe-validate (recommended), wire VAT into the validation config:\n\n\`\`\`yaml\n# vibe-validate.config.yaml (or relevant section)\nphases:\n  - name: vat-build-and-verify\n    parallel: false\n    commands:\n      - name: vat build\n        run: vat build\n      - name: vat verify\n        run: vat verify\n\`\`\`\n\n\`vat verify\` runs the full artifact check (resources → skills → marketplace → consistency); it\'s the authoritative gate before \`npm publish\`. In this repo\'s own config, \`bun run validate\` already does this — adopters typically mirror the pattern.\n\n## First-Time Setup Checklist\n\n1. \`npm install -g vibe-agent-toolkit\` (or add to local deps)\n2. \`vat --help\` — confirm the CLI resolves\n3. Create \`vibe-agent-toolkit.config.yaml\` with the minimal \`version: 1\` plus the sections you need\n4. Add \`resources/skills/SKILL.md\` or a kebab-case SKILL.md file and stage it in git (the skill discovery crawler uses \`git ls-files\` by default — untracked new files are skipped)\n5. \`vat skills validate\` — report any issues before building\n6. \`vat build\` — produces \`dist/\` artifacts\n7. \`vat verify\` — full consistency check; should be a no-op when clean\n8. If publishing: add the \`vat.skills\`, \`scripts.postinstall\`, and \`dependencies.vibe-agent-toolkit\` entries in \`package.json\` before \`npm publish\`\n\n## When Things Are Off\n\n- **\"No skills section in config yaml\"** — either the file isn\'t at the project root, or \`skills.include\` is missing.\n- **\"Found 0 skills\"** — glob doesn\'t match any SKILL.md files. Confirm the path and that the files are tracked by git (VAT\'s discovery respects \`.gitignore\` and \`git ls-files\`).\n- **\`PACKAGE_JSON_LISTS_UNKNOWN_SKILL\`** — \`vat.skills\` mentions a name not produced by \`skills.include\` discovery. Either add the file or remove the name.\n- **\`vat audit\` fires unexpected warnings** — load \`vibe-agent-toolkit:vat-audit\` for the full audit surface, including \`--compat\` and \`--exclude\` flags.\n\n## References\n\n- \`vibe-agent-toolkit:vat-skill-authoring\` — SKILL.md frontmatter, body structure, references, packagingOptions\n- \`vibe-agent-toolkit:vat-agent-authoring\` — TypeScript agent archetypes and runtime adapters\n- \`vibe-agent-toolkit:vat-skill-distribution\` — \`vat build\` / \`vat verify\` / marketplace / npm publish\n- \`vibe-agent-toolkit:vat-knowledge-resources\` — \`resources:\` collections and frontmatter schemas\n- \`vibe-agent-toolkit:vat-rag\` — \`rag:\` stores, embedding providers, \`vat rag index/query\`\n- \`vibe-agent-toolkit:vat-audit\` — \`vat audit\` for plugins, marketplaces, and installed skills\n- \`vibe-agent-toolkit:vat-skill-review\` — pre-publication quality checklist\n- [Getting Started Guide](../../../../docs/getting-started.md) — full setup walkthrough\n";
 
 export const fragments = {
   installingVat: {
@@ -17,14 +17,19 @@ export const fragments = {
   },
   recommendedRepoStructure: {
     header: "## Recommended Repo Structure",
-    body: "\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT walks upward from the invocation directory to find it.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored.",
-    text: "## Recommended Repo Structure\n\n\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT walks upward from the invocation directory to find it.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored."
+    body: "\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT commands pick up this file when run from the project root or a subdirectory.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored.",
+    text: "## Recommended Repo Structure\n\n\`\`\`\nmy-skills-project/\n├── package.json                        # includes \"vat\" block (see below)\n├── vibe-agent-toolkit.config.yaml      # single source of truth for VAT\n├── resources/\n│   ├── skills/                         # SKILL.md sources\n│   │   ├── SKILL.md                    # router skill (optional, for multi-skill bundles)\n│   │   └── my-skill.md\n│   └── content/                        # non-skill markdown (RAG, collections)\n├── agents/                             # TypeScript portable agents (optional)\n│   └── my-agent/\n│       ├── agent.yaml\n│       └── src/\n├── schemas/                            # JSON Schemas for resource collections\n├── docs/                               # project documentation\n└── dist/                               # generated (gitignored): vat build output\n\`\`\`\n\nThree conventions are load-bearing:\n\n1. **\`vibe-agent-toolkit.config.yaml\` at the project root** — VAT commands pick up this file when run from the project root or a subdirectory.\n2. **SKILL.md files live under \`resources/skills/\`** — any path works, but this one is what \`vat build\` and \`vat audit\` expect by default.\n3. **\`dist/\` is the only write target** — everything VAT generates goes there, and it\'s gitignored."
   },
   vibeAgentToolkitconfigyamlShape: {
     header: "## \`vibe-agent-toolkit.config.yaml\` Shape",
     body: "\`\`\`yaml\nversion: 1\n\nskills:\n  include: [\"resources/skills/SKILL.md\", \"resources/skills/*.md\"]\n  defaults:\n    linkFollowDepth: 2\n    excludeNavigationFiles: true\n    targets: [\'claude-code\']\n  config:\n    my-skill:\n      linkFollowDepth: 1\n\nresources:\n  collections:\n    docs:\n      include: [\"docs/**/*.md\"]\n      validation:\n        frontmatterSchema: \"schemas/doc.schema.json\"\n        mode: permissive\n\nclaude:\n  marketplaces:\n    my-marketplace:\n      owner: { name: \"my-org\" }\n      publish:\n        changelog: CHANGELOG.md\n        readme: README.md\n      plugins:\n        - name: my-plugin\n          description: \"What this plugin does\"\n          skills: \"*\"\n\nrag:\n  stores:\n    default:\n      db: .rag-db/\n      include: [\"docs/**/*.md\"]\n\`\`\`\n\nSections and the skills that own their details:\n\n| Section | Owning skill |\n|---|---|\n| Top-level structure, \`version\`, section orientation | this skill (\`vat-adoption-and-configuration\`) |\n| \`skills:\` (include, defaults, per-skill config, packagingOptions) | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| \`resources:\` (collections, schemas, validation modes) | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`claude:\` (marketplaces, plugins, publish, owner) | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`rag:\` (stores, embedding providers) | \`vibe-agent-toolkit:vat-rag\` |\n\nWhen adding to a section, load the owning skill rather than re-deriving the shape from this file.",
     text: "## \`vibe-agent-toolkit.config.yaml\` Shape\n\n\`\`\`yaml\nversion: 1\n\nskills:\n  include: [\"resources/skills/SKILL.md\", \"resources/skills/*.md\"]\n  defaults:\n    linkFollowDepth: 2\n    excludeNavigationFiles: true\n    targets: [\'claude-code\']\n  config:\n    my-skill:\n      linkFollowDepth: 1\n\nresources:\n  collections:\n    docs:\n      include: [\"docs/**/*.md\"]\n      validation:\n        frontmatterSchema: \"schemas/doc.schema.json\"\n        mode: permissive\n\nclaude:\n  marketplaces:\n    my-marketplace:\n      owner: { name: \"my-org\" }\n      publish:\n        changelog: CHANGELOG.md\n        readme: README.md\n      plugins:\n        - name: my-plugin\n          description: \"What this plugin does\"\n          skills: \"*\"\n\nrag:\n  stores:\n    default:\n      db: .rag-db/\n      include: [\"docs/**/*.md\"]\n\`\`\`\n\nSections and the skills that own their details:\n\n| Section | Owning skill |\n|---|---|\n| Top-level structure, \`version\`, section orientation | this skill (\`vat-adoption-and-configuration\`) |\n| \`skills:\` (include, defaults, per-skill config, packagingOptions) | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| \`resources:\` (collections, schemas, validation modes) | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`claude:\` (marketplaces, plugins, publish, owner) | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`rag:\` (stores, embedding providers) | \`vibe-agent-toolkit:vat-rag\` |\n\nWhen adding to a section, load the owning skill rather than re-deriving the shape from this file."
   },
+  configLivesAtTheVatProjectRoot: {
+    header: "## Config lives at the VAT project root",
+    body: "A VAT project is a directory that contains a \`vibe-agent-toolkit.config.yaml\`. That file is authoritative for the project: it defines \`resources\`, \`skills\`, \`claude\`, and (optionally) \`rag\`. Nothing outside the config contributes to its behavior — there is no ambient configuration, no inheritance from parent directories, and no merge with sibling configs.\n\nVAT commands (\`vat build\`, \`vat verify\`, \`vat skills validate\`, \`vat skills build\`) read the config at the directory they are invoked from. Run them from the project root or from a subdirectory, or pass \`--cwd <path>\` to point them at a specific project. If you run a lifecycle command from somewhere that has no config, it will not find one — there is no upward walk here.\n\n**Multiple \`vibe-agent-toolkit.config.yaml\` files in one git repository mean multiple distinct VAT projects.** Each project is independent: configs do not compose, do not merge, and do not inherit from one another. Running VAT from outside any project directory operates on a union of whatever projects it discovers, but each project\'s rules are applied only to its own skills — per-skill packaging overrides in \`project-a/vibe-agent-toolkit.config.yaml\` never affect skills under \`project-b/\`.\n\n\`vat audit\` is the one command that knowingly spans projects, and even there it does not compose: audit is a general-purpose read-only scan that you may point at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill\'s nearest-ancestor \`vibe-agent-toolkit.config.yaml\` and applies **only** that skill\'s packaging rules (from its own project\'s \`skills.config.<name>\`) to the finding. This is display sanity, not federation — audit never merges config data across project boundaries.\n\nIn practice, prefer one \`vibe-agent-toolkit.config.yaml\` per git repository. Multiple configs in a single repo are reasonable only for:\n\n- Committed test harnesses or fixtures that define their own toy VAT projects (for VAT\'s own tests, or for an adopter\'s integration tests).\n- Genuinely unrelated projects that happen to share a monorepo and each ship their own skills.\n\nIf you are tempted to use nested configs to \"share\" or \"override\" settings across related skills, fold everything into one project-level config instead — that\'s what \`skills.defaults\` and \`skills.config.<name>\` are for.\n\n(Note: \`agent.yaml\`, the manifest for TypeScript portable agents, is a separate surface with its own rules and is out of scope for this guidance — see \`vibe-agent-toolkit:vat-agent-authoring\`.)",
+    text: "## Config lives at the VAT project root\n\nA VAT project is a directory that contains a \`vibe-agent-toolkit.config.yaml\`. That file is authoritative for the project: it defines \`resources\`, \`skills\`, \`claude\`, and (optionally) \`rag\`. Nothing outside the config contributes to its behavior — there is no ambient configuration, no inheritance from parent directories, and no merge with sibling configs.\n\nVAT commands (\`vat build\`, \`vat verify\`, \`vat skills validate\`, \`vat skills build\`) read the config at the directory they are invoked from. Run them from the project root or from a subdirectory, or pass \`--cwd <path>\` to point them at a specific project. If you run a lifecycle command from somewhere that has no config, it will not find one — there is no upward walk here.\n\n**Multiple \`vibe-agent-toolkit.config.yaml\` files in one git repository mean multiple distinct VAT projects.** Each project is independent: configs do not compose, do not merge, and do not inherit from one another. Running VAT from outside any project directory operates on a union of whatever projects it discovers, but each project\'s rules are applied only to its own skills — per-skill packaging overrides in \`project-a/vibe-agent-toolkit.config.yaml\` never affect skills under \`project-b/\`.\n\n\`vat audit\` is the one command that knowingly spans projects, and even there it does not compose: audit is a general-purpose read-only scan that you may point at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill\'s nearest-ancestor \`vibe-agent-toolkit.config.yaml\` and applies **only** that skill\'s packaging rules (from its own project\'s \`skills.config.<name>\`) to the finding. This is display sanity, not federation — audit never merges config data across project boundaries.\n\nIn practice, prefer one \`vibe-agent-toolkit.config.yaml\` per git repository. Multiple configs in a single repo are reasonable only for:\n\n- Committed test harnesses or fixtures that define their own toy VAT projects (for VAT\'s own tests, or for an adopter\'s integration tests).\n- Genuinely unrelated projects that happen to share a monorepo and each ship their own skills.\n\nIf you are tempted to use nested configs to \"share\" or \"override\" settings across related skills, fold everything into one project-level config instead — that\'s what \`skills.defaults\` and \`skills.config.<name>\` are for.\n\n(Note: \`agent.yaml\`, the manifest for TypeScript portable agents, is a separate surface with its own rules and is out of scope for this guidance — see \`vibe-agent-toolkit:vat-agent-authoring\`.)"
+  },
   packagejsonWiring: {
     header: "## \`package.json\` Wiring",
     body: "For projects that publish skills via npm, three fields tie VAT into the npm lifecycle:\n\n\`\`\`json\n{\n  \"name\": \"@myorg/my-skills\",\n  \"dependencies\": {\n    \"vibe-agent-toolkit\": \"latest\"\n  },\n  \"scripts\": {\n    \"build\": \"vat build\",\n    \"postinstall\": \"vat claude plugin install --npm-postinstall || exit 0\"\n  },\n  \"vat\": {\n    \"skills\": [\"my-skill-one\", \"my-skill-two\"]\n  }\n}\n\`\`\`\n\n- **\`dependencies.vibe-agent-toolkit\`** — runtime dep, not dev. Needed so the postinstall hook can find \`vat\`.\n- **\`scripts.postinstall\`** — registers the built plugin into the user\'s \`~/.claude/plugins/\` tree after \`npm install -g\` or any install that runs lifecycle scripts. The \`|| exit 0\` keeps \`npm install\` from aborting if the hook can\'t run (unusual but defensive).\n- **\`vat.skills\`** — declares which skill names this package ships. \`vat verify\` cross-checks this list against \`skills.include\` in \`vibe-agent-toolkit.config.yaml\`; mismatches fire \`PACKAGE_JSON_LISTS_UNKNOWN_SKILL\` / \`PACKAGE_JSON_MISSING_SKILL\`. The list is a packaging contract with npm, not a build input — \`vat build\` discovers skills from the config globs.\n\nThe full distribution pipeline (build, verify, npm publish, marketplace layout, managed settings) lives in \`vibe-agent-toolkit:vat-skill-distribution\`.",

package/dist/generated/resources/skills/vat-audit.d.ts

@@ -18,6 +18,7 @@ export const text: string;
 export const fragments: {
   readonly runningTheAudit: Fragment;
   readonly whatGetsDetectedAutomatic: Fragment;
+  readonly auditVsConfiguredVatProjects: Fragment;
   readonly compatibilityAnalysis--Compat: Fragment;
   readonly exitCodes: Fragment;
   readonly ciUsage: Fragment;

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

@@ -7,7 +7,7 @@ export const meta = {
   description: "Use when running vat audit to validate Claude plugins, agent skills, or marketplaces. Covers the audit command, --compat flag for surface compatibility analysis, --exclude for noise filtering, and interpreting audit output."
 };
 
-export const text = "\n# VAT Audit: Validating Plugins, Skills & Marketplaces\n\n## Running the Audit\n\n\`\`\`bash\n# Audit current directory (recursive by default)\nvat audit\n\n# Audit a specific directory\nvat audit ./plugins/\n\n# Audit your entire Claude installation\nvat audit --user\n\n# Exclude noisy directories\nvat audit --exclude \"dist/**\" --exclude \"node_modules/**\"\n\n# Verbose: show all resources, not just those with issues\nvat audit --verbose\n\n# Compatibility analysis: which Claude surfaces each plugin supports\nvat audit ./plugins/ --compat\n\`\`\`\n\n## What Gets Detected (Automatic)\n\nRunning \`vat audit <path>\` recursively walks the directory and auto-detects:\n\n| Found | Detected as |\n|---|---|\n| \`.claude-plugin/plugin.json\` in a dir | Claude Plugin |\n| \`.claude-plugin/marketplace.json\` in a dir | Claude Marketplace |\n| \`SKILL.md\` file | Agent Skill |\n| \`agent.yaml\` + \`SKILL.md\` | VAT Agent |\n| \`installed_plugins.json\` | Registry file |\n\nRecursion is the default — you do not need \`--recursive\`.\n\n## Compatibility Analysis (\`--compat\`)\n\n\`\`\`bash\nvat audit ./plugins/ --compat\n\`\`\`\n\nOutput per plugin:\n\`\`\`yaml\nplugin: mission-control\ncompatibility:\n  claude-code:\n    compatible: true\n    evidence: []\n  cowork:\n    compatible: true\n    evidence: []\n  claude-desktop:\n    compatible: false\n    evidence:\n      - type: python-script\n        file: hooks-handlers/handler.py\n        detail: Python execution not available in claude-desktop\n\`\`\`\n\nUse this before a release to determine which surfaces each plugin supports.\n\n## Exit Codes\n\n\`vat audit\` is **advisory** — it reports every issue it detects but never blocks on validation severity:\n\n- \`0\` — always, when the audit completes, regardless of errors or warnings in the report.\n- \`2\` — system error (path not found, permission denied, etc.) — the audit could not run.\n\nFor gated checks that exit \`1\` on validation errors, use \`vat skills validate\` or \`vat skills build\` instead. Those commands apply \`validation.severity\` and honor \`validation.allow\` from config.\n\n## CI Usage\n\n\`\`\`yaml\n# vibe-validate.config.yaml\nsteps:\n  - name: Plugin and skill validation\n    command: vat audit plugins/ --exclude \"**/__pycache__/**\"\n\`\`\`\n\n## Interpreting Output\n\n\`\`\`yaml\nstatus: warning\nsummary:\n  filesScanned: 23\n  success: 21\n  warnings: 2\n  errors: 0\n\`\`\`\n\nSeverity taxonomy in audit output:\n- **Errors:** Missing required frontmatter, broken links, invalid plugin.json schema, link integrity violations\n- **Warnings:** Skill too long, description too short, best practice violations\n\nAudit always exits \`0\` regardless — surface-level severity drives display grouping only.\n\n**Hiding codes from audit output.** Audit ignores \`validation.allow\` by design (it is the read-only report), but it does honor \`validation.severity\`. Set a code to \`ignore\` in \`vibe-agent-toolkit.config.yaml\` to suppress it from the audit output:\n\n\`\`\`yaml\nskills:\n  config:\n    my-skill:\n      validation:\n        severity:\n          LINK_TO_NAVIGATION_FILE: ignore   # hidden from audit output\n\`\`\`\n\n**Per-instance allow entries.** For per-path suppression with an audit trail, use \`validation.allow\` and run \`vat skills validate\` or \`vat skills build\` — those commands apply \`allow\` and gate the build. See \`docs/validation-codes.md\` for the full code reference and the VAT agent-authoring skill for configuration patterns.\n";
+export const text = "\n# VAT Audit: Validating Plugins, Skills & Marketplaces\n\n## Running the Audit\n\n\`\`\`bash\n# Audit current directory (recursive by default)\nvat audit\n\n# Audit a specific directory\nvat audit ./plugins/\n\n# Audit your entire Claude installation\nvat audit --user\n\n# Exclude noisy directories\nvat audit --exclude \"dist/**\" --exclude \"node_modules/**\"\n\n# Verbose: show all resources, not just those with issues\nvat audit --verbose\n\n# Compatibility analysis: which Claude surfaces each plugin supports\nvat audit ./plugins/ --compat\n\`\`\`\n\n## What Gets Detected (Automatic)\n\nRunning \`vat audit <path>\` recursively walks the directory and auto-detects:\n\n| Found | Detected as |\n|---|---|\n| \`.claude-plugin/plugin.json\` in a dir | Claude Plugin |\n| \`.claude-plugin/marketplace.json\` in a dir | Claude Marketplace |\n| \`SKILL.md\` file | Agent Skill |\n| \`agent.yaml\` + \`SKILL.md\` | VAT Agent |\n| \`installed_plugins.json\` | Registry file |\n\nRecursion is the default — you do not need \`--recursive\`.\n\n## Audit vs configured VAT projects\n\nAudit is the general-purpose command — you may point it at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill\'s nearest-ancestor \`vibe-agent-toolkit.config.yaml\` and respects the skill\'s per-skill packaging rules (\`excludeReferencesFromBundle\`, \`linkFollowDepth\`, \`files\`) to avoid false flags — but it never composes configs across project boundaries. Per-skill rules from one project do not bleed into skills in another project. For gated, configured-project-level validation, use the lifecycle commands (\`vat skills validate\`, \`vat verify\`) and run them from within the project directory.\n\n## Compatibility Analysis (\`--compat\`)\n\n\`\`\`bash\nvat audit ./plugins/ --compat\n\`\`\`\n\nOutput per plugin:\n\`\`\`yaml\nplugin: mission-control\ncompatibility:\n  claude-code:\n    compatible: true\n    evidence: []\n  cowork:\n    compatible: true\n    evidence: []\n  claude-desktop:\n    compatible: false\n    evidence:\n      - type: python-script\n        file: hooks-handlers/handler.py\n        detail: Python execution not available in claude-desktop\n\`\`\`\n\nUse this before a release to determine which surfaces each plugin supports.\n\n## Exit Codes\n\n\`vat audit\` is **advisory** — it reports every issue it detects but never blocks on validation severity:\n\n- \`0\` — always, when the audit completes, regardless of errors or warnings in the report.\n- \`2\` — system error (path not found, permission denied, etc.) — the audit could not run.\n\nFor gated checks that exit \`1\` on validation errors, use \`vat skills validate\` or \`vat skills build\` instead. Those commands apply \`validation.severity\` and honor \`validation.allow\` from config.\n\n## CI Usage\n\n\`\`\`yaml\n# vibe-validate.config.yaml\nsteps:\n  - name: Plugin and skill validation\n    command: vat audit plugins/ --exclude \"**/__pycache__/**\"\n\`\`\`\n\n## Interpreting Output\n\n\`\`\`yaml\nstatus: warning\nsummary:\n  filesScanned: 23\n  success: 21\n  warnings: 2\n  errors: 0\n\`\`\`\n\nSeverity taxonomy in audit output:\n- **Errors:** Missing required frontmatter, broken links, invalid plugin.json schema, link integrity violations\n- **Warnings:** Skill too long, description too short, best practice violations\n\nAudit always exits \`0\` regardless — surface-level severity drives display grouping only.\n\n**Hiding codes from audit output.** Audit ignores \`validation.allow\` by design (it is the read-only report), but it does honor \`validation.severity\`. Set a code to \`ignore\` in \`vibe-agent-toolkit.config.yaml\` to suppress it from the audit output:\n\n\`\`\`yaml\nskills:\n  config:\n    my-skill:\n      validation:\n        severity:\n          LINK_TO_NAVIGATION_FILE: ignore   # hidden from audit output\n\`\`\`\n\n**Per-instance allow entries.** For per-path suppression with an audit trail, use \`validation.allow\` and run \`vat skills validate\` or \`vat skills build\` — those commands apply \`allow\` and gate the build. See \`docs/validation-codes.md\` for the full code reference and the VAT agent-authoring skill for configuration patterns.\n";
 
 export const fragments = {
   runningTheAudit: {
@@ -20,6 +20,11 @@ export const fragments = {
     body: "Running \`vat audit <path>\` recursively walks the directory and auto-detects:\n\n| Found | Detected as |\n|---|---|\n| \`.claude-plugin/plugin.json\` in a dir | Claude Plugin |\n| \`.claude-plugin/marketplace.json\` in a dir | Claude Marketplace |\n| \`SKILL.md\` file | Agent Skill |\n| \`agent.yaml\` + \`SKILL.md\` | VAT Agent |\n| \`installed_plugins.json\` | Registry file |\n\nRecursion is the default — you do not need \`--recursive\`.",
     text: "## What Gets Detected (Automatic)\n\nRunning \`vat audit <path>\` recursively walks the directory and auto-detects:\n\n| Found | Detected as |\n|---|---|\n| \`.claude-plugin/plugin.json\` in a dir | Claude Plugin |\n| \`.claude-plugin/marketplace.json\` in a dir | Claude Marketplace |\n| \`SKILL.md\` file | Agent Skill |\n| \`agent.yaml\` + \`SKILL.md\` | VAT Agent |\n| \`installed_plugins.json\` | Registry file |\n\nRecursion is the default — you do not need \`--recursive\`."
   },
+  auditVsConfiguredVatProjects: {
+    header: "## Audit vs configured VAT projects",
+    body: "Audit is the general-purpose command — you may point it at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill\'s nearest-ancestor \`vibe-agent-toolkit.config.yaml\` and respects the skill\'s per-skill packaging rules (\`excludeReferencesFromBundle\`, \`linkFollowDepth\`, \`files\`) to avoid false flags — but it never composes configs across project boundaries. Per-skill rules from one project do not bleed into skills in another project. For gated, configured-project-level validation, use the lifecycle commands (\`vat skills validate\`, \`vat verify\`) and run them from within the project directory.",
+    text: "## Audit vs configured VAT projects\n\nAudit is the general-purpose command — you may point it at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill\'s nearest-ancestor \`vibe-agent-toolkit.config.yaml\` and respects the skill\'s per-skill packaging rules (\`excludeReferencesFromBundle\`, \`linkFollowDepth\`, \`files\`) to avoid false flags — but it never composes configs across project boundaries. Per-skill rules from one project do not bleed into skills in another project. For gated, configured-project-level validation, use the lifecycle commands (\`vat skills validate\`, \`vat verify\`) and run them from within the project directory."
+  },
   compatibilityAnalysis--Compat: {
     header: "## Compatibility Analysis (\`--compat\`)",
     body: "\`\`\`bash\nvat audit ./plugins/ --compat\n\`\`\`\n\nOutput per plugin:\n\`\`\`yaml\nplugin: mission-control\ncompatibility:\n  claude-code:\n    compatible: true\n    evidence: []\n  cowork:\n    compatible: true\n    evidence: []\n  claude-desktop:\n    compatible: false\n    evidence:\n      - type: python-script\n        file: hooks-handlers/handler.py\n        detail: Python execution not available in claude-desktop\n\`\`\`\n\nUse this before a release to determine which surfaces each plugin supports.",

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. \`[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_STALE_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 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. \`[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_STALE_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_STALE_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."
+    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-adoption-and-configuration/SKILL.md

@@ -47,7 +47,7 @@ my-skills-project/
 
 Three conventions are load-bearing:
 
-1. **`vibe-agent-toolkit.config.yaml` at the project root** — VAT walks upward from the invocation directory to find it.
+1. **`vibe-agent-toolkit.config.yaml` at the project root** — VAT commands pick up this file when run from the project root or a subdirectory.
 2. **SKILL.md files live under `resources/skills/`** — any path works, but this one is what `vat build` and `vat audit` expect by default.
 3. **`dist/` is the only write target** — everything VAT generates goes there, and it's gitignored.
 
@@ -105,6 +105,25 @@ Sections and the skills that own their details:
 
 When adding to a section, load the owning skill rather than re-deriving the shape from this file.
 
+## Config lives at the VAT project root
+
+A VAT project is a directory that contains a `vibe-agent-toolkit.config.yaml`. That file is authoritative for the project: it defines `resources`, `skills`, `claude`, and (optionally) `rag`. Nothing outside the config contributes to its behavior — there is no ambient configuration, no inheritance from parent directories, and no merge with sibling configs.
+
+VAT commands (`vat build`, `vat verify`, `vat skills validate`, `vat skills build`) read the config at the directory they are invoked from. Run them from the project root or from a subdirectory, or pass `--cwd <path>` to point them at a specific project. If you run a lifecycle command from somewhere that has no config, it will not find one — there is no upward walk here.
+
+**Multiple `vibe-agent-toolkit.config.yaml` files in one git repository mean multiple distinct VAT projects.** Each project is independent: configs do not compose, do not merge, and do not inherit from one another. Running VAT from outside any project directory operates on a union of whatever projects it discovers, but each project's rules are applied only to its own skills — per-skill packaging overrides in `project-a/vibe-agent-toolkit.config.yaml` never affect skills under `project-b/`.
+
+`vat audit` is the one command that knowingly spans projects, and even there it does not compose: audit is a general-purpose read-only scan that you may point at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill's nearest-ancestor `vibe-agent-toolkit.config.yaml` and applies **only** that skill's packaging rules (from its own project's `skills.config.<name>`) to the finding. This is display sanity, not federation — audit never merges config data across project boundaries.
+
+In practice, prefer one `vibe-agent-toolkit.config.yaml` per git repository. Multiple configs in a single repo are reasonable only for:
+
+- Committed test harnesses or fixtures that define their own toy VAT projects (for VAT's own tests, or for an adopter's integration tests).
+- Genuinely unrelated projects that happen to share a monorepo and each ship their own skills.
+
+If you are tempted to use nested configs to "share" or "override" settings across related skills, fold everything into one project-level config instead — that's what `skills.defaults` and `skills.config.<name>` are for.
+
+(Note: `agent.yaml`, the manifest for TypeScript portable agents, is a separate surface with its own rules and is out of scope for this guidance — see `vibe-agent-toolkit:vat-agent-authoring`.)
+
 ## `package.json` Wiring
 
 For projects that publish skills via npm, three fields tie VAT into the npm lifecycle:

package/dist/skills/vat-audit/SKILL.md

@@ -41,6 +41,10 @@ Running `vat audit <path>` recursively walks the directory and auto-detects:
 
 Recursion is the default — you do not need `--recursive`.
 
+## Audit vs configured VAT projects
+
+Audit is the general-purpose command — you may point it at any path, configured or not. When it encounters a SKILL.md inside a configured VAT project, it walks UP to that skill's nearest-ancestor `vibe-agent-toolkit.config.yaml` and respects the skill's per-skill packaging rules (`excludeReferencesFromBundle`, `linkFollowDepth`, `files`) to avoid false flags — but it never composes configs across project boundaries. Per-skill rules from one project do not bleed into skills in another project. For gated, configured-project-level validation, use the lifecycle commands (`vat skills validate`, `vat verify`) and run them from within the project directory.
+
 ## Compatibility Analysis (`--compat`)
 
 ```bash

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

@@ -63,7 +63,7 @@ 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. `[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_STALE_IN_PACKAGE]` flags mixed styles across a package (detector implemented, pipeline wiring pending).
+- **[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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/vat-development-agents",
-  "version": "0.1.33-rc.1",
+  "version": "0.1.33-rc.3",
   "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.33-rc.1",
-    "@vibe-agent-toolkit/cli": "0.1.33-rc.1",
+    "@vibe-agent-toolkit/agent-schema": "0.1.33-rc.3",
+    "@vibe-agent-toolkit/cli": "0.1.33-rc.3",
     "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
-    "@vibe-agent-toolkit/resource-compiler": "0.1.33-rc.1",
+    "@vibe-agent-toolkit/resource-compiler": "0.1.33-rc.3",
     "ts-patch": "^3.2.1",
     "typescript": "^5.7.3"
   },