Scope
capabilities.yml declares domain owners (e.g., reference_integrity: owner: verify-refs) and umbrellas (e.g., references includes [reference_integrity, literature_discovery, zotero_sync]). There is no automated check that:
- every
skills/*/skill.yml is referenced by exactly one domain in capabilities.yml
- every
domain.<name>.owner resolves to an existing skills/<owner>/SKILL.md
- every umbrella's
includes list resolves to declared domains
- no orphan skill exists (declared in
skills/ but unreferenced)
The current discovery instability (skills not surfacing in user sessions, fallback paths documented in ~/.claude/rules/manuscript-references.md) is downstream of this missing validation.
Proposed change
Add scripts/validate_capabilities.py (or extend validate_skills.sh) with the four assertions above. Wire into the existing pre-commit hook and any CI workflow. Exit non-zero on drift.
Why this is a separate issue
PR #13 deliberately scoped to the reference pre-submission gate; bundling a registry validator would expand review surface unnecessarily. The validator is a CI/dev-tooling concern, not a skill-functionality change.
Acceptance
- New validator script under
scripts/
- Wired into pre-commit and CI (whichever exists)
- README updated with the four invariants
- A failing test fixture (drift example) confirms non-zero exit
Scope
capabilities.ymldeclares domain owners (e.g.,reference_integrity: owner: verify-refs) and umbrellas (e.g.,referencesincludes[reference_integrity, literature_discovery, zotero_sync]). There is no automated check that:skills/*/skill.ymlis referenced by exactly one domain incapabilities.ymldomain.<name>.ownerresolves to an existingskills/<owner>/SKILL.mdincludeslist resolves to declared domainsskills/but unreferenced)The current discovery instability (skills not surfacing in user sessions, fallback paths documented in
~/.claude/rules/manuscript-references.md) is downstream of this missing validation.Proposed change
Add
scripts/validate_capabilities.py(or extendvalidate_skills.sh) with the four assertions above. Wire into the existing pre-commit hook and any CI workflow. Exit non-zero on drift.Why this is a separate issue
PR #13 deliberately scoped to the reference pre-submission gate; bundling a registry validator would expand review surface unnecessarily. The validator is a CI/dev-tooling concern, not a skill-functionality change.
Acceptance
scripts/