Guide de développement de skill

English version: ../../en/guides/skill-development.md

Ce guide montre comment écrire, signer, publier, charger, versionner et retirer une skill. Il s'adresse aux développeurs qui ont le rôle developer ou tenant_admin ; changer le statut d'une skill demande tenant_admin ou security_officer.

Concept

Une skill est un ensemble d'instructions (son SKILL.md) et un point d'entrée optionnel qu'un agent charge à l'exécution. Le Skill Registry conserve le manifeste, le contenu et son empreinte SHA-256 ; le Skill Loader ne remet la skill à un agent que si l'empreinte correspond, si la signature est vérifiée, si l'agent liste la skill dans spec.skills et si l'agent a reçu chaque droit de la skill. Une skill est une donnée pour le modèle : elle ne remplace jamais un contrôle de permission.

Les statuts sont draft, approved, restricted, deprecated et blocked. Une skill vérifiée devient approved à l'enregistrement ; une skill non vérifiée reste draft.

Champs du manifeste

Le manifeste suit contracts/v1/skill-manifest.schema.json.

Champ	Type	Obligatoire	Description
apiVersion, kind	chaîne	oui	enterprise-ai.io/v1 et Skill.
metadata.name, metadata.version, metadata.owner	chaîne	oui	Nom de style DNS, version semver, responsable.
spec.description	chaîne	oui	Quand l'agent doit utiliser la skill.
spec.instructions	chaîne	oui	Le contenu du SKILL.md, conservé en ligne.
spec.entrypoint	chaîne	non	Point d'entrée du code quand la skill fournit du code.
spec.dependencies	tableau	non	Chaque élément : ref, version, optional.
spec.permissions	objet	oui	data_classification_max (obligatoire), scopes, network (booléen), filesystem (none, read, write).
spec.artifact	objet	non	oci_ref ou git_ref, et digest (sha256:<64 hex>), obligatoire pour un artefact Git ou OCI.
spec.signature	objet	non	digest (obligatoire), cosign_bundle, signer, issued_at.
spec.compatible_runtimes	tableau	non	Moteurs avec lesquels la skill a été testée.

Créer une skill

Une skill est décrite par un manifeste skill.yaml (contracts/v1/skill-manifest.schema.json) et son SKILL.md ; enterprise-ai create skill les écrit et valide le manifeste.

enterprise-ai create skill invoice-reader
enterprise-ai validate -f invoice-reader/skill.yaml

Étapes

1. Créer la skill. La commande écrit skill.yaml et SKILL.md, puis valide le manifeste selon le contrat v1. Dans le portail : Studio développeur > Studio de skills > Nouveau.

   enterprise-ai create skill invoice-reader

   Résultat attendu : les deux fichiers sont listés et le manifeste est déclaré valide selon skill-manifest.

   En cas d'échec : un code de sortie 1 avec « exists » signifie que les fichiers existent déjà ; ajoutez --force ou choisissez un autre nom.

2. Écrire les instructions et les permissions. Décrivez dans SKILL.md quand utiliser la skill, ses étapes et les outils sur lesquels elle s'appuie. Réglez spec.permissions.scopes et data_classification_max sur ce dont la skill a réellement besoin : le loader la refuse à un agent qui n'a pas reçu ces droits.

   Résultat attendu : SKILL.md et spec.instructions disent la même chose.

   En cas d'échec : un agent dont data_classification_max est au-dessus de celle de la skill reçoit 403 skill_permission_denied au chargement.

3. Valider le manifeste. Contrôle hors ligne selon le contrat. Dans le portail : Valider sur le serveur.

   enterprise-ai validate -f invoice-reader/skill.yaml

   Résultat attendu : code de sortie 0.

   En cas d'échec : le code de sortie 1 liste les champs invalides.

4. Calculer l'empreinte et signer. publish skill calcule l'empreinte SHA-256 du dossier, l'écrit dans spec.artifact.digest et spec.signature.digest, et avec --sign signe avec cosign sign-blob. Lancez-la d'abord avec --dry-run pour voir le manifeste qui sera envoyé.

   enterprise-ai publish skill ./invoice-reader --sign --key cosign.key --dry-run

   cosign.key : votre fichier de clé cosign ou une référence KMS.

   Résultat attendu : l'empreinte sha256:... est affichée, puis le manifeste en YAML.

   En cas d'échec : un avertissement indique que cosign est absent ; installez-le ou publiez sans signature (la skill restera draft et ne pourra pas être chargée).

5. Publier. Sans --dry-run la commande appelle POST /v1/skills. Dans le portail : Enregistrer comme nouvelle version.

   enterprise-ai publish skill ./invoice-reader --sign --key cosign.key

   Résultat attendu : apply_status vaut created ou updated, et verified vaut true.

   En cas d'échec : 422 invalid_manifest avec artifact.digest signale un artefact Git ou OCI sans empreinte.

6. Vérifier la signature. POST /v1/skills/{name}/verify vérifie de nouveau l'empreinte et la signature de la version conservée. Dans le portail : Studio de skills > skill > Test > Vérifier.

   Résultat attendu : verified: true, avec method et signer.

   En cas d'échec : reason vaut digest_mismatch (contenu modifié après la signature) ou la signature manque.

7. Accorder la skill à un agent et la charger. Ajoutez skill:invoice-reader@<version> à spec.skills de l'agent, appliquez l'agent, puis le moteur appelle GET /v1/skills/{name}/load avec ?agent=<agent>.

   Résultat attendu : la réponse donne digest, signer, instructions, permissions et dependencies.

   En cas d'échec : voyez la table de dépannage ; chaque refus est audité sous skill.load avec sa raison.

8. Publier une nouvelle version. Augmentez metadata.version, signez et publiez de nouveau. La version conservée est remplacée, sa vérification est relancée, et une skill blocked reste blocked.

   Résultat attendu : apply_status vaut updated.

   En cas d'échec : relancez l'étape 6 et lisez reason.

9. Restreindre, déprécier ou bloquer. POST /v1/skills/{name}/status applique draft, restricted, deprecated ou blocked immédiatement ; approved ouvre une approbation de promotion et répond 202, décidée avec POST /v1/approvals/{approval_id}/decide (Agents > Approbations).

   client.skills.set_status("invoice-reader", "blocked", reason="prompt injection found")

   Résultat attendu : le nouveau statut est renvoyé ; une skill blocked ou deprecated n'est plus chargée.

   En cas d'échec : 400 invalid_request pour un statut inconnu.

Signer et publier

enterprise-ai publish skill vérifie la signature (cosign sign-blob avec --sign) puis appelle POST /v1/skills ; POST /v1/skills/{name}/verify revérifie la signature et GET /v1/skills/{name}/load charge la skill vérifiée.

enterprise-ai publish skill ./invoice-reader --sign --key cosign.key --dry-run

Vérifier depuis le code

Une skill non signée ou dont la signature ne correspond pas n'est jamais chargée.

client.skills.verify("invoice-reader")

Dépannage

Symptôme	Cause	Correction
404 skill_not_found	Aucune skill de ce nom dans le tenant.	Vérifiez le nom avec enterprise-ai get skills.
422 invalid_manifest	Erreur de contrat, ou artefact Git ou OCI sans artifact.digest.	Validez le manifeste ; publiez avec enterprise-ai publish skill, qui pose l'empreinte.
403 skill_blocked	La skill est blocked ou deprecated.	Publiez une version corrigée et demandez à un tenant_admin de changer le statut.
409 skill_digest_mismatch	Le contenu conservé ne correspond plus à son empreinte.	Signez et publiez de nouveau le contenu.
403 skill_unsigned	La signature manque ou n'est pas vérifiée.	Publiez avec --sign et une clé de confiance.
403 skill_not_granted	L'agent ne liste pas la skill dans spec.skills.	Ajoutez la référence au manifeste de l'agent et appliquez-le.
403 skill_permission_denied	La skill demande un droit que l'agent n'a pas, ou la classification de l'agent dépasse celle de la skill.	Alignez spec.permissions de la skill et de l'agent.
400 invalid_request	Statut inconnu dans POST /v1/skills/{name}/status.	Utilisez draft, approved, restricted, deprecated ou blocked.

Étapes suivantes

• Guide de développement d'agent pour accorder la skill.
• Guide de développement des packs pour livrer des skills dans un pack Marketplace.
• Guide des tests et référence de la CLI.