Anatomie d'une skill : la SKILL.md disséquée

Une skill vue de l'extérieur : un dossier, pas de la magie

Avant d'ouvrir le capot, la vue d'ensemble. Une skill, sur le disque, c'est ceci :

compte-rendu-reunion/
├── SKILL.md          ← le cœur : frontmatter + instructions
├── scripts/          ← optionnel : code d'appui déterministe
│   └── format_check.py
└── templates/        ← optionnel : gabarits, exemples de référence
    └── exemple-cr.md

Trois observations qui cadrent tout le reste :

C'est du texte. Pas de binaire, pas de format propriétaire, pas de compilation. Une skill se lit, se diffe, se versionne dans Git comme n'importe quel fichier du dépôt. C'est une propriété précieuse — pour la revue, pour l'audit, pour la maintenance — et une limite qu'il faut connaître : tout ce qui s'y trouve sera lisible en clair dans un contexte de conversation.

Le SKILL.md est obligatoire, le reste est optionnel. Une skill minimale tient dans un seul fichier. Les scripts et gabarits n'apparaissent que quand ils apportent quelque chose que le texte ne peut pas garantir — on y revient plus bas.

Le dossier est autonome. Une skill bien conçue ne dépend pas d'une autre skill pour fonctionner. Si vous sentez le besoin d'un « import », c'est le signe d'un mauvais découpage — retour à la planche à dessin.

Le frontmatter : la vitrine permanente

Ouvrons maintenant le fichier du fil rouge — la skill de compte-rendu que nous construirons pour de bon à l'étape 3. Voici son en-tête :

---
name: compte-rendu-reunion
description: Rédige les comptes-rendus de réunion au format maison —
  sections Décisions / Actions / Points ouverts, ton factuel, une page
  maximum. À utiliser dès qu'on demande un compte-rendu, un CR, un
  relevé de décisions ou une synthèse de réunion.
---

Deux champs, et une asymétrie fondamentale à comprendre :

name — l'identifiant. Court, en minuscules, avec des tirets. Il sert à référencer la skill (logs, gestion, invocation explicite). Rôle purement technique.

description — la vitrine. C'est la seule partie de la skill que le modèle voit en permanence. Tout le reste du fichier — les instructions, les exemples, les règles — est invisible tant que le modèle n'a pas décidé, sur la seule foi de cette description, que la skill mérite d'être chargée.

Relisez cette dernière phrase, c'est le mécanisme central : le modèle ne « fouille » pas vos skills à chaque requête. Il consulte un catalogue de descriptions, et charge — ou pas.

La description au microscope

Puisque tout se joue là, disséquons celle du fil rouge. Elle répond à deux questions, dans cet ordre :

1. Que fait la skill ? — « Rédige les comptes-rendus de réunion au format maison — sections Décisions / Actions / Points ouverts, ton factuel, une page maximum. » Concret, spécifique, vérifiable. Pas « aide à la rédaction de documents » : ça, c'est une description qui ne déclenche rien parce qu'elle pourrait tout déclencher.

2. Quand l'utiliser ? — « À utiliser dès qu'on demande un compte-rendu, un CR, un relevé de décisions ou une synthèse de réunion. » Notez le choix des mots : ce sont les formulations que les utilisateurs emploient réellement, y compris l'abréviation « CR ». La description parle la langue des requêtes qu'elle doit intercepter.

La comparaison qui rend le principe évident :

❌ description: Aide à produire des documents de qualité pour l'équipe.
   → trop vague : jamais chargée (ou chargée à tort sur tout)

❌ description: Skill de compte-rendu v2, remplace l'ancienne version,
   validée par Marc en mars.
   → parle de la skill, pas de la tâche : le modèle n'y trouve
     aucun signal de déclenchement

✅ description: Rédige les comptes-rendus de réunion au format maison
   [...] À utiliser dès qu'on demande un compte-rendu, un CR, un
   relevé de décisions ou une synthèse de réunion.
   → quoi + quand, avec les mots des utilisateurs

Le corps : les instructions

Passée la barrière du frontmatter, le corps du SKILL.md est chargé intégralement. C'est ici que vit l'expertise. Celui de notre fil rouge (version abrégée — la version complète est le livrable de l'étape 3) :

# Compte-rendu de réunion — format maison

## Structure obligatoire
1. **Contexte** — une ligne : date, participants, objet.
2. **Décisions** — ce qui a été tranché. Une décision par puce,
   au passé composé, sans conditionnel.
3. **Actions** — qui / quoi / pour quand. Jamais d'action sans
   porteur ni échéance ; si l'un des deux manque, l'inscrire
   en Points ouverts.
4. **Points ouverts** — ce qui reste à trancher, avec la
   prochaine étape prévue.

## Ton et style
- Factuel. Ni commentaire, ni interprétation des intentions.
- Une page maximum. Au-delà, résumer davantage — pas
  d'annexes.

## Cas limites
- Notes brutes illisibles ou contradictoires : produire le CR
  des points clairs, lister explicitement les zones d'ombre en
  Points ouverts. Ne jamais inventer une décision.
- Informations RH ou individuelles sensibles : ne pas les
  inclure ; signaler leur existence au demandeur, hors CR.

Trois traits d'écriture à retenir, qui valent pour toutes vos futures skills :

L'impératif et le concret. « Une décision par puce, au passé composé » — pas « les décisions devraient idéalement être formulées clairement ». Une skill est une procédure, pas une charte de bonnes intentions.

Les cas limites sont écrits. Notes contradictoires, données sensibles : les situations ambiguës sont tranchées dans le fichier, à froid, par vous — plutôt qu'improvisées par le modèle, à chaud, différemment à chaque fois. C'est exactement la valeur d'une procédure documentée : la répétabilité dans les cas non nominaux. Les lecteurs certifiés ISO 27001 reconnaîtront le principe.

Rien de superflu. Chaque ligne chargée coûte des tokens et de l'attention. L'historique des versions, les remerciements, le contexte politique du projet : dehors. Le corps d'une skill se juge comme un runbook — ce qui n'aide pas l'exécution n'a rien à y faire.

Les scripts embarqués : quand le texte ne suffit pas

Dernier compartiment du dossier : les scripts d'appui. La règle de partage est simple —

Le texte pour le jugement, le code pour le déterminisme.

Rédiger une synthèse, adapter un ton, trancher un cas limite : jugement → instructions. Vérifier qu'un fichier produit respecte un format, convertir des données, appliquer une transformation exacte : déterminisme → script que le modèle exécute, plutôt qu'une opération qu'il « fait de tête » avec un risque d'à-peu-près.

Dans notre fil rouge, scripts/format_check.py vérifie que le CR produit contient bien les quatre sections dans l'ordre — un contrôle qualité mécanique, exactement le genre de tâche qu'on ne confie pas à l'improvisation.

📍 Parcours Skills & MCP — étape 2/9

1. 🗺️ La carte avant le territoire
2. 🔬 Anatomie d'une skill ← vous êtes ici
3. 🛠️ Créer sa première skill
4. 🏛️ Skills en entreprise : gouvernance
5. 🔌 MCP : le protocole expliqué
6. ⚡ Utiliser un serveur MCP existant
7. ⚙️ Créer son serveur MCP minimal
8. 🛡️ Sécuriser ses MCP
9. 📡 L'écosystème : où trouver, où ça bouge

Prochaine étape → Créer sa première skill : on écrit la version complète du fil rouge, du cahier des charges au test — avec la méthode en cinq temps pour une description qui déclenche à coup sûr.

Pour situer cette étape dans la carte d'ensemble : étape 1, la carte avant le territoire.