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

[phatmandrake]

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

• [DOCS] Skills docs omit the 250-character cap for /skills descriptions #40121 — Docs gap for the 250-char per-description cap (partially resolved)

🤖 Generated with Claude Code

[github-actions]

Found 1 possible duplicate issue:

1. [DOCS] Skills docs omit the 250-character cap for /skills descriptions #40121

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[dhollman]

We bumped this up to ~1.5k for now, and have more granular control via .claude/settings.json coming soon!

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.