@vibe-agent-toolkit/vat-development-agents 0.1.37 → 0.1.38

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

@@ -7,7 +7,7 @@ export const meta = {
   description: "Use when working with VAT resource collections, per-directory frontmatter schema validation, link validation, or the vat resources command. Covers collection configuration, schema mapping, and validation modes."
 };
 
-export const text = "\n# VAT Resources: Collections & Frontmatter Validation\n\n## What Resource Collections Are\n\nA **resource collection** is a named group of files that share a validation schema.\nCollections are defined in \`vibe-agent-toolkit.config.yaml\` and enable different\ndirectories to have different required frontmatter — without writing a single line of code.\n\n## Config Format\n\n\`\`\`yaml\nversion: 1\n\nresources:\n  collections:\n    # Name your collection to match the doc type\n    systems:\n      include: [\"docs/systems/**/*.md\"]\n      exclude: [\"docs/systems/README.md\"]   # exclude human-only ToCs\n      validation:\n        frontmatterSchema: \"schemas/system.schema.json\"\n        mode: permissive    # required fields enforced; extra fields allowed\n\n    adrs:\n      include: [\"docs/architecture/adr/**/*.md\"]\n      validation:\n        frontmatterSchema: \"schemas/adr.schema.json\"\n        mode: permissive\n\n    skills:\n      include: [\"**/SKILL.md\"]\n      validation:\n        frontmatterSchema: \"@vibe-agent-toolkit/agent-skills/schemas/skill-frontmatter.json\"\n        mode: strict         # SKILL.md: no extra fields beyond spec\n\`\`\`\n\n## Validation Modes\n\n| Mode | Required fields | Extra fields | Use for |\n|---|---|---|---|\n| \`permissive\` | Enforced | Allowed | Docs with project-specific extras |\n| \`strict\` | Enforced | Error | SKILL.md, API specs, tightly controlled schemas |\n\n## Running Validation\n\n\`\`\`bash\n# Validate all collections (reads vibe-agent-toolkit.config.yaml)\nvat resources validate\n\n# Validate specific collection only\nvat resources validate --collection systems\n\n# Validate with extra schema (adds to collection schemas)\nvat resources validate --frontmatter-schema ./extra.json\n\`\`\`\n\n## A File Can Belong to Multiple Collections\n\nIf a file matches multiple \`include\` patterns, **all matching schemas are validated**.\nValidation fails if any schema fails.\n\n## Schema Path Formats\n\n\`\`\`yaml\nfrontmatterSchema: \"./schemas/system.schema.json\"          # relative to config\nfrontmatterSchema: \"/absolute/path/schema.json\"            # absolute\nfrontmatterSchema: \"@vibe-agent-toolkit/agent-skills/...\"  # npm package export\n\`\`\`\n\n## Adding a New Doc Type\n\n1. Create \`schemas/<type>.schema.json\` with \`required\` fields\n2. Add a collection entry in \`vibe-agent-toolkit.config.yaml\`\n3. Run \`vat resources validate\` — any existing docs missing required fields will be flagged\n4. Fix frontmatter in existing docs, then CI is clean\n\n## Recommend \`format: \"uri-reference\"\` for path-shaped frontmatter fields\n\nWhen designing a schema for a knowledge-base collection that references other files (e.g., \`parent_prd\`, \`supersedes\`, \`adr_citations[*].adr\`, \`artifacts\`), declare \`format: \"uri-reference\"\` on the field. VAT will then validate those values against the file system using the same engine as markdown link checking — broken paths, missing anchors, gitignore violations, and unknown URI schemes all produce errors.\n\nTo require local committed files (no absolute URLs), add a \`pattern\` excluding scheme prefixes. Standard JSON Schema; stays portable.\n\nVAT walks four URI-family formats: \`uri-reference\`, \`uri\`, \`iri-reference\`, \`iri\`. \`uri-template\` (RFC 6570) is intentionally NOT walked — templated values contain placeholders.\n\nAbsolute URLs in URI-reference fields feed into the existing external URL health-check pass when \`checkUrlLinks: true\` is set on the collection.\n\nOpt-out: \`checkFrontmatterLinks: false\` per collection, or \`--no-check-frontmatter-links\` on the CLI.\n\n## Annotating Frontmatter Schemas with Zod 4\n\nIf your project generates JSON Schemas from Zod (via \`z.toJSONSchema()\`), annotate frontmatter fields that hold links with the appropriate \`format\` so VAT\'s link validator picks them up:\n\n\`\`\`typescript\nimport { z } from \'zod\';\n\nconst PrdFrontmatter = z.object({\n  spec_ref:   z.string().meta({ format: \'uri-reference\' }),   // repo-relative or absolute\n  roadmap:    z.url().meta({ format: \'uri\' }),                // full URL only\n  doc_anchor: z.string().meta({ format: \'json-pointer\' }),    // JSON Pointer\n});\n\`\`\`\n\n\`format\` values VAT walks for link validation: \`uri\`, \`uri-reference\`, \`iri\`, \`iri-reference\`. \`uri-template\` (RFC 6570) is intentionally NOT walked — templated values contain placeholders.\n\n**Zod 3 users:** \`.meta()\` does not exist in Zod 3. Either upgrade your schema-generation step to Zod 4 (runtime consumers can stay on Zod 3 via peer dependency + common-subset usage), or post-process the generated JSON Schema to inject \`format\` on the relevant field paths.\n\n**Tip:** \`format\` is advisory in JSON Schema; pair it with a \`pattern\` regex when you also need parse-time rejection of invalid inputs.\n\n## Validation Output\n\n\`\`\`yaml\nstatus: success\nfilesScanned: 47\ncollections:\n  systems:\n    resourceCount: 7\n    hasSchema: true\n    validationMode: permissive\n  adrs:\n    resourceCount: 12\n    hasSchema: true\n    validationMode: permissive\nduration: 234ms\n\`\`\`\n\nErrors appear in stderr with \`file:line: message\` format for editor navigation.\n";
+export const text = "\n# VAT Resources: Collections & Frontmatter Validation\n\n## What Resource Collections Are\n\nA **resource collection** is a named group of files that share a validation schema.\nCollections are defined in \`vibe-agent-toolkit.config.yaml\` and enable different\ndirectories to have different required frontmatter — without writing a single line of code.\n\n## Config Format\n\n\`\`\`yaml\nversion: 1\n\nresources:\n  collections:\n    # Name your collection to match the doc type\n    systems:\n      include: [\"docs/systems/**/*.md\"]\n      exclude: [\"docs/systems/README.md\"]   # exclude human-only ToCs\n      validation:\n        frontmatterSchema: \"schemas/system.schema.json\"\n        mode: permissive    # required fields enforced; extra fields allowed\n\n    adrs:\n      include: [\"docs/architecture/adr/**/*.md\"]\n      validation:\n        frontmatterSchema: \"schemas/adr.schema.json\"\n        mode: permissive\n\n    skills:\n      include: [\"**/SKILL.md\"]\n      validation:\n        frontmatterSchema: \"@vibe-agent-toolkit/agent-skills/schemas/skill-frontmatter.json\"\n        mode: strict         # SKILL.md: no extra fields beyond spec\n\`\`\`\n\n## Validation Modes\n\n| Mode | Required fields | Extra fields | Use for |\n|---|---|---|---|\n| \`permissive\` | Enforced | Allowed | Docs with project-specific extras |\n| \`strict\` | Enforced | Error | SKILL.md, API specs, tightly controlled schemas |\n\n## Running Validation\n\n\`\`\`bash\n# Validate all collections (reads vibe-agent-toolkit.config.yaml)\nvat resources validate\n\n# Validate specific collection only\nvat resources validate --collection systems\n\n# Validate with extra schema (adds to collection schemas)\nvat resources validate --frontmatter-schema ./extra.json\n\`\`\`\n\n## A File Can Belong to Multiple Collections\n\nIf a file matches multiple \`include\` patterns, **all matching schemas are validated**.\nValidation fails if any schema fails.\n\n## Schema Path Formats\n\n\`\`\`yaml\nfrontmatterSchema: \"./schemas/system.schema.json\"          # relative to config\nfrontmatterSchema: \"/absolute/path/schema.json\"            # absolute\nfrontmatterSchema: \"@vibe-agent-toolkit/agent-skills/...\"  # npm package export\n\`\`\`\n\n## Adding a New Doc Type\n\n1. Create \`schemas/<type>.schema.json\` with \`required\` fields\n2. Add a collection entry in \`vibe-agent-toolkit.config.yaml\`\n3. Run \`vat resources validate\` — any existing docs missing required fields will be flagged\n4. Fix frontmatter in existing docs, then CI is clean\n\n## Recommend \`format: \"uri-reference\"\` for path-shaped frontmatter fields\n\nWhen designing a schema for a knowledge-base collection that references other files (e.g., \`parent_prd\`, \`supersedes\`, \`adr_citations[*].adr\`, \`artifacts\`), declare \`format: \"uri-reference\"\` on the field. VAT will then validate those values against the file system using the same engine as markdown link checking — broken paths, missing anchors, gitignore violations, and unknown URI schemes all produce errors.\n\nTo require local committed files (no absolute URLs), add a \`pattern\` excluding scheme prefixes. Standard JSON Schema; stays portable.\n\nVAT walks four URI-family formats: \`uri-reference\`, \`uri\`, \`iri-reference\`, \`iri\`. \`uri-template\` (RFC 6570) is intentionally NOT walked — templated values contain placeholders.\n\nAbsolute URLs in URI-reference fields feed into the existing external URL health-check pass when \`checkUrlLinks: true\` is set on the collection.\n\nOpt-out: \`checkFrontmatterLinks: false\` per collection, or \`--no-check-frontmatter-links\` on the CLI.\n\n## Annotating Frontmatter Schemas with Zod 4\n\nIf your project generates JSON Schemas from Zod (via \`z.toJSONSchema()\`), annotate frontmatter fields that hold links with the appropriate \`format\` so VAT\'s link validator picks them up:\n\n\`\`\`typescript\nimport { z } from \'zod\';\n\nconst PrdFrontmatter = z.object({\n  spec_ref:   z.string().meta({ format: \'uri-reference\' }),   // repo-relative or absolute\n  roadmap:    z.url().meta({ format: \'uri\' }),                // full URL only\n  doc_anchor: z.string().meta({ format: \'json-pointer\' }),    // JSON Pointer\n});\n\`\`\`\n\n\`format\` values VAT walks for link validation: \`uri\`, \`uri-reference\`, \`iri\`, \`iri-reference\`. \`uri-template\` (RFC 6570) is intentionally NOT walked — templated values contain placeholders.\n\n**Zod 3 users:** \`.meta()\` does not exist in Zod 3. Either upgrade your schema-generation step to Zod 4 (runtime consumers can stay on Zod 3 via peer dependency + common-subset usage), or post-process the generated JSON Schema to inject \`format\` on the relevant field paths.\n\n**Tip:** \`format\` is advisory in JSON Schema; pair it with a \`pattern\` regex when you also need parse-time rejection of invalid inputs.\n\n## URI-references in frontmatter\n\nVAT validates frontmatter fields whose schema position has \`format: uri-reference\`\n(or \`uri\`, \`iri-reference\`, \`iri\`) against the same rules as body links:\n\n- Leading-\`/\` is RFC 3986 §4.2 absolute-path reference — resolved against\n  the project root. Same semantics as body links.\n- Anchor fragments and external URLs are accepted; broken local refs error.\n- Inline comments on URI-ref fields are **preserved** when any tool rewrites\n  the file via \`openFrontmatter\` (VAT packager, hand-rolled adopter scripts).\n\nExample:\n\n\`\`\`yaml\n---\nparent_spec: /docs/specs/foo.md  # the spec this one supersedes\nadrs-cited:\n  - /docs/adrs/0007-storage.md  # primary reference\n  - /docs/adrs/0011-snapshot.md  # impacted by storage choice\n---\n\`\`\`\n\nSchema:\n\n\`\`\`json\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"parent_spec\": { \"type\": \"string\", \"format\": \"uri-reference\" },\n    \"adrs-cited\": {\n      \"type\": \"array\",\n      \"items\": { \"type\": \"string\", \"format\": \"uri-reference\" }\n    }\n  }\n}\n\`\`\`\n\nFor tools that **modify** frontmatter (not just validate it), see\n[[markdown-rewriting]].\n\n## Validation Output\n\n\`\`\`yaml\nstatus: success\nfilesScanned: 47\ncollections:\n  systems:\n    resourceCount: 7\n    hasSchema: true\n    validationMode: permissive\n  adrs:\n    resourceCount: 12\n    hasSchema: true\n    validationMode: permissive\nduration: 234ms\n\`\`\`\n\nErrors appear in stderr with \`file:line: message\` format for editor navigation.\n";
 
 export const fragments = {
   whatResourceCollectionsAre: {
@@ -55,6 +55,11 @@ export const fragments = {
     body: "If your project generates JSON Schemas from Zod (via \`z.toJSONSchema()\`), annotate frontmatter fields that hold links with the appropriate \`format\` so VAT\'s link validator picks them up:\n\n\`\`\`typescript\nimport { z } from \'zod\';\n\nconst PrdFrontmatter = z.object({\n  spec_ref:   z.string().meta({ format: \'uri-reference\' }),   // repo-relative or absolute\n  roadmap:    z.url().meta({ format: \'uri\' }),                // full URL only\n  doc_anchor: z.string().meta({ format: \'json-pointer\' }),    // JSON Pointer\n});\n\`\`\`\n\n\`format\` values VAT walks for link validation: \`uri\`, \`uri-reference\`, \`iri\`, \`iri-reference\`. \`uri-template\` (RFC 6570) is intentionally NOT walked — templated values contain placeholders.\n\n**Zod 3 users:** \`.meta()\` does not exist in Zod 3. Either upgrade your schema-generation step to Zod 4 (runtime consumers can stay on Zod 3 via peer dependency + common-subset usage), or post-process the generated JSON Schema to inject \`format\` on the relevant field paths.\n\n**Tip:** \`format\` is advisory in JSON Schema; pair it with a \`pattern\` regex when you also need parse-time rejection of invalid inputs.",
     text: "## Annotating Frontmatter Schemas with Zod 4\n\nIf your project generates JSON Schemas from Zod (via \`z.toJSONSchema()\`), annotate frontmatter fields that hold links with the appropriate \`format\` so VAT\'s link validator picks them up:\n\n\`\`\`typescript\nimport { z } from \'zod\';\n\nconst PrdFrontmatter = z.object({\n  spec_ref:   z.string().meta({ format: \'uri-reference\' }),   // repo-relative or absolute\n  roadmap:    z.url().meta({ format: \'uri\' }),                // full URL only\n  doc_anchor: z.string().meta({ format: \'json-pointer\' }),    // JSON Pointer\n});\n\`\`\`\n\n\`format\` values VAT walks for link validation: \`uri\`, \`uri-reference\`, \`iri\`, \`iri-reference\`. \`uri-template\` (RFC 6570) is intentionally NOT walked — templated values contain placeholders.\n\n**Zod 3 users:** \`.meta()\` does not exist in Zod 3. Either upgrade your schema-generation step to Zod 4 (runtime consumers can stay on Zod 3 via peer dependency + common-subset usage), or post-process the generated JSON Schema to inject \`format\` on the relevant field paths.\n\n**Tip:** \`format\` is advisory in JSON Schema; pair it with a \`pattern\` regex when you also need parse-time rejection of invalid inputs."
   },
+  uriReferencesInFrontmatter: {
+    header: "## URI-references in frontmatter",
+    body: "VAT validates frontmatter fields whose schema position has \`format: uri-reference\`\n(or \`uri\`, \`iri-reference\`, \`iri\`) against the same rules as body links:\n\n- Leading-\`/\` is RFC 3986 §4.2 absolute-path reference — resolved against\n  the project root. Same semantics as body links.\n- Anchor fragments and external URLs are accepted; broken local refs error.\n- Inline comments on URI-ref fields are **preserved** when any tool rewrites\n  the file via \`openFrontmatter\` (VAT packager, hand-rolled adopter scripts).\n\nExample:\n\n\`\`\`yaml\n---\nparent_spec: /docs/specs/foo.md  # the spec this one supersedes\nadrs-cited:\n  - /docs/adrs/0007-storage.md  # primary reference\n  - /docs/adrs/0011-snapshot.md  # impacted by storage choice\n---\n\`\`\`\n\nSchema:\n\n\`\`\`json\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"parent_spec\": { \"type\": \"string\", \"format\": \"uri-reference\" },\n    \"adrs-cited\": {\n      \"type\": \"array\",\n      \"items\": { \"type\": \"string\", \"format\": \"uri-reference\" }\n    }\n  }\n}\n\`\`\`\n\nFor tools that **modify** frontmatter (not just validate it), see\n[[markdown-rewriting]].",
+    text: "## URI-references in frontmatter\n\nVAT validates frontmatter fields whose schema position has \`format: uri-reference\`\n(or \`uri\`, \`iri-reference\`, \`iri\`) against the same rules as body links:\n\n- Leading-\`/\` is RFC 3986 §4.2 absolute-path reference — resolved against\n  the project root. Same semantics as body links.\n- Anchor fragments and external URLs are accepted; broken local refs error.\n- Inline comments on URI-ref fields are **preserved** when any tool rewrites\n  the file via \`openFrontmatter\` (VAT packager, hand-rolled adopter scripts).\n\nExample:\n\n\`\`\`yaml\n---\nparent_spec: /docs/specs/foo.md  # the spec this one supersedes\nadrs-cited:\n  - /docs/adrs/0007-storage.md  # primary reference\n  - /docs/adrs/0011-snapshot.md  # impacted by storage choice\n---\n\`\`\`\n\nSchema:\n\n\`\`\`json\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"parent_spec\": { \"type\": \"string\", \"format\": \"uri-reference\" },\n    \"adrs-cited\": {\n      \"type\": \"array\",\n      \"items\": { \"type\": \"string\", \"format\": \"uri-reference\" }\n    }\n  }\n}\n\`\`\`\n\nFor tools that **modify** frontmatter (not just validate it), see\n[[markdown-rewriting]]."
+  },
   validationOutput: {
     header: "## Validation Output",
     body: "\`\`\`yaml\nstatus: success\nfilesScanned: 47\ncollections:\n  systems:\n    resourceCount: 7\n    hasSchema: true\n    validationMode: permissive\n  adrs:\n    resourceCount: 12\n    hasSchema: true\n    validationMode: permissive\nduration: 234ms\n\`\`\`\n\nErrors appear in stderr with \`file:line: message\` format for editor navigation.",

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

@@ -17,6 +17,7 @@ export const text: string;
 
 export const fragments: {
   readonly skillmdStructure: Fragment;
+  readonly crossDocumentReferencesInSkillmdFrontmatter: Fragment;
   readonly bodyStructure: Fragment;
   readonly referencesSection: Fragment;
   readonly packagingoptionsReference: Fragment;

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

@@ -7,7 +7,7 @@ export const meta = {
   description: "Use when authoring or revising a SKILL.md file — frontmatter, body structure, references, packagingOptions (linkFollowDepth, excludeReferencesFromBundle), and validation overrides. Paired with vat-skill-review for pre-publication checks."
 };
 
-export const text = "\n# VAT Skill Authoring: SKILL.md Structure and Packaging\n\nThis skill covers authoring SKILL.md files for portable Claude skills: frontmatter shape, body structure, reference links, and the packaging options that control how the skill is bundled for distribution. For the TypeScript agent side (archetypes, result envelopes, orchestration, runtime adapters) use \`vibe-agent-toolkit:vat-agent-authoring\`.\n\n## SKILL.md Structure\n\nA SKILL.md file is the definition file for a portable skill. It tells Claude what the skill does and how to use it. All SKILL.md files must have YAML frontmatter:\n\n\`\`\`markdown\n---\nname: my-skill\ndescription: One sentence — what this skill does and when to use it (≤250 chars)\n---\n\n# My Skill\n\nRest of the skill documentation...\n\`\`\`\n\nRequired frontmatter fields:\n\n- \`name\` — unique identifier, kebab-case (\`^[a-z][a-z0-9-]*$\`), matches the skill\'s directory name after build. Avoid the reserved words \`claude\` and \`anthropic\` (Claude Code rejects non-certified skills using those words — surfaced as \`RESERVED_WORD_IN_NAME\`).\n- \`description\` — trigger description used for Claude\'s skill routing; be specific about activation conditions.\n\nBest practices for \`description\`:\n\n- Lead with an action verb or \`Use when <concrete trigger>\` — filler openers like \"This skill...\", \"A skill that...\", \"Use when you want to...\" fire \`SKILL_DESCRIPTION_FILLER_OPENER\`.\n- Include 2–4 trigger keywords a user is likely to type.\n- Write in third person. First-person (\"I can...\") and conversational second-person (\"You can use...\") fire \`SKILL_DESCRIPTION_WRONG_PERSON\`.\n- Keep under 250 characters so the Claude Code \`/skills\` listing doesn\'t truncate the tail (target ≤200 for safety, ≤130 if shipping a large skill collection). The hard schema limit is 1024.\n\n## Body Structure\n\n- Lead with a short orientation paragraph: what the skill owns and when to reach for it.\n- Use H2 sections for major content blocks; avoid deeply nested H3/H4 trees — they hurt Claude\'s ability to route attention inside the file.\n- Keep SKILL.md under ~500 lines. Longer than that fires \`SKILL_LENGTH_EXCEEDS_RECOMMENDED\` and is a strong signal to split via progressive disclosure (linked reference files) or to spin the content into a sibling skill.\n- Avoid time-sensitive phrasing like \"as of April 2026\" in the body — it ages the skill quickly (\`SKILL_TIME_SENSITIVE_CONTENT\`).\n\n## References Section\n\nA short \`## References\` section at the bottom is the canonical place to list linked resources. Two patterns:\n\n- **Progressive disclosure** — link to \`.md\` files inside the skill directory that get bundled. Keep reference depth ≤ 2 hops; deeper chains fire \`REFERENCE_TOO_DEEP\`.\n- **Prose references to sibling skills** — write \`vibe-agent-toolkit:vat-audit\`, not \`[vat-audit](./vat-audit.md)\`. Markdown links to sibling SKILL.md files cause the packager to transclude the other skill (and fire \`LINK_TO_SKILL_DEFINITION\`).\n\nAvoid linking to navigation files (\`README.md\`, \`index.md\`) — they\'re excluded from the bundle and the link resolves to nothing (\`LINK_TO_NAVIGATION_FILE\`).\n\n## packagingOptions Reference\n\nPackaging options are configured per skill in \`vibe-agent-toolkit.config.yaml\` under \`skills.config.<name>\`:\n\n\`\`\`yaml\nskills:\n  include: [\"resources/skills/SKILL.md\", \"resources/skills/*.md\"]\n  defaults:\n    linkFollowDepth: 2\n  config:\n    my-skill:\n      linkFollowDepth: 1\n      resourceNaming: resource-id\n      stripPrefix: knowledge-base\n      excludeReferencesFromBundle:\n        rules:\n          - patterns: [\"**/concepts/**\"]\n            template: \"Use search to find: {{link.text}}\"\n        defaultTemplate: \"{{link.text}} (search knowledge base)\"\n\`\`\`\n\n**\`linkFollowDepth\`** — How deep to follow links from SKILL.md:\n\n| Value | Behavior |\n|-------|----------|\n| \`0\` | Skill file only (no links followed) |\n| \`1\` | Direct links only |\n| \`2\` | Direct + one transitive level **(default)** |\n| \`\"full\"\` | Complete transitive closure |\n\n**\`resourceNaming\`** — How bundled files are named:\n\n| Strategy | Example | Use When |\n|----------|---------|----------|\n| \`basename\` | \`overview.md\` | Few files, unique names **(default)** |\n| \`resource-id\` | \`topics-quickstart-overview.md\` | Many files, flat output |\n| \`preserve-path\` | \`topics/quickstart/overview.md\` | Preserve structure |\n\nUse \`stripPrefix\` to remove a common directory prefix (e.g., \`\"knowledge-base\"\`).\n\n**\`excludeReferencesFromBundle\`** — Rules for excluding files and rewriting their links:\n\n- \`rules[]\` — ordered glob patterns (first match wins), each with optional Handlebars template\n- \`defaultTemplate\` — applied to depth-exceeded links not matching any rule\n\n**Template variables:**\n\n| Variable | Description |\n|----------|-------------|\n| \`{{link.text}}\` | Link display text |\n| \`{{link.href}}\` | Original href (without fragment) |\n| \`{{link.fragment}}\` | Fragment including \`#\` prefix, or empty |\n| \`{{link.type}}\` | Link type (\`\"local_file\"\`, etc.) |\n| \`{{link.resource.id}}\` | Target resource ID (if resolved) |\n| \`{{link.resource.fileName}}\` | Target filename (if resolved) |\n| \`{{skill.name}}\` | Skill name from frontmatter |\n\n## Validation Overrides\n\nThe \`validation\` sub-key in a skill\'s config provides the unified override framework for VAT validation codes:\n\n\`\`\`yaml\nskills:\n  config:\n    my-skill:\n      validation:\n        severity:\n          LINK_DROPPED_BY_DEPTH: error           # upgrade: block on depth-dropped links\n          LINK_TO_NAVIGATION_FILE: ignore        # silence: this skill intentionally links to READMEs\n        allow:\n          PACKAGED_UNREFERENCED_FILE:\n            - paths: [\"templates/runtime.json\"]\n              reason: \"consumed programmatically at runtime\"\n              expires: \"2026-09-30\"\n          SKILL_LENGTH_EXCEEDS_RECOMMENDED:\n            - reason: \"whole-skill concern; paths defaults to [\'**/*\']\"\n\`\`\`\n\nTwo sub-keys, each covering a different override granularity:\n\n- **\`severity\`** — class-level. Raise any code to \`error\` (blocks build), lower to \`warning\` (emits, non-blocking), or \`ignore\` (fully suppressed). Applies to every instance of that code.\n- **\`allow\`** — per-instance. Suppress specific \`(code, path)\` matches with a required \`reason\` and optional \`expires\` date. \`paths\` is optional (defaults to \`[\"**/*\"]\` — the whole skill). Use for legitimate exceptions that don\'t warrant code-wide silencing.\n\nCommon adjustments:\n\n- Downgrade \`LINK_DROPPED_BY_DEPTH\` to \`ignore\` when intentionally linking out to external docs.\n- Allow specific files under \`PACKAGED_UNREFERENCED_FILE\` when they\'re consumed programmatically by CLI scripts at runtime.\n- Raise \`ALLOW_EXPIRED\` to \`error\` for zero-tolerance expiry policies.\n\nExpired \`allow\` entries still apply — VAT emits \`ALLOW_EXPIRED\` as a reminder rather than silently re-surfacing the underlying issue (no surprise build breaks when a date passes). Unused \`allow\` entries surface as \`ALLOW_UNUSED\` (analogous to ESLint\'s unused-disable).\n\n\`vat audit\` is advisory: it applies \`severity\` for display grouping only, ignores \`allow\`, and always exits 0. Use \`vat skills validate\` or \`vat skills build\` for gated checks.\n\n## Pre-publication Check\n\nBefore shipping a skill, walk through the \`vibe-agent-toolkit:vat-skill-review\` checklist — it covers naming, description quality, structure, validation-code triage, and Anthropic\'s skill-authoring best practices. The \`vat skill review <skill>\` CLI command renders a skill-specific view of the same checklist.\n\n## References\n\n- \`vibe-agent-toolkit:vat-skill-review\` — pre-publication quality checklist (general + CLI-backed items, tied to VAT validation codes)\n- \`vibe-agent-toolkit:vat-skill-distribution\` — plugin/marketplace config, \`vat build\`, \`vat verify\`, npm publishing\n- \`vibe-agent-toolkit:vat-knowledge-resources\` — the \`resources:\` config section for multi-collection frontmatter schema validation\n- [Validation Codes Reference](../../../../docs/validation-codes.md) — full list of codes VAT emits, their default severity, and override recipes.\n- [Skill Quality and Compatibility — VAT\'s Stance](../../../../docs/skill-quality-and-compatibility.md) — what VAT believes makes a skill good and compatible.\n";
+export const text = "\n# VAT Skill Authoring: SKILL.md Structure and Packaging\n\nThis skill covers authoring SKILL.md files for portable Claude skills: frontmatter shape, body structure, reference links, and the packaging options that control how the skill is bundled for distribution. For the TypeScript agent side (archetypes, result envelopes, orchestration, runtime adapters) use \`vibe-agent-toolkit:vat-agent-authoring\`.\n\n## SKILL.md Structure\n\nA SKILL.md file is the definition file for a portable skill. It tells Claude what the skill does and how to use it. All SKILL.md files must have YAML frontmatter:\n\n\`\`\`markdown\n---\nname: my-skill\ndescription: One sentence — what this skill does and when to use it (≤250 chars)\n---\n\n# My Skill\n\nRest of the skill documentation...\n\`\`\`\n\nRequired frontmatter fields:\n\n- \`name\` — unique identifier, kebab-case (\`^[a-z][a-z0-9-]*$\`), matches the skill\'s directory name after build. Avoid the reserved words \`claude\` and \`anthropic\` (Claude Code rejects non-certified skills using those words — surfaced as \`RESERVED_WORD_IN_NAME\`).\n- \`description\` — trigger description used for Claude\'s skill routing; be specific about activation conditions.\n\nBest practices for \`description\`:\n\n- Lead with an action verb or \`Use when <concrete trigger>\` — filler openers like \"This skill...\", \"A skill that...\", \"Use when you want to...\" fire \`SKILL_DESCRIPTION_FILLER_OPENER\`.\n- Include 2–4 trigger keywords a user is likely to type.\n- Write in third person. First-person (\"I can...\") and conversational second-person (\"You can use...\") fire \`SKILL_DESCRIPTION_WRONG_PERSON\`.\n- Keep under 250 characters so the Claude Code \`/skills\` listing doesn\'t truncate the tail (target ≤200 for safety, ≤130 if shipping a large skill collection). The hard schema limit is 1024.\n\n## Cross-document references in SKILL.md frontmatter\n\nWhen SKILL.md frontmatter references other documents (parent specs, ADRs,\nrelated skills), use **leading-\`/\`** URI-references:\n\n\`\`\`yaml\n---\nparent_spec: /docs/specs/foo.md\nrelated-skills:\n  - /packages/foo/resources/skills/bar/SKILL.md\n---\n\`\`\`\n\nThese resolve against the project root per RFC 3986 §4.2 (same rule VAT\napplies to body links). Source-relative paths (\`../../docs/foo.md\`) also\nwork but are fragile when skills move.\n\nIf a tool needs to programmatically rewrite these references — e.g., when\nmoving a file — load [[markdown-rewriting]] for the canonical pattern.\nNever use \`gray-matter\`, \`front-matter\`, or \`js-yaml\` directly for SKILL.md\nedits; they silently drop frontmatter comments. ESLint enforces this for\nVAT-internal code.\n\n## Body Structure\n\n- Lead with a short orientation paragraph: what the skill owns and when to reach for it.\n- Use H2 sections for major content blocks; avoid deeply nested H3/H4 trees — they hurt Claude\'s ability to route attention inside the file.\n- Keep SKILL.md under ~500 lines. Longer than that fires \`SKILL_LENGTH_EXCEEDS_RECOMMENDED\` and is a strong signal to split via progressive disclosure (linked reference files) or to spin the content into a sibling skill.\n- Avoid time-sensitive phrasing like \"as of April 2026\" in the body — it ages the skill quickly (\`SKILL_TIME_SENSITIVE_CONTENT\`).\n\n## References Section\n\nA short \`## References\` section at the bottom is the canonical place to list linked resources. Two patterns:\n\n- **Progressive disclosure** — link to \`.md\` files inside the skill directory that get bundled. Keep reference depth ≤ 2 hops; deeper chains fire \`REFERENCE_TOO_DEEP\`.\n- **Prose references to sibling skills** — write \`vibe-agent-toolkit:vat-audit\`, not \`[vat-audit](./vat-audit.md)\`. Markdown links to sibling SKILL.md files cause the packager to transclude the other skill (and fire \`LINK_TO_SKILL_DEFINITION\`).\n\nAvoid linking to navigation files (\`README.md\`, \`index.md\`) — they\'re excluded from the bundle and the link resolves to nothing (\`LINK_TO_NAVIGATION_FILE\`).\n\n## packagingOptions Reference\n\nPackaging options are configured per skill in \`vibe-agent-toolkit.config.yaml\` under \`skills.config.<name>\`:\n\n\`\`\`yaml\nskills:\n  include: [\"resources/skills/SKILL.md\", \"resources/skills/*.md\"]\n  defaults:\n    linkFollowDepth: 2\n  config:\n    my-skill:\n      linkFollowDepth: 1\n      resourceNaming: resource-id\n      stripPrefix: knowledge-base\n      excludeReferencesFromBundle:\n        rules:\n          - patterns: [\"**/concepts/**\"]\n            template: \"Use search to find: {{link.text}}\"\n        defaultTemplate: \"{{link.text}} (search knowledge base)\"\n\`\`\`\n\n**\`linkFollowDepth\`** — How deep to follow links from SKILL.md:\n\n| Value | Behavior |\n|-------|----------|\n| \`0\` | Skill file only (no links followed) |\n| \`1\` | Direct links only |\n| \`2\` | Direct + one transitive level **(default)** |\n| \`\"full\"\` | Complete transitive closure |\n\n**\`resourceNaming\`** — How bundled files are named:\n\n| Strategy | Example | Use When |\n|----------|---------|----------|\n| \`basename\` | \`overview.md\` | Few files, unique names **(default)** |\n| \`resource-id\` | \`topics-quickstart-overview.md\` | Many files, flat output |\n| \`preserve-path\` | \`topics/quickstart/overview.md\` | Preserve structure |\n\nUse \`stripPrefix\` to remove a common directory prefix (e.g., \`\"knowledge-base\"\`).\n\n**\`excludeReferencesFromBundle\`** — Rules for excluding files and rewriting their links:\n\n- \`rules[]\` — ordered glob patterns (first match wins), each with optional Handlebars template\n- \`defaultTemplate\` — applied to depth-exceeded links not matching any rule\n\n**Template variables:**\n\n| Variable | Description |\n|----------|-------------|\n| \`{{link.text}}\` | Link display text |\n| \`{{link.href}}\` | Original href (without fragment) |\n| \`{{link.fragment}}\` | Fragment including \`#\` prefix, or empty |\n| \`{{link.type}}\` | Link type (\`\"local_file\"\`, etc.) |\n| \`{{link.resource.id}}\` | Target resource ID (if resolved) |\n| \`{{link.resource.fileName}}\` | Target filename (if resolved) |\n| \`{{skill.name}}\` | Skill name from frontmatter |\n\n## Validation Overrides\n\nThe \`validation\` sub-key in a skill\'s config provides the unified override framework for VAT validation codes:\n\n\`\`\`yaml\nskills:\n  config:\n    my-skill:\n      validation:\n        severity:\n          LINK_DROPPED_BY_DEPTH: error           # upgrade: block on depth-dropped links\n          LINK_TO_NAVIGATION_FILE: ignore        # silence: this skill intentionally links to READMEs\n        allow:\n          PACKAGED_UNREFERENCED_FILE:\n            - paths: [\"templates/runtime.json\"]\n              reason: \"consumed programmatically at runtime\"\n              expires: \"2026-09-30\"\n          SKILL_LENGTH_EXCEEDS_RECOMMENDED:\n            - reason: \"whole-skill concern; paths defaults to [\'**/*\']\"\n\`\`\`\n\nTwo sub-keys, each covering a different override granularity:\n\n- **\`severity\`** — class-level. Raise any code to \`error\` (blocks build), lower to \`warning\` (emits, non-blocking), or \`ignore\` (fully suppressed). Applies to every instance of that code.\n- **\`allow\`** — per-instance. Suppress specific \`(code, path)\` matches with a required \`reason\` and optional \`expires\` date. \`paths\` is optional (defaults to \`[\"**/*\"]\` — the whole skill). Use for legitimate exceptions that don\'t warrant code-wide silencing.\n\nCommon adjustments:\n\n- Downgrade \`LINK_DROPPED_BY_DEPTH\` to \`ignore\` when intentionally linking out to external docs.\n- Allow specific files under \`PACKAGED_UNREFERENCED_FILE\` when they\'re consumed programmatically by CLI scripts at runtime.\n- Raise \`ALLOW_EXPIRED\` to \`error\` for zero-tolerance expiry policies.\n\nExpired \`allow\` entries still apply — VAT emits \`ALLOW_EXPIRED\` as a reminder rather than silently re-surfacing the underlying issue (no surprise build breaks when a date passes). Unused \`allow\` entries surface as \`ALLOW_UNUSED\` (analogous to ESLint\'s unused-disable).\n\n\`vat audit\` is advisory: it applies \`severity\` for display grouping only, ignores \`allow\`, and always exits 0. Use \`vat skills validate\` or \`vat skills build\` for gated checks.\n\n## Pre-publication Check\n\nBefore shipping a skill, walk through the \`vibe-agent-toolkit:vat-skill-review\` checklist — it covers naming, description quality, structure, validation-code triage, and Anthropic\'s skill-authoring best practices. The \`vat skill review <skill>\` CLI command renders a skill-specific view of the same checklist.\n\n## References\n\n- \`vibe-agent-toolkit:vat-skill-review\` — pre-publication quality checklist (general + CLI-backed items, tied to VAT validation codes)\n- \`vibe-agent-toolkit:vat-skill-distribution\` — plugin/marketplace config, \`vat build\`, \`vat verify\`, npm publishing\n- \`vibe-agent-toolkit:vat-knowledge-resources\` — the \`resources:\` config section for multi-collection frontmatter schema validation\n- [Validation Codes Reference](../../../../docs/validation-codes.md) — full list of codes VAT emits, their default severity, and override recipes.\n- [Skill Quality and Compatibility — VAT\'s Stance](../../../../docs/skill-quality-and-compatibility.md) — what VAT believes makes a skill good and compatible.\n";
 
 export const fragments = {
   skillmdStructure: {
@@ -15,6 +15,11 @@ export const fragments = {
     body: "A SKILL.md file is the definition file for a portable skill. It tells Claude what the skill does and how to use it. All SKILL.md files must have YAML frontmatter:\n\n\`\`\`markdown\n---\nname: my-skill\ndescription: One sentence — what this skill does and when to use it (≤250 chars)\n---\n\n# My Skill\n\nRest of the skill documentation...\n\`\`\`\n\nRequired frontmatter fields:\n\n- \`name\` — unique identifier, kebab-case (\`^[a-z][a-z0-9-]*$\`), matches the skill\'s directory name after build. Avoid the reserved words \`claude\` and \`anthropic\` (Claude Code rejects non-certified skills using those words — surfaced as \`RESERVED_WORD_IN_NAME\`).\n- \`description\` — trigger description used for Claude\'s skill routing; be specific about activation conditions.\n\nBest practices for \`description\`:\n\n- Lead with an action verb or \`Use when <concrete trigger>\` — filler openers like \"This skill...\", \"A skill that...\", \"Use when you want to...\" fire \`SKILL_DESCRIPTION_FILLER_OPENER\`.\n- Include 2–4 trigger keywords a user is likely to type.\n- Write in third person. First-person (\"I can...\") and conversational second-person (\"You can use...\") fire \`SKILL_DESCRIPTION_WRONG_PERSON\`.\n- Keep under 250 characters so the Claude Code \`/skills\` listing doesn\'t truncate the tail (target ≤200 for safety, ≤130 if shipping a large skill collection). The hard schema limit is 1024.",
     text: "## SKILL.md Structure\n\nA SKILL.md file is the definition file for a portable skill. It tells Claude what the skill does and how to use it. All SKILL.md files must have YAML frontmatter:\n\n\`\`\`markdown\n---\nname: my-skill\ndescription: One sentence — what this skill does and when to use it (≤250 chars)\n---\n\n# My Skill\n\nRest of the skill documentation...\n\`\`\`\n\nRequired frontmatter fields:\n\n- \`name\` — unique identifier, kebab-case (\`^[a-z][a-z0-9-]*$\`), matches the skill\'s directory name after build. Avoid the reserved words \`claude\` and \`anthropic\` (Claude Code rejects non-certified skills using those words — surfaced as \`RESERVED_WORD_IN_NAME\`).\n- \`description\` — trigger description used for Claude\'s skill routing; be specific about activation conditions.\n\nBest practices for \`description\`:\n\n- Lead with an action verb or \`Use when <concrete trigger>\` — filler openers like \"This skill...\", \"A skill that...\", \"Use when you want to...\" fire \`SKILL_DESCRIPTION_FILLER_OPENER\`.\n- Include 2–4 trigger keywords a user is likely to type.\n- Write in third person. First-person (\"I can...\") and conversational second-person (\"You can use...\") fire \`SKILL_DESCRIPTION_WRONG_PERSON\`.\n- Keep under 250 characters so the Claude Code \`/skills\` listing doesn\'t truncate the tail (target ≤200 for safety, ≤130 if shipping a large skill collection). The hard schema limit is 1024."
   },
+  crossDocumentReferencesInSkillmdFrontmatter: {
+    header: "## Cross-document references in SKILL.md frontmatter",
+    body: "When SKILL.md frontmatter references other documents (parent specs, ADRs,\nrelated skills), use **leading-\`/\`** URI-references:\n\n\`\`\`yaml\n---\nparent_spec: /docs/specs/foo.md\nrelated-skills:\n  - /packages/foo/resources/skills/bar/SKILL.md\n---\n\`\`\`\n\nThese resolve against the project root per RFC 3986 §4.2 (same rule VAT\napplies to body links). Source-relative paths (\`../../docs/foo.md\`) also\nwork but are fragile when skills move.\n\nIf a tool needs to programmatically rewrite these references — e.g., when\nmoving a file — load [[markdown-rewriting]] for the canonical pattern.\nNever use \`gray-matter\`, \`front-matter\`, or \`js-yaml\` directly for SKILL.md\nedits; they silently drop frontmatter comments. ESLint enforces this for\nVAT-internal code.",
+    text: "## Cross-document references in SKILL.md frontmatter\n\nWhen SKILL.md frontmatter references other documents (parent specs, ADRs,\nrelated skills), use **leading-\`/\`** URI-references:\n\n\`\`\`yaml\n---\nparent_spec: /docs/specs/foo.md\nrelated-skills:\n  - /packages/foo/resources/skills/bar/SKILL.md\n---\n\`\`\`\n\nThese resolve against the project root per RFC 3986 §4.2 (same rule VAT\napplies to body links). Source-relative paths (\`../../docs/foo.md\`) also\nwork but are fragile when skills move.\n\nIf a tool needs to programmatically rewrite these references — e.g., when\nmoving a file — load [[markdown-rewriting]] for the canonical pattern.\nNever use \`gray-matter\`, \`front-matter\`, or \`js-yaml\` directly for SKILL.md\nedits; they silently drop frontmatter comments. ESLint enforces this for\nVAT-internal code."
+  },
   bodyStructure: {
     header: "## Body Structure",
     body: "- Lead with a short orientation paragraph: what the skill owns and when to reach for it.\n- Use H2 sections for major content blocks; avoid deeply nested H3/H4 trees — they hurt Claude\'s ability to route attention inside the file.\n- Keep SKILL.md under ~500 lines. Longer than that fires \`SKILL_LENGTH_EXCEEDS_RECOMMENDED\` and is a strong signal to split via progressive disclosure (linked reference files) or to spin the content into a sibling skill.\n- Avoid time-sensitive phrasing like \"as of April 2026\" in the body — it ages the skill quickly (\`SKILL_TIME_SENSITIVE_CONTENT\`).",

package/dist/skills/vat-adoption-and-configuration/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: vat-adoption-and-configuration
-description: Use when starting a new VAT project, adding VAT to an existing repo, or orienting to `vibe-agent-toolkit.config.yaml`. Covers project setup, repo structure, package.json wiring, vibe-validate integration, and the npm postinstall hook.
+description: Use when starting a new VAT project, adding VAT to an existing
+  repo, or orienting to `vibe-agent-toolkit.config.yaml`. Covers project setup,
+  repo structure, package.json wiring, vibe-validate integration, and the npm
+  postinstall hook.
 ---
 
 # VAT Adoption and Configuration

package/dist/skills/vat-agent-authoring/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: vat-agent-authoring
-description: Use when authoring TypeScript portable agents — agent archetypes, agent.yaml, result envelopes, orchestration patterns, and runtime adapters (Vercel/LangChain/OpenAI/Claude Agent SDK). Paired with vat-skill-authoring for the SKILL.md side.
+description: Use when authoring TypeScript portable agents — agent archetypes,
+  agent.yaml, result envelopes, orchestration patterns, and runtime adapters
+  (Vercel/LangChain/OpenAI/Claude Agent SDK). Paired with vat-skill-authoring
+  for the SKILL.md side.
 ---
 
 # VAT Agent Authoring: Archetypes, Envelopes, Orchestration

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

@@ -1,6 +1,9 @@
 ---
 name: vat-audit
-description: Use when running vat audit to validate Claude plugins, agent skills, or marketplaces. Covers the audit command, --compat flag for surface compatibility analysis, --exclude for noise filtering, and interpreting audit output.
+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.
 ---
 
 # VAT Audit: Validating Plugins, Skills & Marketplaces

package/dist/skills/vat-enterprise-org/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: vat-enterprise-org
-description: Use for Anthropic Enterprise/Team org administration via the Admin API — user management, API-key auditing, cost/usage reporting, workspace admin, and enterprise skill distribution. Requires ANTHROPIC_ADMIN_API_KEY.
+description: Use for Anthropic Enterprise/Team org administration via the Admin
+  API — user management, API-key auditing, cost/usage reporting, workspace
+  admin, and enterprise skill distribution. Requires ANTHROPIC_ADMIN_API_KEY.
 ---
 
 # Claude Org Administration

package/dist/skills/vat-knowledge-resources/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: vat-knowledge-resources
-description: Use when working with VAT resource collections, per-directory frontmatter schema validation, link validation, or the vat resources command. Covers collection configuration, schema mapping, and validation modes.
+description: Use when working with VAT resource collections, per-directory
+  frontmatter schema validation, link validation, or the vat resources command.
+  Covers collection configuration, schema mapping, and validation modes.
 ---
 
 # VAT Resources: Collections & Frontmatter Validation
@@ -111,6 +113,46 @@ const PrdFrontmatter = z.object({
 
 **Tip:** `format` is advisory in JSON Schema; pair it with a `pattern` regex when you also need parse-time rejection of invalid inputs.
 
+## URI-references in frontmatter
+
+VAT validates frontmatter fields whose schema position has `format: uri-reference`
+(or `uri`, `iri-reference`, `iri`) against the same rules as body links:
+
+- Leading-`/` is RFC 3986 §4.2 absolute-path reference — resolved against
+  the project root. Same semantics as body links.
+- Anchor fragments and external URLs are accepted; broken local refs error.
+- Inline comments on URI-ref fields are **preserved** when any tool rewrites
+  the file via `openFrontmatter` (VAT packager, hand-rolled adopter scripts).
+
+Example:
+
+```yaml
+---
+parent_spec: /docs/specs/foo.md  # the spec this one supersedes
+adrs-cited:
+  - /docs/adrs/0007-storage.md  # primary reference
+  - /docs/adrs/0011-snapshot.md  # impacted by storage choice
+---
+```
+
+Schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "parent_spec": { "type": "string", "format": "uri-reference" },
+    "adrs-cited": {
+      "type": "array",
+      "items": { "type": "string", "format": "uri-reference" }
+    }
+  }
+}
+```
+
+For tools that **modify** frontmatter (not just validate it), see
+[[markdown-rewriting]].
+
 ## Validation Output
 
 ```yaml

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

@@ -1,6 +1,9 @@
 ---
 name: vat-rag
-description: Use when running `vat rag index` / `vat rag query` or configuring RAG for agent context — covers the CLI commands, native embedding providers and vector store support, chunking, custom metadata, and extension points for adding new backends.
+description: Use when running `vat rag index` / `vat rag query` or configuring
+  RAG for agent context — covers the CLI commands, native embedding providers
+  and vector store support, chunking, custom metadata, and extension points for
+  adding new backends.
 ---
 
 # VAT RAG: Indexing and Querying Markdown with Native Providers

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

@@ -1,6 +1,9 @@
 ---
 name: vat-skill-authoring
-description: Use when authoring or revising a SKILL.md file — frontmatter, body structure, references, packagingOptions (linkFollowDepth, excludeReferencesFromBundle), and validation overrides. Paired with vat-skill-review for pre-publication checks.
+description: Use when authoring or revising a SKILL.md file — frontmatter, body
+  structure, references, packagingOptions (linkFollowDepth,
+  excludeReferencesFromBundle), and validation overrides. Paired with
+  vat-skill-review for pre-publication checks.
 ---
 
 # VAT Skill Authoring: SKILL.md Structure and Packaging
@@ -34,6 +37,29 @@ Best practices for `description`:
 - Write in third person. First-person ("I can...") and conversational second-person ("You can use...") fire `SKILL_DESCRIPTION_WRONG_PERSON`.
 - Keep under 250 characters so the Claude Code `/skills` listing doesn't truncate the tail (target ≤200 for safety, ≤130 if shipping a large skill collection). The hard schema limit is 1024.
 
+## Cross-document references in SKILL.md frontmatter
+
+When SKILL.md frontmatter references other documents (parent specs, ADRs,
+related skills), use **leading-`/`** URI-references:
+
+```yaml
+---
+parent_spec: /docs/specs/foo.md
+related-skills:
+  - /packages/foo/resources/skills/bar/SKILL.md
+---
+```
+
+These resolve against the project root per RFC 3986 §4.2 (same rule VAT
+applies to body links). Source-relative paths (`../../docs/foo.md`) also
+work but are fragile when skills move.
+
+If a tool needs to programmatically rewrite these references — e.g., when
+moving a file — load [[markdown-rewriting]] for the canonical pattern.
+Never use `gray-matter`, `front-matter`, or `js-yaml` directly for SKILL.md
+edits; they silently drop frontmatter comments. ESLint enforces this for
+VAT-internal code.
+
 ## Body Structure
 
 - Lead with a short orientation paragraph: what the skill owns and when to reach for it.

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

@@ -1,6 +1,9 @@
 ---
 name: vat-skill-distribution
-description: Use when setting up `vat build`, configuring plugin distribution (marketplace, plugins, managed settings), npm publishing with postinstall hooks, or `vat verify` — the full pipeline from skill source to installed plugin.
+description: Use when setting up `vat build`, configuring plugin distribution
+  (marketplace, plugins, managed settings), npm publishing with postinstall
+  hooks, or `vat verify` — the full pipeline from skill source to installed
+  plugin.
 ---
 
 # VAT Distribution: Build, Publish & Install
@@ -468,4 +471,4 @@ everything (minus `skills/` and `.claude-plugin/`), merges author `plugin.json`
 VAT-owned identity fields, and applies any `files[]` mappings for artifacts built
 outside the plugin dir.
 
-See [docs/guides/marketplace-distribution.md](resources/marketplace-distribution.md) section "Full-plugin authoring".
+See [docs/guides/marketplace-distribution.md]() section "Full-plugin authoring".

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

@@ -1,6 +1,9 @@
 ---
 name: vat-skill-review
-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.
+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.
 ---
 
 # Skill Quality Checklist (vat skill review)

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

@@ -1,6 +1,9 @@
 ---
 name: vibe-agent-toolkit
-description: Use when starting VAT work or deciding which VAT sub-skill applies. Router that points at sub-skills for adoption, skill/agent authoring, audit, distribution, RAG, knowledge resources, skill review, and enterprise org admin.
+description: Use when starting VAT work or deciding which VAT sub-skill applies.
+  Router that points at sub-skills for adoption, skill/agent authoring, audit,
+  distribution, RAG, knowledge resources, skill review, and enterprise org
+  admin.
 ---
 
 # Vibe Agent Toolkit
@@ -38,6 +41,7 @@ Poor fits:
 | `vat rag index` / `vat rag query`, embedding providers, vector stores, chunking | `vibe-agent-toolkit:vat-rag` |
 | Pre-publication quality review, `vat skill review`, validation-code triage | `vibe-agent-toolkit:vat-skill-review` |
 | Anthropic Admin API: org users, cost/usage, workspace skills, `ANTHROPIC_ADMIN_API_KEY` | `vibe-agent-toolkit:vat-enterprise-org` |
+| Programmatic markdown/frontmatter edits — moving files, updating references, schema-evolution migrations; comment-preserving FrontmatterEditor + rewriteBodyLinks | `vibe-agent-toolkit:markdown-rewriting` |
 
 ## CLI Surface at a Glance
 

package/package.json

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