A skill isn’t a manual for one tool. Siri can call any of your tools with or without a skill, so every tool has to make sense from its own title, description, and parameters.
Write a skill when at least one of these is true
- A task needs context the tools can’t carry. What people usually mean, what your app means by it, the vocabulary, what a good result looks like. What “plan my week” covers in a meal planning app.
- A task takes more than one tool, in order. Get the meal plan, then add its ingredients to the shopping list.
- One request could mean different tasks, and only your app knows which. “I want to make shakshuka on Friday” could mean planning it, shopping for it, or both.
- The model should ask instead of guessing in a specific situation. Before replacing a meal that’s already planned.
- There’s something the model must not do that no single tool’s description can say. Only clear the list when the person explicitly asks.
If none of these apply, skip the skill. Good intent metadata is enough.
Fix the tool instead when…
…the skill would mostly explain how to call one tool: which combination of arguments does what, or which mode to pass. Reshape the tool instead. Describe every case of a mode parameter, split a tool that does two different things, and make titles and descriptions say when to use it.
One skill per task, not per tool
Group by what people want done. “Organize notes” might use four tools; “add a note” probably needs no skill at all.
Skills guide, they don’t enforce
Siri doesn’t run a skill’s steps in a guaranteed order, and a “don’t” line is a request, not a rule. Anything that must never happen belongs in code: don’t expose the tool, or protect it with an authentication policy.