Activation des skills Claude Code

Les skills sont des fichiers Markdown que Claude Code lit au démarrage et applique automatiquement sur la base d’une correspondance de mots-clés avec les requêtes. Les tests de la communauté montrent que les skills ne s’activent automatiquement que dans environ 20% des cas. L’écart entre l’activation automatique souhaitée et le comportement réel est la principale limitation du mécanisme.

Comment fonctionnent les skills

Un skill est un fichier Markdown avec un frontmatter YAML qui vit dans votre projet (généralement dans .claude/skills/ ou un répertoire similaire). Le frontmatter inclut un name et une description. Au démarrage, Claude Code charge le nom et la description de chaque skill dans son contexte.

Lorsque vous faites une requête, Claude vérifie les correspondances de mots-clés entre votre invite et les descriptions de skills chargées. S’il trouve une correspondance, il active le skill et utilise son contenu pour informer sa réponse. S’il n’en trouve pas, le skill reste inutilisé.

C’est le point critique : l’activation dépend de la correspondance de mots-clés, pas de la compréhension sémantique. Claude ne raisonne pas profondément sur la pertinence d’un skill pour votre requête. Il vérifie si les mots de votre invite se chevauchent avec les mots de la description du skill. Si vous décrivez un skill comme “dbt documentation utilities” mais demandez ensuite à Claude de “generate docs for this model”, l’activation dépend de si “docs” déclenche une correspondance avec “documentation”. Parfois oui. Souvent non.

Le problème des 20%

Un praticien a résumé l’expérience vécue par beaucoup : “Je dois toujours dire ‘update process notes and use your skill.’ C’est trop verbeux pour moi. J’ai donc simplement créé une commande slash.”

Ce pattern se répète dans la communauté. Vous configurez un skill en attendant une activation automatique. Cela fonctionne parfois. La plupart du temps, non. Vous finissez par ajouter “and use the skill” à vos invites, ce qui annule tout l’intérêt de l’activation automatique. À ce stade, vous déclenchez manuellement une fonctionnalité implicite — le pire des deux mondes.

Le taux d’activation de 20% n’est pas un bug qu’Anthropic corrigera avec une mise à jour du modèle (bien que des améliorations soient probables avec le temps). C’est une conséquence du fonctionnement de la correspondance de mots-clés avec le langage naturel. Vous formulez les choses différemment à chaque fois. Vous utilisez des synonymes, des abréviations et des références indirectes. La description du skill ne peut pas anticiper toutes les façons dont vous pourriez exprimer une requête pertinente.

Skills vs. commandes : la direction du contrôle

La différence fondamentale entre les skills et les commandes est la direction du contrôle.

Les commandes sont basées sur le pull. Vous tapez /audit-model et Claude l’exécute. Vous décidez quand, vous décidez sur quoi, et le workflow s’exécute de la même façon à chaque fois. L’humain initie.

Les skills sont basés sur le push (en théorie). Claude décide quand les appliquer en fonction de son interprétation de votre requête. L’IA initie — ou non. Vous avez délégué la décision de quand exécuter un workflow au même système de correspondance de mots-clés qui pourrait ne pas reconnaître votre requête.

Pour tout ce où la cohérence est importante — audits, génération de documentation, vérifications pré-commit, scaffolding de tests — le contrôle basé sur le pull est strictement meilleur. Vous ne voulez pas un contrôle qualité des données qui s’exécute 20% du temps. Vous voulez qu’il s’exécute à chaque fois, de manière identique.

Là où les skills fonctionnent réellement

Les skills ne sont pas inutiles. Ils servent simplement un objectif plus restreint que ce que le marketing suggère. Le pattern où les skills brillent vraiment est la connaissance de domaine en arrière-plan — le contexte qui devrait informer le travail de Claude sur de nombreux types de requêtes différents sans être explicitement déclenché.

Bons candidats pour des skills :

• Particularités spécifiques à l’entrepôt. La gestion par BigQuery des types STRUCT, les règles de sensibilité à la casse de Snowflake, la sémantique de merge Delta Lake de Databricks. Ce type de connaissance devrait colorer la façon dont Claude écrit du SQL indépendamment de ce que vous avez demandé.
• Conventions d’équipe et guides de style. Vos patterns de nommage préférés pour les CTE, les standards de documentation, les attentes en matière de revue de code. Ces éléments informent chaque tâche sans avoir besoin d’une invocation explicite.
• Documentation de référence. Dictionnaires de données, définitions de schémas, glossaires de termes métier. Avoir cela disponible comme contexte de fond améliore la sortie de Claude même lorsque vous ne lui demandez pas explicitement de “consulter le dictionnaire de données.”
• Décisions architecturales et justification. Pourquoi vous avez choisi merge plutôt qu’insert_overwrite pour les modèles incrémentaux, pourquoi certains modèles sont matérialisés en tables plutôt qu’en vues, pourquoi vous utilisez un pattern de déduplication spécifique.

Le fil commun : ce sont tous des cas où vous voulez que la connaissance influence le travail de Claude, pas qu’elle déclenche un workflow spécifique. Vous n’avez pas besoin que Claude décide “maintenant je vais appliquer le skill sur les particularités BigQuery.” Vous avez besoin que Claude connaisse simplement les particularités BigQuery chaque fois qu’il écrit du SQL.

Là où les skills échouent

Les skills échouent lorsque vous les utilisez pour des workflows répétables — le type de travail où vous avez besoin des mêmes étapes exécutées de la même façon à chaque fois.

Un skill pour l’audit de modèles, où vous attendez que Claude exécute cinq vérifications spécifiques chaque fois que vous dites “check this model”, décevra. Claude pourrait exécuter trois des cinq vérifications, ou appliquer les critères d’audit de manière incohérente, ou ignorer complètement le skill parce que votre formulation ne l’a pas déclenché. Comparez cela à une commande /audit-model qui exécute les cinq vérifications à chaque fois parce que vous l’avez explicitement invoquée.

Les skills échouent également lorsque vous en empilez trop dans un projet. La description de chaque skill consomme une partie du contexte de Claude au démarrage. Si vous avez quinze skills avec des descriptions qui se chevauchent, la correspondance de mots-clés de Claude devient encore moins fiable — plusieurs skills se disputent l’activation sur la même requête, et le résultat est imprévisible.

La combinaison skill-commande

Pour certains cas d’usage, associer un skill à une commande vous donne les deux modes de couverture. Vous créez un skill avec vos conventions de diagrammes Mermaid et les standards de documentation de lignage. Vous créez également une commande /document-lineage qui génère explicitement des docs de lignage.

Le skill signifie que Claude pourrait appliquer automatiquement vos conventions lorsque vous posez une question liée dans un contexte différent — “how does data flow from sources to this mart?” La commande signifie que vous obtenez définitivement des docs de lignage lorsque vous en avez besoin, formatés à votre façon, avec vos conventions appliquées.

Cette combinaison fonctionne parce que le skill et la commande servent des objectifs différents. Le skill fournit une connaissance ambiante. La commande fournit un déclencheur fiable. Vous ne dépendez pas du skill pour quoi que ce soit de critique — c’est un bonus quand il se déclenche, pas une exigence.

Recommandations pratiques

1. Utiliser les commandes par défaut pour tout workflow que vous exécutez plus de deux fois. Le taux d’échec de 80% de l’activation automatique est inacceptable pour les workflows importants.

2. Utiliser les skills pour la connaissance de domaine, pas pour les procédures. Si le contenu est “voici comment notre entrepôt gère X”, c’est un bon skill. Si le contenu est “exécuter ces cinq étapes dans l’ordre”, c’est une commande.

3. Investir dans l’ingénierie des descriptions pour les skills que vous créez. La description est la seule chose que Claude utilise pour décider d’activer ou non le skill. Les descriptions génériques produisent une activation générique (ou aucune).

4. Maintenir un faible nombre de skills. Trois à cinq skills bien décrits surpassent quinze skills vagues. Chaque skill est en compétition pour l’attention de Claude au moment de l’activation.

5. Ne pas lutter contre l’outil. Si vous vous retrouvez à taper régulièrement “and use the skill”, convertissez ce skill en commande. L’outil vous dit quelque chose sur l’abstraction appropriée.

6. Utiliser CLAUDE.md pour le contexte vraiment universel qui devrait s’appliquer à chaque conversation. CLAUDE.md est lu à chaque fois, inconditionnellement. Il ne dépend pas de la correspondance de mots-clés. Pour les conventions qui doivent toujours s’appliquer, CLAUDE.md est plus fiable que les skills.