Le skill ne s’uploade pas

"Could not find SKILL.md in uploaded folder" → Renommer en SKILL.md (sensible à la casse)

"Invalid frontmatter" → Vérifier les délimiteurs ---, les guillemets non fermés, les balises XML

"Invalid skill name" → Le nom a des espaces ou des majuscules → utiliser kebab-case

Le skill ne se déclenche pas

Checklist rapide :

• La description est-elle trop générique ? (« Aide avec les projets » ne fonctionnera pas)
• Inclut-elle des trigger phrases que les utilisateurs diraient vraiment ?
• Mentionne-t-elle les types de fichiers pertinents ?

Debug : demander à Claude « Quand utiliserais-tu le skill [nom] ? » — il citera la description. Ajuster en fonction.

Le skill se déclenche trop souvent

1. Ajouter des triggers négatifs : Ne PAS utiliser pour l'exploration simple de données (utiliser data-viz skill à la place).
2. Être plus spécifique : Traite des documents PDF juridiques pour la révision de contrats vs Traite des documents
3. Clarifier le périmètre : Spécifiquement pour les workflows de paiement en ligne, pas pour les requêtes financières générales.

Les instructions ne sont pas suivies

Causes fréquentes :

1. Instructions trop verbeuses → garder concis, utiliser listes et numéros, déplacer la doc dans references/
2. Instructions enfouies → mettre les critiques en haut, utiliser ## Important ou ## Critical
3. Langage ambigu → CRITIQUE : Avant d'appeler create_project, vérifier : nom non vide, au moins un membre assigné, date de début pas dans le passé

Technique avancée : pour les validations critiques, bundler un script Python plutôt que des instructions en langage naturel. Le code est déterministe, l’interprétation du langage ne l’est pas.

Problèmes de connexion MCP

1. Vérifier que le serveur MCP est connecté (Settings > Extensions)
2. Vérifier l’authentification (clés API valides, OAuth tokens rafraîchis)
3. Tester le MCP indépendamment : demander à Claude d’appeler le MCP directement sans le skill. Si ça échoue, le problème est le MCP, pas le skill.
4. Vérifier les noms des outils — sensibles à la casse

Problèmes de contexte large

Si le skill est lent ou les réponses dégradées :

1. Optimiser la taille de SKILL.md — déplacer la doc dans references/, garder sous 5 000 mots
2. Évaluer si tu as plus de 20-50 skills activés simultanément