Les skills OpenClaw : Guide complet

Les skills sont le cœur d'OpenClaw. Sans eux, un agent ne sait rien faire. Avec eux, il peut naviguer sur le web, analyser des données, appeler des API ou rédiger du contenu. Ce guide explique précisément ce qu'est un skill dans OpenClaw, comment utiliser les modules natifs, et surtout comment créer les vôtres. Que vous débutiez avec OpenClaw ou que vous souhaitiez aller plus loin dans la personnalisation, cette référence couvre l'ensemble du système. Consulter le Guide complet OpenClaw avant de lire cet article vous donnera un meilleur contexte.

---

Qu'est-ce qu'un skill OpenClaw ?

Un skill est une unité fonctionnelle autonome qu'un agent OpenClaw peut invoquer lors de l'exécution d'une tâche. Concrètement, c'est une classe Python décorée avec @skill, exposant une méthode principale que l'agent appelle avec des paramètres définis.

La philosophie d'OpenClaw repose sur la modularité : chaque skill est indépendant, testable isolément, et peut être partagé entre plusieurs agents. Un skill n'a pas d'état persistant entre deux appels sauf si vous l'y autorisez explicitement via la mémoire de l'agent.

Chaque skill expose :

• Un nom (identifiant unique dans le registre de l'agent)
• Une description (utilisée par le LLM pour décider quand l'invoquer)
• Un schéma d'entrée (paramètres attendus)
• Une méthode run() (la logique métier)

L'agent utilise la description textuelle du skill pour décider, à chaque étape de raisonnement, quel skill appeler. C'est pourquoi la rédaction de la description est aussi importante que le code lui-même.

---

Anatomie d'un skill

Avant d'écrire votre premier skill, il est utile de comprendre comment OpenClaw le voit en interne. Un skill se décompose toujours en quatre couches, du plus visible au plus profond :

1. La signature exposée au LLM — c'est ce que l'agent « lit ». Elle est dérivée du name, de la description et du schéma d'entrée. Le reste du code est invisible pour le modèle.
2. Le contrat d'entrée/sortie — un SkillInput (dictionnaire ou objet Pydantic) en entrée, un SkillOutput en sortie. Ce contrat est ce qui rend les skills composables et testables.
3. La logique métier — le corps de la méthode run(), où vous appelez des API, manipulez des fichiers ou interrogez une base.
4. Les dépendances injectées — clés d'API, clients HTTP, connexions DB, passées au constructeur __init__ à l'instanciation.

Concrètement, le flux d'un appel se déroule ainsi : l'agent sélectionne le skill par son nom, OpenClaw valide les arguments fournis par le LLM contre le schéma d'entrée, appelle run(), puis sérialise le SkillOutput pour le réinjecter dans le contexte du raisonnement.

LLM décide  ──►  validation SkillInput  ──►  run()  ──►  SkillOutput  ──►  contexte agent

La séparation entre le contrat (couches 1-2) et l'implémentation (couches 3-4) est ce qui permet de remplacer la logique d'un skill sans rien changer côté agent, tant que le schéma reste stable.

---

Les skills natifs

OpenClaw embarque un ensemble de skills prêts à l'emploi couvrant les besoins les plus fréquents :

Skill natif	Fonction
WebSearchSkill	Effectue une recherche web et retourne les résultats structurés
WebScraperSkill	Extrait le contenu HTML d'une URL
FileReaderSkill	Lit un fichier local (texte, CSV, JSON)
FileWriterSkill	Écrit ou met à jour un fichier local
HttpRequestSkill	Effectue des requêtes HTTP arbitraires (GET, POST, etc.)
CodeExecutorSkill	Exécute du code Python dans un sandbox isolé
SummarizerSkill	Résume un texte long via le LLM configuré
MemoryReadSkill	Lit la mémoire persistante de l'agent
MemoryWriteSkill	Écrit dans la mémoire persistante de l'agent

Ces skills s'activent à l'instanciation de l'agent. Vous pouvez choisir de n'activer qu'un sous-ensemble pour limiter les capacités d'un agent à son périmètre fonctionnel, ce qui réduit aussi les risques d'hallucination lors du choix d'outil.

from openclaw import Agent
from openclaw.skills import WebSearchSkill, SummarizerSkill

agent = Agent(
    name="ResearchAgent",
    skills=[WebSearchSkill(), SummarizerSkill()],
    llm="gpt-4o"
)

---

Créer un skill personnalisé

La création d'un skill custom suit une structure précise. OpenClaw fournit la classe de base BaseSkill et le décorateur @skill pour l'enregistrement automatique.

Structure minimale

from openclaw.skills import BaseSkill, skill
from openclaw.types import SkillInput, SkillOutput

@skill(
    name="currency_converter",
    description="Convertit un montant d'une devise vers une autre en temps réel via l'API Fixer.io."
)
class CurrencyConverterSkill(BaseSkill):

    def __init__(self, api_key: str):
        self.api_key = api_key

    def run(self, input: SkillInput) -> SkillOutput:
        amount = input.get("amount")
        from_currency = input.get("from")
        to_currency = input.get("to")

        result = self._call_api(amount, from_currency, to_currency)

        return SkillOutput(
            success=True,
            data={"converted_amount": result, "currency": to_currency}
        )

    def _call_api(self, amount, from_c, to_c):
        import requests
        url = f"https://api.fixer.io/latest?access_key={self.api_key}&base={from_c}&symbols={to_c}"
        response = requests.get(url).json()
        rate = response["rates"][to_c]
        return round(amount * rate, 2)

Le décorateur @skill

Le décorateur @skill prend deux paramètres obligatoires :

• name : identifiant unique, en snake_case, sans espaces
• description : texte explicatif destiné au LLM — soyez précis et actionnable

Un conseil pratique : rédigez la description comme si vous expliquiez à un collègue quand utiliser cet outil. Évitez les descriptions vagues comme "Fait des calculs". Préférez "Calcule le taux de conversion entre deux devises ISO 4217 en interrogeant l'API Fixer.io en temps réel."

Schéma de validation

Pour les skills qui nécessitent une validation stricte des entrées, OpenClaw supporte Pydantic :

from pydantic import BaseModel
from openclaw.skills import BaseSkill, skill
from openclaw.types import SkillOutput

class CurrencyInput(BaseModel):
    amount: float
    from_currency: str
    to_currency: str

@skill(
    name="currency_converter_v2",
    description="Convertit un montant entre deux devises ISO 4217.",
    input_schema=CurrencyInput
)
class CurrencyConverterV2Skill(BaseSkill):

    def run(self, input: CurrencyInput) -> SkillOutput:
        # input est maintenant un objet Pydantic validé
        return SkillOutput(success=True, data={"amount": input.amount})

L'utilisation de Pydantic est recommandée dès que le skill reçoit plus de deux paramètres ou que les types ont de l'importance (nombres flottants, URLs, dates, etc.).

---

Le cycle de vie d'un skill

Un skill traverse plusieurs phases entre sa définition et son exécution. Comprendre ce cycle aide à savoir où placer chaque chose — initialisation coûteuse, validation, nettoyage.

1. Enregistrement — au chargement du module, le décorateur @skill inscrit la classe dans le registre global d'OpenClaw. Le skill devient découvrable par son name.
2. Instanciation — quand vous passez MonSkill(api_key=...) à un agent, __init__ s'exécute une seule fois. C'est l'endroit idéal pour créer les ressources réutilisables (client HTTP, connexion DB) afin de ne pas les recréer à chaque appel.
3. Activation — l'agent intègre le skill à son registre local et expose sa signature au LLM. Un skill non activé reste invisible pour le modèle.
4. Invocation — à chaque étape de raisonnement, le LLM peut appeler run(). OpenClaw valide d'abord les entrées, puis exécute la logique. Cette phase peut se répéter de nombreuses fois durant une même tâche.
5. Libération — si votre skill détient des ressources (fichiers ouverts, sessions réseau), implémentez close() ou un gestionnaire de contexte pour les libérer à la fin de la session de l'agent.

from openclaw.skills import BaseSkill, skill
from openclaw.types import SkillInput, SkillOutput
import httpx

@skill(name="api_client", description="Appelle un service interne authentifié.")
class ApiClientSkill(BaseSkill):

    def __init__(self, api_key: str):
        # Instanciation : créé une seule fois, réutilisé à chaque invocation
        self.client = httpx.Client(
            base_url="https://api.interne.example",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=10,
        )

    def run(self, input: SkillInput) -> SkillOutput:
        # Invocation : peut être appelé des dizaines de fois
        resp = self.client.get("/data", params={"q": input.get("query")})
        return SkillOutput(success=True, data=resp.json())

    def close(self):
        # Libération : fermeture propre du client en fin de session
        self.client.close()

Distinguer instanciation et invocation évite un piège classique : recréer un client HTTP ou rouvrir une connexion à chaque appel run(), ce qui dégrade fortement les performances sur les tâches longues.

---

Combiner plusieurs skills

L'intérêt réel d'OpenClaw apparaît quand on combine des skills. Un agent peut enchaîner des appels de skills de façon autonome en fonction de son objectif.

from openclaw import Agent
from openclaw.skills import WebSearchSkill, WebScraperSkill, SummarizerSkill, FileWriterSkill

agent = Agent(
    name="ContentResearcher",
    goal="Recherche les 5 meilleurs articles sur un sujet, extrait leur contenu et produit un résumé.",
    skills=[
        WebSearchSkill(),
        WebScraperSkill(),
        SummarizerSkill(),
        FileWriterSkill()
    ],
    llm="gpt-4o",
    max_steps=20
)

result = agent.run(task="Recherche et résume les meilleurs articles sur LangGraph en 2025.")

Dans cet exemple, l'agent :

1. Utilise WebSearchSkill pour trouver des URLs pertinentes
2. Appelle WebScraperSkill sur chaque URL pour extraire le contenu
3. Passe le contenu à SummarizerSkill pour condenser
4. Écrit le résumé final avec FileWriterSkill

La séquence n'est pas prédéfinie dans le code : c'est le LLM qui décide de l'ordre d'appel en fonction de l'objectif.

---

Exemple concret : skill de scraping

Voici un skill de scraping plus complet, avec gestion des erreurs et extraction sélective via CSS selectors :

import requests
from bs4 import BeautifulSoup
from openclaw.skills import BaseSkill, skill
from openclaw.types import SkillInput, SkillOutput

@skill(
    name="targeted_scraper",
    description=(
        "Extrait le contenu textuel d'une URL en ciblant un sélecteur CSS précis. "
        "Utiliser quand on veut extraire uniquement une section spécifique d'une page web "
        "(article principal, balise title, prix, etc.)."
    )
)
class TargetedScraperSkill(BaseSkill):

    def run(self, input: SkillInput) -> SkillOutput:
        url = input.get("url")
        selector = input.get("css_selector", "body")
        timeout = input.get("timeout", 10)

        if not url:
            return SkillOutput(success=False, error="Paramètre 'url' manquant.")

        try:
            headers = {"User-Agent": "OpenClaw-Agent/1.0"}
            response = requests.get(url, headers=headers, timeout=timeout)
            response.raise_for_status()

            soup = BeautifulSoup(response.text, "html.parser")
            elements = soup.select(selector)

            if not elements:
                return SkillOutput(
                    success=False,
                    error=f"Aucun élément trouvé pour le sélecteur '{selector}'."
                )

            text = "\n".join(el.get_text(strip=True) for el in elements)
            return SkillOutput(success=True, data={"content": text, "url": url})

        except requests.Timeout:
            return SkillOutput(success=False, error=f"Timeout après {timeout}s sur {url}.")
        except requests.RequestException as e:
            return SkillOutput(success=False, error=str(e))

Ce skill illustre plusieurs bonnes pratiques : validation des entrées, gestion granulaire des erreurs, headers HTTP réalistes, et retour structuré.

---

Déboguer un skill

Le débogage d'un skill se fait à deux niveaux : le skill isolé (votre code) et le comportement de l'agent (le choix du skill par le LLM).

Tester run() directement. Un skill se teste sans agent : instanciez la classe et appelez run() avec un SkillInput fabriqué à la main. C'est le moyen le plus rapide d'isoler un bug de logique métier.

from openclaw.types import SkillInput

skill = TargetedScraperSkill()
output = skill.run(SkillInput({"url": "https://example.com", "css_selector": "h1"}))

assert output.success is True
print(output.data["content"])

Activer le mode verbeux. Pour voir les décisions du LLM (quel skill, avec quels arguments), instanciez l'agent en mode trace. Vous obtenez le raisonnement étape par étape, ce qui révèle les mauvais choix de skill ou les arguments mal formés.

agent = Agent(
    name="DebugAgent",
    skills=[TargetedScraperSkill()],
    llm="gpt-4o",
    verbose=True,        # journalise chaque décision et appel de skill
    trace=True,          # conserve la trace complète pour inspection
)
result = agent.run(task="Extrais le titre de https://example.com")
print(result.trace)     # liste ordonnée des appels de skills et de leurs sorties

Les trois symptômes les plus fréquents :

Symptôme	Cause probable	Correctif
Le skill n'est jamais appelé	Description trop vague ou trop proche d'un autre skill	Réécrire la description avec le quand utiliser
Arguments invalides ou manquants	Schéma d'entrée non documenté	Ajouter un input_schema Pydantic avec des Field(description=...)
Le skill échoue silencieusement	Exception avalée, success jamais vérifié	Toujours retourner SkillOutput(success=False, error=...) et tester output.success

Le premier symptôme est de loin le plus courant : si un skill n'est jamais sélectionné alors qu'il devrait l'être, le problème est presque toujours dans la description, pas dans le code. Comparez sa formulation avec celle des skills concurrents pour lever toute ambiguïté.

---

Bonnes pratiques

Nommer avec précision. Le name et la description sont lus par le LLM à chaque décision. Une description ambigüe entraîne des appels incorrects ou des hallucinations de paramètres.

Garder un skill = une responsabilité. Si votre skill fait du scraping ET de l'analyse de sentiment, découpez-le en deux. La composition est préférable à la concentration.

Gérer toutes les erreurs. Retournez toujours un SkillOutput(success=False, error=...) plutôt que de lever une exception non contrôlée. L'agent peut ainsi décider de réessayer ou de changer d'approche.

Tester les skills isolément. Chaque skill est testable sans instancier un agent complet. Écrivez des tests unitaires sur la méthode run() directement.

Documenter le schéma d'entrée. Si vous n'utilisez pas Pydantic, documentez les paramètres attendus dans la docstring de la méthode run() ou dans la description du skill.

Limiter les effets de bord. Un skill qui modifie des fichiers, envoie des emails ou appelle des API coûteuses doit exposer ce comportement clairement dans sa description pour que l'agent l'utilise à bon escient.

---

Conclusion

Le système de skills OpenClaw est conçu pour être à la fois simple à démarrer et extensible à grande échelle. Les skills natifs couvrent les cas d'usage courants ; la création de skills personnalisés suit une structure claire et prévisible. La clé du succès réside dans la qualité des descriptions et dans le principe "un skill, une responsabilité". Pour aller plus loin, consultez Installer OpenClaw pour configurer votre environnement, Exemples de skills OpenClaw pour le code minimal de chaque cas d'usage, Brave Search et OpenClaw : tutoriel du skill web pour un cas concret de recherche web, OpenClaw API skills : connecter une API externe pour un tutoriel orienté intégration, ou Automatisation SEO avec OpenClaw pour un cas d'usage complet.