Créateur de compétences : Développer des compétences Claude efficaces

--- name: skill-creator description: Guide pour créer des compétences efficaces. Cette compétence doit être utilisée lorsque les utilisateurs souhaitent créer une nouvelle compétence (ou mettre à jour une compétence existante) qui étend les capacités de Claude avec des connaissances spécialisées, des flux de travail ou des intégrations d'outils. license: Conditions complètes dans LICENSE.txt --- # 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 packages 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 des tâches spécifiques - ils transforment Claude d'un agent généraliste en un agent spécialisé doté de connaissances procédurales qu'aucun modèle ne peut posséder pleinement. ### Ce que les Compétences Fournissent 1. Flux de travail spécialisés - Procédures en plusieurs étapes pour des domaines spécifiques 2. Intégrations d'outils - Instructions pour travailler avec des formats de fichiers ou des API spécifiques 3. Expertise de domaine - Connaissances spécifiques à l'entreprise, schémas, logique métier 4. Ressources groupées - Scripts, références et actifs pour des tâches complexes et répétitives ## Principes Fondamentaux ### La Concision est Essentielle La fenêtre de contexte est un bien commun. 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 des autres compétences et la demande réelle de l'utilisateur. **Hypothèse par défaut : Claude est déjà très intelligent.** N'ajoutez que le contexte que Claude ne possède 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 des exemples concis à des explications verbeuses. ### Définir des Degrés de Liberté Appropriés Faites correspondre le niveau de spécificité à la fragilité et à la variabilité de la tâche : **Liberté élevée (instructions textuelles)** : Utilisez lorsque plusieurs approches sont valides, que les décisions dépendent du contexte ou que des heuristiques guident l'approche. **Liberté moyenne (pseudocode ou scripts avec paramètres)** : Utilisez lorsqu'un modèle préféré existe, qu'une certaine variation est acceptable ou que la configuration affecte le comportement. **Liberté faible (scripts spécifiques, peu de paramètres)** : Utilisez lorsque les opérations sont fragiles et sujettes aux erreurs, que la cohérence est critique ou qu'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 nombreux itinéraires (liberté élevée). ### Anatomie d'une Compétence Chaque compétence se compose d'un fichier SKILL.md requis et de ressources groupées facultatives : ``` nom-compétence/ ├── SKILL.md (requis) │ ├── Métadonnées YAML frontmatter (requises) │ │ ├── name : (requis) │ │ └── description : (requis) │ └── Instructions Markdown (requises) └── Ressources groupées (facultatives) ├── scripts/ - Code exécutable (Python/Bash/etc.) ├── references/ - Documentation destinée à être chargée dans le contexte selon les besoins └── assets/ - Fichiers utilisés dans la sortie (modèles, icônes, polices, etc.) ``` #### SKILL.md (requis) 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 doit être 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 doit être utilisée. - **Corps** (Markdown) : Instructions et conseils pour utiliser la compétence. Chargé uniquement APRÈS le déclenchement de la compétence (si cela se produit). #### Ressources Groupées (facultatives) ##### Scripts (`scripts/`) Code exécutable (Python/Bash/etc.) pour des tâches nécessitant une fiabilité déterministe ou réécrites à plusieurs reprises. - **Quand les inclure** : Lorsque le même code est réécrit à plusieurs reprises ou qu'une fiabilité déterministe est nécessaire - **Exemple** : `scripts/rotate_pdf.py` pour les tâches de rotation de PDF - **Avantages** : Efficace en tokens, déterministe, peut être exécuté sans chargement dans le contexte - **Remarque** : Les scripts peuvent encore devoir être lus par Claude pour des correctifs ou des 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 dans le contexte pour informer le processus et la réflexion de Claude. - **Quand les inclure** : Pour la documentation à laquelle Claude devrait se référer pendant le travail - **Exemples** : `references/finance.md` pour les schémas financiers, `references/mnda.md` pour le modèle de NDA de l'entreprise, `references/policies.md` pour les politiques de l'entreprise, `references/api_docs.md` pour les spécifications API - **Cas d'utilisation** : Schémas de base de données, documentation API, connaissances de domaine, politiques d'entreprise, guides de flux de travail détaillés - **Avantages** : Maintient SKILL.md léger, chargé uniquement lorsque Claude détermine que c'est nécessaire - **Meilleure pratique** : Si les fichiers sont volumineux (>10 000 mots), incluez des modèles de recherche grep dans SKILL.md - **Évitez la duplication** : L'information doit résider soit dans SKILL.md, soit dans les fichiers de références, pas dans les deux. ##### Actifs (`assets/`) Fichiers non destinés à être chargés dans le contexte, mais plutôt utilisés dans la sortie que Claude produit. - **Quand les inclure** : Lorsque la compétence nécessite des fichiers qui seront utilisés dans la sortie finale - **Exemples** : `assets/logo.png` pour les actifs de marque, `assets/slides.pptx` pour les modèles PowerPoint - **Cas d'utilisation** : Modèles, images, icônes, code standard, polices, documents d'exemple ### Principe de Conception par Divulgation Progressive Les compétences utilisent un système de chargement à trois niveaux pour gérer efficacement le contexte : 1. **Métadonnées (name + description)** - Toujours dans le contexte (~100 mots) 2. **Corps de SKILL.md** - Lorsque la compétence se déclenche (<5 000 mots) 3. **Ressources groupées** - Selon les besoins de Claude Gardez le corps de SKILL.md à l'essentiel et sous 500 lignes pour minimiser l'encombrement du contexte. ## Processus de Création de Compétence La création d'une compétence implique ces étapes : 1. Comprendre la compétence avec des exemples concrets 2. Planifier le contenu réutilisable de la compétence (scripts, références, actifs) 3. Initialiser la compétence (exécuter init_skill.py) 4. Modifier la compétence (implémenter les ressources et rédiger SKILL.md) 5. Empaqueter la compétence (exécuter package_skill.py) 6. Itérer en fonction de l'utilisation réelle ### Étape 3 : Initialisation de la Compétence Lors de la création d'une nouvelle compétence à partir de zéro, exécutez toujours le script `init_skill.py` : ```bash scripts/init_skill.py <nom-compétence> --path <répertoire-de-sortie> ``` ### Étape 4 : Modifier la Compétence Consultez ces guides utiles en fonction des besoins de votre compétence : - **Processus en plusieurs é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 modèles et exemples de motifs ### Étape 5 : Empaqueter une Compétence ```bash scripts/package_skill.py <chemin/vers/dossier-compétence> ``` Le script d'empaquetage valide et crée un fichier .skill pour la distribution. FILE:references/workflows.md # Modèles de Flux de Travail ## Flux de Travail Séquentiels Pour les tâches complexes, divisez les opérations en étapes séquentielles claires. Il est souvent utile de donner à Claude un aperçu du processus vers le début de SKILL.md : ```markdown Remplir un formulaire PDF implique ces étapes : 1. Analyser le formulaire (exécuter analyze_form.py) 2. Créer la correspondance des champs (modifier fields.json) 3. Valider la correspondance (exécuter validate_fields.py) 4. Remplir le formulaire (exécuter fill_form.py) 5. Vérifier la sortie (exécuter verify_output.py) ``` ## Flux de Travail Conditionnels Pour les tâches avec une logique de branchement, guidez Claude à travers les points de décision : ```markdown 1. Déterminer le type de modification : **Créer un nouveau contenu ?** → Suivre le « Flux de création » ci-dessous **Modifier un contenu existant ?** → Suivre le « Flux de modification » ci-dessous 2. Flux de création : [étapes] 3. Flux de modification : [étapes] ``` FILE:references/output-patterns.md # Modèles de Sortie Utilisez ces modèles lorsque les compétences doivent produire une sortie cohérente et de haute qualité. ## Modèle de Gabarit Fournissez des gabarits pour le format de sortie. Faites correspondre le niveau de rigueur à vos besoins. **Pour les exigences strictes (comme les réponses API ou les formats de données) :** ```markdown ## Structure du rapport Utilisez TOUJOURS cette structure de gabarit exacte : # [Titre de l'analyse] ## Résumé exécutif [Aperçu en un paragraphe des principales conclusions] ## Principales conclusions - Conclusion 1 avec données à l'appui - Conclusion 2 avec données à l'appui - Conclusion 3 avec données à l'appui ## Recommandations 1. Recommandation spécifique et actionnable 2. Recommandation spécifique et actionnable ``` **Pour des conseils flexibles (lorsque l'adaptation est utile) :** ```markdown ## Structure du rapport Voici un format par défaut raisonnable, mais utilisez votre meilleur jugement : # [Titre de l'analyse] ## Résumé exécutif [Aperçu] ## Principales conclusions [Adaptez les sections en fonction de ce que vous découvrez] ## Recommandations [Adaptez au contexte spécifique] Ajustez les sections selon les besoins pour le type d'analyse spécifique. ``` ## Modèle d'Exemples Pour les compétences où la qualité de la sortie dépend de la visualisation d'exemples, fournissez des paires entrée/sortie : ```markdown ## Format du message de commit Générez des messages de commit en suivant ces exemples : **Exemple 1 :** Entrée : Ajout de l'authentification utilisateur avec des jetons JWT Sortie : ``` feat(auth) : implémenter l'authentification basée sur JWT Ajouter un point de terminaison de connexion et un middleware de validation de jeton ``` **Exemple 2 :** Entrée : Correction d'un bug où les dates s'affichaient incorrectement dans les rapports Sortie : ``` fix(reports) : corriger le format de date dans la conversion de fuseau horaire Utiliser des horodatages UTC de manière cohérente lors de la génération de rapports ``` Suivez ce style : type(portée) : description brève, puis explication détaillée. ``` Les exemples aident Claude à comprendre le style et le niveau de détail souhaités plus clairement que les descriptions seules. FILE:scripts/quick_validate.py #!/usr/bin/env python3 """ Script de validation rapide pour les compétences - version minimale """ import sys import os import re import yaml from pathlib import Path def validate_skill(skill_path): """Validation de base d'une compétence""" skill_path = Path(skill_path) # Vérifier que SKILL.md existe skill_md = skill_path / 'SKILL.md' if not skill_md.exists(): return False, "SKILL.md introuvable" # Lire et valider le frontmatter content = skill_md.read_text() if not content.startswith('---'): return False, "Aucun frontmatter YAML trouvé" # Extraire le frontmatter match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL) if not match: return False, "Format de frontmatter invalide" frontmatter_text = match.group(1) # Analyser le frontmatter YAML try: frontmatter = yaml.safe_load(frontmatter_text) if not isinstance(frontmatter, dict): return False, "Le frontmatter doit être un dictionnaire YAML" except yaml.YAMLError as e: return False, f"YAML invalide dans le frontmatter : {e}" # Définir les propriétés autorisées ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'} # Vérifier les propriétés inattendues (à l'exclusion des clés imbriquées sous metadata) unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES if unexpected_keys: return False, ( f"Clé(s) inattendue(s) dans le frontmatter de SKILL.md : {', '.join(sorted(unexpected_keys))}. " f"Les propriétés autorisées sont : {', '.join(sorted(ALLOWED_PROPERTIES))}" ) # Vérifier les champs requis if 'name' not in frontmatter: return False, "Champ 'name' manquant dans le frontmatter" if 'description' not in frontmatter: return False, "Champ 'description' manquant dans le frontmatter" # Extraire le nom pour validation name = frontmatter.get('name', '') if not isinstance(name, str): return False, f"Le nom doit être une chaîne, obtenu {type(name).__name__}" name = name.strip() if name: # Vérifier la convention de nommage (trait d'union : minuscules avec traits d'union) if not re.match(r'^[a-z0-9-]+$', name): return False, f"Le nom '{name}' doit être en casse-trait-d'union (lettres minuscules, chiffres et traits d'union uniquement)" if name.startswith('-') or name.endswith('-') or '--' in name: return False, f"Le nom '{name}' ne peut pas commencer/se terminer par un trait d'union ni contenir des traits d'union consécutifs" # Vérifier la longueur du nom (64 caractères maximum selon la spécification) if len(name) > 64: return False, f"Le nom est trop long ({len(name)} caractères). Le maximum est de 64 caractères." # Extraire et valider la description description = frontmatter.get('description', '') if not isinstance(description, str): return False, f"La description doit être une chaîne, obtenu {type(description).__name__}" description = description.strip() if description: # Vérifier les crochets angulaires if '<' in description or '>' in description: return False, "La description ne peut pas contenir de crochets angulaires (< ou >)" # Vérifier la longueur de la description (1024 caractères maximum selon la spécification) if len(description) > 1024: return False, f"La description est trop longue ({len(description)} caractères). Le maximum est de 1024 caractères." return True, "La compétence est valide !" if __name__ == "__main__": if len(sys.argv) != 2: print("Utilisation : python quick_validate.py <répertoire-compétence>") sys.exit(1) valid, message = validate_skill(sys.argv[1]) print(message) sys.exit(0 if valid else 1) FILE:scripts/init_skill.py #!/usr/bin/env python3 """ Initialiseur de Compétence - Crée une nouvelle compétence à partir d'un modèle Utilisation : init_skill.py <nom-compétence> --path <chemin> Exemples : init_skill.py ma-nouvelle-compétence --path skills/public init_skill.py mon-aide-api --path skills/private init_skill.py compétence-personnalisée --path /emplacement-personnalisé """ import sys from pathlib import Path SKILL_TEMPLATE = """--- name: {skill_name} description: [À COMPLÉTER : Explication complète et informative de ce que fait la compétence et quand l'utiliser. Inclure QUAND utiliser cette compétence - scénarios spécifiques, types de fichiers ou tâches qui la déclenchent.] --- # {skill_title} ## Aperçu [À COMPLÉTER : 1-2 phrases expliquant ce que cette compétence permet] ## Ressources Cette compétence inclut des répertoires de ressources d'exemple qui montrent comment organiser différents types de ressources groupées : ### scripts/ Code exécutable (Python/Bash/etc.) pouvant être exécuté directement pour effectuer des opérations spécifiques. ### references/ Documentation et matériel de référence destinés à être chargés dans le contexte pour informer le processus et la réflexion de Claude. ### assets/ Fichiers non destinés à être chargés dans le contexte, mais plutôt utilisés dans la sortie que Claude produit. --- **Tout répertoire inutile peut être supprimé.** Toutes les compétences ne nécessitent pas les trois types de ressources. """ EXAMPLE_SCRIPT = '''#!/usr/bin/env python3 """ Script d'aide d'exemple pour {skill_name} Ceci est un script d'espace réservé qui peut être exécuté directement. Remplacez par une implémentation réelle ou supprimez si non nécessaire. """ def main(): print("Ceci est un script d'exemple pour {skill_name}") # À COMPLÉTER : Ajouter la logique réelle du script ici if __name__ == "__main__": main() ''' EXAMPLE_REFERENCE = """# Documentation de Référence pour {skill_title} Ceci est un espace réservé pour une documentation de référence détaillée. Remplacez par un contenu de référence réel ou supprimez si non nécessaire. """ EXAMPLE_ASSET = """# Fichier d'Actif d'Exemple Cet espace réservé représente l'endroit où les fichiers d'actifs seraient stockés. Remplacez par des actifs réels (modèles, images, polices, etc.) ou supprimez si non nécessaire. """ def title_case_skill_name(skill_name): """Convertir le nom de compétence avec traits d'union en casse de titre pour l'affichage.""" return ' '.join(word.capitalize() for word in skill_name.split('-')) def init_skill(skill_name, path): """Initialiser un nouveau répertoire de compétence avec un SKILL.md modèle.""" skill_dir = Path(path).resolve() / skill_name if skill_dir.exists(): print(f"❌ Erreur : Le répertoire de compétence existe déjà : {skill_dir}") return None try: skill_dir.mkdir(parents=True, exist_ok=False) print(f"✅ Répertoire de compétence créé : {skill_dir}") except Exception as e: print(f"❌ Erreur lors de la création du répertoire : {e}") return None skill_title = title_case_skill_name(skill_name) skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title) skill_md_path = skill_dir / 'SKILL.md' try: skill_md_path.write_text(skill_content) print("✅ SKILL.md créé") except Exception as e: print(f"❌ Erreur lors de la création de SKILL.md : {e}") return None try: scripts_dir = skill_dir / 'scripts' scripts_dir.mkdir(exist_ok=True) example_script = scripts_dir / 'example.py' example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name)) example_script.chmod(0o755) print("✅ scripts/example.py créé") references_dir = skill_dir / 'references' references_dir.mkdir(exist_ok=True) example_reference = references_dir / 'api_reference.md' example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title)) print("✅ references/api_reference.md créé") assets_dir = skill_dir / 'assets' assets_dir.mkdir(exist_ok=True) example_asset = assets_dir / 'example_asset.txt' example_asset.write_text(EXAMPLE_ASSET) print("✅ assets/example_asset.txt créé") except Exception as e: print(f"❌ Erreur lors de la création des répertoires de ressources : {e}") return None print(f"\n✅ Compétence '{skill_name}' initialisée avec succès à {skill_dir}") return skill_dir def main(): if len(sys.argv) < 4 or sys.argv[2] != '--path': print("Utilisation : init_skill.py <nom-compétence> --path <chemin>") sys.exit(1) skill_name = sys.argv[1] path = sys.argv[3] print(f"🚀 Initialisation de la compétence : {skill_name}") print(f" Emplacement : {path}") print() result = init_skill(skill_name, path) sys.exit(0 if result else 1) if __name__ == "__main__": main() FILE:scripts/package_skill.py #!/usr/bin/env python3 """ Empaqueteur de Compétence - Crée un fichier .skill distribuable d'un dossier de compétence Utilisation : python utils/package_skill.py <chemin/vers/dossier-compétence> [répertoire-de-sortie] Exemple : python utils/package_skill.py skills/public/ma-compétence python utils/package_skill.py skills/public/ma-compétence ./dist """ import sys import zipfile from pathlib import Path from quick_validate import validate_skill def package_skill(skill_path, output_dir=None): """Empaqueter un dossier de compétence dans un fichier .skill.""" skill_path = Path(skill_path).resolve() if not skill_path.exists(): print(f"❌ Erreur : Dossier de compétence introuvable : {skill_path}") return None if not skill_path.is_dir(): print(f"❌ Erreur : Le chemin n'est pas un répertoire : {skill_path}") return None skill_md = skill_path / "SKILL.md" if not skill_md.exists(): print(f"❌ Erreur : SKILL.md introuvable dans {skill_path}") return None print("🔍 Validation de la compétence...") valid, message = validate_skill(skill_path) if not valid: print(f"❌ Échec de la validation : {message}") print(" Veuillez corriger les erreurs de validation avant l'empaquetage.") return None print(f"✅ {message}\n") skill_name = skill_path.name if output_dir: output_path = Path(output_dir).resolve() output_path.mkdir(parents=True, exist_ok=True) else: output_path = Path.cwd() skill_filename = output_path / f"{skill_name}.skill" try: with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf: for file_path in skill_path.rglob('*'): if file_path.is_file(): arcname = file_path.relative_to(skill_path.parent) zipf.write(file_path, arcname) print(f" Ajouté : {arcname}") print(f"\n✅ Compétence empaquetée avec succès vers : {skill_filename}") return skill_filename except Exception as e: print(f"❌ Erreur lors de la création du fichier .skill : {e}") return None def main(): if len(sys.argv) < 2: print("Utilisation : python utils/package_skill.py <chemin/vers/dossier-compétence> [répertoire-de-sortie]") sys.exit(1) skill_path = sys.argv[1] output_dir = sys.argv[2] if len(sys.argv) > 2 else None print(f"📦 Empaquetage de la compétence : {skill_path}") if output_dir: print(f" Répertoire de sortie : {output_dir}") print() result = package_skill(skill_path, output_dir) sys.exit(0 if result else 1) if __name__ == "__main__": main()