Construire un Skill Claude qui utilise openlegi

Ce guide explique comment créer un Skill au format Agent Skills pour exploiter openlegi. Un Skill est l'unité élémentaire d'extension de Claude : un dossier contenant un fichier SKILL.md et, en option, des scripts, des références et des assets. Là où un plugin regroupe plusieurs capacités cohérentes pour une équipe, un Skill encapsule une compétence atomique distribuable indépendamment.

Skill ou plugin : quand choisir quoi

Un plugin Claude bundle plusieurs skills, des agents planifiés, des hooks et une configuration MCP partagée via un fichier CLAUDE.md. Un Skill au format Agent Skills est plus léger : un dossier autonome qui se charge dynamiquement quand sa description correspond au contexte. (Anthropic Engineering)

Trois critères de choix.

Granularité : un Skill couvre une compétence (vérifier une citation d'article, formater une note de jurisprudence). Un plugin couvre une pratique (droit du travail, des affaires, contentieux spécifiques, etc).

Portabilité : depuis octobre 2025, Agent Skills est un standard ouvert publié sur agentskills.io. Il a été adopté par Claude Code, OpenAI Codex CLI, Gemini CLI, Cursor et GitHub Copilot. (agentskills.io) Un Skill bien construit fonctionne sur plusieurs assistants. Un plugin reste spécifique à l'écosystème Claude (Cowork et Claude Code).

Surface de distribution : un Skill peut être uploadé sur claude.ai dans les settings, via l'API Claude, ou ajouté dans Claude Code via le système de fichiers. (Claude Platform Docs) Les trois surfaces ne synchronisent pas entre elles.

À noter. Pour publier sur claude.ai uniquement, un Skill suffit. Pour packager une suite complète (veille hebdo + recherche + rédaction de notes) avec un profil de pratique partagé, un plugin est plus adapté.

Le mécanisme de progressive disclosure

L'architecture Skills repose sur un chargement en trois niveaux qui contrôle l'usage de contexte. (Anthropic Engineering)

Au démarrage, Claude pré-charge uniquement les métadonnées de tous les skills installés. Il décide ensuite de consulter ou non un skill en se basant sur sa description. Si le skill est déclenché, son corps est injecté dans le contexte. Les fichiers bundlés ne sont lus que si la procédure les référence explicitement. (Anthropic Engineering)

Cette mécanique a une conséquence pratique : la qualité de la description détermine la qualité du déclenchement. Anthropic recommande de garder ce champ informatif et explicite, en mentionnant à la fois ce que fait le skill et dans quels contextes il doit s'activer. (Anthropic Skills repo)

Raccourci recommandé : faire générer le skill par le skill-creator

Avant de rédiger un skill manuellement, la voie la plus efficace est de déléguer le travail au skill-creator, un méta-skill publié par Anthropic dont la fonction est précisément de créer d'autres skills. (anthropics/skills, skill-creator)

L'astuce qui rend cette approche particulièrement adaptée à openlegi : quand le skill-creator s'exécute dans une session Claude où le connecteur MCP openlegi est branché, il découvre automatiquement la liste des outils disponibles (rechercher_code, rechercher_jurisprudence_judiciaire, recherche_journal_officiel, etc.) ainsi que leurs descriptions détaillées et leurs paramètres. Il s'appuie sur ces métadonnées pour construire la procédure du skill sans qu'on ait à les lui réécrire. Les descriptions d'outils MCP openlegi sont riches et autoportantes, ce qui rend la génération du skill quasi-immédiate.

Installation du skill-creator

/plugin marketplace add anthropic-agent-skills@https://github.com/anthropics/skills
/plugin install example-skills@anthropic-agent-skills

Le skill-creator est inclus dans le bundle example-skills. (anthropics/skills)

Prompt type à copier-coller

Lancez une conversation Claude (Cowork, Code ou claude.ai si le skill y est installé) et envoyez :

Crée un skill openlegi pour [décris ta tâche en une phrase].

Contexte technique :
- Les outils MCP openlegi sont déjà disponibles dans cette session.
  Inspecte-les via tool_search ou liste-les pour t'imprégner de leurs
  descriptions et de leurs paramètres avant de drafter le skill.
- Documentation openlegi optimisée pour LLM :
  https://www.openlegi.fr/llms-full.txt
- Garde-fous obligatoires : citation systématique du lien article_lc,
  pas de paraphrase de texte légal, signalement explicite des troncatures.

Procède selon ta méthode habituelle : cold-start interview, draft du
SKILL.md, propositions de prompts de test, puis itération.

Trois éléments font la différence dans ce prompt.

La référence à tool_search force le skill-creator à interroger l'environnement avant d'écrire le skill, plutôt que d'inventer des appels d'outils qui n'existent pas. Les descriptions retournées contiennent les paramètres exacts (code_name, champ, panorama, etc.) qu'il reproduira fidèlement.

Le lien vers llms-full.txt donne au skill-creator une vue exhaustive de la doc openlegi formatée pour LLM. (openlegi, accueil) Il y trouve les conventions de nommage, les limitations connues et les exemples d'usage.

La mention explicite des garde-fous juridiques garantit que le skill généré intègre les règles openlegi sur la vérification, la non-paraphrase et la troncature, plutôt qu'un boilerplate générique.

Ce qui sort de la procédure

Le skill-creator suit une boucle structurée : capture d'intention via questions à l'utilisateur, rédaction du SKILL.md, génération de prompts de test, exécution des tests (en parallèle via subagents si disponibles, en série sinon), évaluation qualitative, itération. (anthropics/skills, skill-creator)

Le livrable final est un dossier complet (SKILL.md + éventuels scripts/, references/, assets/) que le skill-creator peut packager en fichier .skill prêt à uploader. (anthropics/skills)

Limites à connaître

Cette approche fonctionne mieux pour les skills à output objectivement vérifiable (recherche, extraction, vérification de citation). Pour les skills à output subjectif (style rédactionnel, formatage de note), le skill-creator recommande lui-même de privilégier l'évaluation qualitative manuelle. (anthropics/skills, skill-creator)

Une revue humaine du SKILL.md généré reste indispensable avant publication. Le skill-creator peut sous-estimer certaines spécificités du droit français (renumérotations, droits transitoires, droit européen directement applicable) si l'utilisateur ne les a pas mentionnées pendant l'interview. Les sections suivantes de ce guide servent alors de checklist de revue.

Astuce avancée. Le skill-creator inclut une boucle d'optimisation automatique de la description (voir scripts/run_loop.py dans le repo). Elle exécute les prompts de test plusieurs fois sur des variantes de description pour mesurer le taux de déclenchement et sélectionner la meilleure. C'est l'étape qui transforme un skill fonctionnel en skill robuste. (anthropics/skills, skill-creator)

La suite de ce guide documente la création manuelle, soit comme alternative pour les utilisateurs qui préfèrent garder le contrôle, soit comme référence pour réviser un skill produit par le skill-creator.

Prérequis

Un Skill ne déclare pas lui-même de connecteurs MCP. Il suppose que le serveur openlegi est déjà branché sur l'environnement Claude où il s'exécute.

Anatomie d'un Skill

Structure minimale :

mon-skill/
├── SKILL.md           # obligatoire
├── scripts/           # optionnel
├── references/        # optionnel
└── assets/            # optionnel

Le seul fichier requis est SKILL.md. Tout le reste est optionnel et n'est chargé qu'à la demande. (anthropics/skills)

Étape 1 : la frontmatter YAML

Tout skill commence par un bloc YAML entre deux lignes ---. Deux champs sont requis : name et description. (Claude Platform Docs)

---
name: verification-article-fr
description: Vérifie qu'une citation d'article de code juridique français est exacte en comparant le texte cité au texte officiel récupéré via openlegi. Utiliser ce skill chaque fois que l'utilisateur cite un article du Code civil, Code du travail, Code de commerce, Code pénal ou tout autre code français, ou quand l'utilisateur demande de vérifier une référence légale, contrôler un numéro d'article, valider une citation juridique ou détecter des hallucinations sur du droit français.
---

Quelques règles tirées de la pratique d'Anthropic.

Le nom du skill doit correspondre au nom du dossier qui le contient. (anthropics/skills)

La description doit dire à la fois ce que fait le skill ET dans quels contextes le déclencher. Anthropic note que Claude a tendance à sous-déclencher les skills, ce qui justifie de rendre la description légèrement "pushy" en multipliant les formulations de déclenchement possibles. (anthropics/skills, skill-creator)

La description doit rester sous 1024 caractères, car elle est chargée en permanence dans le contexte de Claude. (Anthropic, claude-for-legal)

Étape 2 : le corps du skill

Après la frontmatter, le markdown libre contient la procédure que Claude suivra quand le skill se déclenchera. La forme impérative est recommandée. (anthropics/skills, skill-creator)

Exemple complet pour verification-article-fr :

---
name: verification-article-fr
description: [...comme ci-dessus...]
---

# Vérification de citation d'article (droit français)

Quand un utilisateur cite un article d'un code juridique français, ce skill
récupère le texte officiel via openlegi et compare avec ce qui a été cité,
en signalant explicitement toute divergence.

## Procédure

1. **Identifier la référence à vérifier** :
   - Code source (Code civil, Code du travail, etc.)
   - Numéro d'article (L1234-5, R625-1, etc.)
   - Texte cité (verbatim ou paraphrase)

2. **Appeler openlegi** via l'outil `rechercher_code` :
   ```json
   {
     "search": "<numéro d'article>",
     "code_name": "<nom du code>",
     "champ": "NUM_ARTICLE",
     "max_results": 1
   }
   ```

3. **Comparer la version officielle avec la citation** :
   - Reproduire le texte officiel retourné, sans paraphrase
   - Diffuser le texte cité par l'utilisateur
   - Identifier les divergences mot à mot

4. **Produire une note de vérification** :

   Si la citation est exacte :
   > ✅ Citation conforme au texte officiel.
   > Source : [lien article_lc Légifrance]

   Si la citation diverge :
   > ⚠️ Divergences détectées entre la citation et le texte officiel.
   >
   > **Texte cité** : "[citation utilisateur]"
   > **Texte officiel** : "[texte openlegi]"
   > **Divergences** : [liste précise]
   >
   > Source : [lien article_lc Légifrance]

## Cas particuliers

### Article potentiellement renuméroté

Si la citation porte sur le Code civil pré-2016, le Code du travail pré-2008
ou le Code de commerce, vérifier que le numéro retourné par openlegi
correspond bien au texte attendu, et non à un nouvel article ayant pris
le même numéro après réforme. Voir `references/renumerotations.md`
pour la liste des codes concernés.

### Texte tronqué

Si la réponse openlegi se termine par `...` ou `…`, signaler la troncature
sans tenter de compléter. Inviter l'utilisateur à ouvrir le lien Légifrance
pour le texte intégral.

### Article non trouvé

Si openlegi retourne `SEARCH_NO_RESULTS`, ne pas inventer le texte. Indiquer
que l'article n'a pas été trouvé dans la base consolidée et proposer des
alternatives (article voisin, ancienne numérotation).

## Garde-fous absolus

- Ne jamais paraphraser le texte officiel : reproduire à l'identique.
- Toujours afficher le lien `article_lc` Légifrance retourné par openlegi.
- Si l'utilisateur conteste la version openlegi, l'inviter à vérifier
  directement sur legifrance.gouv.fr. openlegi est une interface, pas
  la source officielle.

Anthropic recommande de garder le corps du SKILL.md sous 500 lignes. Au-delà, il est préférable de découper en fichiers de référence dans references/ que Claude lira à la demande. (anthropics/skills, skill-creator)

Étape 3 : ajouter des scripts déterministes

Pour les opérations répétitives qui ne nécessitent pas de raisonnement (parsing, diff, génération de fichier), un script vaut mieux qu'une instruction en langage naturel. Le code est plus rapide et plus reproductible. (Anthropic Engineering)

Exemple : scripts/diff_citation.py

#!/usr/bin/env python3
"""
Compare un texte cité avec le texte officiel openlegi.
Retourne une liste de divergences mot à mot.

Usage:
    python diff_citation.py --cite "texte cité" --official "texte officiel"
"""
import argparse
import difflib
import json
import sys


def diff_texts(cite: str, official: str) -> dict:
    """Produit un diff structuré entre deux textes."""
    cite_words = cite.split()
    official_words = official.split()

    matcher = difflib.SequenceMatcher(None, cite_words, official_words)
    divergences = []

    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
        if tag == "equal":
            continue
        divergences.append({
            "type": tag,
            "cited": " ".join(cite_words[i1:i2]) or None,
            "official": " ".join(official_words[j1:j2]) or None,
        })

    return {
        "match_ratio": matcher.ratio(),
        "is_exact_match": matcher.ratio() == 1.0,
        "divergences": divergences,
    }


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--cite", required=True)
    parser.add_argument("--official", required=True)
    args = parser.parse_args()

    result = diff_texts(args.cite, args.official)
    json.dump(result, sys.stdout, ensure_ascii=False, indent=2)


if __name__ == "__main__":
    main()

Dans le corps du skill, on référence le script :

4. Si le texte cité dépasse 50 mots, utiliser le script
   `scripts/diff_citation.py` pour produire un diff structuré
   plutôt que de comparer mot à mot manuellement.

Le script est exécuté par Claude via le tool bash (ou équivalent), sans être chargé en contexte. C'est ce qu'Anthropic appelle l'usage du code comme outil exécutable plutôt que comme documentation. (Anthropic Engineering)

Étape 4 : ajouter des références

Le dossier references/ contient des fichiers markdown qui ne sont pas chargés par défaut mais référencés par le corps du SKILL.md. C'est utile pour les contenus volumineux (listes, taxonomies, jurisprudence de référence). (anthropics/skills)

Exemple : references/renumerotations.md

# Codes français renumérotés

Liste des réformes connues qui ont réaffecté d'anciens numéros d'articles
à de nouveaux articles. À consulter quand une citation porte sur un de
ces codes et précède la date de réforme.

## Code civil

**Ordonnance n° 2016-131 du 10 février 2016** : refonte du droit
des contrats et des obligations.

Exemples de réaffectations :
- Ancien Art. 1382 (responsabilité délictuelle) devenu Art. 1240.
- Le numéro 1382 est aujourd'hui occupé par un article sur
  les présomptions judiciaires.

## Code du travail

**Recodification 2008** : changement complet de la numérotation.
- Articles L1132-1 et suivants, R625-1 et suivants : nouveaux numéros
  depuis 2008. Les anciens numéros (L122-45 etc.) ne sont plus en vigueur.

## Code de commerce

Plusieurs ordonnances successives ont modifié la numérotation.
Vérifier systématiquement la date de la citation et la date de version
retournée par openlegi.

Pour les références volumineuses (>300 lignes), Anthropic recommande d'inclure une table des matières au début du fichier pour permettre à Claude de naviguer efficacement. (anthropics/skills, skill-creator)

Étape 5 : ajouter des assets

Le dossier assets/ contient les fichiers utilisés dans la sortie produite par le skill : templates, polices, icônes, modèles de documents. Contrairement aux références, ils ne sont pas lus pour informer Claude mais utilisés directement dans le résultat final. (anthropics/skills)

Pour le skill verification-article-fr, on pourrait fournir un template de note de vérification :

assets/
└── template-note-verification.md

# Note de vérification

**Référence vérifiée** : {{reference}}
**Date de vérification** : {{date}}
**Source consultée** : openlegi (interface Légifrance)
**Lien officiel** : {{article_lc}}

## Résultat

{{resultat_verification}}

## Texte officiel

{{texte_officiel}}

## Texte cité

{{texte_cite}}

## Divergences détectées

{{divergences}}

---

*Cette note est un brouillon à valider. Pour tout usage professionnel,
ouvrir le lien officiel et vérifier le texte directement sur Légifrance.*

Étape 6 : optimiser la description

La description est le seul élément du skill qui détermine son déclenchement. Anthropic fournit dans son skill-creator un outil d'optimisation automatique de la description, qui exécute une boucle d'évaluation sur des prompts de test pour mesurer le taux de déclenchement et proposer des variantes. (anthropics/skills, skill-creator)

À défaut d'outillage, quelques règles empiriques.

Inclure les termes que l'utilisateur emploie réellement. Pour un skill juridique français, "article", "code", "vérifier", "citation", "référence", "hallucination" sont des signaux forts.

Énumérer plusieurs formulations équivalentes. "Vérifier une référence", "contrôler un numéro d'article", "valider une citation" sont trois formulations qui doivent toutes déclencher le skill.

Mentionner les types de documents source si pertinent. "Code civil, Code du travail, Code de commerce" donne plus de signaux qu'une formule générique comme "code juridique".

Éviter les descriptions vagues du type "ce skill aide à vérifier des trucs". Le signal de déclenchement doit être concret.

Étape 7 : tester le skill

Anthropic recommande de définir 2 à 3 prompts de test représentatifs avant publication. (anthropics/skills, skill-creator)

Pour verification-article-fr :

Test 1 : "L'article L1132-1 du Code du travail dispose que toute discrimination
est interdite. Peux-tu vérifier cette citation ?"
Attendu : déclenchement du skill, appel openlegi, restitution du texte officiel
avec liste des 25 critères de discrimination effectivement listés dans
l'article (non tronqués).

Test 2 : "Selon l'article 1382 du Code civil, tout fait quelconque de l'homme
qui cause à autrui un dommage oblige celui par la faute duquel il est arrivé
à le réparer."
Attendu : déclenchement, détection de la renumérotation (devenu Art. 1240),
signalement explicite.

Test 3 : "Quelle est la différence entre droit civil et droit pénal ?"
Attendu : pas de déclenchement (la question ne cite aucun article).

L'objectif des tests négatifs (test 3) est de vérifier que le skill ne sur-déclenche pas sur des questions tangentielles.

Étape 8 : packager le skill

Le format de distribution est un fichier .skill qui est essentiellement le dossier compressé. Le repo anthropics/skills fournit un script package_skill.py pour cela. (anthropics/skills)

Manuellement, l'opération équivaut à :

cd parent-folder/
zip -r verification-article-fr.skill verification-article-fr/

Le fichier .skill peut alors être uploadé sur claude.ai (Settings > Capabilities > Skills), poussé via l'API Claude, ou placé dans le répertoire .claude/skills/ d'un projet Claude Code.

Étape 9 : distribuer sur les trois surfaces

Les Skills ne synchronisent pas automatiquement entre claude.ai, l'API et Claude Code. Il faut publier sur chaque surface séparément. (Claude Platform Docs)

claude.ai : upload du fichier .skill via les settings. Disponible immédiatement dans toutes les conversations de l'utilisateur.

API Claude : upload via l'endpoint Skills API. Le skill devient utilisable dans toute requête API qui le référence. Pour les déploiements multi-utilisateurs (chatbot, intégration interne), c'est le mode privilégié.

Claude Code : déposer le dossier dans .claude/skills/ du projet. Le skill devient disponible dans la session Claude Code de ce projet.

Conséquence pratique. Un Skill destiné à être utilisé largement (par exemple, le skill de vérification d'article décrit ici) doit être publié au moins sur claude.ai et l'API pour couvrir la majorité des cas d'usage en cabinet.

Adoption hors Claude

Le standard Agent Skills est ouvert. Au moment de la publication de ce guide, il est implémenté par Claude Code, OpenAI Codex CLI, Gemini CLI, GitHub Copilot et Cursor. (agentskills.io)

Un skill openlegi rédigé selon le format de base (frontmatter standard, markdown, scripts optionnels) fonctionne sans modification sur la plupart de ces outils. Les fonctionnalités avancées propres à Claude (context forking, par exemple) ne sont pas portables. (Agensi)

Cette portabilité a une implication stratégique pour openlegi : un skill bien conçu autour des outils MCP openlegi devient utilisable depuis n'importe quel assistant compatible MCP plus Agent Skills, ce qui élargit l'usage au-delà de l'écosystème Claude.

Garde-fous spécifiques aux skills juridiques

Anthropic insiste sur le fait que les skills sont des capacités exécutables qui peuvent invoquer des outils et exécuter du code. Un skill malveillant peut détourner ces capacités. (Claude Platform Docs)

Pour les skills juridiques, deux points de vigilance.

Auditer les scripts bundlés. Avant d'installer un skill provenant d'un tiers, lire le contenu des fichiers dans scripts/. Un skill qui télécharge des données externes sans rapport avec sa fonction déclarée doit être considéré comme suspect. (Claude Platform Docs)

Préserver le caractère d'aide à la décision. Tout skill qui produit du contenu juridique doit explicitement positionner sa sortie comme un brouillon à valider, jamais comme un avis. Cette règle reprend la position d'Anthropic sur claude-for-legal : chaque output est un brouillon pour revue d'avocat, pas un avis juridique, pas une conclusion légale. (Anthropic, claude-for-legal)

Avertissement openlegi. openlegi est une interface d'accès à Légifrance, pas un substitut. Tout skill construit sur openlegi doit prévoir un mécanisme de renvoi vers le texte officiel Légifrance via le lien article_lc. Cette règle est documentée dans les limitations connues d'openlegi. (openlegi, Limitations connues)

Exemple complet : repo de référence

Un squelette minimal d'un skill openlegi a la structure suivante :

verification-article-fr/
├── SKILL.md
├── scripts/
│   └── diff_citation.py
├── references/
│   └── renumerotations.md
└── assets/
    └── template-note-verification.md

Pour des exemples grandeur réelle, le repo anthropics/skills contient les skills de production qui alimentent Claude (docx, pdf, pptx, xlsx) ainsi qu'un skill-creator complet, sous licence Apache 2.0 pour les exemples communautaires et source-available pour les skills documents. (anthropics/skills)

Limites et points de vigilance

Le contenu des Skills n'est pas couvert par les arrangements Zero Data Retention. Les définitions de skills et les données d'exécution sont conservées selon la politique de rétention standard d'Anthropic. (Claude Platform Docs) Pour les cabinets soumis à des contraintes strictes de confidentialité, ce point doit être vérifié avant déploiement.

Les Skills ne se synchronisent pas entre claude.ai, l'API et Claude Code. Il faut maintenir la publication sur chaque surface. (Claude Platform Docs)

Claude tend à sous-déclencher les skills sur les tâches simples qu'il peut accomplir directement avec ses outils de base. (anthropics/skills, skill-creator) Un skill construit pour une opération triviale (lire un fichier, par exemple) ne se déclenchera pas, même si sa description matche. Les skills sont conçus pour des tâches multi-étapes ou spécialisées.

Aller plus loin