Skip to content

Skill registry validator: assert capabilities.yml ↔ skills/*/skill.yml consistency #15

@Yoojin-nam

Description

@Yoojin-nam

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:

  1. every skills/*/skill.yml is referenced by exactly one domain in capabilities.yml
  2. every domain.<name>.owner resolves to an existing skills/<owner>/SKILL.md
  3. every umbrella's includes list resolves to declared domains
  4. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions