feat(catalog): check bundle links, descriptions and mirror drift

dokimi/changelog.d/20261030_170000_napetrov_catalog-bundle-drift-checks.md

@@ -0,0 +1,14 @@
+### Added
+
+- **`catalog scan` checks each skill's bundle and description, and detects drifted mirrors** —
+  a relative Markdown link in `SKILL.md` to a file that does not exist is a `warn`
+  (`link-missing`), and says so when the file exists from the catalog root instead (a wrong
+  base). A link or `../` code span that reaches a file outside the skill directory is a `warn`
+  (`link-escapes-skill`, `path-escapes-skill`): it breaks when the skill is installed alone.
+  A description with no "when" clause is a `warn` (`description-no-when`), as is one
+  whose words overlap another skill's by at least half (`description-near-duplicate`). Two
+  skills in different paths with the same directory name and different `SKILL.md` text are
+  a `warn` on both (`mirror-drift`), naming the other copies. Links inside code fences, URLs,
+  anchors, and code spans that name no file are not checked. Skills with
+  `disable-model-invocation: true` are exempt from the description checks. Warnings never
+  change the exit code; a spec `error` fails only with `--strict`, while a load error always fails.

dokimi/docs/external-content.md

@@ -129,6 +129,19 @@ offers; each other copy is the `warn` and names it. Warnings never change
 the exit code. `disable-model-invocation: true` is printed as a `note`, because
 the model is never offered that skill.
 
+The scan also checks the bundle and the description. A relative Markdown link
+to a file the skill does not have is a `warn` (`link-missing`), and says when the
+file exists from the catalog root instead. Example links such as `[Title](URL)`
+are common, so `--strict` does not fail on them. A link, or a `../` code span,
+that reaches a file outside the skill directory is a `warn`
+(`link-escapes-skill`, `path-escapes-skill`), since it breaks when the skill is
+installed alone. A description with no "when" clause (`use when ...`, `when deploying ...`) is a `warn`
+(`description-no-when`), and so is one that overlaps another skill's by at least
+half (`description-near-duplicate`). Two skills in different paths with the same
+directory name and different `SKILL.md` text are a `warn` on both
+(`mirror-drift`), naming the other copies. Skills with
+`disable-model-invocation: true` are exempt from the description checks.
+
 Frontmatter that is not valid YAML (a bare colon in `description:`, say) stops
 the skill from loading, since the loader reads it as having no description. The
 scan reports that as a `frontmatter-parse` error carrying the YAML message, and