Siri’s model never reads a skill’s body to decide whether it applies. It reads the description, and only loads the body after a match. A good body behind a weak description is never used.
The three parts of a description that routes
- What the skill does, in one plain sentence. “Reorder food from a past delivery.”
- When to use it, in the words people say. “Use when the user asks to reorder, order again, get the usual, or repeat a previous order.” List the verbs and phrases your users actually use, not the ones in your codebase.
- What it doesn’t cover, when another skill handles something close. “Not for browsing menus or starting a new order.” This is how the right skill gets chosen the first time.
Specific, but not narrow
The description has to be specific enough to tell this skill apart from your app’s other skills, and broad enough not to miss common phrasings. A useful test: write down ten ways someone might ask for the task, then check each one against the description.
Things that hurt routing
- Vague wording, like “Recipe stuff” or “Helps with various tasks”. The skill is never chosen, or it’s chosen for the wrong requests.
- Internal names. People don’t say “trigger the reorder flow”.
- An unquoted
:inside the description. YAML reads it as a nested mapping, the build fails, and your app ships no skills at all. Quote the description or rephrase.
Limits
The description is required, can’t be empty, and is capped at 1,024 characters. You rarely need more than two or three sentences.
Paste yours into the validator to check the format and get routing tips.