#2048
Is there a recommended max length for skill description fields?
While writing custom skills, I couldn't find guidance on how long the description field should be, and the question matters more than it looks:
- Descriptions appear to live in the system prompt, so every long description is a permanent per-request token cost across all sessions.
- Trigger selection also has to weigh the user's request against that text — intuitively, a description that buries its trigger conditions in 300 words of prose seems harder to match reliably than a tight one-liner, but I haven't seen this documented anywhere.
Questions:
- Is there a recommended max length (in words or tokens) for description?
- Is matching purely prompt-based (model reads all descriptions and decides), or is there any pre-filtering?
- When a skill covers several capabilities, is it better to split it into multiple narrow skills or keep one skill with a broad description? The tradeoff seems to be trigger precision vs. prompt bloat.
If there's existing guidance I missed, a link would be great — otherwise this might be worth a short section in the docs.
Two hard numbers, both documented. The Agent Skills spec caps
descriptionat 1024 characters. Claude Code also cutsdescription+when_to_useat 1,536 characters in the skill listing (skillListingMaxDescChars), and, per the same docs page, the whole listing is budgeted at one percent of the context window; past that it drops descriptions, least-invoked skills first, and keeps only names. So put the trigger in the first sentence: that's the part that survives. On pre-filtering: a skill withpaths:stays out of the listing until matching files are touched, anddisable-model-invocation: truestops Claude picking it on its own. https://code.claude.com/docs/en/skills