Le Registre de compétences TrueFoundry expliqué : Versionner la connaissance procédurale entre les agents

Les compétences (Skills) regroupent des instructions, des références, des scripts et des ressources dans des procédures réutilisables. Un registre rend ces bundles détectables et versionnés, mais pas automatiquement fiables.

Une compétence est un package de procédure, pas une nouvelle permission

Une compétence d'agent décrit comment exécuter une tâche récurrente. Son fichier racine SKILL.md contient un nom, une description axée sur l'action et la procédure. Un bundle plus riche peut inclure du matériel de référence, des scripts et des ressources. Cette structure sépare la connaissance procédurale d'un prompt système monolithique et permet au runtime de charger des détails uniquement lorsque la compétence est pertinente.

La distinction entre connaissance et autorité est essentielle. Une compétence peut indiquer à un agent comment interroger un entrepôt de données, trier un incident ou rédiger des notes de version. Elle n'accorde pas, en soi, d'accès à la base de données, n'autorise pas une réponse à un incident et ne garantit pas l'exactitude d'une note de version générée. Les outils, les identifiants, la politique de la gateway et les systèmes en aval restent le chemin d'autorité.

Le Registre de compétences de TrueFoundry attribue au package une identité partagée. Les compétences résident dans des dépôts (Repositories), héritent de l'accès au dépôt et de l'historique des versions, et sont adressées par des noms pleinement qualifiés (FQN) numérotés. Les équipes peuvent publier une fois et réutiliser le bundle dans les agents TrueFoundry, Claude Code ou Cursor.

La divulgation progressive réduit le contexte initial en exposant uniquement les métadonnées de sélection. Elle ne rend pas la procédure sélectionnée sûre pour autant ; le bundle complet reste donc un artefact gouverné.

La divulgation progressive est la conception au runtime

TrueForge indique qu'une compétence rattachée ne contribue qu'à travers son nom et sa description au contexte initial du modèle. Le corps complet du fichier SKILL.md est lu à la demande depuis le sandbox lorsque l'agent décide que la compétence est pertinente. Cela réduit le contexte initial tout en maintenant la procédure disponible.

La description constitue donc une surface de routage. Si elle est vague, l'agent peut échouer à sélectionner la compétence ou la choisir pour la mauvaise tâche. Veillez à ce qu'elle soit axée sur l'action, indiquez clairement quand la compétence doit être utilisée et évitez les chevauchements de descriptions qui rendent la sélection ambiguë. Le comportement de sélection doit être évalué avec des requêtes utilisateur réalistes, y compris des cas limites.

Le chargement progressif contrôle la taille du contexte ; il n'isole pas le contenu non approuvé. Une fois sélectionné, le corps de la compétence et les fichiers d'assistance influencent l'agent. Les scripts peuvent s'exécuter dans le sandbox configuré, et les références peuvent façonner l'utilisation des outils. Traitez une compétence multifichiers comme un artefact logiciel doté d'une chaîne d'approvisionnement.

Trois parcours de publication, un artefact versionné

TrueFoundry documente trois parcours de publication. L'UI crée une compétence à fichier unique dont le corps est le contenu SKILL.md rédigé dans l'éditeur. Les bundles multifichiers utilisent la commande d'upload de la CLI ou un manifeste déclaratif appliqué via GitOps. Tous les parcours créent une compétence versionnée sous un dépôt et génèrent un FQN tel qu'une compétence qualifiée par son dépôt à la version 1.

L'UI ne prend actuellement en charge que le fichier unique SKILL.md. Les références, scripts et ressources nécessitent de passer par la CLI ou GitOps ; la prise en charge multifichiers dans l'UI est documentée dans la feuille de route. La CLI valide le frontmatter et téléverse le bundle. GitOps pointe un manifeste vers un répertoire de compétences local et publie via le même workflow d'application utilisé pour les autres ressources TrueFoundry.

Les parcours de publication diffèrent sur le plan opérationnel mais convergent vers le même dépôt et la même identité de version. Cette identité permet aux agents et aux surfaces de codage locales de consommer un bundle concret plutôt qu'une copie informelle.

L'accès au dépôt est hérité

Dans le modèle documenté, les compétences ne disposent pas de autorisations individuelles distinctes. Les droits de découverte, de modification et d'utilisation proviennent du dépôt parent. Cela fait des limites des dépôts l'unité pratique de gouvernance. Regroupez les compétences par propriété et sensibilité compatibles plutôt que de placer chaque procédure dans un seul catalogue doté d'un accès large.

L'accès au dépôt détermine qui peut récupérer ou utiliser le bundle. Il ne restreint pas chaque action recommandée par la compétence. Un utilisateur autorisé à utiliser une compétence de base de données a toujours besoin d'une autorisation au niveau de l'outil de base de données et des ressources métier. À l'inverse, révoquer une compétence ne révoque pas nécessairement l'accès à l'outil sous-jacent.

Le verrouillage des versions est le fondement de la reproductibilité

La documentation de la CLI Skills exige une version sous forme d'entier positif lors du téléchargement et indique qu'un alias latest n'est pas pris en charge. C'est une propriété opérationnelle utile : les consommateurs désignent un bundle concret. Verrouillez cette même version concrète dans la configuration de l'agent et dans les environnements de développement locaux lorsque vous avez besoin d'un comportement comparable.

Une version a toujours besoin de traçabilité. Enregistrez le commit du dépôt source, l'auteur de la publication, le processus de build ou de packaging, les empreintes (digests) des fichiers, les dépendances et le résultat de la revue. Pour les scripts, verrouillez les packages externes et enregistrez l'environnement d'exécution. Un FQN numéroté identifie ce que le registre a stocké ; la traçabilité explique comment ce bundle a été produit.

Les scripts et les références créent des risques différents

Les fichiers de référence peuvent être obsolètes, incomplets ou modifiés de manière malveillante. Les scripts peuvent lire et transformer des données, invoquer des commandes locales ou appeler des services via les interfaces disponibles. Les ressources peuvent contenir du contenu actif ou malformé. Examinez chaque classe avec un contrôle approprié plutôt que de traiter le répertoire comme du Markdown indifférencié.

Les contrôles statiques peuvent valider le frontmatter, la traversée de répertoires (path traversal), la structure des archives, la taille des fichiers, les binaires interdits, les déclarations de dépendances et les modèles dangereux connus. Des tests en sandbox peuvent exécuter des scripts avec des entrées synthétiques et un accès réseau refusé. Les évaluations de tâches peuvent mesurer si l'agent sélectionne la compétence et respecte ses contraintes. La revue humaine doit se concentrer sur les procédures privilégiées et les actions irréversibles.

Le pipeline d'admission sépare le stockage, l'inspection, la performance des tâches et l'autorisation au runtime. Aucun contrôle unique ne certifie l'ensemble des propriétés d'une compétence.

La promotion doit prendre en compte les consommateurs

La même compétence peut être utilisée par un agent TrueFoundry, Claude Code et Cursor, mais ces surfaces ne partagent pas nécessairement des modèles, des outils, un sandbox ou des identités d'utilisateur identiques. La portabilité du format n'équivaut pas à une équivalence de comportement au runtime. Testez la compétence dans chaque surface prise en charge et consignez l'environnement dans le résultat.

Une compétence sûre lorsqu'elle est associée à des outils MCP en lecture seule peut devenir risquée lorsqu'un environnement de codage local expose un accès en écriture et des commandes shell. Les métadonnées de publication doivent nommer les dépendances d'outils attendues, les autorisations requises, les versions de runtime compatibles et les environnements interdits.

Un cycle de vie rigoureux des compétences

Commencez par une tâche précise et une description qui rend la sélection testable. Rédigez la procédure avec des préconditions explicites, les outils autorisés, les exigences de preuve, la gestion des erreurs et les règles d'arrêt. Publiez une version candidate. Exécutez des tests statiques, en sandbox et comportementaux. Admettez-la pour les consommateurs désignés. Observez la sélection, l'utilisation des outils, les échecs et les résultats. Décommissionnez la version en retirant les consommateurs et les accès, puis conservez les preuves requises par la politique de sécurité.

Ne modifiez pas directement une compétence largement utilisée via une distribution informelle de fichiers. Publiez une nouvelle version, comparez le bundle complet (diff) et déployez progressivement auprès des consommateurs. Lorsqu'une vulnérabilité est découverte dans un script ou une référence, identifiez chaque agent et surface de développement consommateurs grâce à l'inventaire des versions.

Les versions numérotées sont des identités, pas des promesses de compatibilité

Un numéro de version indique aux consommateurs quel bundle ils ont reçu. Il ne communique pas, en soi, si une mise à jour est rétrocompatible. Un nom d'outil modifié, un chemin d'accès au fichier, un schéma de sortie ou une autorisation requise peuvent interrompre le fonctionnement d'un agent même si la procédure semble similaire à la lecture.

Publiez des métadonnées de compatibilité aux côtés du bundle : runtime attendu, outils requis, contrats d'entrée et de sortie pris en charge, versions des dépendances, classifications des données et migrations connues. Pour les changements de rupture, maintenez la version précédente disponible suffisamment longtemps pour que les consommateurs puissent migrer délibérément. Évitez d'apprendre aux agents à télécharger un bundle "latest" changeant au runtime ; résolvez le numéro approuvé lors de la publication.

L'inventaire est essentiel pour la réponse aux incidents

Lorsqu'une référence devient fausse ou qu'une dépendance de script est compromise, les équipes d'intervention doivent répondre rapidement à deux questions : quelles versions contiennent le problème, et où ces versions sont-elles utilisées ? L'identité du registre fournit le premier point d'ancrage, mais l'inventaire des consommateurs doit inclure les agents TrueFoundry ainsi que toutes les installations locales de Claude Code ou Cursor synchronisées à partir du registre.

Les copies locales peuvent survivre aux modifications d'accès au dépôt. La révocation de l'autorisation d'utilisation empêche toute récupération future, mais n'efface pas un bundle déjà téléchargé sur la machine d'un développeur. Les plans d'incident doivent distinguer le confinement dans le registre, le détachement au runtime, la correction locale, la révocation des identifiants d'outils et la réconciliation en aval. Le décommissionnement n'est complet que lorsque l'autorité à risque et les copies affectées ont été traitées.

L'évaluation des résultats doit suivre la procédure

L'évaluation d'une compétence nécessite plus que des tests de sélection. Vérifiez que l'agent respecte les préconditions, utilise les outils prévus, respecte les limites de lignes ou de coûts, gère les données manquantes, cite les bonnes références et s'arrête avant de générer des effets non autorisés. Vérifiez ensuite le résultat effectif de la tâche. Une trajectoire d'outil syntaxiquement correcte peut tout de même produire un mauvais résultat métier.

Stockez le FQN de la compétence avec chaque évaluation et trace d'exécution au runtime. Cela permet aux équipes de comparer les versions, de détecter les régressions et de déterminer si un échec provient de la compétence, du modèle, de l'outil, des données ou de la politique globale. Sans le lien vers la version, il devient impossible de gouverner une procédure partagée à grande échelle.

Tests d'échec utiles à conserver

• Utilisez des prompts qui doivent et ne doivent pas sélectionner la compétence ; mesurez les fausses sélections et les sélections manquées.
• Publiez un bundle multifichiers contenant des chemins inattendus, des liens symboliques, des fichiers trop volumineux et des dépendances non déclarées.
• Modifiez uniquement un script ou une référence d'assistance ; confirmez que le diff du bundle et le changement de version l'exposent clairement.
• Exécutez la même version sur l'ensemble des surfaces prises en charge et comparez la portée et le comportement des outils.
• Révoquez l'accès d'utilisation au dépôt et confirmez que les consommateurs ne peuvent pas récupérer une nouvelle copie.
• Retirez une compétence d'un agent tout en laissant l'accès aux outils intact ; confirmez que la distinction est comprise.
• Décommissionnez une version vulnérable et faites l'inventaire de chaque consommateur verrouillé avant de déclarer la correction terminée.

Comment le Registre de compétences et TrueForge s'articulent

Le Registre de compétences est la surface de distribution et de gouvernance pour les bundles procéduraux versionnés. TrueForge est le runtime qui expose les métadonnées des compétences rattachées, charge la procédure complète à la demande et exécute les travaux d'assistance via son sandbox et ses outils. L'AI Gateway et l'MCP Gateway gouvernent le trafic des modèles et des outils autour de ce runtime.

Aucune de ces couches ne certifie une procédure à elle seule. L'intérêt de la plateforme réside dans sa complémentarité : l'identité du registre et l'accès au dépôt, la gestion du contexte au runtime, l'autorisation des outils et les preuves peuvent s'aligner autour de la même version de compétence verrouillée.

La règle opérationnelle

Traitez les compétences comme des artefacts de publication équivalents à du code. Conservez des descriptions précises, verrouillez les versions numérotées, examinez le bundle complet, testez la sélection et l'exécution, et limitez le périmètre des dépôts aux véritables frontières de responsabilité.

Le registre de TrueFoundry rend la connaissance procédurale réutilisable entre les agents et les surfaces de développement. TrueForge rend cette connaissance économique à charger au runtime. Le système ne devient fiable que lorsque le versionnement est associé à l'admission, au moindre privilège, au sandboxing et aux preuves de résultats.

Références

1. TrueFoundry — AI Gateway Skills Registry.
2. TrueFoundry — Create, Manage, and Use Skills.
3. TrueForge — Skills.
4. TrueForge — Harness Capabilities.

Avertissement éditorial. Cet article reflète l'interprétation technique par TrueFoundry des documents publics cités en date du 19 septembre 2026. Les capacités des produits sont limitées à la documentation liée. Les exemples et les paramètres par défaut sont présentés à titre illustratif ; ils ne constituent pas un conseil juridique, un avis d'audit, une évaluation indépendante ou une garantie de sécurité ou de conformité.

‍