Vérifiez la conformité de votre fichier SKILL.md en un clic

Un fichier SKILL.md est le cœur d'une compétence pour agents conversationnels comme Claude Code. Imaginez-le comme une fiche technique lisible par une machine : en haut, un bloc YAML appelé frontmatter décrit les métadonnées (nom, description, compatibilité), et en dessous, du Markdown explique comment utiliser la compétence. Quand un agent parcourt un dossier de compétences, il lit d'abord le frontmatter pour décider s'il doit charger cette compétence. Si la description correspond à la requête de l'utilisateur, l'agent active la compétence et exécute les instructions du corps Markdown.

Prenons un exemple concret : une compétence nommée facture-export pourrait avoir une description comme « Exporte les données de facturation au format CSV pour 12 mois ». L'agent, en voyant cette description, saura qu'il peut proposer cette compétence quand un utilisateur demande à exporter ses factures. Sans cette description claire, la compétence resterait invisible, même si son code est parfait.

Le Validateur SKILL.md vérifie que ce frontmatter respecte la spécification Agent Skills (agentskills.io). Il ne juge pas la qualité des instructions, mais s'assure que le fichier est bien formé : pas de champs manquants, des limites respectées (comme 64 caractères pour le nom), et des avertissements sur des pratiques non optimales (comme une description trop courte). C'est un outil indispensable pour les développeurs qui veulent que leurs compétences soient découvertes et utilisées par les agents.

Le frontmatter d'un fichier SKILL.md est un bloc YAML qui commence et se termine par trois tirets (---). Il doit contenir au minimum deux champs : name et description. Voici un tableau récapitulatif des champs et de leurs contraintes, tels que vérifiés par le Validateur SKILL.md :

Champ	Obligatoire	Limite ou règle
name	Oui	64 caractères max, minuscules, chiffres et tirets simples uniquement. Doit correspondre au nom du dossier (si fourni).
description	Oui	1 024 caractères max. Doit décrire ce que fait la compétence et quand l'utiliser.
license	Non	Chaîne de caractères libre (ex: MIT, Apache-2.0).
compatibility	Non	500 caractères max. Liste des agents ou versions compatibles.
metadata	Non	Objet YAML pour les champs personnalisés (ex: author, version).
allowed-tools	Non	Expérimental. Chaîne de noms d'outils séparés par des espaces (pas une liste YAML).

Un champ inconnu en dehors de metadata déclenchera un avertissement. Par exemple, model ou hooks sont des extensions spécifiques à Claude Code : elles sont valides dans cet environnement, mais ignorées par d'autres agents. Le Validateur SKILL.md vous signalera ces champs avec une note pour vous rappeler qu'ils ne sont pas portables.

Exemple de frontmatter valide :

---
name: calcul-tva
description: Calcule la TVA à [percent=20] ou [percent=10] sur un montant HT et génère une facture simplifiée.
license: MIT
compatibility: Claude Code v3+, AgentSkills v1.2+
metadata:
  author: Jean Dupont
---

Si votre fichier ne respecte pas ces règles, l'agent ne le chargera tout simplement pas. Le Validateur SKILL.md vous aidera à identifier ces erreurs avant même de tester la compétence.

La description est le déclencheur principal pour qu'un agent choisisse votre compétence. Une description vague comme « Outil de calcul » ou « Aide à la facturation » ne suffira pas : l'agent ne saura pas dans quel contexte la proposer. Le Validateur SKILL.md vous avertira si votre description fait moins de 60 caractères, car c'est souvent le signe d'une description trop générique.

Une bonne description doit répondre à deux questions : 1. Que fait la compétence ? (ex: « Calcule les cotisations sociales pour un indépendant en France ») 2. Quand l'utiliser ? (ex: « À utiliser pour les déclarations URSSAF ou les simulations de charges »)

Voici des exemples concrets pour des compétences courantes dans un contexte francophone : - ❌ « Convertit des devises » → trop vague. - ✅ « Convertit des euros en dollars, livres sterling ou francs suisses avec le taux du jour pour les devis internationaux. »

• ❌ « Génère un contrat » → manque de précision.
• ✅ « Génère un contrat de prestation de services conforme au droit français (articles 1710 à 1780 du Code civil). »

Le Validateur SKILL.md vous signalera aussi si votre description contient des mots comme « TODO » ou « Lorem ipsum », qui sont des placeholders à supprimer avant publication. Une description bien rédigée augmente considérablement les chances que votre compétence soit sélectionnée par l'agent, même si elle est techniquement parfaite.

Le corps d'un fichier SKILL.md est écrit en Markdown et contient les instructions que l'agent exécutera. La spécification Agent Skills recommande de ne pas dépasser 500 lignes ou environ 5 000 tokens (en estimant 4 caractères par token). Pourquoi cette limite ?

D'abord, les agents ont des contraintes de mémoire et de temps de traitement. Une compétence trop longue peut ralentir l'agent ou être tronquée. Ensuite, un fichier trop détaillé devient difficile à maintenir. L'idée est de garder le corps concis et de déplacer les détails (comme des exemples de code ou des schémas) dans des fichiers séparés dans un dossier references/.

Le Validateur SKILL.md vous avertira si : - Votre corps fait plus de 500 lignes. - Il contient moins de 20 mots (signe d'un contenu trop léger). - Il dépasse 5 000 tokens estimés. - Il utilise des liens absolus (comme https://exemple.com/fichier.pdf) ou des chemins trop profonds (comme ../../dossier/fichier.md).

Pour structurer efficacement votre corps : 1. Utilisez des titres Markdown (##, ###) pour organiser les sections. 2. Privilégiez les liens relatifs (ex: references/exemple.csv). 3. Évitez les blocs de code trop longs : mieux vaut les externaliser dans references/ et les référencer. 4. Supprimez les commentaires ou notes de développement (comme // À améliorer).

Par exemple, pour une compétence de calcul de charges sociales, le corps pourrait ressembler à ceci :

## Entrées requises
- Montant du chiffre d'affaires (en euros)
- Régime fiscal (micro-entreprise ou réel simplifié)

## Sorties générées
- Montant des cotisations URSSAF
- Montant de l'impôt sur le revenu

## Exemple
Voir [references/exemple.csv](references/exemple.csv) pour un cas concret.

Le Validateur SKILL.md vous aidera à garder votre fichier dans ces limites, tout en vous rappelant que ces recommandations visent à optimiser la portabilité et la performance de votre compétence.

La spécification Agent Skills définit un ensemble de champs standard pour assurer la portabilité des compétences entre différents agents. Cependant, certains agents comme Claude Code ajoutent leurs propres extensions pour des fonctionnalités avancées. Le Validateur SKILL.md vous aide à distinguer ces deux catégories.

Champs standard (lus par tous les agents) : - name, description, license, compatibility, metadata - allowed-tools (expérimental, mais défini dans la spécification)

Extensions Claude Code (ignorées par les autres agents) : - model : pour spécifier un modèle d'IA particulier. - hooks : pour des actions pré/post-exécution. - temperature : pour ajuster la créativité de l'agent.

Le Validateur SKILL.md ne considère pas ces extensions comme des erreurs, mais les signale avec une note pour vous rappeler qu'elles ne sont pas portables. Si vous voulez que votre compétence fonctionne sur plusieurs plateformes, placez ces champs dans metadata :

metadata:
  claude:
    model: claude-3-opus
    temperature: 0.7

Un autre point important concerne allowed-tools. La spécification recommande de l'utiliser comme une chaîne de noms d'outils séparés par des espaces (ex: python calculator), mais certains développeurs le définissent comme une liste YAML. Le Validateur SKILL.md vous avertira si vous utilisez une liste, car cela peut poser des problèmes de compatibilité.

Enfin, évitez les champs totalement inconnus en dehors de metadata. Par exemple, un champ priority ne sera pas reconnu et déclenchera un avertissement. Si vous avez besoin de champs personnalisés, regroupez-les sous metadata pour éviter les conflits avec les futures versions de la spécification.

Le Validateur SKILL.md génère un rapport structuré avec trois niveaux de messages : erreurs, avertissements et notes. Voici comment les interpréter et agir en conséquence.

1. Erreurs (bloquantes) : Une compétence n'est considérée comme valide que si elle ne contient aucune erreur. Les erreurs courantes incluent : - Un frontmatter mal formé (oublier les ---, utiliser des tabulations au lieu d'espaces). - Un champ obligatoire manquant (name ou description). - Un name qui dépasse 64 caractères ou contient des caractères interdits (comme des majuscules ou des espaces). - Une description vide ou trop longue (1 024 caractères max).

Exemple d'erreur : Le champ 'name' doit être en minuscules et ne contenir que des chiffres, des lettres et des tirets simples.

2. Avertissements (non bloquants, mais à corriger) : Les avertissements signalent des pratiques qui peuvent nuire à la découverte ou à l'utilisation de votre compétence : - Une description trop courte (60 caractères ou moins). - Des champs inconnus en dehors de metadata. - Un corps trop long (500 lignes ou 5 000 tokens estimés). - Des placeholders comme TODO ou Lorem ipsum.

Exemple d'avertissement : La description fait moins de 60 caractères. Elle risque de ne pas déclencher l'utilisation de la compétence par l'agent.

3. Notes (informatives) : Les notes vous informent sur des aspects spécifiques, comme : - La présence de champs expérimentaux (allowed-tools). - Des extensions Claude Code (model, hooks). - L'absence de formulation « quand utiliser » dans la description.

Exemple de note : Le champ 'model' est une extension Claude Code et sera ignoré par les autres agents.

Statistiques et export : Le rapport inclut aussi des statistiques sur votre fichier : nombre de lignes, de mots, et d'erreurs/avertissements/notes. Vous pouvez exporter ces résultats au format CSV ou en image pour les partager avec votre équipe.

Ce que le Validateur SKILL.md ne vérifie pas : - L'existence des fichiers référencés (comme references/exemple.csv). - La qualité des instructions dans le corps Markdown. - La pertinence des champs personnalisés dans metadata.

En résumé, une compétence valide est une compétence sans erreurs. Les avertissements et notes vous aident à optimiser son utilisation, mais ne bloquent pas son chargement par l'agent.

Votre compétence semble parfaite, mais l'agent ne la propose jamais ? Voici les causes les plus fréquentes, classées par ordre de probabilité, et comment le Validateur SKILL.md peut vous aider à les identifier.

1. Une description trop vague ou trop courte : C'est la cause numéro un. Les agents choisissent les compétences en fonction de leur description. Si elle ne contient pas de mots-clés précis ou si elle est trop générique (ex: « Outil de gestion »), l'agent ne saura pas quand la proposer. Le Validateur SKILL.md vous avertira si votre description fait moins de 60 caractères ou si elle ne contient pas de formulation « quand utiliser ».

Exemple à éviter :

description: Calcule des montants

Exemple corrigé :

description: Calcule le montant TTC à partir d'un prix HT et d'un taux de TVA ([percent=20] ou [percent=10]) pour les factures françaises.

2. Des erreurs de format dans le frontmatter : Un frontmatter mal formé (oublier les ---, utiliser des tabulations) ou un champ obligatoire manquant (name ou description) empêchera l'agent de charger la compétence. Le Validateur SKILL.md détectera ces erreurs immédiatement.

3. Un nom de compétence non conforme : Le champ name doit respecter des règles strictes : - 64 caractères maximum. - Uniquement des minuscules, des chiffres et des tirets simples. - Doit correspondre au nom du dossier (si vous fournissez ce nom).

Exemple d'erreur : Nom-de-compétence (majuscules) ou calcul_tva (tiret bas interdit).

4. Un corps trop long ou mal structuré : Un corps de plus de 500 lignes ou 5 000 tokens estimés peut être ignoré par l'agent. Le Validateur SKILL.md vous avertira si votre fichier dépasse ces limites. Pensez à externaliser les détails dans un dossier references/ et à utiliser des liens relatifs.

5. Des champs inconnus ou mal placés : Si vous utilisez des champs comme model ou hooks en dehors de metadata, le Validateur SKILL.md vous le signalera avec une note. Ces champs sont spécifiques à Claude Code et ignorés par les autres agents, mais ils ne bloquent pas le chargement de la compétence.

6. Des placeholders ou du code de développement : Des mots comme TODO, Lorem ipsum ou des commentaires de développement dans le corps peuvent induire l'agent en erreur. Le Validateur SKILL.md vous avertira si ces éléments sont présents.

En résumé, commencez toujours par vérifier la description et le frontmatter avec le Validateur SKILL.md. Une fois ces éléments corrigés, testez à nouveau votre compétence : dans la majorité des cas, elle sera désormais proposée par l'agent.