Skills fail all at once. These are the traps worth checking before anything else.
1. The bundle isn’t in Copy Bundle Resources
If Skills.skillsbundle isn’t part of a build phase, it isn’t compiled, and Xcode shows no message. The fastest fix is to create the bundle from Xcode’s Skills Bundle file template, which adds it to the build phase for you. If the folder lives in a synchronized group, it’s included automatically.
How to check: after building, look for the compiled Skills.skillsc:
| Platform | Location |
|---|---|
| macOS | MyApp.app/Contents/Resources/Metadata.appintents/Skills.skillsc |
| iOS, iPadOS, visionOS | MyApp.app/Metadata.appintents/Skills.skillsc |
If the build succeeds but there’s no .skillsc, the bundle wasn’t in the build phase.
2. One error anywhere drops every skill
If any skill in the bundle has an error, the app ships no skills at all, not just the broken one. One typo in a rarely used skill can disable your most important one.
3. The name doesn’t match the folder
name must match the skill’s directory name exactly, and must be kebab-case: lowercase letters, digits, and single hyphens. Meal_Planning or meal planning is a build error.
4. Two skills share a name
An app, its extensions, and its embedded frameworks can each have a skills bundle, and their skills are grouped together under the app. If two share a name, only one is kept, and the build doesn’t catch this.
5. Guidance lives in the wrong file
Only SKILL.md is compiled. A references/ folder or extra files next to it are ignored and don’t ship. If you’re used to coding-assistant skills, this one is easy to miss.
A quick checklist
-
Skills.skillscexists in the built app - Every skill passes the validator
- Skill names are unique across the app, extensions, and frameworks
- Everything the model needs is inside
SKILL.md