docs(contributing): the library-vs-agent rubric and the canon: frontmatter field

[dolho]

Summary

• CONTRIBUTING: the library-vs-agent rubric. One question decides it: would you want this skill, unchanged, in another company tomorrow? Yes means it belongs in this library, no means it's an agent skill, and a mixed skill is split: the procedure goes here, company configuration stays in the agent and is read at run time. The same rubric decides where an improvement lands.
• CONTRIBUTING: the canon: frontmatter field. A skill that reads a fleet's canon declares the domains it needs, e.g. canon: [org-context]. This is a declaration of need, not a permission. It includes a parser note: the platform's extract_contract ignores unknown keys, which is the only reason the field costs nothing today, so a strict parser would have to allowlist canon first.
• tools/validate.py: an optional canon: shape gate. When the key is present it must be a non-empty list of lowercase kebab-case ids with no duplicates. Skills without the key are unaffected.

No platform code changes.

Verification

• python3 tools/validate.py --all passes (42 skills), including with --platform-parser against the vendored parser at the CI pin (3f1d4c8). The README index is unchanged.
• I checked the gate against six fixtures, with PyYAML and with the stdlib fallback parser; both give the same results. canon: [org-context, icp-model] and an absent key pass. A bare string, [], [Org_Context] and a duplicate id each fail with a canon finding.
• The platform parser at the CI pin parses a skill carrying canon: with no warning and leaves it out of the contract. That confirms the tolerant behaviour the parser note describes.
• The two skills in feat(role-companions): the role pack — seven skills + role-pack / learning-brain skill sets (ent#510) #2 that already declare canon: [org-context] pass the new gate.

🤖 Generated with Claude Code