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

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

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)

É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

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

...

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"]

    }

  ]

}

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

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/

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/

Capturer les temps

Enregistrez les temps dans timing.json :

{

  "total_tokens": 84852,

  "duration_ms": 23332,

  "total_duration_seconds": 23.3

}

É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"

    }

  ]

}

É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"

    }

  ]

}

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

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=$!

Pour les itérations suivantes :

--previous-workspace api-tester-workspace/iteration-1

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

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"

}

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

É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

  }

]

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

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

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".

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.

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

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.

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.

Regrouper les scripts Apidog

api-tester/

├── SKILL.md

└── scripts/

    ├── run-apidog-tests.py

    └── generate-report.py

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>

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).