Écrire une Skill OpenClaw : SKILL.md, frontmatter et ClawHub

Un agent OpenClaw qui répond, c’est bien ; un agent qui sait faire des choses précises et répétables, c’est tout l’intérêt. Les compétences (skills) sont le mécanisme pour cela : des dossiers contenant un fichier SKILL.md en langage naturel, que l’agent active quand le contexte s’y prête. Ce tutoriel vous fait écrire votre première compétence sur mesure, du fichier vide à l’exécution réelle.

🎯 Ce que vous allez apprendre

• Comprendre ce qu’est une compétence et où OpenClaw va la chercher.
• Rédiger un SKILL.md avec son frontmatter YAML correct.
• Écrire des instructions en langage naturel qu’un agent saura suivre.
• Vérifier, déclencher et déboguer votre compétence.
• Découvrir et installer des compétences existantes depuis ClawHub.

🛠️ Ce que vous allez construire

Vous allez doter votre assistant d’une compétence « vérification de site » : quand vous lui demandez si un site répond, il teste son URL et vous renvoie un verdict clair (en ligne, erreur, injoignable) avec le code HTTP. Une brique utile au quotidien pour surveiller un site sans ouvrir de navigateur.

Prérequis

• OpenClaw installé, un modèle configuré et l’agent capable de répondre.
• L’outil curl présent sur la machine de l’agent (standard sous Linux).
• Un éditeur de texte en ligne de commande (nano suffit).
• Niveau : débutant à intermédiaire. Test express : si vous savez créer un dossier et écrire un fichier texte, vous êtes prêt.
• ⏱️ Temps estimé : ~30 minutes.

Étape 1 — Comprendre la structure d’une compétence

Une compétence n’est pas du code mais un dossier portant un nom, contenant au minimum un fichier SKILL.md. Ce fichier a deux parties : un frontmatter YAML (entre deux lignes ---) qui décrit la compétence, et un corps en markdown qui contient les instructions que l’agent suivra. Le modèle lit la description pour décider quand activer la compétence, puis suit le corps pour l’exécuter.

OpenClaw cherche les compétences dans plusieurs emplacements, par ordre de priorité. Le plus simple pour débuter est l’espace de travail de l’agent :

~/.openclaw/workspace/skills/<nom-de-la-competence>/SKILL.md

Règle à retenir : le nom du dossier doit correspondre exactement au champ name du frontmatter. Si les deux divergent, la compétence est ignorée ou mal nommée. En cas de conflit de nom entre deux emplacements, c’est la source la plus prioritaire qui gagne.

Étape 2 — Créer le dossier de la compétence

On commence par créer l’arborescence. Choisissez un nom en minuscules avec des traits d’union, descriptif de ce que fait la compétence. Ici, verif-site.

mkdir -p ~/.openclaw/workspace/skills/verif-site
cd ~/.openclaw/workspace/skills/verif-site

Le dossier est vide pour l’instant. Tout va se jouer dans le fichier SKILL.md que nous écrivons à l’étape suivante. Cette organisation par dossier permet, plus tard, d’ajouter des fichiers annexes (scripts, gabarits) à côté du SKILL.md sans encombrer les autres compétences.

Étape 3 — Écrire le frontmatter

Le frontmatter est la carte d’identité de la compétence. Deux champs sont obligatoires : name (l’identifiant, qui doit coller au nom du dossier) et description. La description est cruciale : c’est elle que le modèle lit pour décider d’activer ou non la compétence. Une bonne description dit à la fois ce que fait la compétence et quand l’utiliser.

---
name: verif-site
description: Verifie si un site web repond et renvoie son code HTTP. A utiliser quand l'utilisateur demande si un site est en ligne, accessible ou tombe en panne.
---

Soignez la description comme un déclencheur : trop vague (« vérifie des choses »), la compétence ne s’activera jamais au bon moment ; trop étroite, elle ratera des formulations proches. Mentionnez les mots que l’utilisateur emploiera réellement : « en ligne », « accessible », « répond », « en panne ».

✅ Point d’étape — votre SKILL.md commence par un bloc --- contenant name et description, et name vaut exactement verif-site, comme le dossier.

Étape 4 — Rédiger le corps des instructions

Sous le frontmatter, le corps explique à l’agent comment réaliser la tâche, en langage naturel. On écrit comme on briefferait un assistant humain compétent : l’objectif, les étapes, le format de réponse attendu. L’agent dispose d’outils (shell, requêtes réseau) ; on lui indique lesquels utiliser et comment interpréter le résultat.

---
name: verif-site
description: Verifie si un site web repond et renvoie son code HTTP. A utiliser quand l'utilisateur demande si un site est en ligne, accessible ou tombe en panne.
---

# Verification de site

Quand l'utilisateur fournit une URL ou un nom de domaine, teste sa
disponibilite et rapporte un verdict clair.

## Procedure
1. Normalise l'entree : si elle ne commence pas par http, prefixe par https://.
2. Lance une requete HEAD avec un delai d'attente de 10 secondes :
   curl -s -o /dev/null -w "%{http_code}" -I --max-time 10 <URL>
3. Interprete le code renvoye :
   - 200 a 399  -> le site est EN LIGNE
   - 400 a 599  -> le site repond mais renvoie une ERREUR (precise le code)
   - aucune reponse / timeout -> le site est INJOIGNABLE

## Format de reponse
Repond en une phrase : etat, code HTTP, et l'URL testee.
Exemple : "itskillscenter.io est EN LIGNE (code 200)."

Remarquez la précision des instructions : un délai d’attente borné (pour ne pas bloquer), une grille d’interprétation des codes, et un format de réponse imposé. Plus vous êtes explicite, plus le comportement est reproductible. Évitez les ambiguïtés du type « teste le site » sans dire comment ni quoi répondre.

Étape 5 — Vérifier et activer la compétence

OpenClaw fournit une commande pour valider qu’une compétence est bien formée (frontmatter correct, nom cohérent) avant de compter dessus. C’est le premier réflexe après écriture.

openclaw skills verify verif-site

Si la vérification passe, relancez la passerelle pour que l’agent recharge ses compétences. Une erreur ici pointe presque toujours un frontmatter mal formé (indentation YAML, deux-points manquant) ou un nom de dossier qui ne correspond pas au champ name.

✅ Point d’étape — openclaw skills verify verif-site ne signale aucune erreur. La compétence est prête à être déclenchée.

Étape 6 — Déclencher la compétence en conditions réelles

Le test ultime : demander à l’agent quelque chose qui correspond à la description, et voir s’il active la compétence. Écrivez-lui sur Telegram, ou en ligne de commande :

openclaw agent --message "Est-ce que itskillscenter.io est en ligne ?"

L’agent reconnaît l’intention, active verif-site, exécute la requête curl et répond selon le format imposé, par exemple « itskillscenter.io est EN LIGNE (code 200). ». Si l’agent répond de façon générique sans tester l’URL, c’est que la description n’a pas suffi à déclencher la compétence : reformulez-la avec des mots plus proches de votre demande.

Étape 7 — Découvrir et installer des compétences existantes

Vous n’êtes pas obligé de tout écrire : des centaines de compétences sont partagées par la communauté sur ClawHub, le registre public d’OpenClaw. L’agent peut les chercher, et vous pouvez les installer en une commande.

openclaw skills install <slug-de-la-competence>
# Depuis un depot Git :
openclaw skills install git:proprietaire/depot@main
# Une copie locale, sous un autre nom :
openclaw skills install ./chemin/vers/competence --as mon-outil

Avant d’installer une compétence tierce, ouvrez son SKILL.md et lisez ce qu’elle demande à l’agent de faire : une compétence est du texte exécuté avec vos droits et vos clés. Nous détaillons ce risque dans le tutoriel sur la sécurité. Pour mettre à jour vos compétences, openclaw skills update --all.

Étape 8 — Vérification finale

Bouclez la boucle : posez deux questions à l’agent, l’une sur un site qui répond, l’autre sur un domaine inexistant. La première doit renvoyer « EN LIGNE (code 200) », la seconde « INJOIGNABLE ». Si les deux verdicts tombent juste, votre première compétence sur mesure fonctionne de bout en bout.

🐞 Pièges fréquents

🌍 Des compétences taillées pour vos besoins

L’écriture de compétences est l’endroit où un assistant générique devient votre outil. Plutôt que de copier des exemples génériques, codez les tâches qui reviennent chez vous : vérifier qu’un site client répond, résumer un fichier de logs, formater un montant en FCFA, préparer un message de relance. Comme une compétence n’est que du texte, vous pouvez la versionner dans un dépôt Git, la partager avec votre équipe via openclaw skills install git:..., et la faire évoluer sans toucher au cœur de l’agent. C’est aussi une excellente porte d’entrée pour des profils non-développeurs : décrire une procédure en français clair suffit souvent à créer une compétence utile.

✅ Récapitulatif

Vous avez compris la structure d’une compétence, créé le dossier verif-site, écrit un frontmatter valide (name + description), rédigé des instructions précises avec format de réponse imposé, vérifié la compétence, puis vu l’agent la déclencher pour de vrai. Vous savez aussi installer des compétences depuis ClawHub. Votre assistant est devenu programmable en langage naturel.

🧾 Aide-mémoire

💪 À vous de jouer

Défi : étendez verif-site pour qu’elle mesure aussi le temps de réponse et le signale si le site est lent (plus de 2 secondes).

curl -s -o /dev/null -w "%{http_code} %{time_total}" -I --max-time 10 <URL>

Tutoriels frères

• Sécuriser un agent OpenClaw — pourquoi lire une compétence tierce avant de l’installer.
• Piloter OpenClaw en ligne de commande — déclencher et déboguer les compétences.

Pour aller plus loin

• 🔝 Retour au guide principal : OpenClaw, panorama et mise en route.
• Documentation officielle des compétences : docs.openclaw.ai/tools/skills ; registre clawhub.ai.

Les champs optionnels du frontmatter

Au-delà de name et description, le frontmatter accepte des champs facultatifs qui affinent le comportement de la compétence. Vous n’en avez pas besoin pour débuter, mais les connaître évite de réinventer la roue quand un besoin précis se présente.

• user-invocable — booléen (vrai par défaut) : indique si l’utilisateur peut invoquer la compétence directement, comme une commande.
• disable-model-invocation — booléen (faux par défaut) : empêche le modèle de déclencher la compétence de lui-même, utile pour une compétence qu’on ne veut lancer qu’à la demande explicite.
• homepage — une URL de référence, affichée dans l’interface des compétences sur macOS.
• metadata — un objet JSON sur une seule ligne, utilisé au chargement pour filtrer la compétence selon la présence d’un binaire, d’une variable d’environnement ou d’un réglage. C’est ainsi qu’une compétence qui dépend de curl peut se désactiver proprement là où l’outil manque.

Ces champs transforment une compétence basique en composant robuste : activation conditionnelle, invocation contrôlée, documentation intégrée.

Où l’agent cherche les compétences, et qui l’emporte

OpenClaw agrège les compétences de plusieurs racines, dans un ordre de priorité défini. Comprendre cet ordre explique pourquoi une compétence personnelle peut « écraser » une compétence fournie par défaut portant le même nom. De la plus prioritaire à la moins prioritaire, on trouve : l’espace de travail (workspace/skills), les compétences de projet, les compétences personnelles partagées, les compétences gérées sous ~/.openclaw/skills, puis les compétences intégrées livrées avec l’agent. En cas de conflit de nom, la source la plus haute gagne. Concrètement, pour personnaliser une compétence intégrée, on en place une version homonyme dans son espace de travail : elle prend le dessus sans qu’on modifie quoi que ce soit dans l’installation d’origine.

FAQ

Faut-il savoir programmer pour écrire une compétence ?
Non. Une compétence est essentiellement un texte d’instructions. Savoir décrire clairement une procédure suffit pour beaucoup de cas ; les commandes shell ne servent que lorsque la tâche touche le système.

Quelle différence entre une compétence et le fichier AGENTS.md ?
AGENTS.md fixe des règles globales valables pour tout l’agent ; une compétence est une capacité ciblée, activée seulement quand sa description correspond à la demande.

Mes compétences sont-elles partagées automatiquement ?
Non. Elles restent locales dans votre espace de travail tant que vous ne les publiez pas sur ClawHub ou dans un dépôt Git. Vous gardez le contrôle de ce que vous diffusez.

Une compétence peut-elle en appeler une autre ?
L’agent enchaîne les compétences selon le contexte d’une même conversation : il peut activer plusieurs compétences pour répondre à une demande composite, en suivant les descriptions de chacune.