skill-creator should warn when description exceeds 250-char display limit

Summary

The official skill-creator plugin validates descriptions against a 1024-character spec limit (quick_validate.py, improve_description.py), but the /skills system reminder listing truncates each description at 250 characters. Anything past 250 chars is invisible to Claude's auto-invocation logic.

This means the plugin's own improve_description.py optimization loop actively produces descriptions that are 2-4x longer than what Claude can see, and quick_validate.py passes skills that will have their trigger keywords silently truncated.

Observed Impact

Auditing 60+ skills in a production environment found:

• 8 skills using YAML | block scalar descriptions ranged from 377-752 chars
• The plugin's guidance ("100-200 words") produces ~500-1000 chars — all truncated
• Trigger keywords for niche terms (e.g., Registry.pol, GptTmpl.inf for a GPO skill) were buried past the cutoff and invisible to auto-invocation

Suggested Changes

1. quick_validate.py — Add a warning when len(description) > 250 explaining the display truncation (keep 1024 as the hard fail)
2. improve_description.py — Change the target from "100-200 words" to ≤250 characters; change the rewrite trigger from 1024 to 250
3. SKILL.md guidance — Add a note to the description field documentation explaining the 250-char display limit and best practices (front-load trigger keywords, drop role preambles, use quoted strings not | block scalars)

Related

• #40121 — Docs gap for the 250-char per-description cap (partially resolved)

🤖 Generated with Claude Code