when_to_use

when_to_use is an optional SKILL.md frontmatter field holding additional context for when Claude should invoke the skill — trigger phrases or example requests.

Mechanically, it is appended to the description field in the skill listing. This combined text counts toward the same 1,536-character cap that the description and when_to_use text is truncated at. Therefore, it is not free extra room; it is the same budget, spent differently.

Use when_to_use when the natural way to describe what a skill does and the natural way a user would ask for it are different sentences. The description carries the 'what', and when_to_use carries the specific phrasings a user might employ. Because both fields are truncated together, you should prioritize putting the key use case first in your description rather than relying on when_to_use to rescue a vague primary explanation.

Note that the underscore spelling is correct here (when_to_use). This differs from hyphenated fields like argument-hint and allowed-tools. This inconsistency is real and worth double-checking when you write frontmatter manually. For example, the Skill Audit skill uses when_to_use to clarify how users might ask for a code review, separate from its core description.

This field is distinct from the general concept of model-invocation, which refers to the broader process of how Claude decides to use any tool or skill based on the prompt and available context. when_to_use provides specific guidance for that invocation process for a particular skill.