Enforce the skill-authoring rules in CI

[ortizeg]

Correcting an overclaim

I previously said body length was defended by CI. It was not. The only length assertion in the suite was a >500 character floor in test_skills_completeness.py. The 500-line ceiling, the progressive-disclosure structure, and description quality had no guard at all.

They were passing because they'd just been fixed by hand — which is precisely the state that rots. A scorecard that holds only because someone recently tidied up isn't a scorecard, it's a snapshot.

What this adds

tests/test_skill_hygiene.py — one check per scorecard rule, each tied to a failure this library actually had:

Guard	The failure it prevents
Body ≤ 500 lines	19 of 30 skills once averaged 551 lines
Cited references/... exist	The deep-dive-404 failure mode
No orphaned reference files	Unreachable files that only cost tokens
References one level deep	Nested refs cause partial reads
TOC on references >100 lines	Partial read must still reveal scope
Descriptions trigger-first	They were topic summaries ("Covers X, Y, Z") — these under-trigger
Descriptions third person	First person hurts discovery
Descriptions within listing budget	Overflow silently truncates matching keywords
Split skills link their deep dives	An index that doesn't route is just a shorter skill

One subtlety worth reviewing

The third-person check strips quoted user utterances first. A description listing what a user might say — "set up my editor" — is doing keyword coverage, not speaking in first person, and that phrasing is actively encouraged. Without the strip, vscode failed on good practice.

Every guard was proven to bite

Rather than trusting green, I planted a regression for each and observed the failure, then reverted:

loguru/SKILL.md cites reference files that do not exist: ['references/does-not-exist.md']
loguru description is not trigger-first ... Got: structured logging for cv/ml. covers sinks, json, levels...
pypi/SKILL.md is 539 lines (limit 500). Move detail into references/ ...

Verification

• uv run pytest tests/ → 536 passed
• ruff / format / mypy --strict → clean
• Wired into the archetypes CI job as "Enforce skill-authoring rules"

🤖 Generated with Claude Code