fix(skill-quality): DESC_CHAR_CAP is set to the listing-truncation value, not the spec field limit

[kyle-sexton]

Parent

Refs #3118

What to build

plugins/skill-quality/scripts/check-skill.sh:207 sets DESC_CHAR_CAP=1536. That is Claude Code's in-context listing-truncation value for description+when_to_use combined. The Agent Skills spec states the description field maximum separately:

description: Must be non-empty / Maximum 1024 characters / Cannot contain XML tags

(platform.claude.com Agent Skills overview, fetched 2026-08-23.)

These are two caps at two layers, and the gate currently checks only the looser one. Measured across the fleet today: 19 of 224 skills exceed 1024 characters and the gate passes all of them. Median is 624; the longest is claude-ops:audit-skill-visibility at 1520.

Make the gate check both limits as distinct criteria with distinct messages, so a skill cannot pass while breaching the documented field maximum.

Known offenders at time of filing (descending): claude-ops:audit-skill-visibility 1520, claude-config:audit-prompting-postures 1305, work-items:setup 1283, work-items:decompose 1264, skill-quality:check 1249, improvement:find 1247, claude-ops:audit-performance 1200, source-control:babysit-loop 1197, overengineering:audit 1196, architecture:improve 1157, docs-hygiene:audit-progressive-disclosure 1148, overengineering:realign 1146, session-flow:show-options 1142, docs-hygiene:write-for-humans 1109, work-items:ship 1071, code-tidying:dissolve-comments 1068, mutation-testing:audit 1035, docs-hygiene:compress 1030, visualization:visualize 1026.

Captured assumption, verify before deciding severity: the 1024 cap is documented as enforced at package/upload on the API path. Whether Claude Code validates filesystem/plugin skills against it locally is not stated in the docs. The breach may therefore be latent rather than live — but the constant is still wrong for the limit it claims to enforce. Establish which before choosing whether the new check FAILs or WARNs.

Trimming the 19 offenders is explicitly not in this slice. Note that check 3 protects quoted trigger phrases, so trimming descriptions is gated work, not mechanical.

Acceptance criteria

• The 1024-char field limit and the 1536-char listing limit are separate named checks with distinct failure messages.
• A fixture skill with a 1200-char description trips the field-limit check and not the listing check.
• A fixture skill with a 1600-char combined description+when_to_use trips the listing check.
• The FAIL-vs-WARN decision for the field-limit check is recorded in the script comments with the local-enforcement finding that justified it.
• scripts/check-skill.sh self-tests pass.
• The 19 current offenders are enumerated in the issue's closing comment with their measured lengths, so the follow-up trim has a baseline.

Blocked by

None — can start immediately.

[kyle-sexton]

Claimed by an operator-directed /work-items:work invocation (cloud session, branch claude/work-items-integration-it93kq).

Provenance: the work-item-tracker seam cannot run in this environment (gh 2.45 < required 2.94; GraphQL is proxy-restricted), so no lease comment exists — per CONTRACT.md "Degradation without gh", this claim is assignee-only and is picked up as unclaimed coordination by seam-aware lanes. Auto-confirmation recorded here in lieu of the interactive prompt: selection was bound by the invoker naming this issue explicitly.

---

Generated by Claude Code

[kyle-sexton]

Fix is up as PR #3141 (skill-quality 0.19.0). Closing baseline for the follow-up trim, per the acceptance criteria: the 19 in-fleet offenders over the 1024-char spec field maximum, measured today (2026-08-23) with the gate's own frontmatter library (skill_frontmatter::extract + field description + strip_quotes, ${#desc}), descending:

Skill	description chars
claude-ops:audit-skill-visibility	1524
claude-config:audit-prompting-postures	1309
work-items:setup	1283
work-items:decompose	1266
skill-quality:check	1251
improvement:find	1251
overengineering:audit	1204
claude-ops:audit-performance	1202
source-control:babysit-loop	1199
architecture:improve	1165
overengineering:realign	1156
docs-hygiene:audit-progressive-disclosure	1154
session-flow:show-options	1146
docs-hygiene:write-for-humans	1116
work-items:ship	1073
code-tidying:dissolve-comments	1068
docs-hygiene:compress	1044
mutation-testing:audit	1039
visualization:visualize	1030

Median across the 232 measured descriptions is 626. Lengths drift slightly from the figures in the issue body (filed earlier the same day) because descriptions changed in between; same 19 skills. plugins/playbooks/skills/boris/vendor/SKILL.md (5471) also exceeds 1024 but is a vendored snapshot nested inside another skill, not a listed fleet skill, so it is excluded from this baseline.

The new gate criterion (check 2a) WARNs on each of these; the local-enforcement finding justifying WARN over FAIL is recorded in check-skill.sh beside the criterion. Flipping 2a to FAIL once these are trimmed is the follow-up's call.

---

Generated by Claude Code