Compétences
Enregistrer, partager, approuver et charger des instructions réutilisables (Agent Skills) par les opérations de la bibliothèque de compétences, et savoir ce qui est proposé à un tour
La bibliothèque de compétences conserve les instructions réutilisables que les
personnes écrivent pour Cortex : une compétence est un dossier au format Agent
Skills, qui dans cette version se limite à un seul SKILL.md. Une personne
enregistre une compétence, l'améliore dans de nouvelles versions, partage une
version avec une équipe ou toute l'organisation, et la charge dans un tour de
conversation lorsqu'elle y est proposée.
Chaque opération agit pour une personne. La plateforme tire cette personne, son
organisation, ses équipes, son habilitation et la classification à laquelle un
tour s'exécute de l'appel vérifié, jamais de vos paramètres. Un appel fait pour
aucune personne est refusé avec FORBIDDEN.
import { createHttpPlatformTransport, createScrydonSDK } from '@scrydon/sdk/platform'
const platform = createScrydonSDK(
createHttpPlatformTransport({
baseUrl: 'https://scrydon.com',
headers: () => ({ authorization: `Bearer ${accessToken}` }),
})
)
const saved = await platform.skills.create({
skillMd: '---\nname: board-memo\ndescription: House style for board memos\n---\n# Board memo\n…',
changeNote: 'First version',
idempotencyKey: 'board-memo-v1',
})
const shared = await platform.skills.share({
versionId: saved.versionId,
target: { kind: 'team', teamId: '6f1c…' },
idempotencyKey: 'board-memo-v1-finance',
})
// shared.outcome vaut 'live' ou 'pending'Opérations
Chaque opération est un POST. Les lectures exigent le scope skills:read, et
les écritures skills:write. Le tableau est généré à partir du registre des
opérations du SDK.
| Opération | HTTP | Scope | Ce qu'elle fait |
|---|---|---|---|
skills.offered.list | POST /api/platform/v1/skills/offered/list | skills:read | Liste les compétences que cet appel peut charger : à la classification du salon désigné par roomId, sinon à la classification à laquelle il s'exécute. Ne renvoie jamais de contenu. N'enregistre rien. |
skills.load | POST /api/platform/v1/skills/load | skills:read | Charge une compétence proposée : son SKILL.md, son empreinte, les outils qu'elle demande et la liste de ses fichiers, et pour une compétence qui exécute du code son folder. Vérifie d'abord la compétence contre l'offre, et enregistre le chargement dans le journal d'audit. |
skills.library.list | POST /api/platform/v1/skills/library/list | skills:read | Un onglet de votre bibliothèque (mine, groups ou organization), une page à la fois. |
skills.get | POST /api/platform/v1/skills/get | skills:read | Une compétence : son résumé, les versions que vous pouvez lire, et les partages qui suivent une version que vous pouvez lire. |
skills.versions.get | POST /api/platform/v1/skills/versions/get | skills:read | Une version complète : SKILL.md, empreinte, fichiers, contrôles, classification et approbations reçues. |
skills.create | POST /api/platform/v1/skills/create | skills:write | Enregistre une nouvelle compétence en version 1. Vous en êtes l'auteur. |
skills.versions.create | POST /api/platform/v1/skills/versions/create | skills:write | Enregistre une nouvelle version de votre propre compétence. baseVersionId doit être sa dernière version. |
skills.imports.preview | POST /api/platform/v1/skills/imports/preview | skills:write | Lit un envoi (un zip, un tar.gz ou les fichiers d'un dossier) et liste chaque compétence qu'il contient comme prête, refusée ou bloquée. N'enregistre rien. |
skills.imports.commit | POST /api/platform/v1/skills/imports/commit | skills:write | Enregistre dans vos propres compétences les compétences prêtes que vous nommez dans un envoi, chacune en version 1. Toutes sont enregistrées, ou aucune. |
skills.drafts.generate | POST /api/platform/v1/skills/drafts/generate | skills:write | Rédige une nouvelle compétence, ou une modification de l'une des vôtres, à partir d'un court extrait de conversation, par le modèle de langage de votre organisation. Envoyez le roomId du salon et l'appel au modèle s'exécute au moins à la classification de ce salon. N'enregistre rien. |
skills.drafts.save | POST /api/platform/v1/skills/drafts/save | skills:write | Enregistre votre brouillon non enregistré : un par compétence, et un pour une nouvelle compétence. Envoyez le roomId du salon quand le brouillon est conservé dans un salon. |
skills.drafts.get | POST /api/platform/v1/skills/drafts/get | skills:read | Relit ce brouillon, avec le roomId du salon où il a été conservé. |
skills.drafts.delete | POST /api/platform/v1/skills/drafts/delete | skills:write | Abandonne ce brouillon. deleted vaut false lorsqu'il n'y en avait aucun. |
skills.fork | POST /api/platform/v1/skills/fork | skills:write | Copie une version de la compétence de quelqu'un d'autre dans vos propres compétences, en version 1, liée à sa source. |
skills.share | POST /api/platform/v1/skills/share | skills:write | Partage une version avec une équipe ou l'organisation. Le partage est actif aussitôt ou ouvre une demande ; dryRun vous dit lequel et n'écrit rien. |
skills.requests.list | POST /api/platform/v1/skills/requests/list | skills:read | Les demandes de partage que vous pouvez trancher, et les partages actifs récents dans les équipes que vous administrez. |
skills.requests.decide | POST /api/platform/v1/skills/requests/decide | skills:write | Approuve ou refuse une demande de partage. |
skills.grants.pullBack | POST /api/platform/v1/skills/grants/pull-back | skills:write | Retire un partage : l'équipe ou l'organisation revient à la version qu'elle suivait avant, ou perd la compétence s'il n'y en avait aucune. |
skills.bundles.get | POST /api/platform/v1/skills/bundles/get | skills:read | Les compétences épinglées d'un agent : la version de chaque épingle, si elle est encore proposée, et une version newer vers laquelle vous pourriez la déplacer. bundle vaut null avant la première épingle. |
skills.bundles.pin | POST /api/platform/v1/skills/bundles/pin | skills:write | Épingle sur un agent une version d'une compétence qui vous est proposée. Épingler à nouveau la même version ne change rien. |
skills.bundles.update | POST /api/platform/v1/skills/bundles/update | skills:write | Déplace une compétence épinglée vers une autre version qui vous est proposée, comme sa version newer. Une épingle ne bouge jamais d'elle-même. |
skills.bundles.unpin | POST /api/platform/v1/skills/bundles/unpin | skills:write | Retire une compétence de l'agent. Désépingler une compétence qui n'est pas épinglée ne change rien. |
skills.bundles.detach | POST /api/platform/v1/skills/bundles/detach | skills:write | Donne à l'agent sa propre copie d'une liste qu'il partage avec d'autres agents, pour que ses changements cessent de les atteindre. |
skills.bundles.rename | POST /api/platform/v1/skills/bundles/rename | skills:write | Nomme la liste de l'agent, ou efface son nom. Une liste que partagent plusieurs agents exige une personne qui peut modifier chacun d'eux. |
skills.bundles.attach | POST /api/platform/v1/skills/bundles/attach | skills:write | Donne à un agent une liste qu'un autre agent détient déjà, pour que les deux l'utilisent. Chaque épingle doit être une version qui vous est proposée. Une liste sans nom exige un name. Attacher la liste que l'agent détient déjà ne change rien. |
skills.admin.library.list | POST /api/platform/v1/skills/admin/library/list | skills:read | Réservé aux administrateurs de l'organisation. Chaque compétence de l'organisation qui a déjà été partagée, à la plus récente version partagée que couvre votre habilitation, avec ses partages, une éventuelle demande en attente et ses utilisations ce mois-ci. |
skills.admin.requests.list | POST /api/platform/v1/skills/admin/requests/list | skills:read | Réservé aux administrateurs de l'organisation. Chaque demande de partage de l'organisation, de la plus récente à la plus ancienne, chacune indiquant dans canDecide si vous pouvez la trancher. |
skills.admin.loads.list | POST /api/platform/v1/skills/admin/loads/list | skills:read | Réservé aux administrateurs de l'organisation. Les chargements d'une compétence, du plus récent au plus ancien : quand, pour qui, quelle version, pourquoi, et la classification du salon, pour chaque version que vous pouvez lire. |
skills.admin.bundles.list | POST /api/platform/v1/skills/admin/bundles/list | skills:read | Réservé aux administrateurs de l'organisation. Chaque liste de compétences qu'un agent détient, de la plus récente à la plus ancienne, avec les agents qui la détiennent et ses épinglages. En lecture seule. |
skills.create, skills.versions.create et skills.fork exigent une
idempotencyKey, tout comme skills.share sauf s'il s'agit d'un dryRun. La
même clé avec le même corps, de la même personne, renvoie le premier résultat et
n'écrit rien de plus. La même clé avec un autre corps, ou d'une autre personne,
est refusée avec idempotency_key_reused. Trancher deux fois une demande dans le
même sens renvoie son état actuel.
Les écritures skills.bundles.* ne prennent pas de clé : envoyer la même à
nouveau laisse la liste de l'agent telle que la première l'a laissée.
Disponibilité
La bibliothèque de compétences a besoin de son stockage dans votre déploiement.
Lorsqu'il n'y est pas, chaque opération skills.* répond
CAPABILITY_NOT_CONFIGURED (HTTP 409) et ne fait rien.
Qui peut faire quoi
| Action | Qui |
|---|---|
| Lire une compétence et ses versions | Son auteur ; les membres d'une équipe avec laquelle la compétence est partagée ; chaque membre lorsqu'elle est partagée avec l'organisation ; les administrateurs d'une équipe dans laquelle elle attend une approbation ; et les administrateurs de l'organisation, pour toute compétence qui a déjà été partagée ou proposée au partage. Une compétence jamais partagée n'est visible que de son auteur. Dans tous les cas, votre habilitation doit couvrir la classification de la version. |
| Enregistrer une compétence, ou une nouvelle version | L'auteur uniquement. Pour améliorer la compétence de quelqu'un d'autre, copiez-la dans vos propres compétences. |
| Partager avec une équipe | L'auteur, avec n'importe quelle équipe de l'organisation. |
| Partager avec l'organisation | L'auteur, par une demande. Un administrateur de l'organisation qui n'est pas le demandeur l'approuve. |
| Approuver ou refuser une demande d'équipe | Les administrateurs de cette équipe. Lorsque l'équipe n'a pas d'administrateur, un administrateur de l'organisation qui n'a pas fait la demande. |
| Donner une seconde approbation | Un administrateur de l'organisation autre que le premier approbateur et le demandeur. |
| Retirer un partage | Les administrateurs de l'équipe, les administrateurs de l'organisation, ou l'auteur. |
Quand un partage devient actif
skills.share répond outcome: 'live' lorsque l'équipe suit la version
aussitôt, et 'pending' lorsqu'elle attend une approbation. La première règle
qui s'applique décide, et reasons liste ce qui s'est appliqué :
- La cible est l'organisation : un administrateur de l'organisation approuve (
organization). - La version exécute du code : un administrateur d'équipe approuve, et un second approbateur aussi lorsque votre organisation en exige un (
runs_code). - Un contrôle a signalé quelque chose, comme des caractères cachés ou un texte reconnu par votre prévention des pertes de données : un administrateur d'équipe approuve (
checks_flagged). - Votre organisation exige une approbation pour partager avec une équipe (
approval_required), ou votre déploiement l'exige (nato_floor) : un administrateur d'équipe approuve. - Sinon, le partage est actif aussitôt. Les administrateurs de l'équipe le voient dans leurs demandes et peuvent le retirer.
Un administrateur d'équipe qui partage dans sa propre équipe approuve le partage en le faisant. Un second approbateur, lorsque la règle 2 en exige un, reste nécessaire.
Une nouvelle version ne fait pas avancer une équipe d'elle-même. Enregistrer ne touche à aucun partage : l'équipe garde la version qu'elle suit jusqu'à ce que la nouvelle soit partagée avec elle, et approuvée lorsqu'une approbation est nécessaire.
Classification
Chaque version porte une classification du schéma de votre organisation.
- Enregistrée depuis une conversation. Envoyez le
roomIddu salon. La plateforme lit elle-même la classification du salon et vérifie que vous en êtes membre, et la version prend cette classification. N'envoyez pas declassificationen plus : la paire est refusée avecroom_save_classified. - Écrite ailleurs. Envoyez une
classification, ou omettez-la pour utiliser la classification des données non étiquetées de votre organisation.
skills.drafts.generate accepte aussi un roomId, pour le salon dont provient
l'extrait. La plateforme lit la classification de ce salon de la même façon, et
l'appel au modèle de langage s'exécute à la plus élevée de celle-ci et de la
classification à laquelle l'appel s'exécute. Un salon classifié sous un autre
schéma que l'appel est refusé avec scheme_mismatch.
skills.versions.get renvoie aussi les dependencies de la version : une
entrée par paquet que déclare un requirements.txt ou un package.json de la
compétence, avec son ecosystem (pypi ou npm), son name, sa spec, s'il
est épinglé (pinned) et le path du fichier qui le déclare. Une dépendance
non épinglée figure aussi dans les contrôles de la version. Une plateforme
antérieure à dependencies l'omet, ce qui signifie que la liste n'a pas été
indiquée, et non qu'elle est vide. Mettez à jour le SDK avec la plateforme ou
avant elle : les résultats sont vérifiés strictement, donc un SDK plus ancien
que la plateforme refuse une version qui porte dependencies.
Vous ne pouvez pas enregistrer une version au-dessus de votre propre habilitation
(above_clearance). Chaque lecture, décision et chargement vérifie que votre
habilitation couvre la version.
Le SKILL.md est contrôlé par la prévention des pertes de données de votre
organisation lors de son enregistrement. Une correspondance que votre politique
bloque refuse l'enregistrement avec POLICY_BLOCKED et details.policyCode
LLM_BLOCKED_BY_DLP. Une correspondance que votre politique signale seulement
est enregistrée, signalée dans les contrôles de la version et consignée dans le
journal d'audit ; la partager exige alors un administrateur d'équipe. Le partage
ne relance pas l'analyse, et une copie garde les contrôles de la version qu'elle
copie.
Une version enregistrée avec skills.versions.create en dessous d'une version
antérieure de la même compétence est enregistrée et signalée
classification_below_version (SKILL_CHECK.CLASSIFICATION_BELOW_VERSION). Le
signalement porte le nouveau rank, ainsi que le versionNumber et le
versionRank de la version antérieure de rang le plus élevé dans le même
schéma de classification. La partager exige alors un administrateur d'équipe,
comme toute version signalée. Les versions écrites par une extension ne sont
pas comparées. Un client qui analyse les contrôles avec un SDK
antérieur à ce signalement rejette une version qui le porte : mettez donc le SDK
à jour avant la plateforme.
Ce qui est proposé à un tour
skills.offered.list et skills.load travaillent à la classification à
laquelle l'appel s'exécute : celle qu'il affirme, ou la classification des
données non étiquetées de votre organisation lorsqu'il n'en affirme aucune. Vous
ne l'envoyez jamais dans le corps.
Un écran qui liste les compétences d'un salon, comme la palette / de Cortex,
envoie plutôt le roomId de ce salon à skills.offered.list. La plateforme lit
elle-même la classification du salon, en votre nom, et calcule l'offre à ce
niveau ; la classification du résultat l'indique. Un salon dont vous n'êtes pas
membre est refusé avec not_room_member, et un salon dont l'étiquette est
illisible avec room_band_unreadable : aucun des deux ne retombe sur une valeur
par défaut. skills.load n'accepte pas de roomId. Un tour dans ce salon charge
à la classification du salon, donc une compétence proposée au salon peut être
chargée par le tour, sauf si la classification du salon a changé entre-temps.
Une personne se voit proposer :
- ses propres compétences, à leur dernière version ;
- chaque version que suivent ses équipes ;
- la version que suit l'organisation.
Puis, dans cet ordre :
- Tout ce que le tour ne peut pas charger est écarté : une compétence archivée, une version sous un autre schéma de classification, une version au-dessus de la classification du tour, et une version que votre habilitation ne couvre pas. Lorsque votre organisation désactive les compétences personnelles, vos propres compétences ne vous parviennent que par un partage. Ensuite, une compétence que vous avez copiée est écartée, mais seulement tant que votre copie est proposée au tour, car votre copie la remplace. Cela vaut aussi pour une copie qui ne vous parvient que par une équipe ou par l'organisation avec laquelle vous l'avez partagée. Une copie que le tour ne peut pas charger ne masque rien : l'originale vous est donc proposée.
- Une seule version par compétence est gardée : la vôtre, sinon le numéro de version le plus élevé, sinon celle d'une équipe avant celle de l'organisation. Une version écartée à l'étape 1 n'en masque jamais une autorisée : vous recevez donc la version 7 de votre équipe lorsque votre propre version 9 est au-dessus du tour.
- Chaque compétence reçoit un identifiant, son
name. Deux compétences proposées portant le même nom reçoivent chacune leur origine en suffixe, commesar-narrativeetsar-narrative-fincrime. queryrestreint la liste par nom, titre et description. Elle est triée par titre, etlimitla plafonne (25 par défaut, 50 au plus).
skills.load relance la même offre pour l'appel et refuse une compétence qui
n'y figure pas avec not_offered. Il vérifie toute l'offre, pas une seule page,
donc toute compétence qu'une recherche pourrait trouver peut être chargée.
Passez versionId pour exiger la version exacte qui vous a été proposée.
Compétences qui exécutent du code
Une version exécute du code lorsqu'elle contient un fichier sous scripts/ ou un
fichier de script comme .py ou .sh. Elle n'est proposée qu'à un tour d'agent
qui peut l'exécuter, et seulement si toutes ces conditions sont réunies :
- la politique de compétences de votre organisation autorise les scripts
(
scriptsAllowed), et la classification de la version est au niveau descriptsMaxRankou en dessous ; - l'appel vient d'un tour d'agent qui s'exécute dans le bac à sable microVM avec ses outils. L'environnement d'exécution des agents de la plateforme le signe sur l'appel ; aucune application ne peut l'affirmer, et un appel venu d'ailleurs, Cortex compris, ne se voit jamais proposer une compétence qui exécute du code ;
- la version peut s'exécuter : son dossier est stocké, et ses contrôles ne portent
pas l'indicateur
not_runnable.
Partout ailleurs, skills.load la refuse avec not_runnable, et le message dit
quelle condition a échoué, par exemple This skill runs code that may not run here: this step does not run on the microVM tier with the sandbox tools. Une
version qui n'aurait de toute façon pas pu vous être proposée reste refusée avec
not_offered. Une palette / la liste quand même, en dernier, pour pouvoir
l'afficher comme indisponible.
Une version enregistrée avant que les compétences puissent exécuter du code est
jugée au chargement : un dossier de plus de 2 Mio, ou une dépendance non
verrouillée par empreinte, est refusé avec not_runnable et le fichier en
cause, et rien n'est chargé.
Une version qui exécute du code est contrôlée à l'enregistrement. Ses contrôles
portent not_runnable (SKILL_CHECK.NOT_RUNNABLE), avec un code de
SKILL_RUN_REFUSALS et le path du fichier en cause, lorsqu'elle ne peut pas
s'exécuter :
code | Pourquoi |
|---|---|
too_large_to_run | Le dossier dépasse 2 Mio. |
dependencies_not_locked | Une dépendance n'est pas verrouillée par empreinte : une ligne de requirements.txt sans == et --hash=sha256:, ou une ligne d'option comme -r ; un package.json qui déclare dependencies ou optionalDependencies sans package-lock.json (version 2 ou plus) à côté, nommant chacune avec une empreinte d'intégrité. |
Une telle version ne peut être ni partagée ni approuvée (not_runnable).
Un fichier qui s'exécute et récupère lui-même un paquet est également signalé,
avec runtime_install (SKILL_CHECK.RUNTIME_INSTALL), le path, la line
(à partir de 1) et la command de la première commande de ce type dans chaque
fichier, par exemple pip install ou npx. C'est un signalement pour la
personne qui approuve la compétence, pas un refus, et il repose sur une
recherche de texte : une commande qu'un script construit pendant son exécution
n'est pas détectée, et le bac à sable atteint les registres de paquets
qu'autorise la politique de sortie de votre organisation.
Le chargement d'une version qui exécute du code renvoie folder : chaque fichier
du dossier, { path, data } avec les octets en base64, dans l'ordre des chemins.
Les fichiers correspondent à digest, et le bac à sable de l'agent le vérifie
avant de les écrire, en lecture seule, puis installe lui-même les dépendances
verrouillées (pip install --require-hashes,
bun install --frozen-lockfile --ignore-scripts). folder est absent pour une
version qui ne fait qu'instruire.
Lorsque votre organisation définit un miroir de dépendances (paramètres des
compétences Cortex, sous Avancé), folder porte aussi dependencyMirror :
pythonIndexUrl, npmRegistryUrl, ou les deux, chacune une URL https sans
identifiants, sans requête ni fragment. Le bac à sable installe depuis ces adresses au lieu des index
publics et vérifie toujours chaque empreinte du fichier de verrouillage. Seul
l'installateur les reçoit en ligne de commande, jamais l'environnement d'un
script exécuté par la compétence.
Les compétences épinglées d'un agent
Un agent dans Cortex peut recevoir ses propres compétences : une liste de
versions épinglées qui lui sont proposées dans chaque salon, quelle que soit la
personne qui lui parle. Le bloc Agent d'un workflow peut recevoir la même
chose. Les opérations skills.bundles.* désignent l'agent par agent :
{ kind: "persona", matrixUserId } pour un agent Cortex, par son identifiant
d'utilisateur Matrix, ou { kind: "workflow", workflowId } pour le workflow
dont les blocs Agent détiennent la liste.
- Toute personne qui peut ouvrir l'agent lit sa liste. Pour un workflow,
c'est toute personne qui peut lire le workflow ; toute autre reçoit
not_found, comme si l'agent n'existait pas. Chaque épingle dit qui l'a posée et quand, sonstate,runsCode, etnewer: la version la plus haute qui vous est proposée au-dessus de celle épinglée, ounull. - Modifier la liste exige une personne qui peut modifier le workflow de
l'agent. La plateforme le demande au propriétaire du workflow à chaque
écriture. Un workflow dans un environnement en lecture seule est refusé avec
environment_read_only. - Vous n'épinglez que ce qui vous est proposé. Pour un agent Cortex,
envoyez le
roomIddepuis lequel vous épinglez : la version doit être celle qui vous y est proposée, à la classification de ce salon. Un workflow n'a pas de salon : une épingle de workflow ne prend pas deroomIdet est jugée à votre propre habilitation. Tout le reste est refusé avecnot_offered. Une liste contient au plus 25 compétences. - Une compétence qui exécute du code peut être épinglée. Son dossier doit
pouvoir s'exécuter, sinon l'épingle est refusée avec
not_runnable. L'endroit où elle s'exécute est vérifié à chaque chargement, pas à l'épinglage : l'étape de l'agent doit s'exécuter sur le niveau microVM avec ses outils de bac à sable, et la politique de compétences de votre organisation doit autoriser les scripts à la classification de la version. Sur toute autre étape, le chargement est refusé avecnot_runnable, et l'exécution en montre la raison. L'épingle reste. - Une épingle reste à sa version. Quand la compétence évolue,
newerle signale, etskills.bundles.updatedéplace l'épingle. Rien ne la déplace à votre place. - Un partage retiré cesse d'atteindre l'agent. Son épingle indique
no_longer_sharedet n'est plus proposée tant que la compétence n'est pas partagée à nouveau. L'épingle d'une compétence de la personne qui l'a posée reste proposée tant que votre organisation autorise les compétences personnelles. - Plusieurs agents peuvent partager une liste.
skills.bundles.attachdonne une liste à un agent par sonbundleId: vous devez pouvoir modifier cet agent, et chaque épingle de la liste doit vous être proposée à votre habilitation, sinon l'attachement est refusé avecnot_offered. Une liste est nommée quand un deuxième agent l'utilise : une liste sans nom exige unname, et une liste nommée se renomme avecskills.bundles.rename, pas en l'attachant. La liste que l'agent détenait avant est conservée, détenue par aucun agent.sharedWithcompte les autres.skills.bundles.detachdonne à un agent sa propre copie, et renommer une liste partagée exige une personne qui peut modifier chaque agent qui la détient.
Le bloc Agent d'un workflow demande son offre avec un sujet agent_block qui
désigne son workflow, son bloc et les choix de la personne. Il reçoit les
compétences épinglées de l'agent plus chaque choix, mais un choix seulement à la
version exacte proposée à cette personne : tout autre choix est écarté. Quand
une compétence est à la fois épinglée et choisie, la version épinglée l'emporte,
et l'origin de l'élément est bundle, avec le nom de la liste comme
originName. Le sujet doit désigner le workflow pour lequel l'exécution a été
lancée, sinon il est refusé avec subject_mismatch.
Votre bibliothèque
skills.library.list lit un onglet à la fois :
tab | Ce qu'il liste |
|---|---|
mine | Les compétences que vous avez écrites ou copiées, à leur dernière version. |
groups | Les compétences partagées avec vos équipes, un élément par partage. Chaque élément nomme son équipe dans teamName : une compétence partagée avec deux de vos équipes apparaît donc deux fois, et les deux peuvent être à des versions différentes. |
organization | Les compétences partagées avec toute l'organisation. |
Le forkedFrom d'une copie indique d'où elle vient. Son origin vaut team
lorsque la source vous parvient par une équipe, nommée dans originName ;
organization lorsqu'elle vous parvient par l'organisation ; mine lorsque la
source est la vôtre ; et null lorsqu'elle ne vous parvient plus. Lisez
origin, pas originName, pour les distinguer : une équipe peut porter
n'importe quel nom, « organization » compris.
Le movedAt d'un élément est renseigné lorsque son partage a été fait, ou
déplacé vers une autre version, au cours des sept derniers jours. Ce sont les
éléments que Cortex liste sous « De vos groupes cette semaine », eux aussi un par
partage. Demandez des pages jusqu'à ce que nextCursor soit null.
Chaque élément porte un approval : approved lorsqu'au moins un partage de la
compétence, avec une équipe ou avec l'organisation, est actif et non révoqué ;
not_approved lorsque la compétence est privée ou que chacun de ses partages
attend encore une décision. Un partage devient actif une fois approuvé, ou
aussitôt lorsque la politique de l'organisation le laisse passer sans
approbation. Une version plus récente en attente d'approbation ne retire pas
approved à une compétence qu'un partage actif suit déjà. Les éléments de
groups et organization sont des partages actifs : ils sont donc toujours
approved.
Passez approval (approved ou not_approved) pour ne lister que ces
compétences ; omettez-le pour les lister toutes. Le filtre est appliqué avant le
découpage en pages : une page n'est donc jamais incomplète à cause de lui. Un
curseur désigne une position dans la liste, pas le filtre : envoyez avec lui le
même approval que pour la page dont il provient.
Importer des compétences
skills.imports.preview et skills.imports.commit font entrer dans vos propres
compétences celles que vous avez déjà. L'envoi est un zip ou un tar.gz, ou les
fichiers d'un dossier, et ses octets décodés sont limités à
11 Mio. Une importation
accepte au plus 64 compétences.
Un envoi peut contenir :
- des dossiers Agent Skills : chaque dossier qui contient un
SKILL.mdest une compétence, avec ses autres fichiers ; - des fichiers de règles : une règle Cursor (
.mdc), ou un fichier d'instructions ou de prompt GitHub Copilot, devient une compétence. Son texte va dansreferences/, et laconversiondu candidat nomme le fichier d'origine.
La prévisualisation liste chaque compétence que contient l'envoi. Une compétence
ready peut être importée. Une compétence refused n'est pas valide, et son
refusal dit pourquoi, avec les mêmes codes qu'un enregistrement. Une
compétence blocked contient un texte que la politique DLP de votre
organisation bloque. Les liens symboliques et les périphériques sont refusés.
La validation relit l'envoi au lieu de se fier à la prévisualisation. Envoyez le
même envoi et le folder de chaque compétence prête que vous voulez. Chacune est
enregistrée en version 1 d'une nouvelle compétence dont vous êtes l'auteur, à la
classification que vous envoyez (jusqu'à votre propre habilitation), ou à la
classification la plus basse de votre organisation si vous n'en envoyez aucune. Si l'une d'elles ne peut pas
être enregistrée, par exemple parce que vous avez déjà une compétence de ce
name, rien n'est enregistré. Partager les compétences importées est une étape
distincte, selon les règles habituelles.
Pour les administrateurs de l'organisation
Quatre lectures alimentent les pages Bibliothèque, Revue, Utilisation et Listes
d'agents sous Paramètres → Cortex dans Platform. Chacune refuse quiconque n'est pas administrateur
de l'organisation avec FORBIDDEN, sans details.reason, avant toute lecture.
Elles ne montrent rien qu'un administrateur de l'organisation ne puisse déjà
lire : une compétence jamais partagée reste visible de son seul auteur, et une
version au-dessus de votre habilitation est omise.
| Opération | Liste | Filtres |
|---|---|---|
skills.admin.library.list | Un élément par compétence déjà partagée, à la plus récente version partagée que couvre votre habilitation. grants liste les équipes et l'organisation qui la suivent, pending la demande en attente s'il y en a une, et usesThisMonth le nombre de tours qui l'ont chargée ce mois civil (UTC), en ne comptant que les chargements d'une version partagée que couvre votre habilitation. skills.admin.requests.list compte son usesThisMonth de la même façon. | query porte sur le nom ou le titre d'une version partagée. status vaut shared, pending ou archived ; omis, il liste toute compétence non archivée. sort vaut recent (par défaut) ou uses_this_month, la plus utilisée en premier. |
skills.admin.requests.list | Chaque demande de partage de l'organisation dont votre habilitation couvre la version, de la plus récente à la plus ancienne, et pas seulement celles que vous pouvez trancher. canDecide vaut true lorsque skills.requests.decide accepterait votre décision maintenant. baseVersionId est la version que suit la cible, pour comparer, ou null. | status vaut pending, live (partagée sans approbation) ou decided (approuvée, refusée, annulée ou retirée) ; omis, tous les statuts. requestId renvoie cette seule demande, et ne prend pas de cursor. |
skills.admin.loads.list | Les chargements d'une compétence, du plus récent au plus ancien, depuis toujours, une ligne par chargement d'une version partagée que couvre votre habilitation. Chaque ligne donne at, la version (number et digest), la person pour qui le tour a été exécuté, le loadTrigger et le roomRank (null hors d'un salon). agentSubject ne donne que le kind d'agent, et est absent lorsque c'est le tour d'une personne qui l'a chargée. | skillId est obligatoire. Une compétence que skills.admin.library.list ne listerait pas est refusée avec details.reason not_found. |
skills.admin.bundles.list | Un élément par liste de compétences d'agent qu'au moins un agent détient, de la plus récente à la plus ancienne selon sa date de création. holders nomme chaque workflow qui la détient, son environmentId (ou null) et la persona qui l'exécute (son slug et son matrixUserId), ou null pour un workflow qu'aucune persona n'exécute. pins donne pour chaque compétence épinglée son title, sa version, son state (offered ou no_longer_shared, tel que le voient les tours de l'agent) et runsCode. Un épinglage d'une version au-dessus de votre habilitation est omis. Elle ne dit jamais qui a épinglé quoi, et ne change rien : épingler exige l'accès en écriture au workflow de l'agent, qu'être administrateur de l'organisation ne donne pas. | query porte sur le nom de la liste, sans tenir compte de la casse ; une liste sans nom ne correspond jamais. |
Toutes quatre paginent par cursor et limit. La bibliothèque va de la plus
récente à la plus ancienne selon la date d'enregistrement de la version qu'elle
affiche, si bien qu'enregistrer une version qui n'a pas été partagée ne déplace
rien, ou, avec sort: uses_this_month, de la plus utilisée à la moins utilisée,
à égalité par identifiant. Ses pages suivantes comptent les mêmes utilisations
que sa première page : le mois où elle a été lue, jusqu'à l'instant de sa
lecture, si bien qu'un mois qui change ou une compétence utilisée pendant que
vous paginez ne déplace rien, et usesThisMonth y vaut ce qu'il valait à cet
instant. Un curseur ne vaut que pour la liste, et le sort, pour lesquels il a
été émis (invalid_cursor). La revue suit la date de la demande, les
chargements leur date, et les listes leur date de création. Aucune ne compte le total.
usesThisMonth compte les mêmes versions que liste skills.admin.loads.list,
celles que vous pouvez lire, mais une fois par tour et seulement ce mois-ci,
alors que l'historique liste chaque chargement depuis toujours. Les serveurs plus anciens refusent sort : ne l'envoyez qu'à
un serveur qui sert skills.admin.loads.list.
Ne construisez pas une vue d'administration à partir de skills.library.list.
Elle liste ce qui vous est proposé en tant que membre, pas ce que
l'organisation a partagé ; la filtrer côté client montre à un administrateur le
mauvais ensemble.
Audit
Enregistrer, importer, copier, partager, approuver, refuser, retirer et charger écrivent
chacun un événement du journal d'audit qui nomme la compétence, le numéro de
version et son empreinte. Voir le catalogue du journal d'audit.
Chaque changement des compétences épinglées d'un agent écrit un événement
skill_bundle.* qui nomme la liste et chaque workflow qui la détient ; une
épingle, une mise à jour et un désépinglage nomment aussi la version. Une
écriture qui ne change rien n'écrit aucun événement. Un chargement par le tour
d'un agent écrit skill.loaded, qui nomme le workflow et le bloc de l'agent.
Erreurs
Chaque échec est une PlatformApiError avec un code stable. Un refus de la
bibliothèque de compétences porte aussi details.reason, qui est stable et sur
lequel vous pouvez brancher. Ce tableau est généré à partir de
SKILL_ERROR_REASONS dans @scrydon/sdk/platform.
details.reason | Code | HTTP | Quand |
|---|---|---|---|
stale_base | INVALID_REQUEST | 400 | Une autre version de la compétence a été enregistrée d'abord, donc baseVersionId n'est plus la dernière. Repartez de la dernière version. |
idempotency_key_reused | INVALID_REQUEST | 400 | La clé idempotencyKey a déjà répondu à une autre demande : un autre corps, une autre opération ou une autre personne. |
invalid_skill | INVALID_REQUEST | 400 | Le SKILL.md n'est pas une compétence valide. details.refusal dit pourquoi, par exemple invalid_frontmatter ou skill_md_too_large. |
slug_taken | INVALID_REQUEST | 400 | Vous avez déjà une compétence portant ce name. Une copie garde le nom de ce qu'elle copie, donc ce motif refuse aussi la copie d'une compétence dont vous utilisez déjà le nom. |
slug_changed | INVALID_REQUEST | 400 | Une nouvelle version garde le name de sa compétence. Enregistrez une compétence renommée comme une nouvelle compétence. |
unchanged | INVALID_REQUEST | 400 | La nouvelle version est identique à la dernière. |
own_skill | INVALID_REQUEST | 400 | Vous ne pouvez pas copier votre propre compétence. Enregistrez-en plutôt une nouvelle version. |
above_clearance | FORBIDDEN | 403 | La classification dépasse votre propre habilitation, vous ne pourriez donc pas relire la version. |
scheme_mismatch | INVALID_REQUEST | 400 | La classification n'est pas un niveau du schéma de classification actif de votre organisation, ou le salon que désigne un brouillon est classifié sous un autre schéma que l'appel. |
not_room_member | FORBIDDEN | 403 | Le roomId désigne un salon dont vous n'êtes pas membre. |
room_save_classified | INVALID_REQUEST | 400 | Un enregistrement a envoyé à la fois un roomId et une classification. Un enregistrement depuis un salon prend la classification du salon : envoyez l'un ou l'autre. |
room_band_unreadable | FORBIDDEN | 403 | Vous êtes dans le salon, mais son étiquette de classification est illisible. L'appel est refusé plutôt que de recevoir une classification par défaut. |
not_found | FORBIDDEN | 403 | La compétence, la version ou la demande de partage n'existe pas, ou vous ne pouvez ni la lire ni agir dessus. Les deux cas ne sont pas distingués. Un partage vers une équipe qui n'est pas dans votre organisation répond INVALID_REQUEST avec le même motif. |
not_offered | FORBIDDEN | 403 | skills.load a désigné une compétence, ou une version, qui n'est pas proposée à cet appel. |
already_shared | INVALID_REQUEST | 400 | L'équipe ou l'organisation suit déjà cette version. |
already_decided | INVALID_REQUEST | 400 | La demande a déjà été tranchée : elle est close, ou vous l'avez tranchée dans l'autre sens auparavant. Seule une personne qui pouvait trancher la demande reçoit ce motif. |
not_current | INVALID_REQUEST | 400 | Un retrait a désigné un partage qui n'est pas celui que son équipe ou son organisation suit actuellement. |
invalid_cursor | INVALID_REQUEST | 400 | Le cursor n'a pas été émis par cette liste. |
classification_required | INVALID_REQUEST | 400 | skills.offered.list ou skills.load a été appelé sans classification à laquelle proposer des compétences. |
excerpt_too_large | INVALID_REQUEST | 400 | L'extrait de conversation dépasse la limite acceptée par skills.drafts.generate. details.maxCharacters l'indique. |
mode_mismatch | INVALID_REQUEST | 400 | Un brouillon de nouvelle compétence a désigné une compétence ou une version de base. Celles-ci appartiennent à un brouillon qui révise une compétence. |
skills_policy_invalid | CAPABILITY_NOT_CONFIGURED | 409 | La politique de compétences de votre organisation ne peut pas être lue comme une politique valide. Les partages et les offres sont refusés jusqu'à ce qu'un administrateur la corrige. |
import_unreadable | INVALID_REQUEST | 400 | L'envoi n'est pas un zip, un tar.gz ou un ensemble de fichiers lisible, ou il dépasse les limites qu'une importation lit. |
import_empty | INVALID_REQUEST | 400 | L'envoi ne contient aucun dossier de compétence ni aucun fichier de règles. |
import_too_many_skills | INVALID_REQUEST | 400 | L'envoi contient plus de compétences qu'une importation n'en accepte. Importez-le en plusieurs fois. |
import_folder_not_ready | INVALID_REQUEST | 400 | Une validation a nommé un dossier que l'envoi ne contient pas, ou qui n'est pas prêt. Prévisualisez l'envoi à nouveau. |
environment_read_only | FORBIDDEN | 403 | Le workflow de l'agent se trouve dans un environnement en lecture seule. Ses compétences épinglées ne changent qu'avec un déploiement. |
runs_code | FORBIDDEN | 403 | N'est plus renvoyé : un agent peut désormais recevoir une compétence qui exécute du code (voir plus bas). Conservé pour que le code qui le compare compile toujours. |
not_runnable | INVALID_REQUEST | 400 | La version exécute du code qui ne peut pas s'exécuter : son dossier dépasse 2 Mio, ou une dépendance n'est pas verrouillée par empreinte. Elle ne peut être ni partagée, ni approuvée, ni épinglée ; un refus reste possible. Ses contrôles portent l'indicateur not_runnable qui dit pourquoi. skills.load le renvoie aussi pour une version qui exécute du code là où elle ne peut pas s'exécuter pendant ce tour ; le message dit pourquoi. |
bundle_full | INVALID_REQUEST | 400 | L'agent a déjà 25 compétences épinglées. Désépinglez-en une d'abord. Déplacer une compétence épinglée vers une autre version reste possible. |
subject_mismatch | FORBIDDEN | 403 | Un sujet agent_block désigne un autre workflow que celui pour lequel l'exécution a été lancée, ou l'appel n'est pas une exécution de workflow. |
extension_read_only | INVALID_REQUEST | 400 | La compétence vient d'une extension installée, seul endroit où ses versions changent. Copiez-la pour modifier une copie à vous. |
Les autres échecs ne portent aucun motif de la bibliothèque de compétences :
| Code | HTTP | Quand |
|---|---|---|
FORBIDDEN | 403 | L'appel ne porte pas le scope de l'opération, ou il est fait pour aucune personne. |
INVALID_REQUEST | 400 | Le corps ne respecte pas le contrat, par exemple un SKILL.md de plus de 65 536 caractères ou un partage sans idempotencyKey, ou un texte libre (un SKILL.md, une note de version, une recherche, un motif de partage, une note de décision) contenant U+0000 ou un substitut UTF-16 isolé, que Postgres ne peut pas stocker. Un SKILL.md sous ce nombre mais de plus de 64 Kio en UTF-8 est refusé avec invalid_skill. |
POLICY_BLOCKED | 422 | La prévention des pertes de données a bloqué le SKILL.md à l'enregistrement (details.policyCode LLM_BLOCKED_BY_DLP), ou une politique a bloqué le texte que skills.drafts.generate a envoyé au modèle de langage. |
PROVIDER_UNAVAILABLE | 503 | Un stockage, le salon, la politique ou le journal d'audit n'a pas pu être lu ou écrit pour l'instant. Rien n'a été enregistré comme fait ; réessayez avec la même idempotencyKey. |
import { PlatformApiError, SKILL_ERROR_REASONS } from '@scrydon/sdk/platform'
try {
await platform.skills.versions.create({ skillId, baseVersionId, skillMd, changeNote, idempotencyKey })
} catch (err) {
if (err instanceof PlatformApiError && err.details?.reason === SKILL_ERROR_REASONS.STALE_BASE) {
// Quelqu'un a enregistré une version plus récente d'abord : rechargez-la et réappliquez votre modification.
}
}