Écrire et publier des compétences d’agent qui se déclenchent bien et passent la validation

## Limiter la description à ce que fait la compétence et quand l’utiliser Traitez la description comme une métadonnée de routage, et non comme une procédure condensée. Les agents peuvent choisir une compétence à partir de sa description avant de lire le corps complet. Des étapes de processus intégrées à la description risquent donc de remplacer ou de contourner le flux de travail détaillé. Rédigez les descriptions sous la forme d’un bref énoncé de capacité suivi des conditions de déclenchement : ce que fait la compétence et quand l’utiliser. Respectez la limite du schéma actif, notamment un maximum de 1,024 caractères lorsque cette limite s’applique. Ne placez jamais d’étapes ordonnées, de séquences de mise en œuvre ni de procédures de dépannage dans la description ; mettez toutes les instructions pratiques dans le corps de la compétence. Testez les descriptions avec des requêtes réalistes pour confirmer qu’elles se déclenchent pour les demandes prévues, restent inactives pour les travaux sans rapport et conduisent l’agent aux instructions complètes. ## N’utiliser que les champs d’en-tête de la spécification et des renvois valides vers d’autres compétences Suivez la spécification de compétences active au lieu de copier les champs d’un dépôt voisin. Ne conservez au niveau supérieur que les champs définis par la spécification, notamment `name` et `description` ; utilisez `license` et `allowed-tools` uniquement conformément au contrat du dépôt. Lorsqu’il est présent, `allowed-tools` doit être une liste délimitée par des espaces. Placez les champs propres au dépôt sous `metadata`. Limitez les noms aux lettres, aux chiffres et aux traits d’union. Validez la longueur des descriptions et la formulation des déclencheurs. Maintenez les métadonnées structurées, comme l’auteur, la version sémantique, le domaine, les déclencheurs, le rôle, la portée, le format de sortie et les compétences associées, dans les énumérations et formats définis par le dépôt. Chaque entrée de compétence associée doit se résoudre vers un répertoire de compétence existant. Utilisez systématiquement la valeur de licence approuvée par le dépôt ; lorsque le dépôt impose la licence MIT, écrivez exactement `license: MIT`. N’acceptez pas de valeurs d’énumération inconnues, de références rompues ni de champs supérieurs personnalisés simplement parce que l’analyseur YAML les accepte. ## Garder le fichier principal court et placer les détails dans des fichiers de référence Gardez le fichier principal de la compétence suffisamment compact pour qu’il soit chargé comme contexte de routage et d’exploitation. Un premier niveau pratique compte environ 80 à 100 lignes comprenant le rôle, les consignes de déclenchement, un flux de travail central en cinq étapes, les comportements obligatoires et interdits, ainsi qu’une table de routage vers des références plus détaillées. Placez les informations techniques détaillées dans des fichiers de référence ciblés de second niveau, généralement longs de 100 à 600 lignes chacun. Chaque référence doit traiter un seul sujet, inclure des exemples fonctionnels complets avec les types pertinents, expliquer les cas limites et les anti-modèles, et préciser quand les consignes doivent ou ne doivent pas être utilisées. Ne chargez que les références requises par la tâche en cours. Créez des liens croisés vers les compétences associées lorsque cela est utile, sans reproduire tout leur contenu. Considérez la réduction de l’utilisation du contexte comme un résultat de conception ; une structure à deux niveaux bien routée peut viser une réduction d’environ 50% sans omettre les instructions nécessaires. ## Utiliser dans les exemples les mécanismes intégrés de chaque framework Les consignes propres à un framework doivent employer les mécanismes établis de celui-ci. Si le framework fournit une gestion globale des erreurs, un intergiciel, une injection de dépendances, des points d’accroche du cycle de vie ou une autre abstraction intégrée, les exemples doivent employer ce mécanisme plutôt que le recréer manuellement. N’imposez pas une architecture générique unique à des frameworks sans rapport dans le seul but d’obtenir une cohérence visuelle dans tout le dépôt. Les conventions du framework en matière de gestion des erreurs, d’organisation, de tests et d’intégration ont priorité. Conservez des exemples de référence complets et exécutables, avec des types lorsque le langage les prend en charge. Examinez les exemples par rapport à la version du framework concernée et rejetez les modèles qui reproduisent un comportement intégré ou masquent des contraintes propres au framework. ## Terminer chaque fichier de compétence par un seul lien vers la documentation Chaque fichier de compétence doit se terminer par exactement un lien retour canonique vers la documentation sur sa dernière ligne. Utilisez la syntaxe de lien Markdown avec le libellé `Documentation` et l’URL canonique, plutôt qu’une URL brute, afin que les moteurs de rendu stricts produisent un véritable hyperlien. Déduisez le chemin canonique de métadonnées stables, comme `metadata.domain`, et du nom du répertoire de la compétence. Appliquez le domaine de remplacement documenté en l’absence de métadonnées. Lors de l’ajout ou du renommage d’une compétence, mettez à jour ensemble le répertoire, le domaine et le lien retour ; sinon, le lien publié risque d’aboutir à une page inexistante. Prenez explicitement en compte les différents supports de publication. Les agrégateurs de fichiers bruts peuvent avoir besoin du lien retour pour faciliter la découverte, tandis que la génération de la documentation peut exclure ce même lien vers soi des pages générées, des miroirs et des index destinés aux modèles de langage. Préservez ces deux comportements lors de la synchronisation et testez la destination rendue. ## Vérifier les doublons et mettre à jour les renvois en créant ou modifiant une compétence Pour une nouvelle compétence : 1. Vérifiez si les compétences existantes ont des responsabilités qui se chevauchent. 2. Rédigez la compétence principale avec des métadonnées de capacité et de déclenchement, en laissant les étapes du processus dans le corps. 3. Ajoutez des références ciblées pour le contenu approfondi. 4. Ajoutez une table de routage reliant les sujets aux références. 5. Ajoutez l’unique lien retour canonique vers la documentation comme dernière ligne. 6. Testez des requêtes qui doivent déclencher la compétence et d’autres qui ne doivent pas la déclencher. 7. Mettez à jour le guide des compétences et les index de domaines lorsque la taxonomie change. Avant de modifier une compétence, lisez l’intégralité de son corps actuel et les références concernées par le changement. Préservez la structure de description fondée sur la capacité et le déclenchement, ainsi que l’architecture de divulgation progressive. Mettez à jour les tables de routage, les références aux compétences associées, les index de documentation et les tests de déclenchement dès que les noms, la portée, les déclencheurs ou les dépendances changent. ## Synchroniser décomptes et journal des modifications avec un seul fichier de version Utilisez un manifeste de version unique comme source de référence pour la version publiée et les décomptes calculés, notamment ceux des compétences, des flux de travail et des fichiers de référence. Exécutez l’outil de mise à jour du dépôt pour recalculer les décomptes depuis le système de fichiers et synchroniser la documentation générée. Prenez en charge les modes de vérification et de simulation afin que la CI et les responsables de la revue puissent détecter les écarts sans écrire. Ajoutez la nouvelle version au début du journal des modifications selon une structure stable Added, Changed et Fixed, et maintenez le lien de comparaison des versions. Mettez à jour les guides, les arbres de décision, les tables de commandes et les références croisées pour tout contenu nouveau ou modifié avant de régénérer la documentation agrégée. Ne régénérez les ressources pour réseaux sociaux comportant des décomptes que lorsque les valeurs intégrées changent ; un correctif portant uniquement sur la version n’exige pas de nouvelle ressource. Examinez les différences générées afin que l’automatisation ne masque pas des changements sans rapport. ## Lancer les validateurs de compétences et de Markdown avant la publication Exécutez le validateur d’intégrité des compétences avant la publication. Il doit vérifier l’analyse YAML, les champs requis, le format du nom, la longueur de la description et la clause de déclenchement obligatoire `Use when`, l’existence du répertoire de références, la structure des références et la cohérence des décomptes. Fournissez des vérifications limitées à une compétence ou à une famille de validations, ainsi qu’une sortie lisible par machine pour la CI. Exécutez séparément un validateur Markdown. Recherchez les commentaires HTML qui cassent les tableaux, les blocs de code non fermés, les lignes de séparation de tableau manquantes et les nombres de colonnes incohérents. Validez l’ensemble du dépôt après l’examen ciblé. Considérez le code de sortie 0 comme une réussite et le code de sortie 1 comme un échec de validation, tout en examinant explicitement les avertissements. Ne publiez jamais une version comportant des erreurs de validation non résolues simplement parce qu’une vérification plus restreinte a réussi. ## Consigner commandes et résultats avant d’annoncer que la publication est prête Après la synchronisation et la validation, recherchez les références de version obsolètes en excluant l’historique volontaire du journal des modifications. Confirmez manuellement que les descriptions, les tests de déclenchement, les tables de routage, les références aux compétences associées, les liens retour canoniques, les décomptes générés et les ressources conditionnelles correspondent à la publication. Préservez les attributions aux tiers, les avis de licence et les références de recherche lorsque des modèles de comportement ou une discipline de processus ont été adaptés à partir d’autres travaux. Ne perdez pas la provenance pendant le nettoyage. Consignez précisément les commandes de mise à jour et de validation, leurs résultats, les avertissements examinés et toute étape conditionnelle volontairement omise. Ne déclarez la publication prête qu’après la réussite de tous les validateurs requis et si les différences finales ne contiennent aucun changement inexpliqué.