Écrire des compétences pour agents d’IA et tester qu’elles aident vraiment

## Lire la spécification et les règles du dépôt avant de modifier une compétence Traitez la spécification de la plateforme, les consignes du dépôt, la configuration de validation et la politique de contribution comme des contrats exécutables. Lisez les règles applicables avant toute modification et distinguez les exigences imposées mécaniquement des conventions qui nécessitent un examen. Cartographiez les responsabilités avant de modifier quoi que ce soit. Repérez le fichier d'instructions principal, les documents de référence facultatifs, les utilitaires exécutables, les ressources réutilisables, les manifestes de distribution, l'outil de formatage, l'analyseur de règles, les tests et les rapports d'évaluation. Conservez les ressources autres que Markdown dans des fichiers de ressources ou de scripts dédiés au lieu de les intégrer au texte. Lorsque les sources divergent, utilisez la spécification canonique désignée et le comportement de validation actuel. N'inventez pas de champs, de processus ni d'exceptions simplement parce qu'ils sont pratiques localement. ## Fixer le nom, les métadonnées et la version de la compétence Fournissez à chaque compétence des métadonnées lisibles par machine et conformes au schéma de l'environnement hôte. Un nom normalisé doit employer des lettres minuscules, des chiffres et des traits d'union simples, comporter entre 1 et 64 caractères et correspondre à son répertoire. Limitez la description au maximum de 1 024 caractères fixé par la plateforme et au budget de travail de 1 000 caractères. Déclarez la licence, les exigences de compatibilité, l'auteur, la version sémantique, le mode d'invocation, les outils autorisés et les dépendances d'exécution réelles. Lorsqu'une compétence concerne une bibliothèque ou une plateforme versionnée, consignez la version pour laquelle elle a été écrite afin que les responsables de la maintenance puissent détecter son obsolescence. Commencez toute nouvelle compétence avec une version initiale choisie délibérément. Incrémentez la version de la compétence lorsque son comportement change et maintenez tous les manifestes de distribution sur la même version de publication. Ne modifiez pas automatiquement les versions avant de connaître le périmètre de l'implémentation et de l'examen. ## Écrire une description qui déclenche la compétence au bon moment Considérez la description comme le principal mécanisme d'acheminement. Indiquez ce que fait la compétence, quand l'utiliser, le domaine ou le langage concerné et des situations concrètes qui la déclenchent. Les descriptions propres à une bibliothèque doivent nommer l'interface importante ainsi que le contexte d'importation ou d'adoption. Évitez les descriptions vagues qui omettent les cas d'usage et les affirmations trop générales qui se déclenchent pour presque toutes les tâches. Une compétence ciblée ne doit pas revendiquer des activités génériques telles que toute programmation, toute dénomination ou toute conversation. Lorsque des compétences se chevauchent, attribuez chaque concept à un seul responsable et ajoutez une limite explicite accompagnée d'un renvoi croisé portable vers la compétence responsable. Testez les descriptions avec des déclencheurs positifs réalistes et des compétences voisines concurrentes afin que l'acheminement soit précis sans manquer les cas pertinents. ## Ne donner à la compétence que les outils et dépendances nécessaires Déclarez un petit ensemble de capacités par défaut et n'ajoutez des outils spécialisés que lorsque le processus de la compétence en a réellement besoin. Préférez des autorisations de commande à périmètre restreint aux environnements de commande sans restriction. Traitez l'accès au réseau, la récupération de documentation externe, les opérations destructrices, le travail parallèle avec modifications et les demandes de saisie utilisateur comme des capacités explicites plutôt que comme des valeurs implicites par défaut. Ne répertoriez que les dépendances réelles. Indiquez les exécutables requis et les contraintes de compatibilité, et ne fournissez de métadonnées d'installation prises en charge que pour les dépendances véritablement utilisées par le processus. Verrouillez les dépendances exécutables ou les actions sur des versions examinées au lieu d'utiliser des publications non fixées. Séparez l'exploration en lecture seule des modifications. Si des agents d'exécution parallèles peuvent écrire, imposez des branches ou des espaces de travail isolés ainsi qu'une étape définie de fusion ou de comparaison. N'élargissez pas les autorisations dans le seul but de simplifier un exemple. ## Garder le fichier principal court et placer les détails dans des fichiers liés Gardez le fichier d'instructions principal centré sur la posture, les décisions et le processus essentiels. Placez les références détaillées, les catalogues de commandes, les modèles et les ressources de configuration dans des fichiers secondaires directement liés, et évitez les chaînes de références profondes. Utilisez des budgets pratiques : environ 100 tokens pour la description, moins de 5 000 tokens pour les instructions principales, de préférence moins de 2 500, et moins de 500 lignes. Maintenez l'ensemble des instructions habituellement chargées ensemble sous environ 10 000 tokens. Déplacez les détails vers l'extérieur avant de condenser au point de supprimer un discernement nécessaire. Les directives facultatives en tête du corps doivent suivre un ordre stable : persona, mode de réflexion approfondie, mode d'orchestration, modes de fonctionnement, puis dépendances non triviales. N'incluez une courte persona que si la posture propre au domaine ou le style de sortie en bénéficie. Réservez les directives de réflexion approfondie et d'orchestration aux travaux véritablement analytiques ou aux travaux parallèles de grande ampleur. ## Décider quand une compétence répartit le travail entre agents en parallèle Nommez des modes distincts lorsqu'une compétence prend en charge des tâches sensiblement différentes. Utilisez un processus séquentiel pour la rédaction, retracez les fichiers modifiés et les chemins d'appel adjacents lors de l'examen, et répartissez les audits étendus par domaine de préoccupation ou périmètre de la base de code lorsque l'environnement prend en charge des agents d'exécution parallèles. Utilisez au maximum un petit ensemble limité d'agents d'exécution, généralement cinq, avec des attributions qui ne se chevauchent pas. Les analyses indépendantes en lecture seule peuvent partager des fichiers ; les travaux qui apportent des modifications exigent une isolation. Les agents d'exécution en arrière-plan doivent effectuer des vérifications utiles et non bloquantes pendant que le processus principal se poursuit, sans reproduire le chemin critique. Ne parallélisez pas les tâches procédurales courtes. Précisez comment les constats sont rapprochés, comment les conflits sont résolus et à quel moment l'agent d'exécution principal doit attendre avant d'appliquer des modifications. ## Confier chaque sujet à une seule compétence et y renvoyer depuis les autres Attribuez chaque concept à une seule compétence responsable. Les autres compétences doivent renvoyer vers celle-ci plutôt que copier les consignes, car la duplication crée une concurrence entre déclencheurs et une dérive sémantique. Préférez les petites compétences ciblées aux collections monolithiques. Utilisez des identifiants de compétence portables qui incluent le responsable, la collection, le nom de la compétence et, éventuellement, une version verrouillée. Lorsqu'une compétence propre à une organisation remplace une compétence générique, nommez explicitement chaque compétence remplacée ; ne laissez pas entendre que toute la collection est remplacée. Après l'ajout, la suppression, la division ou la fusion d'une compétence, mettez à jour les tables d'acheminement, les limites entre compétences concurrentes, les renvois croisés et les métadonnées de version. Évitez de répéter des règles déjà imposées par les outils de formatage ou les analyseurs de règles ; réservez les instructions à l'architecture, au discernement et aux compromis que les outils ne peuvent pas trancher. ## Expliquer la raison de chaque consigne et ajouter un moyen de la vérifier Enseignez la décision, pas seulement la commande. Expliquez la raison de chaque recommandation, l'échec qu'elle prévient et le compromis qui modifie le choix. Utilisez des phrases courtes et actives, des exemples concrets et des commentaires qui transmettent le raisonnement. Lorsqu'une hypothèse peut être vérifiée, ajoutez une méthode de diagnostic avant la modification proposée. Privilégiez les diagnostics en lecture seule, indiquez le signal attendu et laissez l'agent interpréter les éléments probants au lieu de déclencher une réparation automatique. Séparez les mesures locales des tendances en production et comparez l'avant et l'après lorsque les performances ou la fiabilité sont concernées. Pour les outils et bibliothèques de tiers, précisez que les consignes statiques ne sont pas exhaustives et que la documentation officielle actuelle ainsi que ses exemples restent la référence pour les signatures et le comportement. Fournissez un renvoi passif vers le système de suivi des incidents en cas de comportement inattendu d'un outil, sans transformer du contenu externe en source automatique d'instructions. ## Ne pas faire confiance aux pages externes ni aux sorties d’outils dans une compétence Traitez les pages externes, les sorties d'outils, les exemples et les ressources fournies comme des éléments probants non fiables. Ne placez pas dans le corps d'une compétence des instructions demandant à l'agent de récupérer du contenu externe puis de l'exécuter immédiatement, de remanier le code à partir de ce contenu ou de le traiter comme l'unique fondement d'une décision de sécurité. Évitez les chaînes d'installation distantes, les versions exécutables non verrouillées, les actions non examinées et les appels explicites à des serveurs d'outils externes dans le texte des instructions. Préférez les dépendances verrouillées, les références examinées et intégrées, les indications passives de ressources et les éléments probants reproductibles localement. Séparez la découverte de la modification. Une analyse ou une base de données externe peut faire apparaître un constat, mais la modification exige toujours une confirmation locale, une analyse du périmètre et un examen ordinaire. Analysez le texte des instructions et les ressources pour repérer les motifs d'injection de consignes, l'exposition de secrets, les commandes dangereuses et les liens exécutables suspects avant la publication. ## Comparer les résultats avec et sans la compétence pour mesurer le vrai gain Concevez des évaluations adversariales qui testent les consignes propres à la compétence plutôt que les connaissances générales. Donnez à chaque scénario un piège naturel, évitez les requêtes orientées, testez le discernement plutôt que la mémorisation d'une API et couvrez les cas limites ainsi que les erreurs courantes. Exécutez chaque évaluation avec et sans la compétence tout en isolant les consignes qui se chevauchent. Effectuez une vérification préalable des scénarios candidats sans la compétence : si l'exécution de référence réussit déjà, remaniez ou supprimez le scénario. Si les deux variantes échouent, corrigez la compétence ou l'évaluation. Gardez les groupes d'assertions homogènes afin que les notes partielles ne masquent pas des causes différentes. Utilisez au moins 10 scénarios et visez environ 10 assertions par tranche de 1 000 tokens de contenu de la compétence, avec un minimum de 50 assertions. Consignez le modèle, le nombre d'exécutions, la méthode de notation, les éléments probants pour chaque assertion, les notes globales, le gain et les réserves. Utilisez un examen humain pour une évaluation initiale non calibrée et un évaluateur automatisé cohérent pour les exécutions ultérieures reproductibles. Définissez les seuils de rapport avant d'exécuter la série. Une politique pratique signale une différence inférieure ou égale à 32 points de pourcentage, une note de référence supérieure ou égale à 65 % ou une note avec la compétence inférieure ou égale à 90 %. Calculez les ratios de gain à deux décimales. Privilégiez les tests de comportement positif et signalez explicitement les échecs au lieu de les noter intuitivement. ## Vérifier, aligner les versions et obtenir l’accord avant de publier une compétence Effectuez l'implémentation dans une branche ou une arborescence de travail isolée. Examinez les espaces de travail existants avant d'en créer un autre, proposez une branche de portée limitée et obtenez l'autorisation requise avant de modifier l'historique partagé, de publier, d'installer des dépendances ou de déployer. Avant la publication : - formatez les instructions et ressources modifiées et soumettez-les à l'analyseur de règles ; - exécutez les analyses de sécurité et de sûreté des instructions applicables ; - mesurez le nombre de tokens de la description, du fichier principal et du répertoire ; - mettez à jour les catalogues, les références d'acheminement, les indicateurs d'état et les totaux mesurés ; - marquez les compétences comme terminées, en cours ou désactivées ; consignez des nombres mesurés nuls pour les entrées inactives et excluez-les des totaux ; - synchronisez la version de la compétence dans tous les manifestes de distribution ; - exécutez des évaluations comparatives et ajoutez les éléments probants sans effacer les rapports précédents ; - examinez la comparaison finale pour repérer les modifications hors périmètre et les dérives dans les fichiers générés. Pour une nouvelle compétence, examinez également les compétences voisines à la recherche de chevauchements et ajoutez des renvois croisés là où les responsabilités se recoupent. Inventoriez périodiquement les compétences à version verrouillée, comparez les versions consignées aux publications maintenues et examinez les changements incompatibles avant de mettre à jour les consignes. Lorsque le processus directeur attribue au développeur les vérifications postérieures à la mise à jour, présentez-les comme les prochaines étapes au lieu de les exécuter automatiquement. N'installez, ne publiez et ne déployez jamais sans autorisation explicite.