Créateur de Skill

Ce skill fournit des conseils pour créer des skills efficaces.

À propos des Skills

Les skills sont des packages modulaires et autonomes qui étendent les capacités d'un agent IA en fournissant des connaissances spécialisées, des workflows et des outils. Pensez-les comme des « guides d'intégration » pour des domaines ou tâches spécifiques—ils transforment un agent IA généraliste en agent spécialisé équipé de connaissances procédurales qu'aucun modèle ne peut pleinement posséder.

Ce que les Skills fournissent

1. Workflows spécialisés - Procédures multi-étapes pour des domaines spécifiques
2. Intégrations d'outils - Instructions pour travailler avec des formats de fichier ou des API spécifiques
3. Expertise métier - 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 context window est un bien public. Les skills partagent la context window avec tout ce dont l'agent a besoin : prompt système, historique de conversation, métadonnées d'autres Skills, et la demande utilisateur réelle.

Supposition par défaut : l'agent est déjà capable. Ajoutez uniquement le contexte que l'agent ne possède pas. Remettez en question chaque information : « L'agent 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

Alignez le niveau de spécificité sur la fragilité et la variabilité de la tâche :

Liberté élevée (instructions basées sur du texte) : Utilisez quand plusieurs approches sont valides, les décisions dépendent du contexte, ou des heuristiques guident 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 à l'agent comme explorant un chemin : un pont étroit avec des falaises a besoin de garde-fous spécifiques (liberté faible), tandis qu'un champ ouvert permet plusieurs routes (liberté élevée).

Anatomie d'un Skill

Chaque skill se compose d'un fichier SKILL.md obligatoire et de ressources regroupées optionnelles :

skill-name/
├── SKILL.md (obligatoire)
│   ├── Métadonnées frontmatter YAML (obligatoire)
│   │   ├── name: (obligatoire)
│   │   └── description: (obligatoire)
│   └── Instructions Markdown (obligatoire)
└── Ressources regroupées (optionnel)
    ├── scripts/          - Code exécutable (TypeScript/Python/Bash/etc.)
    ├── references/       - Documentation à charger dans le contexte au besoin
    └── assets/           - Fichiers utilisés en sortie (templates, icônes, polices, etc.)

SKILL.md (obligatoire)

Chaque SKILL.md comprend :

• Frontmatter (YAML) : Contient les champs name et description. Ce sont les seuls champs qu'un agent lit pour déterminer quand le skill s'active, il est donc très important d'être clair et complet en décrivant ce qu'est le skill et quand il devrait être utilisé.
• Corps (Markdown) : Instructions et conseils pour utiliser le skill. Chargé uniquement APRÈS le déclenchement du skill (le cas échéant).

Ressources regroupées (optionnel)

Scripts (scripts/)

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

• Quand inclure : Quand le même code est réécrit régulièrement ou quand la fiabilité déterministe est nécessaire
• Exemple : scripts/rotate-pdf.ts pour les tâches de rotation de PDF
• Avantages : Efficace en tokens, déterministe, peut être exécuté sans charger en contexte
• Note : Les scripts peuvent toujours avoir besoin d'être lus par l'agent pour des corrections ou des ajustements spécifiques à l'environnement

Références (references/)

Documentation et matériel de référence destinés à être chargés au besoin en contexte pour informer le processus et la réflexion de l'agent.

• Quand inclure : Pour la documentation qu'un agent devrait consulter en travaillant
• Exemples : references/finance.md pour les schémas financiers, references/mnda.md pour le template d'accord de confidentialité 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 métier, politiques de l'entreprise, guides de workflow détaillés
• Avantages : Garde SKILL.md léger, chargé uniquement quand l'agent détermine qu'il est nécessaire
• Bonne pratique : Si les fichiers sont volumineux (>10k mots), incluez les motifs de recherche grep dans SKILL.md
• Éviter la duplication : L'information devrait 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 au skill—cela garde SKILL.md léger tout en rendant l'information découvrable sans monopoliser la context window. Conservez uniquement les instructions procédurales essentielles et les conseils de workflow 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 produite par l'agent.

• Quand inclure : Quand le skill 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 templates PowerPoint, assets/frontend-template/ pour le boilerplate HTML/React, assets/font.ttf pour la typographie
• Cas d'usage : Templates, images, icônes, code boilerplate, polices, exemples de documents qui sont copiés ou modifiés
• Avantages : Sépare les ressources de sortie de la documentation, permet aux agents d'utiliser des fichiers sans les charger en contexte

Ce qu'il ne faut pas inclure dans un Skill

Un skill ne devrait contenir que les fichiers essentiels qui soutiennent directement sa fonctionnalité. N'INCLUEZ PAS de documentation extraneous ou de fichiers auxiliaires, notamment :

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

Le skill ne devrait contenir que les informations nécessaires pour qu'un agent IA accomplisse la tâche à accomplir. Il ne devrait pas contenir de contexte auxiliaire sur le processus qui a mené à sa création, les procédures d'installation et de test, la documentation destinée aux utilisateurs, etc. Créer des fichiers de documentation supplémentaires ne fait qu'ajouter du désordre et de la confusion.

Principe de Progressive Disclosure

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

1. Métadonnées (name + description) - Toujours en contexte (~100 mots)
2. Corps de SKILL.md - Quand le skill se déclenche (<5k mots)
3. Ressources regroupées - Au besoin par l'agent (Illimité car les scripts peuvent être exécutés sans être lus en contexte)

Modèles de Progressive Disclosure

Gardez le corps de SKILL.md à l'essentiel et sous 500 lignes pour minimiser le surcharge de contexte. Divisez le contenu en fichiers séparés quand vous approchez 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 du skill sait qu'ils existent et quand les utiliser.

Principe clé : Quand un skill supporte de multiples variations, frameworks ou options, conservez uniquement le workflow essentiel 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érence séparés.

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

# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

L'agent charge FORMS.md, REFERENCE.md ou EXAMPLES.md uniquement quand nécessaire.

Motif 2 : Organisation spécifique au domaine

Pour les Skills avec plusieurs domaines, organisez le contenu par domaine pour éviter de charger un 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 ventes, l'agent lit uniquement sales.md.

De même, pour les skills supportant de multiples frameworks ou variantes, organisez par variante :

cloud-deploy/
├── SKILL.md (workflow + sélection du 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, l'agent lit uniquement aws.md.

Motif 3 : Détails conditionnels

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

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

L'agent lit REDLINING.md ou OOXML.md uniquement quand l'utilisateur a besoin de ces fonctionnalités.

Directives importantes :

• Éviter les références profondément imbriquées - Gardez les références un niveau profond depuis SKILL.md. Tous les fichiers de référence devraient être liés directement depuis SKILL.md.
• Structurer les fichiers de référence plus longs - Pour les fichiers de plus de 100 lignes, incluez une table des matières en haut pour que l'agent puisse voir la portée complète en prévisualisant.

Processus de création de Skill

La création de skill implique ces étapes :

1. Comprendre le skill avec des exemples concrets
2. Planifier le contenu du skill réutilisable (scripts, références, ressources)
3. Initialiser le skill (exécuter init-skill.ts)
4. Éditer le skill (implémenter les ressources et écrire SKILL.md)
5. Empaqueter le skill (exécuter package-skill.ts)
6. Itérer en fonction de l'utilisation réelle

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

Étape 1 : Comprendre le Skill avec des Exemples Concrets

Omettez cette étape uniquement quand les modèles d'utilisation du skill sont déjà clairement compris. Elle reste précieuse même en travaillant avec un skill existant.

Pour créer un skill efficace, comprenez clairement des exemples concrets de comment le skill sera utilisé. Cette compréhension peut venir soit d'exemples utilisateur directs, soit d'exemples générés qui sont validés par les retours utilisateur.

Par exemple, lors de la construction d'un skill image-editor, les questions pertinentes incluent :

• « Quelles fonctionnalités le skill image-editor devrait-il supporter ? Édition, rotation, autre chose ? »
• « Pouvez-vous donner des exemples de comment ce skill serait utilisé ? »
• « Je peux imaginer des utilisateurs demander des choses comme 'Supprime les yeux rouges de cette image' ou 'Tourne cette image'. Y a-t-il d'autres façons dont vous imaginez que ce skill serait utilisé ? »
• « Qu'est-ce qu'un utilisateur dirait qui devrait déclencher ce skill ? »

Pour éviter de surcharger les utilisateurs, évitez de poser trop de questions dans un seul message. Commencez par les questions les plus importantes et faites un suivi au besoin pour une meilleure efficacité.

Concluez cette étape quand il y a une compréhension claire des fonctionnalités que le skill devrait supporter.

Étape 2 : Planifier le Contenu du Skill Réutilisable

Pour transformer des exemples concrets en un skill efficace, analysez chaque exemple en :

1. Considérant comment exécuter sur l'exemple à partir de zéro
2. Identifiant quels scripts, références et ressources seraient utiles quand on exécute ces workflows régulièrement

Exemple : Lors de la construction d'un skill pdf-editor pour gérer des requêtes comme « Aide-moi à tourner ce PDF », l'analyse montre :

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

Exemple : Lors de la conception d'un skill frontend-webapp-builder pour des requêtes comme « Construis-moi une app todo » ou « Construis-moi un dashboard pour suivre mes pas », l'analyse montre :

1. Écrire une webapp frontend nécessite le même boilerplate HTML/React à chaque fois
2. Un template assets/hello-world/ contenant les fichiers de projet boilerplate HTML/React serait utile de stocker dans le skill

Exemple : Lors de la construction d'un skill big-query pour gérer des 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 et relations de table à chaque fois
2. Un fichier references/schema.md documentant les schémas de table serait utile de stocker dans le skill

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

Étape 3 : Initialiser le Skill

À ce moment, il est temps de créer réellement le skill.

Omettez cette étape uniquement si le skill en cours de développement existe déjà, et que l'itération ou l'empaquetage est nécessaire. Dans ce cas, continuez vers l'étape suivante.

Lors de la création d'un nouveau skill à partir de zéro, exécutez toujours le script init-skill.ts. Le script génère convenablement un nouveau répertoire de skill template qui inclut automatiquement tout ce qu'un skill nécessite, rendant le processus de création de skill beaucoup plus efficace et fiable.

Utilisation :

npx tsx scripts/init-skill.ts <skill-name> --path <output-directory>

Le script :

• Crée le répertoire de skill au chemin spécifié
• Génère un template SKILL.md avec frontmatter approprié et des placeholders TODO
• Crée les 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 l'initialisation, personnalisez ou supprimez le SKILL.md généré et les fichiers d'exemple au besoin.

Étape 4 : Éditer le Skill

Lors de l'édition du skill (nouvellement généré ou existant), rappelez-vous que le skill est créé pour être utilisé par un autre agent IA. Incluez les informations qui seraient bénéfiques et non-évidentes pour l'agent. Considérez quelles connaissances procédurales, détails spécifiques au domaine, ou ressources réutilisables aideraient un autre agent à exécuter ces tâches plus efficacement.

Apprendre les Modèles de Conception Éprouvés

Consultez ces guides utiles en fonction des besoins de votre skill :

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

Ces fichiers contiennent les meilleures pratiques établies pour une conception effective de skill.

Commencer par le Contenu du Skill Réutilisable

Pour commencer l'implémentation, commencez par les ressources réutilisables identifiées plus haut : les fichiers scripts/, references/ et assets/. Notez que cette étape peut nécessiter une entrée utilisateur. Par exemple, lors de l'implémentation d'un skill brand-guidelines, l'utilisateur peut avoir besoin de fournir les ressources de marque ou les templates à stocker dans assets/, ou 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 beaucoup de scripts similaires, seul un échantillon représentatif a besoin d'être testé pour assurer la confiance que tous fonctionnent tout en équilibrant le temps nécessaire.

Tout fichier d'exemple et répertoire non nécessaires au skill 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 skills n'en auront pas besoin de tous.

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 du skill
• description : C'est le mécanisme de déclenchement principal de votre skill, et cela aide un agent à comprendre quand utiliser le skill.
  • Incluez à la fois ce que le Skill 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 est chargé uniquement après le déclenchement, donc les sections « Quand Utiliser Ce Skill » dans le corps ne sont pas utiles à l'agent.
  • Exemple de description pour un skill docx : « Création, édition et analyse complètes de documents avec support pour les modifications suivies, commentaires, préservation du formatage et extraction de texte. À utiliser quand un agent doit travailler avec des documents professionnels (fichiers .docx) pour : (1) Créer de nouveaux documents, (2) Modifier ou éditer du 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 le skill et ses ressources regroupées.

Étape 5 : Empaqueter un Skill

Une fois le développement du skill terminé, il doit être empaqueté en un fichier .skill distribué qui est partagé avec l'utilisateur. Le processus d'empaquetage valide automatiquement le skill en premier pour assurer qu'il répond à tous les prérequis :

npx tsx scripts/package-skill.ts <path/to/skill-folder>

Spécification du répertoire de sortie optionnel :

npx tsx scripts/package-skill.ts <path/to/skill-folder> ./dist

Le script d'empaquetage va :

1. Valider le skill automatiquement, en vérifiant :

   • Le format et les champs obligatoires du frontmatter YAML
   • Les conventions de nommage de skill et la structure de répertoire
   • La complétude et la qualité de la description
   • L'organisation des fichiers et les références de ressources

2. Empaqueter le skill si la validation réussit, créant un fichier .skill nommé d'après le skill (par 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 se terminera sans créer de package. Corrigez toute erreur de validation et exécutez la commande d'empaquetage à nouveau.

Étape 6 : Itérer

Après avoir testé le skill, les utilisateurs peuvent demander des améliorations. Cela arrive souvent juste après avoir utilisé le skill, avec le contexte frais de comment le skill a performé.

Workflow d'itération :

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