Créer des compétences et plugins d’agent qui se chargent et se déclenchent correctement

## Lire la documentation officielle et adapter une compétence de référence Avant d'écrire quoi que ce soit, lisez la documentation officielle à jour du système de plugins et de compétences que vous visez : le format de plugin, le format de compétence et les bonnes pratiques de rédaction publiées. La documentation de l'éditeur évolue plus vite que n'importe quel article tiers : traitez-la donc comme la source de vérité et considérez les guides communautaires comme un commentaire qui vient s'y ajouter. Choisissez ensuite une compétence de référence au niveau de complexité dont vous avez besoin et adaptez-la, plutôt que de concevoir une structure à partir de zéro : - Basique : un frontmatter minimal et un court bloc de consignes, rien de plus. - Intermédiaire : un paquet de langage, un répertoire de références et des documents spécifiques à chaque langue. - Avancé : des scripts, des fichiers de workflow, des modèles, des utilitaires d'extraction et plusieurs points d'entrée. Lire deux ou trois plugins en production issus d'autres équipes est en général plus rapide que d'inventer une arborescence. Si l'environnement fournit un agent assistant connaissant la documentation pour les questions sur les plugins et les compétences, adressez-lui ces questions au lieu d'y répondre de mémoire. ## Garder une seule source de métadonnées même si plusieurs runtimes chargent le plugin Lorsque plusieurs runtimes d'agent peuvent charger votre plugin, choisissez un seul format de métadonnées comme format canonique et n'ajoutez pas de copies annexes propres à chaque runtime. Les métadonnées dupliquées finissent par diverger, et cette divergence est découverte par les utilisateurs plutôt que par l'intégration continue. En pratique : - Gardez le manifeste de la place de marché et le manifeste propre au plugin à leur unique emplacement canonique. - Ne créez pas de répertoires de manifestes parallèles spécifiques à un runtime, ni de répertoires de métadonnées de plugin pour un second runtime. - Gardez chaque composant à la racine du plugin, en utilisant les chemins par défaut que les deux runtimes comprennent déjà : le répertoire des compétences, le fichier des hooks, le fichier de configuration MCP et le fichier de configuration de l'application. - Si un plugin a besoin d'une configuration MCP, placez-la dans le fichier de configuration MCP dédié, à la racine du plugin, au lieu d'intégrer un objet à l'intérieur du manifeste du plugin. Exécutez la vérification de chargeabilité pour chaque runtime pris en charge avant de soumettre. Lorsqu'un runtime échoue, corrigez la source canonique afin que l'autre runtime puisse la charger via la compatibilité — jamais en ajoutant une seconde copie des mêmes métadonnées. ## Placer les répertoires de composants à la racine du plugin, pas dans celui des métadonnées Un répertoire de plugin contient un répertoire de métadonnées de plugin comprenant uniquement le manifeste du plugin (nom, version, description, auteur), auquel s'ajoutent des répertoires facultatifs pour les commandes slash, les agents autonomes, les compétences et les hooks d'événements, ainsi qu'un README qui documente le plugin. Chaque compétence vit dans son propre répertoire, sous le répertoire des compétences, avec un document servant de point d'entrée qui porte le frontmatter, et des sous-répertoires facultatifs pour les références, les workflows et les scripts. La règle qui fait le plus trébucher : les répertoires de composants — compétences, commandes, agents et hooks — doivent se trouver à la racine du plugin, et non à l'intérieur du répertoire de métadonnées du plugin. Seul le manifeste du plugin y a sa place. Les chargeurs comme les relecteurs en dépendent, et un répertoire de composants mal placé se manifeste le plus souvent par un plugin qui n'expose silencieusement rien. ## Choisir un nom clair en kebab-case et remplir le frontmatter Le frontmatter du point d'entrée d'une compétence a besoin, au minimum, d'un nom et d'une description. Une liste facultative d'outils autorisés restreint la compétence aux seuls outils dont elle a réellement besoin, ce qu'il vaut la peine de définir dès que la compétence est étroite. - Le nom est en kebab-case et reste dans la limite de longueur, couramment 64 caractères. - La description est rédigée à la troisième personne et indique à la fois ce que fait la compétence et quand l'utiliser. - Préférez la forme en gérondif pour les noms : un nom commençant par un verbe, comme « analyzing-contracts » ou « processing-pdfs », se lit mieux qu'un nom d'agent nominal comme « contract-analyzer » ou « pdf-processor ». - Évitez les noms vagues tels que helper, utils, tools ou misc, qui correspondent à tout et ne veulent rien dire. - Évitez les mots réservés, y compris les noms d'éditeurs et de produits, que le runtime peut traiter de manière particulière. ## Dire dans la description ce que fait la compétence et quand l’utiliser Votre compétence est en concurrence avec une centaine d'autres pour capter l'attention, et la description est souvent le seul texte que l'agent lit au moment de décider s'il doit la charger. Une description vague signifie que la compétence reste inutilisée ou, pire, qu'elle se déclenche dans la mauvaise situation. - Voix à la troisième personne : « Analyse X », et non « J'aide avec X ». - Incluez la situation déclenchante, pas seulement le sujet : « À utiliser lors de l'audit de contrats intelligents » porte bien plus de signal d'aiguillage que « Outil pour contrats intelligents ». - Soyez précis sur la capacité : « Détecte les vulnérabilités de réentrance » vaut mieux que « Aide à la sécurité ». Rédigez la description comme s'il s'agissait de la règle d'aiguillage qu'elle est réellement, puis relisez-la en vous demandant si une compétence concurrente l'emporterait sur la même requête. ## Éviter les chemins absolus et déclarer les dépendances dans le script Ne codez jamais en dur des chemins absolus. Utilisez la variable de répertoire de base fournie par le runtime, et employez des barres obliques même sous Windows, afin que la même compétence fonctionne sur toutes les machines. Lorsqu'une compétence livre des scripts qui ont des dépendances : 1. Déclarez les dépendances directement dans l'en-tête du script, en utilisant le bloc de métadonnées en ligne standard du langage concerné, en incluant la version minimale du langage. Cela permet à l'exécuteur de tout résoudre sans étape d'installation séparée. 2. Invoquez le script via un exécuteur qui respecte ces métadonnées en ligne, pour que la résolution des dépendances soit automatique plutôt qu'un prérequis simplement documenté. 3. Conservez un fichier de projet dans le répertoire des scripts pour l'outillage de développement, comme les linters et les formateurs. 4. Documentez, dans les fichiers de workflow, les dépendances au niveau système que le gestionnaire de paquets du langage ne peut pas installer — l'outillage PDF et OCR, par exemple — avec les commandes d'installation propres à chaque plateforme. ## Garder rapides les hooks lancés avant chaque commande Les hooks qui s'exécutent avant chaque commande se trouvent sur le chemin critique : leur coût est donc payé à chaque invocation. Ici, la performance relève de la correction, pas du confort. - Préférez un shell accompagné d'un filtre JSON léger plutôt qu'un interpréteur complet. Le démarrage de l'interpréteur et de l'analyseur ajoute une latence que les utilisateurs ressentent à chaque commande. - Échouez vite : sortez avec succès et immédiatement pour les commandes qui, manifestement, ne correspondent pas, afin que l'écrasante majorité des invocations soient pratiquement gratuites. - Privilégiez les expressions régulières plutôt qu'une analyse syntaxique complète en arbre. Acceptez de rares faux positifs quand le gain de performance est significatif et que l'agent peut simplement reformuler la commande. - Anticipez les formes que prennent les faux positifs : les commandes de diagnostic qui se contentent de localiser un interpréteur, les commandes de recherche qui mentionnent son nom comme terme de recherche et les noms de fichiers contenant ce nom ne doivent pas déclencher d'interception. - Documentez ces compromis dans la description du changement, afin que les relecteurs puissent voir que ces choix étaient délibérés et non négligents. ## Expliquer quand et pourquoi chercher plutôt que coller des spécifications entières Une compétence doit apporter des consignes que le modèle n'a pas déjà. Coller une spécification entière dans une compétence consomme du contexte et n'ajoute rien que le modèle ne puisse consulter par lui-même. - Ne collez pas de spécifications complètes ni de références d'API. Apprenez plutôt quand et comment aller chercher l'information. - Expliquez le pourquoi, et pas seulement le quoi : incluez les compromis, les critères de décision et les jugements qu'un nouveau venu formulerait de travers. - Documentez les anti-patterns en même temps que la raison pour laquelle ils sont mauvais, plutôt qu'une simple liste d'interdictions. Un bon exemple de ce schéma : une compétence dédiée à un format de débogage binaire complexe n'intègre pas la spécification du format. Elle apprend vers quels outils d'inspection se tourner, comment les interroger et quel outil convient à quelle question. ## Régler la rigueur selon le risque de la tâche et dire quand ne pas utiliser la compétence La rigidité que doit avoir une compétence dépend de la fragilité de la tâche. - Strict pour les tâches fragiles : les audits de sécurité, les implémentations cryptographiques et les contrôles de conformité exigent des procédures rigides, imposées, étape par étape. - Souple pour les tâches variables : l'exploration de code, la documentation et le refactoring doivent proposer des options et laisser place au jugement. Tout point d'entrée de compétence doit comporter deux sections. Une section « Quand l'utiliser » énumérant les scénarios précis où la compétence s'applique, et une section « Quand NE PAS l'utiliser » nommant les cas où une autre approche vaut mieux. La section négative est celle que les gens sautent, et c'est elle qui empêche la compétence de se déclencher au mauvais endroit. Les compétences d'audit et de sécurité ont besoin d'une troisième section, « Rationalisations à rejeter », qui recense les raccourcis et les excuses courants menant à des constats manqués — car, sous la pression du temps, ce sont exactement ces rationalisations qui remontent. ## Garder le fichier principal court et ne lier les détails qu’à un seul niveau Gardez le point d'entrée de la compétence sous environ 500 lignes et répartissez le reste entre un répertoire de références et un répertoire de workflows. Placez le démarrage rapide en premier et les détails derrière des liens, afin qu'un lecteur qui n'a besoin que du parcours courant ne charge jamais le reste. Gardez les liens à un seul niveau de profondeur : le point d'entrée renvoie vers des fichiers, et ces fichiers ne s'enchaînent pas vers d'autres fichiers. La profondeur des répertoires, en elle-même, ne pose pas de problème — un répertoire de références avec des sous-dossiers par thème est tout à fait raisonnable. Le problème, c'est l'indirection en chaîne, pas les dossiers imbriqués. Une forme typique se compose d'une section Démarrage rapide contenant les instructions essentielles, d'une section Utilisation avancée renvoyant vers un document de référence pour les schémas détaillés, et d'une section de référence d'API renvoyant vers un autre document pour la documentation complète des méthodes. ## Passer les contrôles automatiques et humains et augmenter la version avant la revue Distinguez ce que l'automatisation valide de ce qu'un relecteur humain doit juger, et réglez les deux avant d'ouvrir une revue. Contrôles automatisés : un frontmatter valide avec un nom et une description ; un nom en kebab-case dans la limite de longueur ; chaque fichier référencé existe réellement ; aucun chemin de répertoire personnel codé en dur ; la vérification de chargeabilité passe pour chaque runtime pris en charge. Contrôles du relecteur : la description se déclenche correctement et est rédigée à la troisième personne ; les sections « Quand l'utiliser » et « Quand NE PAS l'utiliser » sont toutes les deux présentes ; les exemples sont concrets, montrant l'entrée et le résultat obtenu ; le document explique le pourquoi et pas seulement le quoi. Documentation : le plugin possède un README ; il est ajouté au tableau du README racine ; il est enregistré dans le manifeste de la place de marché au niveau du dépôt, plutôt que dans le répertoire de métadonnées propre au plugin ; et une entrée de propriété nomme les mainteneurs dans le fichier des propriétaires de code. Mises à jour de version pour un plugin existant : incrémentez la version à la fois dans le manifeste du plugin et dans l'entrée de la place de marché au niveau du dépôt, et gardez les deux numéros identiques. De nombreux clients ne récupèrent une mise à jour que lorsque le numéro de version augmente : un incrément oublié signifie donc que personne ne reçoit le correctif.