Ingénierie des descriptions de skills Claude Code

Le champ de description dans le frontmatter YAML d’un skill est la seule entrée que Claude utilise pour décider d’activer ou non le skill pour une requête donnée. Une description vague signifie une activation imprévisible. Une description précise — avec des mots-clés spécifiques, des limites claires et des exclusions explicites — améliore la fiabilité de l’activation. C’est une forme d’ingénierie du contexte : structurer ce que l’IA sait pour qu’elle puisse prendre de meilleures décisions.

Pourquoi la description est importante

L’activation des skills de Claude Code fonctionne par correspondance de mots-clés avec le frontmatter YAML. Au démarrage, Claude charge le name et la description de chaque skill. Lorsque vous faites une requête, il vérifie les correspondances entre vos mots et ces descriptions chargées.

Cela signifie que la description n’est pas une documentation pour les humains. C’est un déclencheur d’activation lisible par machine. L’écrire comme un README — “Ce skill contient des utilitaires pour travailler avec la documentation dbt” — optimise pour le mauvais audience. L’écrire comme un index de recherche — avec des termes spécifiques qu’un utilisateur pourrait réellement saisir — optimise pour l’activation réelle.

Le principe de spécificité

Les descriptions génériques produisent une activation générique (ou nulle). Les descriptions spécifiques produisent une activation ciblée.

Générique (faible activation) :

description: Documentation utilities for dbt projects

Cette description contient trois mots-clés utiles : “documentation”, “dbt” et “projects”. Mais “documentation” est assez large pour correspondre à presque tout, “dbt” correspond à tout dans un projet dbt, et “projects” est du bruit. Claude n’a aucun signal fiable sur quand ce skill est pertinent ou non.

Spécifique (activation plus élevée) :

description: Generate data lineage documentation and Mermaid diagrams.
  Use when user asks about lineage, dependencies, upstream models,
  or documentation for model relationships. Do NOT use for general
  dbt questions unrelated to lineage.

Cette description fait trois choses que la générique ne fait pas :

1. Nomme les sorties. “Lineage documentation” et “Mermaid diagrams” sont des artefacts concrets. Lorsque vous demandez à Claude de “créer un diagramme de lignage”, le mot “diagram” correspond directement.

2. Liste les phrases déclencheuses. “Lineage”, “dependencies”, “upstream models”, “model relationships” — ce sont les mots réels que les utilisateurs tapent lorsqu’ils veulent le contenu de ce skill. Chaque phrase est un chemin d’activation potentiel.

3. Trace une limite négative. “Do NOT use for general dbt questions unrelated to lineage” indique à Claude quand ne pas activer. Sans cela, toute question liée à dbt pourrait faiblement correspondre, conduisant à de fausses activations qui diluent l’utilité du skill.

Anatomie d’une bonne description

Une description de skill bien conçue comporte quatre composantes :

1. Énoncé d’action primaire

Commencez par ce que fait le skill, en utilisant les termes les plus spécifiques possible.

description: Audit dbt models for documentation coverage, test presence,
  and naming convention compliance.

“Audit”, “documentation coverage”, “test presence”, “naming convention compliance” — chaque phrase correspond à une requête concrète qu’un utilisateur pourrait faire.

2. Liste de phrases déclencheuses

Énumérez les façons dont quelqu’un pourrait demander la fonctionnalité de ce skill. Pensez-y comme des mots-clés SEO pour un moteur de recherche interne.

  Use when user asks to audit a model, check documentation,
  verify test coverage, review naming conventions, or validate
  a model against project standards.

Plus vous incluez de synonymes et de formulations, plus il y a de chemins d’activation. “Audit” et “check” et “verify” et “review” et “validate” signifient tous à peu près la même chose — mais un utilisateur pourrait en utiliser n’importe lequel.

3. Limites négatives

Indiquez explicitement quand le skill ne devrait pas s’activer. Cela prévient les faux positifs qui érodent la confiance dans le système de skills.

  Do NOT use for writing new models, generating tests, or creating
  documentation from scratch. This skill evaluates existing models only.

Sans limites négatives, une requête comme “créer de la documentation pour ce modèle” pourrait activer un skill d’audit — parce que “documentation” apparaît à la fois dans la requête et dans la description. La limite négative l’empêche en excluant explicitement les tâches de création.

4. Indices contextuels

Si le skill dépend d’une structure de projet ou d’emplacements de fichiers spécifiques, incluez-les comme indices contextuels afin que Claude sache où chercher lorsque le skill s’active.

  Expects models in models/{base,intermediate,marts}/ with
  corresponding schema.yml files. Naming convention: base__, int__, mrt__ prefixes.

Ces indices servent un double objectif : ils améliorent l’activation (correspondance avec des termes spécifiques au projet comme “base__” ou “mrt__”) et ils donnent à Claude un contexte opérationnel lorsque le skill se déclenche.

Un exemple complet

Assemblant les quatre composantes :

---
name: dbt-model-audit
description: >
  Audit dbt models for documentation coverage, test presence, and naming
  convention compliance. Use when user asks to audit a model, check
  documentation completeness, verify test coverage, review naming
  conventions, or validate a model against project standards. Do NOT use
  for writing new models, generating tests, or creating documentation
  from scratch — this skill evaluates existing models only. Expects models
  in models/{base,intermediate,marts}/ with corresponding schema.yml files.
  Naming convention: base__, int__, mrt__ prefixes.
---

Notez que la description est plus longue que ce que la plupart des gens écrivent. C’est intentionnel. Chaque phrase supplémentaire est un autre mot-clé qui pourrait correspondre à la requête d’un utilisateur. Le coût d’une description plus longue (légèrement plus de contexte consommé au démarrage) est largement compensé par le bénéfice d’une activation plus fiable.

Anti-patterns courants de description

La description en une ligne. description: dbt audit skill donne à Claude presque rien avec quoi correspondre. Trois mots, dont l’un (“skill”) est du métalangage qu’aucun utilisateur n’inclura dans une invite.

La description d’implémentation. description: Reads schema.yml and checks for missing descriptions décrit comment le skill fonctionne, pas quand il devrait s’activer. Les utilisateurs ne demandent pas à Claude de “lire schema.yml”. Ils lui demandent de “vérifier si ce modèle est documenté”.

Le skill qui couvre tout. description: Use for all dbt-related tasks including modeling, testing, documentation, and deployment correspond à tout, ce qui signifie qu’il entre en compétition avec chaque autre skill et le comportement par défaut de Claude. Un skill qui s’active pour tout est aussi inutile que celui qui ne s’active pour rien.

Limites négatives manquantes. Sans exclusions explicites, les skills avec un vocabulaire qui se chevauche interfèrent les uns avec les autres. Si vous avez à la fois un skill de “génération de documentation” et un skill “d’audit de documentation”, les deux ont “documentation” dans leurs descriptions. Les limites négatives (“Do NOT use for auditing existing docs” / “Do NOT use for generating new docs”) les désambiguïsent.

L’évaluation honnête

Même avec des descriptions parfaitement conçues, les skills ne s’activeront pas 100% du temps. Le mécanisme de correspondance de mots-clés a des limitations inhérentes — vous ne pouvez pas anticiper chaque formulation qu’un utilisateur (y compris vous-même) pourrait utiliser.

L’ingénierie des descriptions améliore le taux d’activation d’environ 20% à quelque chose de significativement plus élevé — peut-être 40-60% pour des skills bien décrits dans des domaines ciblés. C’est une vraie amélioration, mais toujours pas assez fiable pour les workflows critiques. Pour tout ce qui nécessite de la cohérence, une commande reste le bon choix.

Là où l’ingénierie des descriptions paie le plus, c’est pour les skills que vous gardez comme connaissance de fond — particularités de l’entrepôt, conventions, matériel de référence. Ces skills n’ont pas besoin de s’activer à chaque fois. Ils ont besoin de s’activer assez souvent pour que la sortie de Claude soit généralement informée par le contexte de votre projet. Passer de 20% à 50% d’activation sur un skill de connaissance de fond fait une différence notable dans la qualité des sorties sans que vous ayez besoin d’invoquer quoi que ce soit explicitement.

Relation avec CLAUDE.md

CLAUDE.md n’a pas de problème d’activation — il se charge inconditionnellement, à chaque fois. Si un élément de contexte est assez important pour toujours influencer le comportement de Claude, il appartient à CLAUDE.md, pas dans un skill avec une description que vous espérez se déclencher correctement.

Les skills sont pour le contexte qui est pertinent parfois. CLAUDE.md est pour le contexte qui est pertinent toujours. L’ingénierie des descriptions aide les skills à s’activer plus fiablement dans les cas “parfois”, mais elle ne peut pas transformer un mécanisme de parfois en mécanisme de toujours. Sachez lequel vous avez besoin avant de décider où placer votre contexte.