Une dissection technique du Frontmatter SKILL.md

Ceci est une référence technique pour le bloc frontmatter au sein d'un fichier SKILL.md de Claude. Son but est d'expliquer chaque champ et son effet sur le comportement de la compétence, spécifiquement comment elle se déclenche. Les informations ici ne sont pas théoriques ; elles sont basées sur notre expérience directe d'analyse, d'installation et de test de 743 compétences uniques soumises à SkillProof. Notre méthodologie implique d'exécuter chaque compétence contre un ensemble standardisé de tâches de programmation réelles, et une partie significative de ce processus consiste d'abord à comprendre l'intention de l'auteur telle que déclarée dans le SKILL.md.

Ce que nous avons constaté, c'est que ce petit bloc YAML est la partie la plus critique et souvent la plus mal comprise de la définition d'une compétence. Un frontmatter mal configuré peut désactiver silencieusement une compétence, amenant un auteur à déboguer son script alors que le problème se trouve dans les métadonnées. Ce guide documente ce que fait chaque champ, comment ils interagissent et quelles configurations éviter.

Le bloc Frontmatter SKILL.md

Chaque fichier SKILL.md commence par un bloc frontmatter YAML, délimité par ---. C'est une convention standard dans de nombreux générateurs de sites statiques et outils de documentation, mais dans le contexte d'une compétence Claude, ce n'est pas seulement pour la consommation humaine. Le modèle analyse ce bloc pour comprendre l'identité, les capacités et les contraintes de la compétence.

Cette section YAML de compétence Claude est le tableau de bord de votre compétence. Le modèle de base utilise ces données pour décider si, quand et comment exécuter les outils que vous avez fournis. La considérer comme de simples commentaires informatifs est la première erreur.

Un bloc frontmatter minimal ressemble à ceci :

---
name: example-skill
description: A brief but precise explanation of what this skill does.
allowed-tools: [python]
---

Nous examinerons chacun de ces champs, ainsi que les indicateurs de contrôle d'invocation critiques, basés sur les modèles observés dans les plus de 700 fichiers que nous avons analysés.

Identité principale : name et description

Ces deux champs définissent ce qu'est la compétence pour l'utilisateur et pour le modèle. Cependant, ils ont des rôles très différents dans la manière dont la compétence est déclenchée.

name

Le champ name est une chaîne de caractères unique qui identifie la compétence. Il est utilisé pour l'invocation explicite lorsqu'un utilisateur tape @ suivi du nom de la compétence. Par exemple, @example-skill. Le nom doit être une chaîne de caractères unique, sans espaces. Conventionnellement, il est en minuscules et utilise le kebab-case.

Bien qu'important pour l'identification et les appels directs de l'utilisateur, le name a peu ou pas d'influence sur la décision autonome du modèle d'utiliser la compétence. Le modèle n'infère pas la capacité du nom git-history-analyzer. Il s'appuie sur la description pour cela.

description

C'est le champ le plus important de tout le frontmatter SKILL.md. La description n'est pas un commentaire. C'est l'ensemble d'instructions principal qui indique au modèle quand votre compétence est l'outil approprié pour une tâche donnée. C'est la documentation API pour le modèle lui-même.

Lors de nos tests, la qualité de la description est la variable ayant la corrélation la plus élevée avec le score de succès d'une compétence. Des descriptions vagues entraînent un déclenchement incohérent, une utilisation incorrecte de l'outil, ou la compétence étant entièrement ignorée. C'est une cause profonde fréquente lorsqu'une compétence Claude ne se déclenche pas comme prévu.

Une description médiocre : "Analyzes code."

C'est inutile. Cela ne fournit aucune information sur le type d'analyse, les entrées qu'elle attend ou les sorties qu'elle produit. Le modèle n'a aucune raison de choisir cette compétence plutôt que ses propres capacités internes.

Une description fonctionnelle : "Accepts a file path as input. Reads the specified file and uses the py-complexity tool to calculate the cyclomatic complexity of each function. Returns a list of functions and their complexity scores."

C'est efficace car c'est précis et orienté vers l'action :

1. Entrées : Elle indique clairement qu'elle accepte un chemin de fichier.
2. Actions : Elle spécifie ce qu'elle fait (lit le fichier, calcule la complexité cyclomatique).
3. Outils : Elle fait même allusion à l'outil qu'elle utilisera (py-complexity).
4. Sorties : Elle définit le format de retour attendu (une liste de fonctions et leurs scores de complexité).

Lorsque le modèle est confronté à une tâche comme "Pouvez-vous vérifier la complexité des fonctions dans main.py ?", il peut faire correspondre directement cette requête aux capacités décrites dans la deuxième description. La première description serait ignorée.

Lorsque vous écrivez votre propre compétence Claude, passez la majeure partie de votre temps à affiner la description. Écrivez-la comme si vous documentiez une fonction pour qu'un autre ingénieur l'utilise, car c'est exactement ce que vous faites.

Permissions d'outil : allowed-tools

Le champ allowed-tools est une liste d'exécutables que la compétence est autorisée à invoquer. Cela agit comme un bac à sable de sécurité. Le modèle ne peut, en aucun cas, appeler un outil qui n'est pas explicitement listé dans ce tableau.

allowed-tools: [python, bash, jq]

C'est une fonctionnalité critique de sécurité et de fiabilité. Elle empêche une compétence d'exécuter du code arbitraire et définit clairement sa portée opérationnelle. Lors de nos tests, nous vérifions que les outils listés sont appropriés pour le but déclaré de la compétence. Une compétence qui prétend être un simple formateur JSON mais liste bash dans allowed-tools est un signal d'alarme. Bien qu'elle puisse utiliser bash pour piper vers jq, elle accorde également à la compétence la capacité d'exécuter n'importe quelle commande shell, ce qui est une extension inutile de privilège.

Nous avons vu des compétences échouer parce qu'elles tentent d'appeler un outil qui n'est pas listé. Inversement, nous avons signalé des compétences pour avoir demandé des permissions trop larges qui ne sont pas justifiées par leur description ou leur implémentation. Le principe du moindre privilège s'applique : n'autoriser que les outils exacts nécessaires au fonctionnement de la compétence.

Contrôle d'invocation : user-invocable et disable-model-invocation

Ces deux indicateurs booléens sont moins courants mais ont un impact profond sur le comportement de la compétence. Ils contrôlent la source de l'invocation : un utilisateur peut-il appeler explicitement la compétence, et le modèle peut-il décider de l'utiliser seul ? La valeur par défaut pour les deux est false s'ils sont omis, mais le comportement par défaut effectif d'une compétence standard suppose user-invocable: true et disable-model-invocation: false.

Leur interaction peut prêter à confusion, voici donc un tableau récapitulatif :

user-invocable	disable-model-invocation	Comportement	Verdict SkillProof
true (ou omis)	false (ou omis)	Standard : L'utilisateur peut mentionner @ ; le modèle peut invoquer de manière autonome.	La configuration attendue pour la plupart des compétences.
false	false (ou omis)	Autonome uniquement : L'utilisateur ne peut pas mentionner @ ; le modèle peut invoquer.	Pour les tâches de fond ou les fonctions d'aide.
true	true	Explicite uniquement : L'utilisateur doit mentionner @ ; le modèle ne peut pas invoquer.	Pour les outils ayant des effets secondaires ou un coût élevé.
false	true	Désactivé : Ni l'utilisateur ni le modèle ne peuvent invoquer.	Configuration défectueuse. Nous les signalons.

user-invocable

Cet indicateur détermine si un utilisateur peut déclencher directement la compétence en utilisant une mention @. La valeur par défaut, true, est le comportement que la plupart des utilisateurs attendent. Une user-invocable claude skill est une compétence que vous pouvez appeler à la demande.

Définir user-invocable: false signifie que la compétence ne peut être déclenchée que par le processus de prise de décision autonome du modèle. L'utilisateur ne peut pas la forcer à s'exécuter. C'est un choix valide pour les compétences qui agissent comme des assistants de fond ou font partie d'une chaîne d'outils plus large, mais cela peut être une source majeure de confusion. Nous avons testé plusieurs compétences où cet indicateur était défini sur false sans aucune mention dans la documentation. Les utilisateurs essayant de mentionner @ la compétence ne verraient aucune réponse et supposeraient qu'elle était cassée. Si vous définissez cela sur false, vous devez le documenter clairement.

disable-model-invocation

Cet indicateur est l'inverse de user-invocable. Il détermine si le modèle est autorisé à choisir proactivement la compétence par lui-même.

La valeur par défaut, false, permet au modèle d'utiliser la compétence chaque fois que sa description correspond à la requête de l'utilisateur.

Définir disable-model-invocation: true interdit au modèle d'utiliser la compétence de manière autonome. La compétence ne peut être exécutée que si user-invocable est également true et que l'utilisateur la mentionne explicitement @. C'est utile pour les outils qui sont coûteux, ont des effets secondaires significatifs (comme effectuer une requête réseau ou modifier des fichiers), ou nécessitent une entrée très spécifique que le modèle pourrait ne pas être en mesure d'inférer correctement par lui-même.

La combinaison d'échec silencieux

La configuration la plus problématique que nous avons découverte lors de nos tests est la combinaison de user-invocable: false et disable-model-invocation: true. Comme le montre le tableau, une compétence configurée de cette manière ne peut être déclenchée par aucun moyen. L'utilisateur est empêché de l'appeler, et le modèle est interdit de la choisir.

Lors de notre examen de plus de 700 fichiers SKILL.md, nous avons trouvé des compétences avec cette configuration exacte. Du point de vue de l'utilisateur, la compétence est installée mais complètement non fonctionnelle. C'est un code mort de fait. Dans tous les cas, nous mettons ces compétences en file d'attente pour une inspection manuelle. Parfois, c'est une erreur de l'auteur. D'autres fois, cela semble être un moyen de désactiver temporairement une compétence dans un dépôt sans la supprimer. Quelle que soit la raison, livrer une compétence avec cette configuration est une erreur.

Implications pratiques tirées de 743 tests de compétences

Comprendre le frontmatter des compétences Claude n'est pas un exercice académique. C'est la clé pour construire des compétences fiables et efficaces. Nos tests de 743 compétences ont renforcé quelques vérités clés :

1. La description est le déclencheur. Le temps passé à l'affiner n'est jamais perdu.
2. Les valeurs par défaut sont généralement correctes. La plupart des compétences devraient être invocables par l'utilisateur et par le modèle.
3. Les déviations doivent être délibérées et documentées. Si vous rendez une compétence autonome uniquement ou explicite uniquement, vos utilisateurs doivent savoir pourquoi.

C'est pourquoi SkillProof existe. Sur les 743 compétences que nous avons traitées, 31 ont en fait eu des performances inférieures à celles d'un Claude simple. Beaucoup de ces échecs n'étaient pas dus à un mauvais code, mais à un frontmatter SKILL.md mal construit qui a fait que la compétence s'est déclenchée au mauvais moment, ou pas du tout. 204 autres compétences ont réussi nos tests mais nécessitaient une configuration non évidente, souvent liée à la compréhension de la façon dont les indicateurs d'invocation étaient définis. Nous publions ces découvertes – les succès et les échecs – car la vraie valeur d'une compétence est déterminée par ses performances réelles, pas seulement par son code.

Trouver les compétences qui réussissent cela est l'objectif de notre répertoire. Une compétence bien configurée comme un Codebase Summarizer aura une description précise et des paramètres d'invocation sensés, lui permettant de fonctionner comme une extension fiable du modèle.

Vous pouvez parcourir les 508 compétences qui ont réussi nos tests dans notre catalogue. Chaque liste inclut le frontmatter SKILL.md exact utilisé et notre verdict sur son efficacité. Voyez par vous-même à quoi ressemble une compétence bien configurée et éprouvée.