fix(skill-quality): check the description field cap separately from the listing cap (#3150)

Adds check 2b: the Agent Skills spec `description` FIELD maximum (1024
codepoints), distinct from check 2's 1536-char listing-entry cap. A description
could sit under 1536 combined, breach 1024 alone, and pass clean; nineteen
skills in this marketplace do.

WARN, not FAIL, on measured evidence: `claude plugin validate --strict`
(Claude Code 2.1.241) passes a 1248-char description clean, so the breach is
latent locally and hard only on Skills API upload.

Counted in codepoints via the same UTF-8 -> UTF-32BE iconv form check 22 uses;
`${#var}` degrades to byte counting under a byte-oriented locale and would
false-warn on multilingual descriptions (600 'é' reports as 1200 under
LC_ALL=C). Caught in review by the Codex reviewer. DESC_LEN stays a byte count
for check 2, so check 2 behavior is unchanged.

Closes #3119

Author: kyle-sexton

plugins/skill-quality/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "skill-quality",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "Skill-authoring QA tooling: a static contract checker that runs twenty-five deterministic checks over a Claude Code skill (frontmatter, explicit invocation mode, description/verb-contract polarity, per-skill listing-entry cap, trigger-keyword preservation, line caps, broken internal refs, markdownlint, gotchas surface, evals presence, precompute opportunity, completion-criteria signal, injection shell-declaration, fresh-eyes declaration conformance), a shared skill-listing budget reporter across a set of skills, and a bundled evals.json schema plus a deterministic eval-quality lint (duplicate case identities, missing fixtures, empty or vague grading criteria, set-coverage warnings). Runs against any repo's skills directory via the convention-resolution ladder \u2014 no baked layout.",
   "author": {
     "name": "Melodic Software",

plugins/skill-quality/CHANGELOG.md

@@ -3,6 +3,45 @@
 All notable changes to the `skill-quality` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.19.0]
+
+### Added
+
+- **`check`: Check 2b — description field cap (1024; WARN; #3119).** The gate
+  carried one description limit, `DESC_CHAR_CAP=1536`, and treated it as the only
+  one. That value is Claude Code's in-context listing truncation for the assembled
+  entry (`description` + `" - "` + `when_to_use`). The Agent Skills spec states a
+  separate, smaller maximum for the `description` **field alone**: "Must be
+  non-empty / Maximum 1024 characters / Cannot contain XML tags"
+  (platform.claude.com Agent Skills overview, fetched 2026-08-23). Two limits at
+  two layers, and only the looser one was checked — so a description could sit
+  under 1536 combined, breach 1024 on its own, and pass clean. Nineteen skills in
+  this marketplace did (lower bound; measured with an independent extractor that
+  reads slightly short of the gate's own).
+
+  Check 2b reports the field breach separately from check 2, with its own message.
+
+  Counted in **codepoints**, not bytes — the spec says "Maximum 1024 characters",
+  and `${#var}` degrades to byte counting under a byte-oriented locale, so 600
+  `é` characters report as 1200 under `LC_ALL=C` and a valid multilingual
+  description would false-warn. Uses the same UTF-8 → UTF-32BE `iconv` form as
+  check 22, with the same UTF-8-locale fallback where `iconv` is absent.
+  `DESC_LEN` stays a byte count for check 2, whose 1536 listing cap is a separate
+  measure. Caught in review by the Codex reviewer on this PR.
+
+  **WARN, not FAIL, on measured evidence.** No local validator enforces the field
+  maximum: `claude plugin validate --strict` (Claude Code 2.1.241) passes a
+  1248-char description clean — verified against a throwaway fixture plugin on
+  2026-08-23, the only warning raised being an unrelated missing `author`. The
+  breach is latent for filesystem and plugin skills, and hard only for a skill
+  uploaded through the Skills API. Failing the build on it would block a fleet
+  over a limit nothing in the local toolchain applies.
+
+  Numbered `2b` rather than `26`: it is the same concern as check 2 at a second
+  layer, and renumbering would break the identity of checks 3–25, which are cited
+  by number across this repo and in tracker items. The plugin's "twenty-five
+  deterministic checks" claim is left standing on that reading.
+
 ## [0.18.1]
 
 ### Fixed

plugins/skill-quality/scripts/check-skill.sh

@@ -44,6 +44,10 @@
 #   2. description + when_to_use <= 1536 chars (per-skill listing-entry cap;
 #      counts the literal " - " joiner the harness inserts when when_to_use is
 #      populated)
+#  2b. description alone <= 1024 Unicode codepoints (Agent Skills spec FIELD
+#      maximum — a separate limit at a separate layer from check 2's listing cap;
+#      WARN, since no local validator enforces it and the Skills API rejects it
+#      at upload; counted locale-independently via iconv, as check 22 does)
 #   3. Trigger-keyword preservation vs the base ref (skipped for new skills;
 #      a phrase moved verbatim to a sibling skill's listing text — one the
 #      sibling did not carry at the base ref — WARNs, since the marketplace
@@ -203,8 +207,18 @@ if [[ "$HAVE_GIT" == 1 ]]; then
   SKILL_REL="${SKILL_REL%/}"
 fi
 
-# Tunables (listing description cap; SKILL.md line caps; vendor sync age).
+# Tunables (listing description cap; description field cap; SKILL.md line caps;
+# vendor sync age).
 DESC_CHAR_CAP=1536
+# Agent Skills spec field maximum for `description` ALONE — a different limit at a
+# different layer from DESC_CHAR_CAP above, which bounds the assembled listing entry
+# (description + " - " + when_to_use). The two do not unify and are checked separately.
+# Enforced by the Skills API at package/upload; NOT enforced locally — measured
+# 2026-08-23, `claude plugin validate --strict` (Claude Code 2.1.241) passes a
+# 1248-char description clean. A breach is therefore latent for filesystem/plugin
+# skills and hard for any skill uploaded through the Skills API, which is why this
+# is a WARN and DESC_CHAR_CAP stays a FAIL.
+DESC_FIELD_CAP=1024
 LINE_HARD_CAP=500
 LINE_SOFT_CAP=200
 SYNCED_MAX_AGE_DAYS=180
@@ -350,6 +364,34 @@ else
   note "description length $DESC_LEN/$DESC_CHAR_CAP chars"
 fi
 
+# --- Check 2b: description field alone <= DESC_FIELD_CAP codepoints ----------
+# The spec's per-FIELD maximum, distinct from check 2's listing-entry cap: a
+# description can sit under 1536 combined and still breach 1024 on its own. The
+# Skills API rejects that at upload; nothing local does (see DESC_FIELD_CAP above),
+# so this warns rather than failing — it reports a real spec breach without
+# blocking a fleet that carries pre-existing offenders.
+#
+# Counted in CODEPOINTS, not bytes: the spec says "Maximum 1024 characters", and
+# a byte count would false-positive on any non-ASCII description under a
+# byte-oriented locale — measured, 600 'é' characters report as 1200 under
+# LC_ALL=C. Same UTF-8 -> UTF-32BE iconv form check 22 uses (every codepoint
+# becomes exactly 4 bytes, so byte-count/4 is the codepoint count on any host),
+# with the same UTF-8-locale fallback where iconv is absent. DESC_LEN stays a
+# byte count for check 2, whose 1536 listing cap is a separate measure.
+if command -v iconv >/dev/null 2>&1; then
+  DESC_CP_LEN=$(($(printf '%s' "$CUR_DESC" | iconv -f UTF-8 -t UTF-32BE | wc -c) / 4))
+else
+  DESC_CP_LEN="$(
+    LC_ALL=C.UTF-8
+    printf '%s' "${#CUR_DESC}"
+  )"
+fi
+if ((DESC_CP_LEN > DESC_FIELD_CAP)); then
+  warn "description alone is $DESC_CP_LEN codepoints (Agent Skills spec field maximum $DESC_FIELD_CAP) — accepted locally, rejected on Skills API upload"
+else
+  note "description field $DESC_CP_LEN/$DESC_FIELD_CAP codepoints (spec field maximum)"
+fi
+
 # --- Check 3: trigger-keyword preservation vs HEAD -------------------------
 
 if [[ "$HAVE_GIT" != 1 ]]; then

plugins/skill-quality/scripts/check-skill.test.sh

@@ -3301,6 +3301,106 @@ else
   pass "awk regexes are free of ERE interval expressions (mawk-portable)"
 fi
 
+# Check 2b: description FIELD cap (1024, Agent Skills spec) is a separate limit
+# from check 2's listing-entry cap (1536). The discriminating case is the middle
+# band — a description over 1024 but whose assembled entry is under 1536 — which
+# check 2 passes and only check 2b catches. Without that case a single cap could
+# satisfy both assertions, so it is the one that proves the layers are distinct.
+
+# 2b-i. A description one char over the field cap WARNs, and does NOT fail: no
+#       local validator enforces this limit (measured — `claude plugin validate
+#       --strict` 2.1.241 passes an oversized description clean), so failing the
+#       build on it would block a fleet over a breach only the Skills API sees.
+desc_1025="$(printf 'd%.0s' $(seq 1 1025))"
+make_skill field-cap-over "---
+name: field-cap-over
+description: \"$desc_1025\"
+---
+
+## Purpose
+
+Field-cap fixture: description alone is 1025 chars, one over the 1024 spec
+field maximum, while the assembled listing entry stays well under 1536.
+"
+out="$(run field-cap-over 2>&1)"
+rc=$?
+if [[ $rc -eq 0 ]] && grep -q 'description alone is 1025 codepoints' <<<"$out"; then
+  pass "check 2b warns at 1025 chars without failing the run"
+else
+  fail "check 2b should WARN (not FAIL) at 1025/1024 (rc=$rc): $out"
+fi
+
+# 2b-ii. Boundary guard: exactly 1024 is legal — the cap is >1024, not >=1024.
+desc_1024="$(printf 'd%.0s' $(seq 1 1024))"
+make_skill field-cap-exact "---
+name: field-cap-exact
+description: \"$desc_1024\"
+---
+
+## Purpose
+
+Field-cap fixture: description alone is exactly 1024 chars, the spec maximum,
+which is legal.
+"
+out="$(run field-cap-exact 2>&1)"
+rc=$?
+if [[ $rc -eq 0 ]] && ! grep -q 'description alone is' <<<"$out"; then
+  pass "check 2b stays silent at exactly 1024 chars (cap is >1024, not >=)"
+else
+  fail "check 2b should not warn at exactly 1024 (rc=$rc): $out"
+fi
+
+# 2b-iii. The discriminating case: desc(1100) + joiner(3) + wtu(40) = 1143 —
+#         comfortably under check 2's 1536 listing cap, so check 2 passes and
+#         reports no overflow, while the description alone breaches 1024. Proves
+#         the two caps are independent layers rather than one limit checked twice.
+desc_1100="$(printf 'd%.0s' $(seq 1 1100))"
+wtu_40="$(printf 'w%.0s' $(seq 1 40))"
+make_skill field-cap-independent "---
+name: field-cap-independent
+description: \"$desc_1100\"
+when_to_use: \"$wtu_40\"
+---
+
+## Purpose
+
+Independence fixture: the assembled entry is 1143 chars (passes check 2) while
+the description field alone is 1100 (breaches check 2b).
+"
+out="$(run field-cap-independent 2>&1)"
+rc=$?
+if [[ $rc -eq 0 ]] &&
+  grep -q 'description alone is 1100 codepoints' <<<"$out" &&
+  ! grep -q 'description+when_to_use is .* chars (cap 1536' <<<"$out"; then
+  pass "check 2b fires on a field breach that check 2's listing cap does not see"
+else
+  fail "check 2b should catch desc 1100 while check 2 passes the 1143 entry (rc=$rc): $out"
+fi
+
+# 2b-iv. Codepoints, not bytes. 600 'é' is 600 characters and 1200 UTF-8 bytes;
+#        the spec's limit is "Maximum 1024 characters", so this must stay silent.
+#        Run under LC_ALL=C, where `${#var}` degrades to byte counting and would
+#        report 1200 — so the assertion fails on the byte-counting form rather
+#        than passing incidentally on a UTF-8 host.
+desc_600_multibyte="$(printf 'é%.0s' $(seq 1 600))"
+make_skill field-cap-multibyte "---
+name: field-cap-multibyte
+description: \"$desc_600_multibyte\"
+---
+
+## Purpose
+
+Multibyte fixture: 600 codepoints, 1200 UTF-8 bytes. Legal against a 1024
+character cap; a byte count would report 1200 and warn.
+"
+out="$(LC_ALL=C run field-cap-multibyte 2>&1)"
+rc=$?
+if [[ $rc -eq 0 ]] && ! grep -q 'description alone is' <<<"$out"; then
+  pass "check 2b counts codepoints, not bytes (600 multibyte chars stay silent under LC_ALL=C)"
+else
+  fail "check 2b must count codepoints: 600 'é' is 600 chars, not 1200 bytes (rc=$rc): $out"
+fi
+
 if [[ $fails -ne 0 ]]; then
   printf '%d assertion(s) failed\n' "$fails" >&2
   exit 1