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

Comment partager des 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, puis 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.

Cette méthode repose sur quatre éléments : une source de référence partagée, une version figée par dépôt, un smoke test par skill et une procédure de revue. La suite explique pourquoi chaque élément est nécessaire, ce que les outils disponibles en 2026 proposent à ce sujet et comment mettre en place l’ensemble sur un remote 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, consultez d’abord ce qu’est un skill d’agent et le fonctionnement de SKILL.md. Cette page porte sur la supply chain de cette unité.

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

Claude Code charge les skills depuis trois emplacements, répertoriés 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 au niveau du projet. Il est chargé pour 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 chaque personne qui le clone le récupère. C’est aussi là que les problèmes commencent. Une skill dans .claude/skills/ appartient à un seul repository. Vous en avez huit. 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’imposent affichent la 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 logique, car une skill est un document, pas un package. Le versioning doit donc venir de la couche qui entoure le 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. Il échoue au bout de soixante jours. Quelqu’un corrige une instruction incorrecte 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 deux reviews différentes, selon le répertoire depuis lequel l’agent a été lancé, sans qu’aucun des deux développeurs ne le sache.

L’échec est silencieux, car aucun état d’erreur n’existe. Un skill est un texte. Une instruction obsolète produit une réponse assurée, mais incorrecte : c’est le type d’erreur qui coûte cher. Rien dans l’agent ne compare votre copie à celles des autres. Le seul signal est une personne qui 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 repose généralement sur une étape de copie : un script d’installation, une ligne `curl` dans la documentation d’intégration ou un alias shell qui synchronise un dossier. Tous ces mécanismes installent la version qui se trouve actuellement en tête de la branche.

Ainsi, deux développeurs travaillant sur le même commit de la même application peuvent utiliser des instructions différentes, parce qu’ils ont effectué la synchronisation à des jours différents. Vous ne pouvez pas non plus répondre à la question qui compte 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 strictement identique, octet par octet. Une mise à niveau du modèle modifie la précision avec laquelle une instruction longue est suivie. 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 travaille à partir de la page d’erreur.

Aucun de ces cas ne provoque d’échec explicite. L’agent continue de répondre. La réponse est simplement moins bonne que le mois dernier. Il est difficile de le remarquer lorsqu’on avance une pull request à la fois.

Ce que résolvent les outils disponibles en 2026

Plusieurs solutions arrivent actuellement sur le marché, et 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, en version 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. Il 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 ce qui est installé. L’inventaire des éléments installés est conservé une seule fois par utilisateur, et non une fois par dépôt. Une demande ouverte sur ce projet (issue 283) demande une commande skills install qui réinstalle chaque skill suivi depuis le lockfile, 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 annoncé est de rendre les skills « suivables, testables et démontrables ». skillspec doctor <path> indique à quel endroit un agent risque de perdre le fil. skillspec boundary map <path> indique ce à quoi 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 figée plutôt que la plus récente :

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

--locked utilise les versions des dépendances avec lesquelles le crate a été publié. La build ne dérive donc pas au fil du temps. skillspec --version doit afficher 0.2.2. Un autre numéro indique 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 écarte la question de l’échelle, le mécanisme relève d’une intégration continue (CI) classique. 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 avant sa fusion. Un link checker fait échouer la build lorsqu’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 toute la bibliothèque afin de détecter les régressions. Chaque skill a également un responsable identifié, chargé de le corriger lorsque sa qualité diminue.

Le même schéma derrière les trois réponses

Vous n’êtes pas obligé d’en choisir une. Derrière ces réponses se trouve une seule structure, et git seul vous en donne tous les éléments.

1. Une source de vérité unique. La skill a exactement un emplacement de référence, 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. Une mise à niveau devient donc un commit dans ce projet, avec un auteur et une date.
3. Un smoke test par skill. Une vérification exécutable prouve que la skill produit toujours le résultat attendu.
4. Un processus de revue. Une modification d’une skill partagée est soumise à review, et chaque consommateur voit 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 adaptés 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 dépôt contient les compétences. Rien d’autre n’y figure. Son historique sert donc de changelog 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 consommateur voudrait effectuer cette mise à niveau :

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.

Pinning 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 consommateur :

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 est l’élément qui 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 pour lire SKILL.md depuis la cible. La skill se charge donc comme une skill de projet normale, tandis que les fichiers résident 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 ne pointe donc vers rien et la skill ne se charge pas, sans afficher d’erreur. Corrigez cela avec git submodule update --init. Un + en début de ligne signifie que le commit extrait diffère de celui qui est enregistré. Ce développeur exécute donc des instructions que les autres n’ont pas. 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 verront tous les autres dépôts consommateurs et tient dans une pull request.

Utiliser le pinning 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 se charge de la distribution et fonctionne avec un remote auto-hébergé. Placez un catalogue dans .claude-plugin/marketplace.json du dépôt des 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 sont utilisées ici. Les confondre est une erreur courante. 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 au pin effectif. Le pin vers un commit précis doit donc figurer dans l’entrée du catalogue.

Chaque dépôt consommateur déclare ensuite la marketplace dans son fichier .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 coéquipier qui fait confiance au dossier du projet est invité à installer la marketplace. Le plugin est alors activé pour lui, sans qu’une page wiki lui indique de le faire. Les skills sont ensuite 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 pushé un nouveau tag, les consommateurs actualisent la marketplace 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 une erreur connue, avec une seule assertion. Claude Code s’exécute de manière non interactive avec -p, et une skill appelée par l’utilisateur fonctionne dans ce mode : placez /skill-name dans la chaîne de prompt pour qu’elle soit 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 une erreur volontaire. L’assertion vérifie que la skill la signale. jq -e renvoie un code de sortie différent de zéro lorsque son filtre produit null ; une skill qui ne détecte plus l’erreur injectée fait donc échouer le script. claude renvoie lui-même un code de sortie 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 d’une exécution à l’autre. 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 que vous avez demandé. Gardez la fixture réduite 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 ignore donc aussi la skill testée. Chargez cette skill explicitement. Le mode bare ne lit pas non plus l’identifiant de connexion de votre abonnement. Définissez donc 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 CI si plugin_errors n’est pas vide. Cela détecte une pin vers une révision qui n’existe plus, ce qui se manifesterait sinon par un agent qui ignore silencieusement vos règles internes.

Une skill partagée est une instruction exécutable

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

Premièrement, 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 correspond à un prétraitement :

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

La commande s’exécute sur la machine qui charge la skill, 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 ne valide ces opérations au moment de leur exécution. Lire une skill partagée signifie donc lire aussi ses substitutions de commandes.

Deuxièmement, le frontmatter peut autoriser des outils à l’avance. allowed-tools accorde les outils indiqués sans demander de confirmation pour le tour qui a invoqué la skill. Pour une skill 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 skills de projet avant d’accorder votre confiance à un repository, car une skill peut s’accorder elle-même un accès étendu aux outils.

Traitez donc la mise à jour d’une skill exactement comme celle d’une dépendance. Utilisez un pin vers un commit exact chaque fois que le mécanisme le permet, car un tag peut être déplacé et une branche change 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. Appliqué via des managed settings, ce réglage ne peut pas être remplacé par l’utilisateur. Les skills bundled et managed ne sont pas concernées par ce réglage.

La même prudence s’applique à ce qu’une skill lit. Une skill qui exécute env ou ouvre un fichier de configuration importe dans le contexte du modèle tout ce qu’elle y trouve. C’est le problème décrit dans garder les secrets hors des agents que vous exécutez.

À lire lors de la mise à jour d’une version

• Le diff de chaque corps SKILL.md, car ce texte contient les instructions que votre agent suivra.
• Toutes les substitutions de commande, car elles s’exécutent sur votre machine au 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 consultent : conservez les règles durables dans les fichiers décrits dans la séparation entre AGENTS.md et HUMAN.md, placez le raisonnement architectural dans un DESIGN.md destiné aux 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 peut réduire la fiabilité avec laquelle une instruction longue est suivie. Une skill qui dépendait du modèle pour atteindre l’étape neuf peut alors ne plus l’atteindre. Un outil en ligne de commande peut renommer un flag. L’agent utilise alors l’ancien flag, lit l’erreur et improvise. Une URL référencée peut commencer à renvoyer une erreur 404. Le harness de l’agent peut modifier sa sélection des skills. Un description qui était auparavant retenu peut alors ne plus correspondre.

C’est pourquoi le smoke test est essentiel dans cette organisation. Exécutez le test de chaque skill selon une planification, en plus de l’exécuter à chaque push. Google exécute chaque semaine ses jobs d’évaluation sur l’ensemble de sa bibliothèque pour cette raison. Pour une équipe qui possède dix skills, un cron hebdomadaire sur un petit VPS suffit. C’est le seul moyen d’être informé de la panne avant un développeur.

La portabilité est également utile. La spécification Agent Skills limite le frontmatter à six clés. Une skill écrite selon cette spécification se charge donc dans des outils autres que celui pour lequel elle a été créée. En revanche, chaque clé propre au harness que vous ajoutez dépend d’un fournisseur. Écrire des skills qui restent fiables après un changement de modèle est une discipline à part entière. Elle est présentée dans faire fonctionner une skill avec n’importe quel modèle.

FAQ

Comment partager une 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 et faites référencer un tag par chaque projet utilisateur au lieu de copier le fichier. Deux mécanismes sont possibles. 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 fournit le même résultat via /plugin, avec le pin déclaré dans le .claude/settings.json du dépôt utilisateur. 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.

Est-il possible d’associer une compétence d’agent à une version précise ?

Pas depuis SKILL.md, car cette frontmatter ne contient aucune clé version. Le pin doit être défini par la couche qui entoure le fichier. Un sous-module git associe par conception un commit exact. Dans une marketplace de plugins Claude Code, une source de plugin accepte ref pour une branche ou un tag, ainsi que sha pour un commit exact. Lorsque les deux sont présents, sha est prioritaire. La source de marketplace elle-même accepte uniquement ref. Préférez le pin d’un commit, car un tag peut être déplacé après sa vérification.

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 qui contient un défaut 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 doit signaler. Demander une sortie structurée avec --output-format json et --json-schema rend la vérification exacte, et jq -e fait échouer le script lorsque la valeur est absente. N’effectuez jamais la vérification sur 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 via la forme de substitution de commande !, et le champ de frontmatter allowed-tools peut autoriser des outils à l’avance sans demander de confirmation. Lisez le diff à chaque mise à jour, utilisez le pin d’un commit exact plutôt qu’une branche et préférez une source contrôlée par votre propre équipe. Sur les machines administrées, "disableSkillShellExecution": true dans les settings 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 de la frontmatter utilisée. 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’en utilisez donc pas dans une compétence destinée à être largement partagée.