feat(ci,cli): gate the SKILL.md description cap in CI and at pack time

[UnbreakableMJ]

Why

Standard §5.6 requires the 1000-rendered-character description cap to be machine-enforced both in CI and in the command that produces the bundle. It was neither:

• .githooks/check-description-length.py only ran from the pre-commit hook, which needs git config core.hooksPath .githooks per clone — opt-in, therefore skippable.
• .github/workflows/ci.yml never invoked it.
• construct skill ship built, committed, and pushed .zip/.skill bundles without consulting it at all.

So an over-cap description surfaced at install time — after the packing work was done and the bundle was already public.

What

CI step. Runs the existing checker over every SKILL.md in the tree. find rather than a glob list, so grok-skills/ and android-skills/ are covered with no list to maintain — same auto-discovery principle as validate-configs.py. No new dependency; the checker is stdlib-only.

construct skill ship pre-pack gate. Refuses to stage, commit, or push an over-cap skill (exit 5, CONFLICT) with a structured oversized_skills array naming each offender and its overage:

{"error":{"code":"CONFLICT","exit_code":5,
 "message":"SKILL.md description exceeds the 1000-character cap: demo (1001 chars, 1 over)",
 "hint":"$EDITOR demo/SKILL.md  # trim the `description` frontmatter field",
 "oversized_skills":[{"chars":1001,"over_by":1,"skill":"demo"}]}}

The check sits directly after the bundle-drift refusal, before anything is staged. Exit code 5 is reused rather than a new code invented — CONFLICT is canonically bound to 5 in the CLI Standard's exit map; the manifest's description for 5 now names both causes.

An off-by-one this surfaced

skillmd::description_len measures what the loader sees and deliberately does not reuse frontmatter(), which trims for display — a folded description: > scalar carries a trailing newline the loader counts, so trimming under-reports by one and would let a description sitting exactly on the cap through.

Measuring untrimmed exposed a latent bug in split(): it excluded the newline before the closing --- fence, so a description that is the last frontmatter key lost its trailing newline and under-counted by one, while the same description followed by another key counted correctly. split() now includes that newline, and unit tests pin both shapes to the same count — otherwise the cap would silently depend on frontmatter key order.

Verification

• cargo test → all pass, including 5 new skillmd unit tests and 2 new ship tests (ship_refuses_oversized_description, ship_allows_description_exactly_at_cap — the cap is inclusive)
• cargo clippy --all-targets → clean
• Cross-gate parity on a real description: copied spacecraft-accessibility-support's 998-char description into a fixture repo — Python checker says 998, ship plans normally; padded to 1001 — Python says 1001, ship exits 5 with 1001 chars, 1 over. The two gates agree exactly at the boundary.
• reuse lint → 606/606 · validate-configs.py → 302 files, 0 failed · description cap → clean across all 63 skills

Docs updated: CONTRIBUTING.md and AGENTS.md now describe all three enforcement points and rank them, and the by-hand command matches what CI runs.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9106f5c3e5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Validate descriptions in pending commits before pushing

When the worktree is clean but ahead > 0, shipped is empty because it is derived only from git status, so this loop validates nothing and the later pending-commit path pushes origin main. Thus a user who committed an oversized SKILL.md with the optional hook disabled can run construct skill ship and push it without the promised CONFLICT; inspect the skills changed in the unpushed commit range, or validate all catalogue skills before taking that push path.

AGENTS.md reference: AGENTS.md:L17-L21

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Parse rendered YAML in the authoritative CI gate

For folded descriptions containing trailing spaces, this new CI gate can pass an over-cap value because .githooks/check-description-length.py applies strip() to every block line (line 51), although YAML preserves those spaces. For example, 999 visible characters followed by 10 spaces renders to 1010 characters including the newline, while the invoked checker reports exactly 1000 and succeeds; use the already-installed YAML parser here/checker so every SKILL.md is measured from the decoded scalar.

AGENTS.md reference: AGENTS.md:L11-L18

Useful? React with 👍 / 👎.