Partager des skills d’agent entre dépôts sans dérive

Partager les skills d’agent entre plusieurs dépôts

Pour partager des skills d’agent entre plusieurs dépôts, cessez de copier le fichier et faites-en une dépendance. Conservez un dépôt central de skills, créez-y des tags et faites pointer chaque projet vers un tag précis. Ajoutez ensuite un smoke test par skill et examinez chaque mise à jour comme une mise à jour de dépendance.

Cela se résume à quatre éléments : une source de référence partagée, une version épinglée par dépôt, un smoke test par skill et un processus de revue. La suite explique pourquoi chaque élément est nécessaire, ce que proposent les outils disponibles en 2026 et comment mettre en place l’ensemble sur un dépôt git auto-hébergé, sans utiliser de service externe.

Un skill d’agent est un dossier qui contient un fichier SKILL.md, ainsi que les scripts et fichiers de référence dont il a besoin. Si cette unité est nouvelle pour vous, lisez d’abord ce qu’est un skill d’agent et comment fonctionne SKILL.md. Cette page traite de la chaîne d’approvisionnement autour de cette unité.

Où se trouve une skill et pourquoi son partage est difficile

Claude Code charge les skills depuis trois emplacements, décrits dans la documentation des skills.

• ~/.claude/skills/<skill-name>/SKILL.md est personnel. Il est chargé dans tous vos projets, mais dans aucun autre compte.
• .claude/skills/<skill-name>/SKILL.md est propre au projet. Il est chargé par toute personne qui récupère ce repository.
• <plugin>/skills/<skill-name>/SKILL.md est fourni dans un plugin. Il est chargé partout où ce plugin est activé.

Le deuxième emplacement est le plus utile pour une équipe, car son contenu est versionné dans le repository et toute personne qui le clone l’obtient. C’est aussi là que les difficultés commencent. Une skill dans .claude/skills/ appartient à un seul repository. Vous avez huit repositories. La skill est donc copiée huit fois.

Le frontmatter n’aide pas. La spécification Agent Skills autorise six clés, et les chemins de distribution qui l’appliquent affichent cette liste lorsque vous en utilisez une autre :

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Remarquez ce qui manque : il n’existe aucune clé version. Rien dans le fichier n’indique quelle copie est la plus récente. C’est cohérent, car une skill est un document, pas un package. Le versioning doit donc être géré par la couche autour du fichier, et cette couche relève de votre responsabilité.

Problème 1 : huit copies qui divergent discrètement

Le copier-coller fonctionne le premier jour. Au soixantième, il échoue. Quelqu’un corrige une instruction erronée dans le dépôt payments, mais ne modifie pas les sept autres. Quelqu’un d’autre ajoute une règle sur la pagination dans orders. Le même nom de skill produit alors des revues différentes selon le répertoire depuis lequel l’agent a été démarré, sans qu’aucun développeur ne le sache.

L’échec est silencieux, car aucun état d’erreur n’existe. Une skill est du texte. Une instruction obsolète produit une réponse assurée, mais erronée : c’est le type d’erreur qui coûte cher. L’agent ne compare pas votre copie avec celles des autres. Le seul signal est qu’une personne remarque que deux dépôts ne concordent pas.

Problème 2 : aucune version n’est figée

Même lorsqu’une équipe centralise ses compétences, le partage passe généralement par une étape de copie : un script de configuration, une ligne `curl` dans la documentation d’intégration ou un alias shell qui synchronise un dossier. Ces méthodes installent toutes la version qui se trouve actuellement en tête de la branche.

Deux développeurs peuvent donc utiliser des instructions différentes alors qu’ils travaillent sur le même commit de la même application, s’ils ont exécuté la synchronisation à des jours différents. Cela empêche également de répondre à la question importante après une mauvaise exécution de l’agent : quelle version de la compétence a produit ce résultat ? Sans révision enregistrée, l’exécution n’est pas reproductible et le rapport de bug ne permet pas d’agir.

Problème 3 : personne ne sait si la compétence fonctionne encore

Une compétence n’a pas de compilateur. Il s’agit d’instructions destinées à un modèle. Elle peut donc cesser de fonctionner alors que le fichier reste identique octet par octet. Une mise à niveau du modèle modifie la fidélité avec laquelle il suit une instruction longue. Un outil en ligne de commande appelé par la compétence renomme une option. Une URL dans un fichier de référence commence à renvoyer une erreur 404, et l’agent utilise la page d’erreur comme source.

Dans aucun de ces cas, l’échec n’est clairement signalé. L’agent répond toujours. La réponse est simplement moins bonne que le mois dernier, ce qui est difficile à remarquer lorsqu’on ne l’évalue qu’une pull request à la fois.

Ce que résolvent les outils disponibles en 2026

Plusieurs réponses arrivent actuellement, mais elles ne s’accordent pas sur l’emplacement de la version.

Lockfiles. L’outil en ligne de commande skills de Vercel Labs (vercel-labs/skills, sous licence MIT, v1.5.22 au 5 août 2026) installe des skills depuis un dépôt git dans le répertoire attendu par votre agent et connaît la structure de plus de soixante-dix agents. npx skills add <repo> installe, npx skills update met à niveau et npx skills list affiche les éléments présents. L’inventaire des éléments installés est conservé une fois par utilisateur, et non une fois par dépôt. Une demande ouverte sur ce projet (issue 283) réclame une commande skills install qui réinstalle chaque skill suivi depuis le lock file, afin qu’une seconde machine obtienne le même ensemble. Considérez cette demande comme un état des lieux. Le principe du lockfile est établi. Sa déclinaison par projet est encore en cours de développement.

Spécifications et tests. SkillSpec adopte l’approche inverse. Il considère un SKILL.md comme un contrat à vérifier, et non comme du texte auquel il faut faire confiance. Son objectif déclaré est de rendre les skills « suivables, testables et démontrables ». skillspec doctor <path> indique les endroits où un agent risque de perdre le fil. skillspec boundary map <path> indique les ressources auxquelles le skill peut accéder, et skillspec boundary assess <path> classe ces résultats par niveau de risque. Il s’agit d’un crate Rust, distribué sous double licence MIT ou Apache 2.0, en version 0.2.2 au 29 juillet 2026. Installez la version épinglée plutôt que la plus récente :

cargo install skillspec --version 0.2.2 --locked
skillspec --version

--locked effectue la build avec les versions des dépendances utilisées lors de la publication du crate, afin d’éviter toute dérive pendant la build. skillspec --version doit afficher 0.2.2. Un autre numéro signifie qu’un binaire plus ancien situé plus tôt dans votre PATH est utilisé.

Pratiques des fournisseurs. Google a décrit la manière dont il construit les skills de google/skills dans un article consacré à la construction, aux tests et à la mise à l’échelle des skills pour agents. Si l’on met de côté l’échelle, le mécanisme relève de l’intégration continue (CI) classique. Avant la fusion, chaque skill passe des linters qui vérifient les métadonnées frontmatter, le nombre de lignes, la structure des répertoires et le nommage. Un link checker fait échouer la build dès qu’une URL renvoie 404, ce qui permet de détecter le lien plausible inventé par un agent. Les auteurs doivent fournir, avec le skill, une suite de prompts d’évaluation et une grille de notation. Des jobs d’évaluation planifiés s’exécutent ensuite chaque semaine sur l’ensemble de la bibliothèque pour détecter les régressions. Chaque skill possède également un responsable identifié, chargé de corriger les problèmes lorsque sa qualité diminue.

Le schéma commun aux trois réponses

Vous n’avez pas à en choisir une. Elles reposent toutes sur une même structure, et git standard vous en donne tous les éléments.

1. Une source de vérité unique. La skill a un emplacement unique, et chaque repository pointe vers cet emplacement au lieu d’en conserver une copie.
2. Une version figée par repository. Chaque projet enregistre la révision exacte qu’il utilise. La mise à niveau devient donc un commit dans ce projet, avec un auteur et une date.
3. Un smoke test par skill. Un contrôle exécutable vérifie que la skill produit toujours le résultat attendu.
4. Un processus de review. Toute modification d’une skill partagée est soumise à une review, et chaque consommateur peut consulter un diff avant de l’adopter.

C’est la structure d’une dépendance. Les skills sont devenues des artefacts partagés plus vite que les outils nécessaires à leur gestion n’ont évolué. Les outils auxquels vous faites déjà confiance sont donc le choix le plus sûr.

Une organisation pour une petite équipe sur un remote Git auto-hébergé

Un seul dépôt contient les compétences. Il ne contient rien d’autre. Son historique se lit donc comme un journal des modifications des instructions.

agent-skills/
  skills/
    api-review/
      SKILL.md
    release-notes/
      SKILL.md
  tests/
    api-review.sh
    release-notes.sh
  CHANGELOG.md

Les releases sont des tags. Utilisez des tags annotés, car ils contiennent un message et une date. Rédigez le message en indiquant la raison pour laquelle un utilisateur voudrait appliquer cette mise à jour :

git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0

Que votre remote soit Gitea, Forgejo, GitLab ou un dépôt bare accessible en SSH sur votre propre VPS, rien de ce qui suit ne change. Tout repose sur git et un symlink.

Épingler une version avec un sous-module git

Un sous-module enregistre un commit précis d’un autre dépôt dans votre dépôt. Cet enregistrement constitue le pinning. Dans chaque projet qui l’utilise :

git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"

Le lien symbolique permet ce fonctionnement. Une entrée de skill au niveau du projet peut être un lien symbolique vers un répertoire situé ailleurs sur le disque, et Claude Code le suit puis lit SKILL.md dans la cible. Le skill se charge donc comme un skill de projet normal, tandis que les fichiers se trouvent dans le sous-module, au commit que vous avez choisi.

Vérifiez le pinning :

git submodule status

Une ligne correcte commence par une espace, puis contient le commit, le chemin et le tag le plus proche :

 4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)

Un - en début de ligne signifie que le sous-module n’a jamais été initialisé. .claude/skills/api-review pointe donc vers rien et le skill ne se charge pas, sans message d’erreur. Corrigez ce problème avec git submodule update --init. Un + en début de ligne signifie que le commit extrait diffère de celui qui est enregistré. Le développeur exécute donc des instructions que personne d’autre n’utilise. Les nouveaux clones nécessitent git clone --recurse-submodules. Cette commande doit figurer dans le README, car un clone simple laisse vendor/agent-skills vide et n’affiche aucune erreur.

La mise à niveau est volontaire, ce qui est précisément l’objectif :

git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"

La ligne diff constitue le chemin de revue. Elle montre la même modification que tous les autres dépôts utilisateurs verront et s’intègre dans une pull request.

Épingler une version avec une marketplace de plugins

Si vous préférez ne pas demander à chaque développeur d’apprendre à utiliser les submodules, le système de plugins de Claude Code prend en charge la distribution et fonctionne avec un dépôt distant auto-hébergé. Ajoutez un catalogue dans .claude-plugin/marketplace.json du dépôt de skills :

{
  "name": "acme-agents",
  "owner": { "name": "Platform team", "email": "platform@example.com" },
  "plugins": [
    {
      "name": "team-skills",
      "description": "Shared review and release skills",
      "version": "1.4.0",
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0",
        "sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
      }
    }
  ]
}

Deux sources différentes interviennent ici, et les confondre est l’erreur la plus fréquente. La source de la marketplace, c’est-à-dire l’emplacement depuis lequel le catalogue lui-même est récupéré, accepte ref pour une branche ou un tag, mais n’accepte pas sha. Une source de plugin dans le catalogue accepte les deux. Lorsque les deux sont définis, sha correspond à la version effectivement épinglée. L’épingle vers un commit précis doit donc figurer dans l’entrée du catalogue.

Chaque dépôt utilisateur déclare ensuite la marketplace dans son .claude/settings.json versionné :

{
  "extraKnownMarketplaces": {
    "acme-agents": {
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0"
      }
    }
  },
  "enabledPlugins": {
    "team-skills@acme-agents": true
  }
}

Un membre de l’équipe qui fait confiance au dossier du projet reçoit une invite pour installer la marketplace. Le plugin est ensuite activé pour lui sans qu’une page de wiki lui demande de le faire. Les skills sont alors accessibles via /team-skills:api-review, car les skills des plugins utilisent le nom du plugin comme espace de noms et ne peuvent pas entrer en conflit avec un skill de projet portant le même nom. Après avoir poussé un nouveau tag, les utilisateurs actualisent leur installation avec /plugin marketplace update acme-agents, puis exécutent /reload-plugins si le résumé de l’installation le demande.

Écrire un smoke test pour une skill

Un smoke test est une exécution scriptée de l’agent sur une fixture contenant un défaut connu, avec une seule assertion. Claude Code s’exécute en mode non interactif avec -p, et une skill appelée par l’utilisateur fonctionne dans ce mode : placez /skill-name dans la chaîne de prompt ; elle est développée avant le début de l’exécution.

#!/usr/bin/env bash
set -euo pipefail

claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --allowedTools "Read" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
  | jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/null

fixtures/orders-api.md est un fichier court qui contient un seul défaut volontaire. L’assertion vérifie que la skill le signale. jq -e renvoie un code différent de zéro lorsque son filtre produit null ; une skill qui ne détecte plus le défaut introduit fait donc échouer le script. claude renvoie lui-même un code différent de zéro lorsque l’exécution échoue, et set -euo pipefail transforme l’un ou l’autre échec en test en échec.

Un modèle reformule ses réponses entre les exécutions. N’effectuez donc jamais l’assertion sur une phrase complète. Vérifiez plutôt un identifiant que la skill doit produire ou un champ d’un schéma demandé. Gardez la fixture courte pour que l’exécution reste peu coûteuse.

Dans la CI, ajoutez --bare. Sans cette option, claude -p charge le même contexte qu’une session interactive, notamment les hooks, les plugins et CLAUDE.md présents sur la machine d’exécution. La configuration personnelle d’un membre de l’équipe peut donc modifier le résultat. Le mode bare désactive toute découverte automatique. Il désactive donc aussi la skill testée : chargez explicitement cette skill. Le mode bare ne lit pas non plus les informations de connexion de votre abonnement. Définissez d’abord ANTHROPIC_API_KEY dans l’environnement :

claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --plugin-dir vendor/agent-skills \
  --allowedTools "Read" \
  --output-format json

Avec --output-format stream-json, le premier événement de l’exécution indique quels plugins ont été chargés et contient un tableau plugin_errors pour ceux qui ne l’ont pas été. Faites échouer le job de CI si plugin_errors n’est pas vide. Vous détecterez ainsi une pinning vers une révision qui n’existe plus, problème qui se manifeste sinon par un agent ignorant discrètement vos règles internes.

Une compétence partagée est une instruction exécutable

Deux fonctionnalités rendent cette affirmation littérale, et toutes deux sont importantes lorsque le fichier provient d’une autre équipe.

Tout d’abord, un SKILL.md peut exécuter des commandes shell avant que le modèle ne lise quoi que ce soit. Une ligne comme celle-ci dans le corps du fichier constitue un prétraitement :

- Current branch: !`git rev-parse --abbrev-ref HEAD`

La commande s’exécute sur la machine qui charge la compétence, et sa sortie remplace le placeholder dans le texte reçu par le modèle. Un bloc délimité ouvert par trois backticks suivis de ! exécute plusieurs commandes de la même manière. Personne n’approuve ces opérations au moment de l’exécution. Lire une compétence partagée revient donc à lire les substitutions de commandes qu’elle contient.

Ensuite, le frontmatter peut préautoriser des outils. allowed-tools autorise les outils listés sans afficher de demande d’autorisation pour le tour qui a invoqué la compétence. Pour une compétence de projet, cette autorisation prend effet dès qu’une personne accepte la boîte de dialogue de confiance de l’espace de travail pour le dossier. La documentation de Claude Code énonce clairement la conséquence : examinez les compétences de projet avant d’accorder votre confiance à un dépôt, car une compétence peut s’accorder un accès étendu aux outils.

Traitez donc la mise à jour d’une compétence exactement comme la mise à jour d’une dépendance. Épinglez-la sur un commit exact chaque fois que le mécanisme le permet, car un tag peut être déplacé et une branche évolue par définition. Sur une machine verrouillée, "disableSkillShellExecution": true dans les settings remplace chaque substitution de commande par le texte littéral [shell command execution disabled by policy] au lieu de l’exécuter. Lorsqu’il est appliqué par des settings gérés, l’utilisateur ne peut pas le remplacer. Les compétences intégrées et gérées ne sont pas concernées par ce setting.

La même prudence s’applique à ce qu’une compétence lit. Une compétence qui exécute env ou ouvre un fichier de configuration importe tout ce qu’elle y trouve dans le contexte du modèle. C’est le problème décrit dans garder les secrets hors des agents que vous exécutez. Une compétence qui récupère une page ou exécute une requête étend cette même exposition vers l’extérieur, car le texte récupéré arrive dans le contexte et ressemble exactement aux instructions que vous avez écrites. Cette limite mérite d’être comprise avant de diriger un agent vers votre propre instance SearXNG pour effectuer des recherches web.

À lire lors d’une mise à jour de version

• Le diff de chaque corps SKILL.md, car ce texte contient les instructions que votre agent suivra.
• Chaque substitution de commande, car elle s’exécute sur votre machine lors du chargement de la skill.
• Toute modification de allowed-tools, car cette ligne accorde des outils sans demander de confirmation.
• L’exécution des tests associée au tag. Si le dépôt partagé exécute ses propres smoke tests dans la CI, le tag que vous utilisez doit être associé à une exécution réussie.

Un reviewer qui ne peut pas lire l’intégralité du diff en dix minutes examine une skill devenue trop volumineuse. Scindez-la. Le même principe s’applique aux documents du dépôt que vos agents lisent : conservez les règles durables dans les fichiers décrits dans la séparation entre AGENTS.md et HUMAN.md et le raisonnement architectural dans un DESIGN.md rédigé pour les agents, et limitez les skills à des procédures ciblées.

Quand un changement de modèle ou d’outil casse une skill

Plusieurs éléments peuvent changer sous une skill sans que personne ne la modifie. Une mise à niveau du modèle change la fiabilité avec laquelle il suit une instruction longue. Une skill qui dépendait du modèle pour atteindre l’étape neuf peut donc ne plus y parvenir. Un outil en ligne de commande renomme une option. L’agent utilise alors l’ancienne option, lit l’erreur et improvise. Une URL référencée commence à renvoyer une erreur 404. Un agent harness modifie la manière dont il sélectionne les skills. Ainsi, un description qui remportait auparavant la correspondance peut ne plus être sélectionné. Lorsqu’une procédure commence ainsi à s’arrêter prématurément, aucun changement de version ne suffit. Les instructions doivent intégrer une structure qui force l’exécution des dernières étapes. C’est l’approche utilisée par la skill unlazy et sa méthode Depth Tree.

C’est pourquoi le smoke test est l’élément essentiel de cette organisation. Exécutez le test de chaque skill selon une planification, en plus de l’exécuter lors d’un push. Google exécute ses tâches d’évaluation chaque semaine sur l’ensemble de sa bibliothèque pour cette raison. Pour une équipe qui gère dix skills, un cron job hebdomadaire sur un petit VPS suffit. C’est le seul moyen de détecter le problème avant qu’un développeur ne le découvre.

La portabilité est également utile. La spécification Agent Skills limite le frontmatter à six clés. Une skill écrite selon cette spécification peut donc être chargée par des outils autres que celui pour lequel elle a été écrite. En revanche, chaque clé propre à un harness que vous ajoutez constitue un pari sur un fournisseur. Écrire des skills qui résistent à un changement de modèle est une discipline à part entière. Elle est présentée dans faire fonctionner une skill sur n’importe quel modèle.

FAQ

Comment partager une même compétence d’agent entre plusieurs dépôts ?

Placez la compétence dans un dépôt git dédié, créez-y des tags de version, puis faites référencer un tag par chaque projet consommateur au lieu de copier le fichier. Deux mécanismes conviennent. Un sous-module git enregistre un commit exact, et un lien symbolique depuis .claude/skills/<name> vers le sous-module permet de charger la compétence comme une compétence normale du projet. Une marketplace de plugins accomplit la même tâche avec /plugin, la version étant épinglée dans le .claude/settings.json du dépôt consommateur. Dans les deux cas, la version figure dans l’historique git. Vous pouvez donc déterminer quelles instructions ont produit une exécution donnée de l’agent.

Peut-on épingler une compétence d’agent sur une version précise ?

Pas depuis SKILL.md, car ce frontmatter ne possède pas de clé version. L’épinglage doit être défini dans la couche qui entoure le fichier. Un sous-module git épingle par conception un commit exact. Dans une marketplace de plugins Claude Code, une source de plugin accepte ref pour une branche ou un tag et sha pour un commit exact. Lorsque les deux sont présents, sha est prioritaire. La source de la marketplace elle-même accepte uniquement ref. Préférez l’épinglage sur un commit, car un tag peut être déplacé après sa validation.

Que doit vérifier un smoke test de compétence ?

Vérifiez un élément stable. Exécutez la compétence de manière non interactive sur une fixture contenant un problème connu, puis vérifiez qu’un identifiant précis apparaît dans la sortie, par exemple l’identifiant d’une règle que la compétence est censée signaler. Demander une sortie structurée avec --output-format json et --json-schema rend le contrôle exact, et jq -e fait échouer le script si la valeur est absente. Ne vérifiez jamais une phrase complète, car un modèle reformule ses réponses d’une exécution à l’autre.

Est-il sûr d’installer une compétence partagée depuis le dépôt d’une autre équipe ?

Traitez-la comme une dépendance logicielle, car il s’agit d’instructions exécutables. Un SKILL.md peut exécuter des commandes shell au chargement avec la forme de substitution de commande !, et le champ allowed-tools du frontmatter peut autoriser des outils à l’avance sans demander de confirmation. Examinez le diff à chaque mise à jour, épinglez un commit exact plutôt qu’une branche et préférez une source contrôlée par votre équipe. Sur les machines administrées, "disableSkillShellExecution": true dans les paramètres empêche toute exécution de substitutions de commande.

Une compétence partagée fonctionne-t-elle avec des agents autres que Claude Code ?

Cela dépend du frontmatter utilisé. La spécification Agent Skills définit six clés : name, description, license, compatibility, metadata et allowed-tools. Une compétence limitée à ces clés se charge dans les outils qui implémentent la spécification. Elle se charge également dans Claude Code sans modification. Les clés et fonctionnalités du corps propres à un harness, lorsqu’elles dépassent la spécification, sont ignorées ou rejetées ailleurs. N’utilisez donc pas ces éléments dans une compétence destinée à être largement partagée.