Créateur de compétences

Cette compétence fournit des conseils pour créer des compétences efficaces.

À propos des compétences

Les compétences sont des paquets modulaires et autonomes qui étendent les capacités de Claude en fournissant des connaissances spécialisées, des flux de travail et des outils. Considérez-les comme des « guides d'intégration » pour des domaines ou tâches spécifiques — elles transforment Claude d'un agent polyvalent en un agent spécialisé doté de connaissances procédurales qu'aucun modèle ne peut posséder complètement.

Ce que les compétences offrent

1. Flux de travail spécialisés - Procédures multi-étapes pour des domaines spécifiques
2. Intégrations d'outils - Instructions pour travailler avec des formats de fichiers ou des APIs spécifiques
3. Expertise de domaine - Connaissances spécifiques à l'entreprise, schémas, logique métier
4. Ressources regroupées - Scripts, références et ressources pour les tâches complexes et répétitives

Principes fondamentaux

La concision est essentielle

La fenêtre de contexte est un bien public. Les compétences partagent la fenêtre de contexte avec tout ce dont Claude a besoin : le prompt système, l'historique de conversation, les métadonnées d'autres compétences et la requête utilisateur réelle.

Hypothèse par défaut : Claude est déjà très intelligent. Ajoutez uniquement du contexte que Claude n'a pas déjà. Remettez en question chaque information : « Claude a-t-il vraiment besoin de cette explication ? » et « Ce paragraphe justifie-t-il son coût en tokens ? »

Préférez les exemples concis aux explications verbeux.

Établir des degrés de liberté appropriés

Ajustez le niveau de spécificité à la fragilité et la variabilité de la tâche :

Liberté élevée (instructions basées sur le texte) : Utilisez quand plusieurs approches sont valides, les décisions dépendent du contexte ou l'heuristique guide l'approche.

Liberté moyenne (pseudocode ou scripts avec paramètres) : Utilisez quand un motif préféré existe, une certaine variation est acceptable ou la configuration affecte le comportement.

Liberté faible (scripts spécifiques, peu de paramètres) : Utilisez quand les opérations sont fragiles et sujettes aux erreurs, la cohérence est critique ou une séquence spécifique doit être suivie.

Pensez à Claude comme explorant un chemin : un pont étroit avec des falaises nécessite des garde-fous spécifiques (liberté faible), tandis qu'un champ ouvert permet de nombreuses routes (liberté élevée).

Anatomie d'une compétence

Chaque compétence se compose d'un fichier SKILL.md obligatoire et de ressources optionnelles :

nom-de-compétence/
├── SKILL.md (obligatoire)
│   ├── Métadonnées frontmatter YAML (obligatoire)
│   │   ├── name: (obligatoire)
│   │   └── description: (obligatoire)
│   └── Instructions Markdown (obligatoire)
└── Ressources regroupées (optionnel)
    ├── scripts/          - Code exécutable (Python/Bash/etc.)
    ├── references/       - Documentation à charger en contexte selon les besoins
    └── assets/           - Fichiers utilisés en sortie (modèles, icônes, polices, etc.)

SKILL.md (obligatoire)

Chaque SKILL.md se compose de :

• Frontmatter (YAML) : Contient les champs name et description. Ce sont les seuls champs que Claude lit pour déterminer quand la compétence est utilisée, il est donc très important d'être clair et complet dans la description de ce qu'est la compétence et quand elle devrait être utilisée.
• Corps (Markdown) : Instructions et conseils pour utiliser la compétence. Chargés uniquement APRÈS le déclenchement de la compétence (le cas échéant).

Ressources regroupées (optionnel)

Scripts (scripts/)

Code exécutable (Python/Bash/etc.) pour les tâches nécessitant une fiabilité déterministe ou régulièrement réécrites.

• Quand les inclure : Quand le même code est régulièrement réécrit ou qu'une fiabilité déterministe est nécessaire
• Exemple : scripts/rotate_pdf.py pour les tâches de rotation PDF
• Avantages : Efficace en tokens, déterministe, peut être exécuté sans charger en contexte
• Remarque : Les scripts peuvent toujours nécessiter d'être lus par Claude pour les correctifs ou les ajustements spécifiques à l'environnement

Références (references/)

Documentation et matériel de référence destinés à être chargés selon les besoins en contexte pour informer le processus et la réflexion de Claude.

• Quand les inclure : Pour la documentation que Claude doit consulter en travaillant
• Exemples : references/finance.md pour les schémas financiers, references/mnda.md pour le modèle NDA de l'entreprise, references/policies.md pour les politiques de l'entreprise, references/api_docs.md pour les spécifications API
• Cas d'usage : Schémas de base de données, documentation API, connaissances de domaine, politiques de l'entreprise, guides de flux de travail détaillés
• Avantages : Garde SKILL.md allégé, chargé uniquement quand Claude détermine qu'il est nécessaire
• Bonne pratique : Si les fichiers sont volumineux (>10 000 mots), incluez des motifs de recherche grep dans SKILL.md
• Éviter la duplication : L'information doit vivre soit dans SKILL.md soit dans les fichiers de références, pas les deux. Préférez les fichiers de références pour les informations détaillées sauf si c'est vraiment essentiel pour la compétence — cela garde SKILL.md allégé tout en rendant l'information découvrable sans bloquer la fenêtre de contexte. Conservez uniquement les instructions procédurales essentielles et les conseils de flux de travail dans SKILL.md ; déplacez le matériel de référence détaillé, les schémas et les exemples vers les fichiers de références.

Ressources (assets/)

Fichiers non destinés à être chargés en contexte, mais plutôt utilisés dans la sortie que Claude produit.

• Quand les inclure : Quand la compétence a besoin de fichiers qui seront utilisés dans la sortie finale
• Exemples : assets/logo.png pour les ressources de marque, assets/slides.pptx pour les modèles PowerPoint, assets/frontend-template/ pour le code HTML/React, assets/font.ttf pour la typographie
• Cas d'usage : Modèles, images, icônes, code de base, polices, exemples de documents copiés ou modifiés
• Avantages : Sépare les ressources de sortie de la documentation, permet à Claude d'utiliser les fichiers sans les charger en contexte

Ce qu'il ne faut pas inclure dans une compétence

Une compétence ne doit contenir que les fichiers essentiels qui soutiennent directement sa fonctionnalité. N'CRÉEZ PAS de documentation extraneous ou de fichiers auxiliaires, notamment :

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• etc.

La compétence ne doit contenir que les informations nécessaires pour qu'un agent IA fasse le travail. Elle ne doit pas contenir de contexte auxiliaire sur le processus de création, les procédures de configuration et de test, la documentation destinée aux utilisateurs, etc. Créer des fichiers de documentation supplémentaires n'ajoute que du désordre et de la confusion.

Principe de conception « Progressive Disclosure »

Les compétences utilisent un système de chargement à trois niveaux pour gérer efficacement le contexte :

1. Métadonnées (nom + description) - Toujours en contexte (~100 mots)
2. Corps de SKILL.md - Quand la compétence se déclenche (<5 000 mots)
3. Ressources regroupées - Selon les besoins de Claude (Illimité car les scripts peuvent être exécutés sans lecture en fenêtre de contexte)

Motifs de Progressive Disclosure

Gardez le corps de SKILL.md essentiel et sous 500 lignes pour minimiser le bruit de contexte. Divisez le contenu en fichiers séparés quand vous approchez de cette limite. Quand vous divisez le contenu en d'autres fichiers, il est très important de les référencer depuis SKILL.md et de décrire clairement quand les lire, pour assurer que le lecteur de la compétence sait qu'ils existent et quand les utiliser.

Principe clé : Quand une compétence supporte plusieurs variations, frameworks ou options, gardez seulement le flux de travail central et les conseils de sélection dans SKILL.md. Déplacez les détails spécifiques aux variantes (motifs, exemples, configuration) dans des fichiers de références séparés.

Motif 1 : Guide de haut niveau avec références

# Traitement PDF

## Démarrage rapide

Extraire le texte avec pdfplumber :
[exemple de code]

## Fonctionnalités avancées

- **Remplissage de formulaires** : Voir [FORMS.md](FORMS.md) pour le guide complet
- **Référence API** : Voir [REFERENCE.md](REFERENCE.md) pour toutes les méthodes
- **Exemples** : Voir [EXAMPLES.md](EXAMPLES.md) pour les motifs courants

Claude charge FORMS.md, REFERENCE.md ou EXAMPLES.md seulement quand nécessaire.

Motif 2 : Organisation spécifique au domaine

Pour les compétences avec plusieurs domaines, organisez le contenu par domaine pour éviter de charger du contexte non pertinent :

bigquery-skill/
├── SKILL.md (aperçu et navigation)
└── reference/
    ├── finance.md (revenus, métriques de facturation)
    ├── sales.md (opportunités, pipeline)
    ├── product.md (utilisation API, fonctionnalités)
    └── marketing.md (campagnes, attribution)

Quand un utilisateur demande des métriques de vente, Claude ne lit que sales.md.

De même, pour les compétences supportant plusieurs frameworks ou variantes, organisez par variante :

cloud-deploy/
├── SKILL.md (flux de travail + sélection de fournisseur)
└── references/
    ├── aws.md (motifs de déploiement AWS)
    ├── gcp.md (motifs de déploiement GCP)
    └── azure.md (motifs de déploiement Azure)

Quand l'utilisateur choisit AWS, Claude ne lit que aws.md.

Motif 3 : Détails conditionnels

Montrez le contenu basique, liez vers le contenu avancé :

# Traitement DOCX

## Créer des documents

Utilisez docx-js pour les nouveaux documents. Voir [DOCX-JS.md](DOCX-JS.md).

## Éditer des documents

Pour les modifications simples, modifiez le XML directement.

**Pour les modifications suivies** : Voir [REDLINING.md](REDLINING.md)
**Pour les détails OOXML** : Voir [OOXML.md](OOXML.md)

Claude lit REDLINING.md ou OOXML.md seulement quand l'utilisateur a besoin de ces fonctionnalités.

Lignes directrices importantes :

• Éviter les références profondément imbriquées - Gardez les références à un niveau de SKILL.md. Tous les fichiers de références doivent se lier directement depuis SKILL.md.
• Structurer les fichiers de références plus longs - Pour les fichiers de plus de 100 lignes, incluez une table des matières en haut afin que Claude puisse voir l'étendue complète lors de la prévisualisation.

Processus de création de compétence

La création de compétence implique ces étapes :

1. Comprendre la compétence avec des exemples concrets
2. Planifier le contenu de compétence réutilisable (scripts, références, ressources)
3. Initialiser la compétence (exécuter init_skill.py)
4. Éditer la compétence (implémenter les ressources et écrire SKILL.md)
5. Empaqueter la compétence (exécuter package_skill.py)
6. Itérer en fonction de l'utilisation réelle

Suivez ces étapes dans l'ordre, en les sautant seulement s'il y a une raison claire pour laquelle elles ne s'appliquent pas.

Étape 1 : Comprendre la compétence avec des exemples concrets

Sautez cette étape uniquement quand les motifs d'utilisation de la compétence sont déjà clairement compris. Elle reste précieuse même en travaillant avec une compétence existante.

Pour créer une compétence efficace, comprenez clairement des exemples concrets de la façon dont la compétence sera utilisée. Cette compréhension peut provenir soit d'exemples utilisateurs directs soit d'exemples générés validés avec le retour utilisateur.

Par exemple, en construisant une compétence d'éditeur d'images, les questions pertinentes incluent :

• « Quelles fonctionnalités la compétence d'éditeur d'images devrait-elle supporter ? Édition, rotation, autre ? »
• « Pouvez-vous donner des exemples de comment cette compétence serait utilisée ? »
• « Je peux imaginer les utilisateurs demandant des choses comme 'Supprime les yeux rouges de cette image' ou 'Pivote cette image'. Y a-t-il d'autres façons que vous imaginez cette compétence être utilisée ? »
• « Que dirait un utilisateur qui devrait déclencher cette compétence ? »

Pour éviter de surcharger les utilisateurs, évitez de poser trop de questions dans un seul message. Commencez par les questions les plus importantes et suivez selon les besoins pour une plus grande efficacité.

Concluez cette étape quand il y a une compréhension claire de la fonctionnalité que la compétence doit supporter.

Étape 2 : Planifier le contenu de compétence réutilisable

Pour transformer les exemples concrets en une compétence efficace, analysez chaque exemple par :

1. Considérer comment exécuter l'exemple à partir de zéro
2. Identifier quels scripts, références et ressources seraient utiles lors de l'exécution de ces flux de travail à plusieurs reprises

Exemple : En construisant une compétence pdf-editor pour traiter les requêtes comme « Aidez-moi à faire pivoter ce PDF », l'analyse montre :

1. Faire pivoter un PDF nécessite de réécrire le même code à chaque fois
2. Un script scripts/rotate_pdf.py serait utile à stocker dans la compétence

Exemple : En concevant une compétence frontend-webapp-builder pour les requêtes comme « Construis-moi une app de todo » ou « Construis-moi un tableau de bord pour suivre mes pas », l'analyse montre :

1. Écrire une webapp frontend nécessite le même code HTML/React standard à chaque fois
2. Un modèle assets/hello-world/ contenant les fichiers de projet HTML/React standard serait utile à stocker dans la compétence

Exemple : En construisant une compétence big-query pour traiter les requêtes comme « Combien d'utilisateurs se sont connectés aujourd'hui ? », l'analyse montre :

1. Interroger BigQuery nécessite de redécouvrir les schémas de table et les relations à chaque fois
2. Un fichier references/schema.md documentant les schémas de table serait utile à stocker dans la compétence

Pour établir le contenu de la compétence, analysez chaque exemple concret pour créer une liste des ressources réutilisables à inclure : scripts, références et ressources.

Étape 3 : Initialiser la compétence

À ce stade, il est temps de créer réellement la compétence.

Sautez cette étape seulement si la compétence développée existe déjà et que l'itération ou l'empaquetage est nécessaire. Dans ce cas, continuez vers l'étape suivante.

En créant une nouvelle compétence à partir de zéro, exécutez toujours le script init_skill.py. Le script génère commodément un nouveau répertoire de compétence modèle qui inclut automatiquement tout ce qu'une compétence nécessite, rendant le processus de création de compétence beaucoup plus efficace et fiable.

Utilisation :

scripts/init_skill.py <skill-name> --path <output-directory>

Le script :

• Crée le répertoire de compétence au chemin spécifié
• Génère un modèle SKILL.md avec le frontmatter approprié et les espaces réservés TODO
• Crée des répertoires de ressources d'exemple : scripts/, references/ et assets/
• Ajoute des fichiers d'exemple dans chaque répertoire qui peuvent être personnalisés ou supprimés

Après initialisation, personnalisez ou supprimez le fichier SKILL.md généré et les fichiers d'exemple selon les besoins.

Étape 4 : Éditer la compétence

Lors de l'édition de la compétence (nouvellement générée ou existante), souvenez-vous que la compétence est créée pour une autre instance de Claude. Incluez les informations qui seraient bénéfiques et non évidentes pour Claude. Considérez quelles connaissances procédurales, détails spécifiques au domaine ou ressources réutilisables aideraient une autre instance de Claude à exécuter ces tâches plus efficacement.

Apprendre les motifs de conception éprouvés

Consultez ces guides utiles en fonction des besoins de votre compétence :

• Processus multi-étapes : Voir references/workflows.md pour les flux de travail séquentiels et la logique conditionnelle
• Formats de sortie spécifiques ou normes de qualité : Voir references/output-patterns.md pour les motifs de modèles et d'exemples

Ces fichiers contiennent les meilleures pratiques établies pour la conception efficace de compétences.

Commencer par le contenu de compétence réutilisable

Pour commencer l'implémentation, commencez par les ressources réutilisables identifiées ci-dessus : fichiers scripts/, references/ et assets/. Notez que cette étape peut nécessiter une entrée utilisateur. Par exemple, en implémentant une compétence brand-guidelines, l'utilisateur peut avoir besoin de fournir des ressources de marque ou des modèles à stocker dans assets/, ou de la documentation à stocker dans references/.

Les scripts ajoutés doivent être testés en les exécutant réellement pour assurer qu'il n'y a pas de bugs et que la sortie correspond à ce qui est attendu. S'il y a de nombreux scripts similaires, seul un échantillon représentatif doit être testé pour assurer la confiance que tous fonctionnent tout en équilibrant le temps pour l'achèvement.

Tous les fichiers et répertoires d'exemple non nécessaires pour la compétence doivent être supprimés. Le script d'initialisation crée des fichiers d'exemple dans scripts/, references/ et assets/ pour démontrer la structure, mais la plupart des compétences n'en auront pas besoin.

Mettre à jour SKILL.md

Directives d'écriture : Utilisez toujours la forme impérative/infinitive.

Frontmatter

Écrivez le frontmatter YAML avec name et description :

• name : Le nom de la compétence
• description : C'est le mécanisme de déclenchement primaire de votre compétence, et aide Claude à comprendre quand utiliser la compétence.
  • Incluez à la fois ce que la compétence fait et les déclencheurs/contextes spécifiques pour quand l'utiliser.
  • Incluez toutes les informations « quand utiliser » ici - Pas dans le corps. Le corps n'est chargé qu'après le déclenchement, donc les sections « Quand utiliser cette compétence » dans le corps ne sont pas utiles à Claude.
  • Exemple de description pour une compétence docx : « Création, édition et analyse de documents complets avec support pour les modifications suivies, commentaires, préservation de la mise en forme et extraction de texte. Utilisez quand Claude doit travailler avec des documents professionnels (fichiers .docx) pour : (1) Créer de nouveaux documents, (2) Modifier ou éditer le contenu, (3) Travailler avec les modifications suivies, (4) Ajouter des commentaires, ou toute autre tâche de document »

N'incluez aucun autre champ dans le frontmatter YAML.

Corps

Écrivez les instructions pour utiliser la compétence et ses ressources regroupées.

Étape 5 : Empaqueter une compétence

Une fois le développement de la compétence terminé, elle doit être empaquetée dans un fichier .skill distribuable qui est partagé avec l'utilisateur. Le processus d'empaquetage valide automatiquement la compétence en premier pour assurer qu'elle répond à toutes les exigences :

scripts/package_skill.py <path/to/skill-folder>

Spécification optionnelle du répertoire de sortie :

scripts/package_skill.py <path/to/skill-folder> ./dist

Le script d'empaquetage :

1. Valide la compétence automatiquement, en vérifiant :

   • Format du frontmatter YAML et champs obligatoires
   • Conventions de nommage de compétences et structure de répertoire
   • Complétude et qualité de la description
   • Organisation de fichiers et références de ressources

2. Empaquète la compétence si la validation réussit, en créant un fichier .skill nommé d'après la compétence (p.ex., my-skill.skill) qui inclut tous les fichiers et maintient la structure de répertoire appropriée pour la distribution. Le fichier .skill est un fichier zip avec une extension .skill.

Si la validation échoue, le script signalera les erreurs et s'arrêtera sans créer de paquet. Corrigez les erreurs de validation et exécutez la commande d'empaquetage à nouveau.

Étape 6 : Itérer

Après le test de la compétence, les utilisateurs peuvent demander des améliorations. Cela se produit souvent juste après l'utilisation de la compétence, avec un contexte frais de la façon dont la compétence a fonctionné.

Flux de travail d'itération :

1. Utiliser la compétence sur des tâches réelles
2. Remarquer les difficultés ou les inefficacités
3. Identifier comment SKILL.md ou les ressources regroupées devraient être mises à jour
4. Implémenter les changements et tester à nouveau