Créer un skill avec SKILL.md

Skills : des composants réutilisables

Les agents définissent qui exécute une tâche. Les skills définissent quoi : ce sont des composants réutilisables qui ajoutent des outils, des slash commands et des comportements spécialisés à Mistral Vibe. La distinction devient concrète dès que vous l’appliquez à votre équipe — un agent reflète une posture de travail personnelle, un skill encapsule une procédure que tout le monde doit exécuter de la même façon.

Un skill est un répertoire contenant un fichier SKILL.md avec un frontmatter YAML. Cette structure suit la spécification ouverte Agent Skills, ce qui les rend portables et partageables : le même dossier fonctionne sur la machine de votre collègue sans adaptation.

Anatomie d’un SKILL.md

Voici la structure complète d’un skill, ici une revue de code automatisée :

---
name: code-review
description: Effectue des revues de code automatisées avec analyse de qualité
license: MIT
user-invocable: true
allowed-tools:
  - read_file
  - grep
  - ask_user_question
---

# Code Review Skill

Ce skill analyse la qualité du code source en vérifiant :

1. **Conventions de nommage** — variables, fonctions, classes
2. **Complexité cyclomatique** — fonctions trop longues ou imbriquées
3. **Duplication** — code copié-collé à factoriser
4. **Sécurité** — patterns dangereux (eval, injection SQL, XSS)

## Utilisation

Lancez `/code-review` suivi du chemin ou de la description du code à analyser.

## Format de sortie

Le rapport est structuré en trois niveaux :
- 🔴 **Critique** — à corriger immédiatement
- 🟡 **Avertissement** — à corriger avant merge
- 🟢 **Suggestion** — amélioration optionnelle

Les champs du frontmatter YAML

Le champ name est l’identifiant unique du skill. Il sert à l’activer, le désactiver et le référencer dans les configurations — c’est aussi ce nom qui devient la slash command, ce qui vaut la peine d’être gardé court.

name: code-review

La description est la phrase qui apparaît quand Vibe liste les skills disponibles. Écrivez-la du point de vue de celui qui cherche : elle doit permettre de choisir entre deux skills voisins sans ouvrir les fichiers.

description: Effectue des revues de code automatisées avec analyse de qualité

Le champ license indique la licence du skill, ce qui devient important dès que vous le partagez au-delà de votre poste de travail.

license: MIT

Le booléen user-invocable détermine si le skill peut être lancé directement par l’utilisateur via une slash command. Passez-le à false pour les skills techniques qui servent de brique interne à d’autres skills, et que personne n’a de raison d’appeler à la main.

user-invocable: true   # Accessible via /code-review
user-invocable: false  # Utilisé uniquement en interne par d'autres skills

Enfin, allowed-tools énumère les outils que le skill est autorisé à utiliser. Le principe est le même que pour les agents : chaque outil listé est un pouvoir accordé, et la liste ci-dessous, qui inclut write_file, ne conviendrait pas à un skill d’audit.

allowed-tools:
  - read_file
  - grep
  - list_dir
  - ask_user_question
  - write_file

Le corps du SKILL.md

Après le frontmatter, le corps du fichier est du Markdown libre. Il sert à la fois de documentation et de prompt : Vibe le lit pour comprendre comment le skill fonctionne et dans quel contexte l’appliquer. C’est donc l’endroit où décrire ce que fait le skill, les étapes de son fonctionnement, le format de sortie attendu et des exemples d’utilisation. Un corps vague donne un skill imprévisible ; un corps précis donne un skill qui produit le même résultat d’une semaine à l’autre.

Créer votre premier skill

Construisons un skill de génération de tests. Commencez par créer son répertoire :

mkdir -p ~/.vibe/skills/test-generator

Déposez-y le SKILL.md suivant. Observez comment le corps répond aux questions que Vibe se poserait autrement : quel framework choisir, comment nommer les blocs, où écrire le fichier produit.

---
name: test-generator
description: Génère des tests unitaires pour les fonctions TypeScript/JavaScript
license: MIT
user-invocable: true
allowed-tools:
  - read_file
  - write_file
  - grep
  - list_dir
---

# Test Generator

Génère des tests unitaires complets pour les fonctions
TypeScript et JavaScript.

## Processus

1. Lire le fichier source cible
2. Identifier toutes les fonctions exportées
3. Pour chaque fonction, générer :
   - Test du cas nominal
   - Test avec entrées vides/null
   - Test des cas limites
   - Test des erreurs attendues
4. Écrire les tests dans un fichier `.test.ts` adjacent

## Conventions

- Framework : Vitest (par défaut) ou Jest si détecté
- Nommage : `describe` par fonction, `it` par cas de test
- Assertions : `expect` avec matchers précis
- Pas de mocks sauf si nécessaire (dépendances externes)

## Exemple

Pour un fichier `utils/math.ts` contenant `add(a, b)`,
le skill génère `utils/math.test.ts` avec les tests correspondants.

Une fois le fichier créé, le skill est immédiatement disponible : aucune commande d’installation, aucun redémarrage. Lancez Vibe et appelez-le sur un fichier réel.

vibe
# > /test-generator src/utils/math.ts

Vibe charge le skill, lit son SKILL.md pour comprendre le comportement attendu, et exécute la tâche avec les outils autorisés. Prenez le temps de lire le résultat : c’est en confrontant la sortie à ce que vous imaginiez que vous corrigerez le corps du fichier.

Bonnes pratiques

Tenez-vous à un skill par fonctionnalité. Mélanger revue de code et génération de tests dans un même fichier produit un prompt qui hésite, et vous empêche de désactiver l’un sans perdre l’autre. Limitez de même les outils autorisés à ceux dont le skill a réellement besoin.

Le reste tient à la qualité de la rédaction. Le corps du SKILL.md est votre prompt : soyez précis, et incluez des exemples concrets de ce que le skill produit — un exemple de sortie vaut mieux que trois lignes de description. Testez enfin votre skill sur plusieurs cas, y compris un cas tordu, avant de le partager avec l’équipe.

Points clés à retenir

• Un skill est un répertoire avec un fichier SKILL.md contenant un frontmatter YAML
• Le frontmatter définit le nom, la description, les outils autorisés et l’invocabilité
• Le corps Markdown sert à la fois de documentation et de prompt pour Vibe
• user-invocable: true rend le skill accessible via une slash command
• Créez des skills spécialisés avec le minimum d’outils nécessaire