DEV Community

Cover image for Créer Automatiquement des Compétences Claude Code avec Skill Creator
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Créer Automatiquement des Compétences Claude Code avec Skill Creator

#ai #llm #automation #productivity

En bref

Les compétences de code Claude sont des capacités personnalisées qui étendent les fonctionnalités de Claude pour des flux de travail spécifiques. Le système de création de compétences (Skill Creator) automatise la création de compétences grâce à un processus structuré : définissez le but de votre compétence, rédigez le fichier SKILL.md, créez des cas de test, exécutez des évaluations avec des mesures quantitatives et améliorez itérativement en fonction des retours.

Essayez Apidog dès aujourd'hui

Introduction

Vous utilisez Claude Code au quotidien et répétez souvent les mêmes séquences : mise en place de structures de projet, exécution de commandes de test, formatage de sorties. À chaque fois, il faut tout réexpliquer. Que faire pour automatiser ces workflows récurrents ? Les compétences de code Claude permettent de capturer ces procédures et de les rendre réutilisables. Skill Creator vous guide dans un processus automatisé et reproductible.

Ce guide vous détaille la création d'une compétence, son évaluation et l’optimisation pour un déclenchement fiable. Des exemples concrets issus du référentiel officiel d'Anthropic sont inclus.

💡 Si vous créez des compétences liées aux API, Apidog s'intègre naturellement. Testez vos endpoints, validez les réponses et générez la documentation dans un même flux.

Que sont les compétences de code Claude ?

Les compétences de code Claude sont des ensembles d'instructions spécialisées qui étendent les capacités de Claude à des domaines ou des workflows spécifiques. Considérez-les comme des plugins personnalisés au format markdown.

L'architecture du système de compétences

Le chargement suit trois niveaux :

  1. Métadonnées (~100 mots) : nom, description — toujours en contexte.
  2. Corps du SKILL.md (<500 lignes) : instructions principales, chargées à l’activation.
  3. Ressources regroupées (illimité) : scripts, références, assets chargés à la demande. 
skill-name/
├── SKILL.md (requis)
│   ├── YAML frontmatter (nom, description)
│   └── Instructions Markdown
└── Bundled Resources (facultatif)
    ├── scripts/    - Code exécutable pour tâches répétitives
    ├── references/ - Documentation à la demande
    └── assets/     - Modèles, icônes, polices
Enter fullscreen mode Exit fullscreen mode

Quand les compétences se déclenchent

Les compétences apparaissent dans available_skills avec leur nom et description. Claude décide d'en charger une selon la description.

Note: Les compétences ne se déclenchent que pour les tâches hors du scope natif de Claude. Les requêtes triviales ("lire ce fichier") n’activeront pas la compétence. Les workflows complexes et multi-étapes déclenchent de façon fiable si la description correspond.

Exemples concrets tirés du référentiel d'Anthropic

Compétence Objectif Caractéristiques clés
skill-creator Créer de nouvelles compétences Génération de cas de test, évaluation comparative, optimisation de description
mcp-builder Construire des serveurs MCP Modèles Python/Node, cadre d’évaluation, best practices
docx Générer des documents Word Scripts python-docx, système de templates, guide de style
pdf Extraire et manipuler des PDF Gestion de formulaires, extraction de texte, docs de référence
frontend-design Construire des interfaces web Bibliothèque de composants, motifs Tailwind, accessibilité

Le flux de travail de création de compétences

Le processus suit une boucle systématique :

  1. Capturer l'intention — Définir ce que doit accomplir la compétence
  2. Rédiger un brouillon — Écrire SKILL.md
  3. Créer des cas de test — Définir des invites réalistes
  4. Exécuter des évaluations — Tester avec/sans la compétence
  5. Examiner les résultats — Feedback qualitatif + métriques quantitatives
  6. Itérer — Améliorer selon résultats
  7. Optimiser la description — Précision du déclenchement
  8. Packager — Distribuer en .skill

Détail de chaque étape ci-dessous.

Étape 1 : Capturer l'intention

Clarifiez le but de la compétence. Si vous standardisez un workflow existant, extrayez un modèle de vos discussions précédentes.

Posez-vous :

  1. Quel résultat concret ?
  2. Quand déclencher ? (expressions, contextes)
  3. Quel format de sortie ? (code, rapport, fichiers)
  4. Faut-il des cas de test ? (tests objectifs → oui ; sorties subjectives → pas obligatoire)

Exemple : compétence de test d’API 

Intention : Aider les devs à tester systématiquement les API REST
Déclenchement : Quand l’utilisateur mentionne "test d’API", endpoints, REST, GraphQL, validation de réponses
Sortie : Rapport de test avec statuts, commandes curl, comparaisons de réponse
Cas de test : Oui (sorties objectivement vérifiables)
Enter fullscreen mode Exit fullscreen mode

Étape 2 : Rédiger le fichier SKILL.md

Fichier central contenant métadonnées YAML + instructions.

Structure type 

---
name: api-tester
description: Comment tester systématiquement les API REST. À utiliser lorsque les utilisateurs mentionnent les tests d'API, les points de terminaison, REST, GraphQL, ou veulent valider les réponses d'API. Assurez-vous de suggérer cette compétence chaque fois que des tests sont impliqués.
compatibility: Nécessite curl ou des outils client HTTP
---

# Compétence de test d'API

## Flux de travail principal

1. **Comprendre le point de terminaison** – Lire la spec ou demander le schéma
2. **Concevoir les cas de test** – Nominaux, limites, erreurs
3. **Exécuter les tests** – Utiliser curl ou [Apidog](https://apidog.com/?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation)
4. **Valider les réponses** – Codes, headers, structure
5. **Rapporter les résultats** – Résumés réussite/échec avec preuves

## Modèle de cas de test

- Auth valide + payload correct
- Auth valide + champs requis manquants
- Auth invalide (401 attendu)
- Limitation de débit
- Temps de réponse sous charge

## Format de sortie
Enter fullscreen mode Exit fullscreen mode

Rapport de test d'API

Résumé

  • Tests exécutés : X
  • Réussis : Y
  • Échoués : Z

Tests échoués

Nom du test

Attendu : 200 OK
Réel : 400 Bad Request
Réponse : {...}

Recommandations

...

Enter fullscreen mode Exit fullscreen mode

Bonnes pratiques

  • Progressivité : SKILL.md < 500 lignes ; références détaillées dans des fichiers séparés.
  • Expliciter le pourquoi : expliquez la raison des règles.
  • Forme impérative : "Toujours valider le code de statut" (pas "Vous devriez…").
  • Inclure des exemples : entrée/sortie attendue.

Étape 3 : Créer des cas de test

Redigez 2-3 invites réalistes, proches de l’usage réel. Stockez-les dans evals/evals.json :

{
  "skill_name": "api-tester",
  "evals": [
    {
      "id": 1,
      "prompt": "Test the /users endpoint on api.example.com - it needs a Bearer token and returns a list of users with id, name, email fields",
      "expected_output": "Test report with at least 5 test cases including auth failure, success, and pagination tests",
      "files": []
    },
    {
      "id": 2,
      "prompt": "I need to verify our new POST /orders endpoint handles invalid quantities correctly",
      "expected_output": "Test cases that send negative, zero, and non-numeric quantities with appropriate error responses",
      "files": ["openapi.yaml"]
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Critères d'une bonne invite

  • URL spécifique
  • Contexte concret
  • Comportement attendu
  • Partagez les scénarios avec l’utilisateur avant exécution.

Étape 4 : Exécuter les évaluations

Testez chaque cas de test deux fois : avec et sans la compétence.

Structure d'espace de travail 

api-tester-workspace/
├── iteration-1/
│   ├── eval-0-auth-failure/
│   │   ├── with_skill/
│   │   │   ├── outputs/
│   │   │   └── timing.json
│   │   ├── without_skill/
│   │   │   ├── outputs/
│   │   │   └── timing.json
│   │   └── eval_metadata.json
│   ├── eval-1-pagination/
│   │   └── ...
│   ├── benchmark.json
│   └── benchmark.md
├── iteration-2/
└── feedback.json
Enter fullscreen mode Exit fullscreen mode

Exécution parallèle

Pour chaque cas de test :

Avec compétence :

Execute this task:
- Skill path: /path/to/api-tester
- Task: Test the /users endpoint on api.example.com
- Input files: none
- Save outputs to: api-tester-workspace/iteration-1/eval-0/with_skill/outputs/
Enter fullscreen mode Exit fullscreen mode

Référence :

Execute this task:
- Skill path: (none)
- Task: Test the /users endpoint on api.example.com
- Input files: none
- Save outputs to: api-tester-workspace/iteration-1/eval-0/without_skill/outputs/
Enter fullscreen mode Exit fullscreen mode

Capturer les temps

Enregistrez les temps dans timing.json :

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}
Enter fullscreen mode Exit fullscreen mode

Étape 5 : Rédiger les assertions

Pendant les exécutions, écrivez des assertions quantitatives dans eval_metadata.json et evals/evals.json :

{
  "assertions": [
    {
      "name": "includes_auth_failure_test",
      "description": "Le rapport de test inclut au moins un cas de test d'échec d'authentification",
      "type": "contains",
      "value": "401"
    },
    {
      "name": "includes_success_test",
      "description": "Le rapport de test inclut au moins un test de requête réussie",
      "type": "contains",
      "value": "200"
    },
    {
      "name": "includes_curl_commands",
      "description": "Chaque cas de test inclut des commandes curl exécutables",
      "type": "regex",
      "value": "curl -"
    },
    {
      "name": "includes_response_validation",
      "description": "Le rapport valide la structure de la réponse par rapport au schéma",
      "type": "contains",
      "value": "schema"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Étape 6 : Noter et agréger

Après exécution :

Notation

Générez un sous-agent évaluateur qui lit agents/grader.md et note les assertions. Résultats dans grading.json :

{
  "eval_id": 0,
  "grading": [
    {
      "text": "includes_auth_failure_test",
      "passed": true,
      "evidence": "Found 401 status code in test case 3"
    },
    {
      "text": "includes_curl_commands",
      "passed": true,
      "evidence": "Found 'curl -X POST' in test case 1"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Les champs doivent être exactement text, passed, evidence.

Agrégation des benchmarks

Depuis skill-creator :

python -m scripts.aggregate_benchmark api-tester-workspace/iteration-1 --skill-name api-tester
Enter fullscreen mode Exit fullscreen mode

Cela produit benchmark.json et benchmark.md avec taux de réussite, temps, tokens, moyennes et écarts types.

Analyse

Lisez les benchmarks pour :

  • Détecter les assertions non discriminantes
  • Identifier les évaluations à forte variance
  • Évaluer les compromis qualité/temps

Consultez agents/analyzer.md pour des analyses approfondies.

Étape 7 : Lancer le visualiseur d’évaluations

Affichez les sorties qualitatives et quantitatives dans une interface navigateur.

Générer le visualiseur 

nohup python /path/to/skill-creator/eval-viewer/generate_review.py \
  api-tester-workspace/iteration-1 \
  --skill-name "api-tester" \
  --benchmark api-tester-workspace/iteration-1/benchmark.json \
  > /dev/null 2>&1 &
VIEWER_PID=$!
Enter fullscreen mode Exit fullscreen mode

Pour les itérations suivantes :

--previous-workspace api-tester-workspace/iteration-1
Enter fullscreen mode Exit fullscreen mode

Rendu utilisateur

  • Outputs : invite, sortie, sortie précédente, notes, commentaires
  • Benchmark : taux de réussite, temps, jetons, analyses

En environnement sans GUI :

--static /path/to/output/review.html
Enter fullscreen mode Exit fullscreen mode

Les commentaires sont téléchargés en feedback.json après validation utilisateur.

Étape 8 : Lire les commentaires et itérer

À la fin de la revue, lisez feedback.json :

{
  "reviews": [
    {
      "run_id": "eval-0-with_skill",
      "feedback": "the chart is missing axis labels",
      "timestamp": "2026-03-23T10:30:00Z"
    }
  ],
  "status": "complete"
}
Enter fullscreen mode Exit fullscreen mode

Focalisez-vous sur les cas ayant reçu des commentaires.

Points clés d'amélioration

  • Généraliser : ne pas suradapter à un test précis
  • Succinct : supprimez l’inutile
  • Expliquer le pourquoi : argumentez chaque exigence
  • Regrouper les scripts répétés : mutualiser dans /scripts

Boucle d’itération

  1. Améliorez la compétence
  2. Relancez tous les tests dans le dossier iteration-N+1/
  3. Relancez le visualiseur avec --previous-workspace
  4. Attendez la revue
  5. Reprenez les retours, recommencez

Arrêtez quand :

  • L’utilisateur est satisfait
  • Tous les commentaires sont vides
  • Plus de progrès significatifs

Arrêtez le visualiseur :

kill $VIEWER_PID 2>/dev/null
Enter fullscreen mode Exit fullscreen mode

Étape 9 : Optimiser la description de la compétence

Le champ description dans SKILL.md détermine le déclenchement.

Générer des requêtes d’évaluation de déclenchement

Créez 20 requêtes : 8-10 positives (doivent déclencher), 8-10 négatives (ne doivent pas).

[
  {
    "query": "ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think",
    "should_trigger": true
  },
  {
    "query": "I need to create a pivot table from this CSV and email it to the team",
    "should_trigger": false
  }
]
Enter fullscreen mode Exit fullscreen mode

Relecture utilisateur

  • Lisez assets/eval_review.html
  • Remplacez les placeholders
  • Ouvrez le fichier HTML, laissez l’utilisateur éditer et exporter en eval_set.json

Boucle d’optimisation 

python -m scripts.run_loop \
  --eval-set /path/to/trigger-eval.json \
  --skill-path /path/to/api-tester \
  --model claude-sonnet-4-6 \
  --max-iterations 5 \
  --verbose
Enter fullscreen mode Exit fullscreen mode

Le script :

  • Sépare en train/test
  • Évalue, propose des améliorations, réévalue
  • Sélectionne la best_description selon score test

Mettez à jour SKILL.md avec la nouvelle description et montrez l’amélioration à l’utilisateur.

Étape 10 : Packager et distribuer

Une fois finalisé :

python -m scripts.package_skill /path/to/api-tester
Enter fullscreen mode Exit fullscreen mode

Cela génère un fichier .skill à installer.

Installation

Placez le .skill dans le répertoire de compétences de l’utilisateur ou utilisez la commande d’installation de Claude Code.

Erreurs courantes lors de la création de compétences

Erreur 1 : Description vague 

# Mauvais
description: Une compétence pour travailler avec les API
# Bon
description: Comment tester systématiquement les API REST. À utiliser lorsque les utilisateurs mentionnent les tests d'API, les points de terminaison, REST, GraphQL, ou veulent valider les réponses d'API. Assurez-vous de suggérer cette compétence chaque fois que des tests sont impliqués, même s'ils ne mentionnent pas explicitement "tests".
Enter fullscreen mode Exit fullscreen mode

Erreur 2 : Instructions trop restrictives 

# Mauvais
TOUJOURS utiliser ce format exact. NE JAMAIS s'en écarter. DOIT inclure ces sections.
# Bon
Utilisez ce format car il garantit que les parties prenantes peuvent rapidement trouver les informations dont elles ont besoin. Si votre public a des besoins différents, adaptez la structure en conséquence.
Enter fullscreen mode Exit fullscreen mode

Erreur 3 : Oublier les cas de test

Même pour les compétences subjectives, exécutez 2-3 exemples pour vérifier la qualité.

Erreur 4 : Ignorer les temps

Capturez les durées et optimisez l’efficacité.

Erreur 5 : Ne pas regrouper les scripts répétés

Regroupez les scripts d’aide dans /scripts pour éviter la duplication.

Exemples concrets de compétences

Compétence MCP Builder

  • Objectif : construction de serveurs MCP (Model Context Protocol)
  • Caractéristiques : modèles Python/Node.js, cadre d’évaluation, bonnes pratiques
  • Structure : 
mcp-builder/
├── SKILL.md
├── reference/
│   ├── mcp_best_practices.md
│   ├── python_mcp_server.md
│   └── node_mcp_server.md
└── evaluation/
    └── evaluation.md
Enter fullscreen mode Exit fullscreen mode

Compétence Docx

  • Génération programmatique de documents Word
  • Scripts python-docx, système de modèles, guide de style

Workflow :

  1. Comprendre les exigences
  2. Sélectionner/créer un template
  3. Générer via python-docx
  4. Valider la structure de sortie

Compétence front-end design

  • Construction d’interfaces web modernes
  • Bibliothèque de composants, motifs Tailwind CSS, vérification d’accessibilité
  • Documentation progressive : workflow principal dans SKILL.md, composants dans /references

Tester votre compétence avec Apidog

Pour les compétences API, Apidog s'intègre nativement.

Apidog Integration

Exemple : intégration de la compétence de test d’API 

## Exécution des tests d'API

Utilisez Apidog pour des tests systématiques :

1. Importer la spécification OpenAPI dans Apidog
2. Générer des cas de test à partir de la spec
3. Exécuter les tests et exporter les résultats JSON
4. Valider les réponses selon les schémas attendus

Pour les assertions personnalisées, utilisez la fonction de script d'Apidog.
Enter fullscreen mode Exit fullscreen mode

Regrouper les scripts Apidog 

api-tester/
├── SKILL.md
└── scripts/
    ├── run-apidog-tests.py
    └── generate-report.py
Enter fullscreen mode Exit fullscreen mode

Centralisez les scripts pour éviter la redondance à chaque invocation.

Conclusion

Les compétences de code Claude permettent d’étendre Claude à vos workflows. Skill Creator offre un processus systématique :

  1. Capturer l'intention — Définir la finalité
  2. Rédiger SKILL.md — Instructions et exemples clairs
  3. Cas de test — Invites réalistes
  4. Évaluation parallèle — Avec/sans compétence
  5. Revue des résultats — Qualitatif et quantitatif
  6. Itération — Améliorations continues
  7. Optimisation de la description — Précision du déclenchement
  8. Packaging — Distribution en .skill

FAQ

Combien de temps pour créer une compétence ?

Compétence simple : 15–30 min. Complexe (plusieurs fichiers/scripts) : 2–3 h, itérations incluses.

Dois-je écrire des cas de test pour chaque compétence ?

Non. Faites-le pour les sorties objectivement vérifiables (code, transformation de fichiers, extraction de données). Pour les sorties subjectives, privilégiez l’évaluation qualitative.

Que faire si ma compétence ne se déclenche pas de façon fiable ?

Optimisez la description : ajoutez des contextes précis, rendez-la explicite quant au déclenchement. Utilisez la boucle d’optimisation de description avec 20 requêtes d’évaluation.

Comment partager une compétence avec mon équipe ?

Packagez avec :

python -m scripts.package_skill <chemin>
Enter fullscreen mode Exit fullscreen mode

Distribuez le .skill à placer dans le dossier de compétences.

Les compétences peuvent-elles appeler des API externes ?

Oui. Regroupez les scripts d’appel API dans /scripts. Stockez les clés API dans les variables d’environnement.

Limite de taille de fichier pour les compétences ?

Pas de limite stricte, mais gardez SKILL.md < 500 lignes. Références détaillées et scripts séparés.

Comment mettre à jour une compétence existante ?

Copiez la compétence à un emplacement inscriptible, modifiez, puis repackagez. Gardez le nom d'origine (pas de suffixe version sauf variante distincte).

Top comments (0)