Define and enforce one authoritative SKILL contract

[TheTrustedAdvisor]

Summary

The repository currently has contract drift between root guidance, actual skill files, and validation tooling. There is no single authoritative, enforced definition of what a valid SKILL.md contract is.

Evidence

Examples of drift observed in the repo:

• CLAUDE.md requires description to include TRIGGER/DO NOT TRIGGER conditions, while CONTRIBUTING.md explicitly says not to use that verbose form.
• The documented optional frontmatter fields do not fully match real skill usage (when_to_use appears in live skills).
• The repo says skills should be self-contained / avoid cross-skill references, while some skills route to or reference other skills directly.
• validate-skills.yml only runs the description-length hook, and hooks/validate-skill-descriptions.sh only checks extracted description length.
• The documented standard SKILL structure is not consistently the structure used by real skills.

Why this matters

This is more than isolated doc drift: contributors, reviewers, and validators do not all operate from the same contract. That increases review friction, validator blind spots, and long-term repo drift.

Expected outcome

• Choose one canonical SKILL contract and point all root guidance at it.
• Clarify the supported frontmatter schema and whether fields like when_to_use are part of the contract.
• Clarify whether cross-skill routing is forbidden, allowed, or allowed only in narrowly defined forms.
• Expand validation only after the canonical contract is settled.