Compétences dans les extensions
Livrez des Agent Skills dans une extension Scrydon. L'installation de l'extension ajoute chaque compétence à la bibliothèque de compétences de l'organisation, où un administrateur de l'organisation l'approuve avant qu'elle ne soit proposée à quiconque.
Cet artefact est livré dans une extension. Pour le cycle de vie partagé — extension build, téléversement, installation — voir Extensions & SDK d'authoring.
Une entrée de contenu compétence (skill) livre un dossier Agent Skills : un SKILL.md avec des instructions, plus tous les fichiers dont la compétence se sert, scripts compris. Quand une organisation installe l'extension, chaque compétence devient une compétence de la bibliothèque de compétences de cette organisation. Elle est en lecture seule, et ses versions suivent les versions de votre extension. Elle n'est proposée à personne tant qu'un administrateur de l'organisation ne l'a pas approuvée.
Structure
Chaque compétence est un dossier placé à côté du fichier d'entrée de votre extension. Listez les dossiers dans provides.skills :
aml-skills/
├── index.ts
└── skill-sar-narrative/
├── SKILL.md
└── scripts/
└── total.pyimport { defineExtension } from "@scrydon/sdk-authoring/extensions";
export default defineExtension({
id: "aml-skills",
name: "AML Skills",
version: "1.0.0",
logo: "<svg …/>",
provides: { skills: ["skill-sar-narrative"] },
});---
name: sar-narrative
description: Drafts the narrative section of a suspicious activity report from case notes and a transaction list. Use when an analyst asks for a SAR narrative.
---
# SAR narrative
Write the narrative in five parts, in this order: …provides.skills n'accepte que des chemins. Une compétence n'a pas de forme en ligne, car c'est un dossier et non une définition. extension build copie tels quels tous les fichiers de chaque dossier dans l'archive : un fichier .ts ou .py dans une compétence est un script destiné à l'agent, et la construction ne le compile jamais.
Un exemple complet se trouve dans le SDK, sous src/extensions/container/examples/aml-skills/.
Une compétence par entrée
Chaque chemin de provides.skills correspond à une compétence :
- le chemin est un seul nom de dossier, directement sous le fichier d'entrée, et non un chemin imbriqué ;
SKILL.mdse trouve à la racine de ce dossier. Un dossier qui n'en contient pas fait échouerextension validateetextension buildavecsubdir_missing_skill_md;- la compétence est livrée à la version de l'extension. Un dossier de compétence n'a pas de manifeste, il ne déclare donc jamais de version propre.
Une extension peut lister autant de compétences que nécessaire, et les combiner avec tout autre type de contenu.
Le nom
C'est le name du frontmatter de SKILL.md qui identifie la compétence, et non le nom du dossier. Il suit la règle d'Agent Skills : lettres minuscules, chiffres et traits d'union simples, 64 caractères au plus. Le nom d'une compétence d'extension doit en outre commencer par une lettre. Un nom comme 9-step-review est refusé au téléversement avec skill_name_not_content_id.
Gardez le même nom d'une version à l'autre. La bibliothèque de l'organisation garde une compétence par extension et par nom : renommer une compétence dans une version ultérieure ajoute donc une seconde compétence, au lieu d'une nouvelle version de la première. Deux extensions différentes peuvent livrer le même nom sans conflit.
description est également obligatoire, 1 024 caractères au plus. C'est ce que Cortex affiche quand quelqu'un choisit une compétence : indiquez ce qu'elle fait et quand l'utiliser.
extension validate ne vérifie que la structure. La plateforme lit le frontmatter au téléversement de l'archive : un frontmatter incorrect est détecté à ce moment-là, et non hors ligne.
Limites
Un dossier de compétence contient au plus 200 fichiers et 8 Mio au total, avec 1 Mio au plus par fichier. SKILL.md fait au plus 64 Kio. Les limites propres à l'archive s'y ajoutent : 400 fichiers et 5 Mio par fichier pour l'ensemble de l'extension.
Scripts et fichiers de verrouillage
Une compétence peut apporter des scripts (.py, .sh, .js, .ts, .rb, .ps1). Une telle compétence exécute du code, et elle suit les mêmes règles que toute autre compétence qui exécute du code dans la bibliothèque (voir Compétences qui exécutent du code) :
- elle ne s'exécute que dans le bac à sable isolé d'un agent, et seulement si l'organisation autorise les compétences qui exécutent du code ;
- le dossier fait au plus 2 Mio ;
- chaque dépendance est verrouillée par empreinte. Un
requirements.txtfixe chaque paquet avec==et un--hash=sha256:. Unpackage.jsonqui déclare des dépendances doit avoir, à côté, unpackage-lock.jsonavec une empreinte d'intégrité pour chacune.
Les fichiers de verrouillage et les autres fichiers qui ne sont pas du code, placés sous un dossier de compétence (requirements.txt, package-lock.json, fichiers de données), sont admis dans l'archive parce qu'ils se trouvent sous un chemin de compétence déclaré. Le même fichier ailleurs dans l'extension reste refusé, comme auparavant.
Une compétence qui exécute du code mais ne peut pas s'exécuter, par exemple parce qu'une dépendance n'est pas verrouillée, s'installe malgré tout. Elle est marquée comme non exécutable, elle ne peut pas être approuvée et elle n'est jamais proposée à personne. Des scripts qui n'utilisent que la bibliothèque standard du langage n'ont besoin d'aucun fichier de verrouillage.
Ce que fait l'installation
Quand un administrateur de l'organisation installe l'extension depuis Ajouter une extension, chaque compétence est écrite dans la bibliothèque de compétences de l'organisation :
- avec l'extension pour auteur, affichée « Extension id » dans la bibliothèque et dans la revue ;
- en version 1, étiquetée avec la version de l'extension ;
- au niveau de classification le plus bas de l'organisation.
L'installation ne propose la compétence à personne. Elle ouvre une seule demande en attente pour partager la compétence avec toute l'organisation. Cette demande attend la décision des administrateurs de l'organisation dans Paramètres › Cortex › Revue des skills et, dans Cortex, sous Vous › Activité. La compétence n'est proposée à l'organisation qu'une fois la demande approuvée par un administrateur de l'organisation. L'onglet Includes de l'extension liste chaque compétence et la version que détient la bibliothèque.
Une archive que vous téléversez vous-même, depuis Sources › Téléverser une extension, liste chaque compétence qu'elle contient, avec son nom et sa description, avant le téléversement.
Avec le profil OTAN, qui exige des sources d'extension signées, une extension provenant d'une source non signée ne peut pas être installée : aucune de ses compétences n'atteint la bibliothèque. Les compétences n'ont pas de vérification de signature propre : elles héritent de celle de l'extension.
Personne ne peut modifier une compétence d'extension dans la bibliothèque. Enregistrer une nouvelle version est refusé ; un membre qui veut la modifier la copie dans Les miens et modifie la copie.
Mises à jour
Installer une nouvelle version de l'extension ajoute une nouvelle version de chaque compétence dont le dossier a changé, étiquetée avec la nouvelle version de l'extension. Un dossier dont les fichiers n'ont pas changé n'ajoute aucune version.
Une nouvelle version n'arrive dans la bibliothèque que lorsqu'un administrateur l'installe, depuis Ajouter une extension ou Synchroniser. La mise à jour planifiée qui tient à jour le reste du contenu des extensions installées n'installe pas les compétences.
Quand une synchronisation de la source d'extensions trouve une version dont la bibliothèque détient déjà les dossiers de compétences, et dont le reste du contenu est installé, elle ignore cette extension : aucun administrateur n'est sollicité pour approuver une installation qui n'écrirait rien.
Une compétence appartient à la source qui l'a écrite. Si une autre source publie une extension avec le même identifiant, ou si quelqu'un la téléverse à la main, son installation est refusée avec skill_lineage_contested tant que la bibliothèque détient une version issue de la première source. Le message nomme les deux graphies de l'extension.
Une nouvelle version n'atteint jamais personne d'elle-même. Là où la compétence est déjà partagée, le partage garde la version approuvée, et une nouvelle demande attend l'approbation de la nouvelle version, selon les règles habituelles. Relancer la même installation renvoie les mêmes versions au lieu de les écrire une seconde fois.
Pas de désinstallation
L'extension ne peut pas retirer une compétence. Quand l'organisation cesse d'utiliser l'extension, ou qu'une version ultérieure abandonne une compétence, la compétence reste dans la bibliothèque à sa dernière version, et chaque partage reste en place. Pour ne plus la proposer, un administrateur de l'organisation retire le partage depuis la bibliothèque de compétences.