Compétences d'agent

Usage: sovrium skills [--output <dir>] [--target claude|agents|all] [--check] [--force]

Une IA qui modifie votre configuration ne vaut que ce qu'elle sait de Sovrium. Livrée à elle-même, elle devine à partir de ce qu'elle a lu pendant son entraînement : des noms d'options d'une version plus ancienne, une page web au lieu du manuel de votre version, une configuration qui passe la validation mais que personne n'a jamais regardée dans un navigateur. Les compétences d'agent (agent skills) comblent cet écart. Chacune est un court SKILL.md que votre IA lit lorsqu'une tâche y correspond, accompagné d'un dossier references/ qu'elle ouvre lorsqu'elle a besoin du détail.

Le binaire en embarque cinq :

Une partie de chaque dossier references/ est générée à partir des descriptions d'options du binaire lui-même : un catalogue de types de champs ou de composants décrit donc toujours la version que vous exécutez.

Ce qu'elle écrit

sovrium skills écrit chaque compétence dans .claude/skills/<name>/ sous le répertoire courant — le SKILL.md et ses references/ — ainsi qu'un .sovrium-skills.json à côté. --output <dir> écrit plutôt sous une autre racine de projet.

Le fichier JSON enregistre, pour chaque fichier écrit, une empreinte SHA-256 de ses octets et la version de Sovrium qui l'a écrit. Commitez-le avec les compétences : c'est ainsi que l'exécution suivante sait quels fichiers appartiennent à Sovrium et lesquels vous avez modifiés. Chaque SKILL.md indique aussi sa version dans son frontmatter, sous metadata.product-version.

sovrium init écrit les mêmes compétences lorsqu'il échafaude un projet, que ce soit depuis le modèle de départ par défaut, un --template, un dépôt de modèle ou --from-url. Il n'écrase jamais un répertoire de compétence déjà présent.

Rafraîchir après une mise à niveau

Après avoir installé une nouvelle version de Sovrium, relancez la commande :

sovrium skills

Les fichiers que Sovrium a écrits et que vous n'avez pas modifiés sont remplacés par ceux de la nouvelle version. Une compétence que la nouvelle version ne livre plus est supprimée, à condition que vous ne l'ayez pas modifiée. Une seconde exécution sans rien à faire ne change rien.

Les fichiers que vous avez modifiés

Un fichier dont les octets ne correspondent plus à ce que Sovrium a enregistré est désormais le vôtre, et la commande refuse de l'écraser. Elle se termine avec le code 1 et nomme chacun de ces fichiers. Vous pouvez :

• conserver votre version, et laisser ce fichier délibérément périmé, ou
• lancer sovrium skills --force pour reprendre la version de Sovrium. --force ne remplace que les fichiers écrits par Sovrium ; un fichier que vous avez ajouté dans un dossier de compétence reste en place.

Un répertoire de compétence portant un nom de Sovrium que Sovrium n'a jamais écrit — votre propre sovrium-app, par exemple — est refusé même avec --force : sans l'enregistrement, rien ne prouve qu'il revient à Sovrium de le remplacer. Les compétences d'autres noms ne sont jamais lues ni touchées.

Liens symboliques

La commande n'écrit, ne remplace et ne supprime jamais rien à travers un lien symbolique. Si un dossier de compétence, un fichier qu'il contient ou .sovrium-skills.json est un lien, elle se termine avec le code 1 en nommant le lien et n'écrit rien, dans aucune cible. --force n'y change rien. Remplacez le lien par un vrai fichier ou dossier, ou supprimez-le, puis relancez la commande. sovrium init saute une compétence dont le dossier est un lien, le signale, et écrit les autres.

Le dossier des compétences lui-même peut être un lien : faire pointer .claude/skills vers .agents/skills pour partager une seule copie fonctionne, tant que le lien se résout à l'intérieur du projet. Un dossier de compétences qui mène hors du projet est refusé avant que quoi que ce soit ne soit écrit.

Vérifier en CI

sovrium skills --check

--check n'écrit rien. Il se termine avec le code 0 lorsque chaque compétence est à jour, et avec le code 1 lorsqu'un fichier manque, subsiste d'une version plus ancienne ou a été modifié — en les listant un par un. Lancez-le en CI pour repérer un projet dont les compétences ont pris du retard sur le binaire qu'épingle son pipeline.

Autres agents : --target agents

Claude Code lit .claude/skills/, tout comme Cursor. Codex, GitHub Copilot, Gemini CLI et OpenCode lisent .agents/skills/.

sovrium skills --target agents   # .agents/skills/
sovrium skills --target all      # both directories

Chaque répertoire conserve son propre .sovrium-skills.json : chacun est donc rafraîchi et vérifié indépendamment. claude est la valeur par défaut.

Sous forme de prompts MCP

Claude Desktop n'a pas de shell pour lancer sovrium skills, et ne lit pas les dossiers de compétences de votre projet. Lorsqu'il est connecté via sovrium mcp, les mêmes compétences sont disponibles sous forme de prompts MCP : choisissez-en une dans le menu des prompts, et le texte de son SKILL.md est ajouté à la conversation. Un prompt ne porte que le SKILL.md, pas ses references/. Votre configuration en MCP explique comment connecter un client.

Sur quoi reposent les compétences

Les compétences suivent le format Agent Skills, et leurs conseils sont tirés de sources publiées : la documentation des moteurs de recherche pour la compétence SEO, les recommandations publiques de design et d'accessibilité pour la compétence des pages, et des collections publiées de compétences d'agent pour leur structure. Chaque compétence liste ce dont elle s'est inspirée, avec la date et la licence, dans son references/sources.md.