Créer des compétences d’agent à partir de la documentation d’un projet et les tenir à jour

## Vérifier qui maintient une compétence avant de la modifier Déterminez le mode de gestion de chaque compétence avant de créer ou de mettre à jour des fichiers. Utilisez des compétences générées pour les projets qui publient de la documentation sans maintenir de paquet de compétences d’agent, des compétences synchronisées pour les projets qui publient déjà leurs propres compétences, et des compétences rédigées à la main pour une expertise délibérément sélectionnée. Ne mélangez pas ces processus. Les compétences générées sont synthétisées à partir de la documentation, les compétences synchronisées sont copiées depuis leur source de compétences en amont, et les compétences rédigées à la main restent intactes sauf si la tâche les inclut explicitement. ## Ne garder de la documentation que ce qui aide l’agent dans ses tâches Concentrez-vous sur les capacités, les points de décision, les modes d’utilisation pratiques, les exemples fonctionnels et les circonstances dans lesquelles un agent doit choisir une approche plutôt qu’une autre. Privilégiez les connaissances qui améliorent sensiblement l’exécution des tâches. Écartez les introductions destinées aux utilisateurs, les guides pas à pas d’installation, les documents génériques de prise en main, les textes promotionnels et les concepts qu’un modèle compétent maîtrise déjà de manière fiable. Réécrivez et synthétisez les documents sources au lieu de copier la documentation mot pour mot. Gardez la compétence compacte. Créez uniquement les références nécessaires pour traiter des concepts distincts, évitez les fichiers redondants et expliquez à la fois le fonctionnement d’un modèle et les raisons ou les circonstances qui justifient son utilisation. ## Ajouter un nouveau projet au registre et générer sa compétence Ajoutez une nouvelle source générée au registre de projets faisant autorité dans le dépôt, en indiquant son emplacement source et un identifiant de projet stable. Initialisez ou synchronisez la source à l’aide du processus pris en charge par le dépôt, au lieu de créer une copie locale non suivie. Lisez la documentation du projet et toutes les instructions de génération propres au projet de manière suffisamment complète pour comprendre ses capacités et ses conventions. Organisez les éléments utiles en catégories telles que les concepts fondamentaux, les fonctionnalités, les pratiques recommandées et les processus avancés. Créez le répertoire de sortie dont le nom correspond à l’identifiant enregistré de la source générée. Rédigez les fichiers de référence, construisez l’index de la compétence et enregistrez des métadonnées de génération contenant la révision exacte de la source. ## Mettre à jour les compétences générées seulement là où la documentation a changé Lisez la révision de la source enregistrée dans les métadonnées de génération et comparez-la à la source actuelle. Limitez la comparaison de la source à la zone de documentation qui régit la compétence générée. Mettez à jour uniquement les références touchées par cette différence, puis actualisez si nécessaire la version du projet, la date de génération, le tableau des sujets et les descriptions de l’index. Conservez les références non touchées et évitez de régénérer du contenu sans rapport simplement parce que le dépôt source a progressé. Après examen, remplacez la révision enregistrée par la révision exacte utilisée pour la mise à jour, afin que la comparaison suivante repose sur une base fiable. ## Copier les compétences maintenues en amont sans les modifier à la main Pour une compétence maintenue en amont, utilisez le registre afin de déterminer quelle compétence source copier et quel nom de sortie utiliser. Le nom de sortie peut volontairement différer du répertoire en amont ; ne le déduisez donc jamais du seul nom de la source. Lors de la première importation, copiez l’arborescence de compétences configurée et enregistrez la révision en amont dans les métadonnées de synchronisation. Pour les mises à jour, comparez la révision enregistrée au répertoire actuel des compétences en amont, copiez uniquement les fichiers modifiés inclus dans la configuration et faites progresser la révision enregistrée. Ne modifiez jamais manuellement le contenu d’une compétence synchronisée. Transmettez les corrections au responsable en amont, puis récupérez-les au moyen du processus de synchronisation afin d’éviter toute dérive des copies locales. ## Écrire un index court avec un lien vers chaque référence Dotez l’index de la compétence d’un en-tête de métadonnées valide comprenant un nom en kebab-case, une description concise de la capacité, des métadonnées de provenance, la date de génération ou de synchronisation et la version pertinente de l’outil ou du projet. Ajoutez un court paragraphe d’orientation, puis regroupez les références en catégories claires. Pour chaque sujet, fournissez une brève description et un lien relatif vers la référence correspondante, afin qu’un agent ne charge que les éléments nécessaires à la tâche en cours. Gardez l’index concis et centré sur la navigation. Ne dupliquez pas dans l’index le contenu complet des références et n’ajoutez pas d’entrées pour des fichiers inexistants. ## Traiter un seul sujet pratique par fichier de référence Dotez chaque fichier de référence d’un en-tête de métadonnées comprenant un nom stable et une description ciblée, suivi d’un titre de concept clair. Traitez une seule capacité ou un seul processus cohérent par fichier, au lieu de combiner des fonctionnalités sans rapport. Incluez des conseils pratiques d’utilisation, des exemples de code fonctionnels lorsque le concept est exécutable, les principales contraintes et le raisonnement qui sous-tend les modèles recommandés. Écartez les informations contextuelles qui n’aident pas un agent à prendre ou à exécuter une décision. Terminez par des références aux sources qui identifient la documentation utilisée pour synthétiser le contenu. Gardez ces références traçables sans transformer la compétence en copie des documents sources. ## Noter la révision source et la date de chaque compétence Pour les compétences générées, enregistrez l’emplacement de la source, sa révision exacte et la date de génération. Pour les compétences synchronisées, enregistrez l’emplacement de la compétence en amont, la révision exacte en amont et la date de synchronisation. Maintenez la version de l’index alignée sur l’état réel de la source et utilisez la date de la dernière génération ou synchronisation conformément à la politique du dépôt. Ne revendiquez pas une version ou une révision du projet plus récente que celle dont le contenu est issu. Considérez le registre comme la liste canonique des projets pris en charge et des emplacements de sources. Évitez de dupliquer des URL de dépôts susceptibles de changer ou des correspondances de responsabilité entre les fichiers de compétences lorsque le registre en est déjà le référentiel. ## Relire les derniers changements pour repérer liens cassés et révisions périmées Avant de terminer, confirmez que la classification de la source, l’entrée du registre, la règle de nommage de la sortie, les liens de l’index, les en-têtes de métadonnées des références, l’organisation des catégories, les métadonnées de révision et les citations des sources concordent tous. Vérifiez que le contenu généré est synthétisé plutôt que copié, que le contenu synchronisé ne présente aucune dérive manuelle, que les compétences rédigées à la main n’ont pas été modifiées hors du périmètre prévu et que chaque référence apporte une valeur distincte à l’agent. Examinez la différence finale afin de repérer les fichiers sans rapport, les références excessives, les versions obsolètes, les exemples manquants, les liens rompus et les modifications de sources non enregistrées. Signalez toute limitation de la source ou des outils ayant empêché une génération ou une synchronisation complète.