Référence : format d'un fichier de skill
Description neutre des fichiers markdown servis par l'outil
read_skill.
Emplacement
| Règle | Valeur |
|---|---|
| Répertoire | skillsDir (défaut skills). |
| Motifs | <skillsDir>/<nom>.md (à plat) et <skillsDir>/<nom>/SKILL.md (un répertoire par skill), librement mélangés. Les autres fichiers du répertoire d'un skill sont ignorés. Un README.md à la racine du répertoire est de la documentation, pas un skill : il est ignoré. |
| Nom du skill sur disque | Le nom du fichier sans .md, ou le nom du répertoire pour un SKILL.md. |
| Les deux formes pour un même nom | read_skill renvoie le fichier à plat. |
| Répertoire absent | Pas une erreur : zéro skill, read_skill non déclaré. |
En-tête (front matter)
Optionnel. Quand il est présent, le fichier commence par une ligne --- et l'en-tête se termine à la ligne --- suivante. Seules trois clés sont lues ; les autres sont ignorées.
| Clé | Type | Défaut | Description |
|---|---|---|---|
name |
chaîne | nom du fichier sans .md |
Nom affiché dans le catalogue et accepté par read_skill. Une valeur vide garde le défaut. |
description |
chaîne | "" |
Résumé d'une ligne affiché dans le catalogue. Un skill qui n'en a pas apparaît comme un nom nu, auquel le modèle ne peut rien rattacher ; la bannière de démarrage le signale. |
keywords |
liste séparée par des virgules | vide | Les mots qu'un utilisateur taperait vraiment, dans n'importe quelle langue. Affichés dans le catalogue après la description, plafonnés aux 8 premiers — le catalogue part à chaque requête. C'est le pont lexical : « salue Bob » atteint greetings par saluer, jamais par le nom. L'ordre compte : au-delà du huitième mot, rien n'atteint le modèle — mettez les plus distinctifs en premier. La bannière avertit quand une liste est tronquée. Ne dépensez pas les huit sur des mots déjà présents dans la description : le catalogue affiche les deux, et une description est dans une seule langue — les mots-clés sont là pour les autres. |
Une ligne description: dans le corps, après le --- de fermeture, n'est pas une métadonnée.
Rendu du catalogue
La description de l'outil est :
Load a skill: the step-by-step procedure to follow for this kind of task. Call it BEFORE doing the work, with the name of the matching skill, and then follow what it says. Available skills:
<name> — <description> (<keyword>, <keyword>, …)
<name>
Les entrées sont triées par nom ; la partie — <description> est omise quand la description est vide, et la partie (…) quand il n'y a pas de mots-clés.
Exemple
---
name: what-time-is-it
description: Give the current date and time.
keywords: time, date, clock
---
# What time is it?
Run:
```bash
date "+%A %d %B %Y — %H:%M:%S (%Z)"
Les `keywords` de cet exemple arrivent dans le catalogue sous la forme `what-time-is-it — Give the current date and time. (time, date, clock, now, today, heure, date du jour, quelle heure)`.
## Demander un skill par son nom
`$nom` dans une question désigne un skill à exécuter, avec le reste de la ligne comme paramètres — `use $greetings Bob`. Le sélecteur `$` de la fenêtre l'écrit pour vous ; tapé à la main il marche aussi en mode ligne et en ACP. Dans un éditeur, le skill apparaît en plus dans le menu `/` du client, avec une aide de saisie pour ses paramètres — voir [ACP — les skills comme commandes](acp.md#les-skills-comme-commandes). Il ajoute une ligne à ce que lit le modèle, et c'est toujours le modèle qui fait l'appel `read_skill`. Voir [Commandes slash — les trois sélecteurs](slash-commands.md#les-trois-sélecteurs).
## Écrire un skill que le modèle va EXÉCUTER
Un skill qui demande au modèle de lancer une commande a un mode d'échec, et ce n'est pas celui qu'on attend : le modèle **recopie la commande au lieu de l'exécuter**, dans un bloc de code clôturé, et répond comme s'il avait fait le travail.
Mesuré sur `mellum2-12b-a2.5b-instruct`, le même skill dans les deux formes :
| Ce que dit le skill | Résultat |
|---|---|
| bloc clôturé ` ```bash ` | `⚙ 0 command(s)` — le modèle réaffiche la commande, trois passes sur trois |
| la commande **indentée**, et « call your `bash` tool with this command » | `⚙ 1 command(s)` — trois passes sur trois |
Un bloc clôturé est une affordance d'*affichage*. Mettez-en un dans le contexte du modèle et la continuation la plus probable est le même bloc — c'est exactement ce qu'un petit modèle produit. Nommer l'outil et indenter la commande retire l'invitation.
C'est dépendant du modèle — `qwen3.5-4b` exécutait correctement la version clôturée — donc un skill qui marche sur votre modèle peut échouer sur celui d'un autre. Écrivez-le de la façon sûre quand même.
La règle, pour un skill dont tout l'intérêt est qu'une commande tourne :
- **pas de clôture ` ```bash ` autour de la commande à exécuter.** Indentez-la de quatre espaces.
- **nommez l'outil** : « call your `bash` tool with this command », pas « run: ».
- gardez ce que disent les skills livrés — *the answer is the command's output, nothing else* — car c'est ce qui empêche le modèle de répondre de mémoire.
Un skill qui est de la documentation plutôt qu'une commande à lancer — `bg-jobs`, qui en montre une demi-douzaine — garde ses clôtures. Rien là-dedans n'est « la commande à exécuter », donc il n'y a pas d'invitation à mal lire.
## Exemples livrés
| Chemin | `name` | `description` |
|--------|--------|---------------|
| `skills/greetings/SKILL.md` | `greetings` | Greet somebody with a festive message. |
| `skills/vulcan-salute/SKILL.md` | `vulcan-salute` | Send a vulcan salute to somebody. |
| `skills/what-time-is-it/SKILL.md` | `what-time-is-it` | Give the current date and time. |
Ils utilisent la disposition un répertoire par skill ; lancé depuis la racine du dépôt, `mm` indique `skills: 3`.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 |
|