Skill description

The description frontmatter field is what Claude uses to decide when to apply a skill. It is the single most load-bearing line in a SKILL.md file, because it is the only part of the skill that is always in context. If description is omitted, Claude Code uses the first paragraph of the markdown content.

Put the key use case FIRST. The combined description and when-to-use text is truncated at 1,536 characters in the skill listing to reduce context usage. This cap is configurable with the skillListingMaxDescChars setting. There is also an overall listing budget across all skills, adjustable via the skillListingBudgetFraction setting or the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable. To free budget, low-priority entries can be set to 'name-only' in skillOverrides so they list without a description.

A good description says what the skill does AND when to use it, in the user's words rather than the author's. SkillProof's test protocol scores this directly: the trigger stage writes three phrasings that SHOULD activate the skill and two adjacent ones that should NOT, then judges honestly whether the description would win the load. Vague descriptions are the most common reason a technically fine skill never fires. For example, the Skill Audit skill's description clearly states its purpose: "Audits a codebase for quality, consistency, and broken patterns before release."