skill-creator

Créateur de Compétences

Une compétence pour créer de nouvelles compétences et les améliorer de manière itérative.

À un niveau élevé, le processus de création d'une compétence se déroule comme suit :

• Décidez ce que vous voulez que la compétence fasse et approximativement comment elle doit le faire.
• Rédigez un brouillon de la compétence.
• Créez quelques prompts de test et exécutez claude-avec-accès-à-la-compétence dessus.
• Aidez l'utilisateur à évaluer les résultats à la fois qualitativement et quantitativement.
  • Pendant que les exécutions se déroulent en arrière-plan, rédigez quelques évaluations quantitatives s'il n'y en a pas (s'il y en a déjà, vous pouvez les utiliser telles quelles ou les modifier si vous pensez que quelque chose doit changer). Expliquez-les ensuite à l'utilisateur (ou si elles existent déjà, expliquez celles qui existent).
  • Utilisez le script eval-viewer/generate_review.py pour montrer les résultats à l'utilisateur afin qu'il les examine, et laissez-le aussi consulter les métriques quantitatives.
• Réécrivez la compétence en fonction des retours de l'évaluation des résultats par l'utilisateur (et aussi s'il y a des défauts évidents qui apparaissent dans les benchmarks quantitatifs).
• Répétez jusqu'à satisfaction.
• Étendez l'ensemble de test et réessayez à plus grande échelle.

Votre travail lorsque vous utilisez cette compétence est de déterminer où se trouve l'utilisateur dans ce processus, puis d'intervenir et de l'aider à progresser à travers ces étapes. Par exemple, peut-être que l'utilisateur dit "Je veux créer une compétence pour X". Vous pouvez aider à préciser ce qu'il veut, rédiger un brouillon, écrire les cas de test, déterminer comment il veut évaluer, exécuter tous les prompts, et répéter.

D'un autre côté, peut-être qu'il a déjà un brouillon de la compétence. Dans ce cas, vous pouvez passer directement à la partie évaluation/itération de la boucle.

Bien sûr, vous devez toujours être flexible et si l'utilisateur dit "Je n'ai pas besoin d'exécuter plein d'évaluations, juste suis-moi", vous pouvez le faire à la place.

Ensuite, une fois la compétence terminée (mais encore une fois, l'ordre est flexible), vous pouvez aussi exécuter l'améliorateur de description de compétence, pour lequel nous avons un script séparé, afin d'optimiser le déclenchement de la compétence.

Cool ? Cool.

Communiquer avec l'utilisateur

Le créateur de compétences est susceptible d'être utilisé par des personnes ayant des niveaux de familiarité très variés avec le jargon informatique. Si vous n'avez pas entendu parler (et comment le pourriez-vous, c'est seulement très récent que ça a commencé), il y a une tendance maintenant où la puissance de Claude inspire des plombiers à ouvrir leurs terminaux, des parents et grands-parents à chercher "comment installer npm". D'un autre côté, la majorité des utilisateurs sont probablement assez compétents en informatique.

Alors, faites attention aux indices contextuels pour comprendre comment formuler votre communication ! Dans le cas par défaut, juste pour vous donner une idée :

• "évaluation" et "benchmark" sont limites, mais acceptables.
• Pour "JSON" et "assertion", vous devez voir des signes sérieux de l'utilisateur qu'il sait de quoi il s'agit avant de les utiliser sans explication.

Il est acceptable d'expliquer brièvement les termes en cas de doute, et n'hésitez pas à clarifier les termes avec une courte définition si vous n'êtes pas sûr que l'utilisateur les comprendra.

---

Créer une compétence

Capturer l'Intention

Commencez par comprendre l'intention de l'utilisateur. La conversation actuelle peut déjà contenir un workflow que l'utilisateur souhaite capturer (par exemple, il dit "transforme cela en compétence"). Si c'est le cas, extrayez d'abord les réponses de l'historique de la conversation — les outils utilisés, la séquence des étapes, les corrections apportées par l'utilisateur, les formats d'entrée/sortie observés. L'utilisateur devra peut-être combler les lacunes, et doit confirmer avant de passer à l'étape suivante.

1. Que doit permettre cette compétence à Claude de faire ?
2. Quand cette compétence doit-elle se déclencher ? (quelles phrases/contextes utilisateur)
3. Quel est le format de sortie attendu ?
4. Devons-nous configurer des cas de test pour vérifier que la compétence fonctionne ? Les compétences avec des sorties objectivement vérifiables (transformations de fichiers, extraction de données, génération de code, étapes de workflow fixes) bénéficient de cas de test. Les compétences avec des sorties subjectives (style d'écriture, art) n'en ont souvent pas besoin. Suggérez la valeur par défaut appropriée en fonction du type de compétence, mais laissez l'utilisateur décider.

Interview et Recherche

Posez des questions de manière proactive sur les cas limites, les formats d'entrée/sortie, les fichiers d'exemple, les critères de succès et les dépendances. Attendez de rédiger les prompts de test jusqu'à ce que cette partie soit bien définie.

Vérifiez les MCP disponibles - s'ils sont utiles pour la recherche (recherche de documentation, recherche de compétences similaires, consultation des meilleures pratiques), faites la recherche en parallèle via des sous-agents si disponibles, sinon en ligne. Arrivez préparé avec du contexte pour réduire la charge sur l'utilisateur.

Rédiger le SKILL.md

Basé sur l'interview de l'utilisateur, remplissez ces composants :

• name : Identifiant de la compétence
• description : Quand déclencher, ce qu'elle fait. C'est le mécanisme principal de déclenchement — incluez à la fois ce que la compétence fait ET les contextes spécifiques pour l'utiliser. Toutes les informations "quand utiliser" vont ici, pas dans le corps. Note : actuellement, Claude a tendance à "sous-déclencher" les compétences — à ne pas les utiliser quand elles seraient utiles. Pour contrer cela, veuillez rendre les descriptions de compétences un peu "insistantes". Par exemple, au lieu de "Comment construire un tableau de bord simple et rapide pour afficher des données internes d'Anthropic.", vous pourriez écrire "Comment construire un tableau de bord simple et rapide pour afficher des données internes d'Anthropic. Assurez-vous d'utiliser cette compétence chaque fois que l'utilisateur mentionne des tableaux de bord, la visualisation de données, des métriques internes, ou veut afficher tout type de données d'entreprise, même s'il ne demande pas explicitement un 'tableau de bord'."
• compatibility : Outils requis, dépendances (optionnel, rarement nécessaire)
• **le reste de la compétence :) **

Guide de Rédaction des Compétences

Anatomie d'une Compétence

skill-name/
├── SKILL.md (obligatoire)
│   ├── Frontmatter YAML (name, description obligatoires)
│   └── Instructions Markdown
└── Ressources fournies (optionnel)
    ├── scripts/    - Code exécutable pour des tâches déterministes/répétitives
    ├── references/ - Documentation chargée dans le contexte selon les besoins
    └── assets/     - Fichiers utilisés dans la sortie (modèles, icônes, polices)

Divulgation Progressive

Les compétences utilisent un système de chargement à trois niveaux :

1. Métadonnées (nom + description) - Toujours dans le contexte (~100 mots)
2. Corps du SKILL.md - Dans le contexte chaque fois que la compétence se déclenche (<500 lignes idéalement)
3. Ressources fournies - Selon les besoins (illimité, les scripts peuvent s'exécuter sans chargement)

Ces comptes de mots sont approximatifs et vous pouvez librement aller plus loin si nécessaire.

Schémas clés :

• Gardez le SKILL.md sous 500 lignes ; si vous approchez de cette limite, ajoutez un niveau supplémentaire de hiérarchie avec des indications claires sur où le modèle utilisant la compétence doit aller ensuite pour continuer.
• Référencez clairement les fichiers depuis SKILL.md avec des directives sur quand les lire
• Pour les fichiers de référence volumineux (>300 lignes), incluez une table des matières

Organisation par domaine : Lorsqu'une compétence prend en charge plusieurs domaines/cadres, organisez par variante :

cloud-deploy/
├── SKILL.md (workflow + sélection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude lit uniquement le fichier de référence pertinent.

Principe de Non-Surprise

Cela va sans dire, mais les compétences ne doivent pas contenir de malware, de code d'exploitation, ou tout contenu qui pourrait compromettre la sécurité du système. Le contenu d'une compétence ne doit pas surprendre l'utilisateur par son intention si elle est décrite. N'acceptez pas les demandes de création de compétences trompeuses ou conçues pour faciliter un accès non autorisé, une exfiltration de données, ou d'autres activités malveillantes. Les choses comme "jouer le rôle d'un XYZ" sont acceptables.

Schémas de Rédaction

Préférez utiliser la forme impérative dans les instructions.

Définition des formats de sortie - Vous pouvez le faire comme ceci :

## Structure du rapport
Utilisez TOUJOURS ce modèle exact :
# [Titre]
## Résumé exécutif
## Constatations principales
## Recommandations

Schéma d'exemples - Il est utile d'inclure des exemples. Vous pouvez les formater comme ceci (mais si "Entrée" et "Sortie" sont dans les exemples, vous voudrez peut-être vous en écarter un peu) :

## Format du message de commit
**Exemple 1 :**
Entrée : Ajout de l'authentification utilisateur avec des jetons JWT
Sortie : feat(auth) : implémenter l'authentification basée sur JWT

Style d'Écriture

Essayez d'expliquer au modèle pourquoi les choses sont importantes plutôt que d'utiliser des MUST lourds et autoritaires. Utilisez la théorie de l'esprit et essayez de rendre la compétence générale et non très étroite à des exemples spécifiques. Commencez par écrire un brouillon puis regardez-le avec un œil neuf et améliorez-le.

Cas de Test

Après avoir rédigé le brouillon de la compétence, trouvez 2-3 prompts de test réalistes — le genre de chose qu'un utilisateur réel dirait réellement. Partagez-les avec l'utilisateur : [vous n'êtes pas obligé d'utiliser ce langage exact] "Voici quelques cas de test que j'aimerais essayer. Est-ce que cela semble correct, ou voulez-vous en ajouter d'autres ?" Ensuite, exécutez-les.

Enregistrez les cas de test dans evals/evals.json. N'écrivez pas encore d'assertions — juste les prompts. Vous rédigerez les assertions à l'étape suivante pendant que les exécutions sont en cours.

{
  "skill_name": "exemple-compétence",
  "evals": [
    {
      "id": 1,
      "prompt": "Prompt de tâche de l'utilisateur",
      "expected_output": "Description du résultat attendu",
      "files": []
    }
  ]
}

Voir references/schemas.md pour le schéma complet (incluant le champ assertions, que vous ajouterez plus tard).

Exécution et évaluation des cas de test

Cette section est une séquence continue — ne vous arrêtez pas en cours de route. N'utilisez PAS /skill-test ou toute autre compétence de test.

Placez les résultats dans <nom-compétence>-workspace/ comme un répertoire frère du répertoire de la compétence. Dans l'espace de travail, organisez les résultats par itération (iteration-1/, iteration-2/, etc.) et à l'intérieur de celle-ci, chaque cas de test obtient un répertoire (eval-0/, eval-1/, etc.). Ne créez pas tout cela à l'avance — créez simplement des répertoires au fur et à mesure.

Étape 1 : Lancer toutes les exécutions (avec-compétence ET baseline) dans le même tour

Pour chaque cas de test, lancez deux sous-agents dans le même tour — un avec la compétence, un sans. C'est important : ne lancez pas d'abord les exécutions avec compétence puis revenez pour les baselines plus tard. Lancez tout en même temps pour que tout se termine à peu près en même temps.

Exécution avec compétence :

Exécutez cette tâche :
- Chemin de la compétence : <chemin-vers-compétence>
- Tâche : <prompt d'évaluation>
- Fichiers d'entrée : <fichiers d'évaluation s'il y en a, ou "aucun">
- Enregistrez les sorties dans : <espace de travail>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Sorties à enregistrer : <ce qui intéresse l'utilisateur — par exemple, "le fichier .docx", "le CSV final">

Exécution baseline (même prompt, mais la baseline dépend du contexte) :

• Création d'une nouvelle compétence : aucune compétence du tout. Même prompt, pas de chemin de compétence, enregistrez dans without_skill/outputs/.
• Amélioration d'une compétence existante : l'ancienne version. Avant de modifier, faites un instantané de la compétence (cp -r <chemin-compétence> <espace de travail>/skill-snapshot/), puis pointez le sous-agent baseline vers l'instantané. Enregistrez dans old_skill/outputs/.

Écrivez un eval_metadata.json pour chaque cas de test (les assertions peuvent être vides pour l'instant). Donnez à chaque évaluation un nom descriptif basé sur ce qu'elle teste — pas seulement "eval-0". Utilisez ce nom aussi pour le répertoire. Si cette itération utilise des prompts d'évaluation nouveaux ou modifiés, créez ces fichiers pour chaque nouveau répertoire d'évaluation — ne supposez pas qu'ils sont reportés des itérations précédentes.

{
  "eval_id": 0,
  "eval_name": "nom-descriptif-ici",
  "prompt": "Le prompt de tâche de l'utilisateur",
  "assertions": []
}

Étape 2 : Pendant que les exécutions sont en cours, rédigez les assertions

N'attendez pas simplement la fin des exécutions — vous pouvez utiliser ce temps de manière productive. Rédigez des assertions quantitatives pour chaque cas de test et expliquez-les à l'utilisateur. Si des assertions existent déjà dans evals/evals.json, examinez-les et expliquez ce qu'elles vérifient.

Les bonnes assertions sont objectivement vérifiables et ont des noms descriptifs — elles doivent se lire clairement dans le visualiseur de benchmark afin que quelqu'un qui jette un coup d'œil aux résultats comprenne immédiatement ce que chacune vérifie. Les compétences subjectives (style d'écriture, qualité de conception) sont mieux évaluées qualitativement — n'imposez pas d'assertions à des choses qui nécessitent un jugement humain.

Mettez à jour les fichiers eval_metadata.json et evals/evals.json avec les assertions une fois rédigées. Expliquez aussi à l'utilisateur ce qu'il verra dans le visualiseur — à la fois les sorties qualitatives et le benchmark quantitatif.

Étape 3 : Au fur et à mesure que les exécutions se terminent, capturez les données de chronométrage

Lorsque chaque tâche de sous-agent se termine, vous recevez une notification contenant total_tokens et duration_ms. Enregistrez ces données immédiatement dans timing.json dans le répertoire d'exécution :

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

C'est la seule opportunité de capturer ces données — elles arrivent via la notification de tâche et ne sont pas persistées ailleurs. Traitez chaque notification au fur et à mesure qu'elle arrive plutôt que d'essayer de les traiter par lots.

Étape 4 : Noter, agréger et lancer le visualiseur

Une fois toutes les exécutions terminées :

1. Noter chaque exécution — lancez un sous-agent de notation (ou notez en ligne) qui lit agents/grader.md et évalue chaque assertion par rapport aux sorties. Enregistrez les résultats dans grading.json dans chaque répertoire d'exécution. Le tableau expectations dans grading.json doit utiliser les champs text, passed et evidence (pas name/met/details ou d'autres variantes) — le visualiseur dépend de ces noms de champs exacts. Pour les assertions qui peuvent être vérifiées par programmation, écrivez et exécutez un script plutôt que de les juger à l'œil — les scripts sont plus rapides, plus fiables et peuvent être réutilisés entre les itérations.

2. Agréger en benchmark — exécutez le script d'agrégation depuis le répertoire du créateur de compétences :

   python -m scripts.aggregate_benchmark <espace de travail>/iteration-N --skill-name <nom>
   

   Cela produit benchmark.json et benchmark.md avec le taux de réussite, le temps et les tokens pour chaque configuration, avec moyenne ± écart-type et le delta. Si vous générez benchmark.json manuellement, consultez references/schemas.md pour le schéma exact attendu par le visualiseur. Placez chaque version avec compétence avant son homologue baseline.

3. Faire une passe d'analyse — lisez les données du benchmark et mettez en évidence les schémas que les statistiques agrégées pourraient cacher. Consultez agents/analyzer.md (la section "Analyse des Résultats de Benchmark") pour savoir quoi chercher — par exemple, les assertions qui réussissent toujours quelle que soit la compétence (non discriminantes), les évaluations à variance élevée (potentiellement instables), et les compromis temps/tokens.

4. Lancez le visualiseur avec à la fois les sorties qualitatives et les données quantitatives :

   nohup python <chemin-createur-compétences>/eval-viewer/generate_review.py
   

…

[tronqué pour la traduction]