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 pour chaque skill et examinez chaque mise à jour comme une mise à jour de dépendance.

Cette approche comporte quatre éléments : une source de référence partagée, une version épinglée pour chaque dépôt, un smoke test pour chaque skill et un processus de revue. La suite explique pourquoi chaque élément est nécessaire, ce que proposent les outils livrés en 2026 à ce sujet et comment mettre en place l’ensemble sur un dépôt git auto-hébergé, sans utiliser de forge git externe ni de registre de paquets. Les smoke tests constituent la seule exception. Ils exécutent Claude Code, qui envoie chaque requête à une API de modèle ; cette étape quitte donc encore votre serveur.

Un skill d’agent est un répertoire contenant 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, commencez par lire ce qu’est un skill d’agent et comment fonctionne SKILL.md. Cette page porte sur la chaîne d’approvisionnement de cette unité.

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

Claude Code charge les skills depuis les emplacements suivants, entre autres, et la documentation des skills répertorie chaque chemin.

• .claude/skills/<skill-name>/SKILL.md dans le répertoire de configuration géré est l’emplacement destiné à l’entreprise. Il est chargé pour chaque utilisateur sur les machines où une organisation le déploie.
• ~/.claude/skills/<skill-name>/SKILL.md est personnel. Il est chargé dans tous vos projets, mais dans aucun autre projet.
• .claude/skills/<skill-name>/SKILL.md correspond au niveau du projet. Il est chargé par toute personne qui récupère ce dépôt.
• <plugin>/skills/<skill-name>/SKILL.md est fourni avec un plugin. Il est chargé partout où ce plugin est activé.

Claude Code charge également les skills depuis les répertoires imbriqués des projets, les répertoires fournis avec --add-dir et les skills activées pour votre compte claude.ai.

L’emplacement au niveau du projet est celui qui convient à une équipe, car il est versionné dans le dépôt 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 dépôt. Vous avez huit dépôts. La skill est donc copiée huit fois.

Le frontmatter n’aide pas. La spécification Agent Skills autorise six clés, et les outils de distribution qui l’appliquent 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

Notez ce qui manque : il n’existe aucune clé version. Le fichier ne contient aucune information permettant de déterminer quelle copie est la plus récente. C’est logique, car une skill est un document, pas un package. En revanche, le versionnement doit 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. 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 les outils disponibles en 2026 résolvent

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

Fichiers de verrouillage. L’outil en ligne de commande skills de Vercel Labs (vercel-labs/skills, sous licence MIT, v1.7.2 au 9 octobre 2026) installe les 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é. Il conserve deux fichiers de verrouillage. Un fichier global, ~/.agents/.skill-lock.json, enregistre ce qu’un utilisateur a installé. Depuis la v1.4.1 (20 février 2026), une installation au niveau du projet écrit également skills-lock.json à la racine du projet. Le code source de l’outil indique que ce fichier doit être ajouté au contrôle de version. npx skills experimental_install restaure les skills d’un projet à partir de ce fichier. L’issue 283 demandait une commande skills install pour restaurer le fichier de verrouillage global sur une autre machine. Elle a été clôturée comme « non planifiée » le 5 novembre 2026. Le mainteneur la considère comme identique à l’issue 549. Ces deux issues doivent être lues comme un état des lieux. Le fichier de verrouillage par projet existe. La commande qui le restaure est encore marquée comme expérimentale dans la v1.7.6 publiée. La branche principale du projet prend désormais aussi en charge npx skills install, sans source permettant de restaurer le fichier de verrouillage du projet.

Spécifications et tests. SkillSpec adopte l’approche inverse. Il considère un SKILL.md comme un contrat à vérifier, et non comme un texte auquel faire confiance. Son objectif déclaré est de rendre les skills « applicables, testables et démontrables ». skillspec doctor <path> indique à quel endroit un agent risque de perdre le fil. skillspec boundary map <path> affiche le contenu du skill. skillspec boundary assess <path> indique ce qu’il peut atteindre, avec un classement par niveau de risque. Il s’agit d’un crate Rust sous double licence MIT ou Apache 2.0. La version 0.2.2 a été publiée le 29 juillet 2026. Elle reste la plus récente sur crates.io au 10 octobre 2026. Installez la version figée plutôt que la plus récente :

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

--locked effectue la compilation avec les versions des dépendances utilisées lors de la publication du crate. La compilation ne dérive donc pas de manière imprévisible. skillspec --version doit afficher 0.2.2. Un autre numéro indique qu’un binaire plus ancien, présent plus tôt dans votre PATH, est utilisé en priorité.

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 d’agent. Si l’on fait abstraction de l’échelle, le mécanisme relève de l’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 la fusion. Un vérificateur de liens fait échouer la build dès qu’une URL renvoie 404. Cela détecte notamment les liens plausibles qu’un agent a inventés. Les auteurs doivent fournir, avec le skill, une suite de prompts d’évaluation et une grille de notation. Des tâches d’évaluation planifiées s’exécutent ensuite chaque semaine sur l’ensemble de la bibliothèque afin de détecter les régressions. Chaque skill possède également un responsable identifié, chargé de le corriger lorsque sa qualité baisse.

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.

Plutôt que d’utiliser des sous-modules, utilisez une marketplace de plugins

Si vous préférez ne pas demander à chaque développeur d’apprendre à utiliser les sous-modules, le système de plugins de Claude Code prend en charge la distribution. Il fonctionne avec un remote auto-hébergé. Ajoutez un catalogue à .claude-plugin/marketplace.json dans le 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 interviennent ici. Les confondre est l’erreur la plus fréquente. La source de la marketplace, c’est-à-dire l’emplacement depuis lequel le catalogue 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 est le pin effectif. Le pin vers un commit précis doit donc figurer dans l’entrée du catalogue. Les noms de type diffèrent également. Dans le catalogue, url désigne un dépôt git à cloner. Dans une source de marketplace, url désigne un lien direct vers un fichier marketplace.json, tandis qu’un dépôt git est indiqué par git.

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

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

Claude Code enregistre la marketplace pour un membre de l’équipe dès que celui-ci accepte la boîte de dialogue de confiance de l’espace de travail pour le dossier du projet. Il n’est donc pas nécessaire de lui indiquer cette étape dans une page de wiki. L’entrée du catalogue pointe vers une URL git plutôt que vers un chemin relatif. Le plugin ne s’installe donc pas uniquement à partir des paramètres du dépôt. Chaque membre de l’équipe exécute claude plugin install team-skills@acme-agents --scope project une fois. Tant que cette commande n’a pas été exécutée, Claude Code indique que le plugin est activé dans les paramètres du projet, mais qu’il n’est pas installé. Les skills répondent alors à /team-skills:api-review, car les skills des plugins sont préfixés par le nom du plugin et ne peuvent pas entrer en conflit avec un skill du projet portant le même nom. Après avoir poussé 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 contre une fixture présentant un défaut connu, avec une 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 contenant 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 injecté 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 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 demandé, et gardez la fixture petite pour limiter le coût de l’exécution.

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 où il s’exécute. La configuration personnelle d’un membre de l’équipe peut donc modifier le résultat. Le mode bare désactive l’auto-discovery, sauf pour les skills placées dans .claude/skills/ sous un répertoire fourni explicitement avec --add-dir ; il ignore donc la skill du projet que vous testez ici. Chargez cette skill explicitement. Le mode bare ne lit pas non plus l’authentification 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

Un plugin chargé avec --plugin-dir prend son nom dans .claude-plugin/plugin.json. Sans ce manifest, il porte le nom de son répertoire. Commitez un plugin.json avec "name": "team-skills" à côté du catalog dans le dépôt des skills, sinon la commande ci-dessus doit appeler /agent-skills:api-review à la place.

Avec --output-format stream-json, l’événement system/init indique quels plugins ont été chargés et contient un tableau plugin_errors pour ceux qui ne l’ont pas été. Il ouvre le flux sauf si des événements de démarrage arrivent en premier. Faites échouer le job de CI si plugin_errors n’est pas vide. Cela détecte une référence épinglée vers une révision qui n’existe plus. Sinon, l’agent peut simplement ignorer silencieusement vos règles internes.

Une compétence 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 compétence. Sa sortie remplace le placeholder dans le texte reçu par le modèle. Un bloc délimité ouvert par trois accents graves suivis de ! exécute plusieurs commandes de la même manière. Aucune confirmation n’est demandée au moment de l’exécution. Claude Code vérifie chaque commande par rapport à vos règles d’autorisation. En dehors du mode automatique, une commande non autorisée par ces règles interrompt la compétence, sauf si celle-ci l’a préalablement autorisée avec la deuxième fonctionnalité ci-dessous. Les règles de refus et de demande de confirmation restent prioritaires sur cette préautorisation. Lire une compétence partagée revient donc à lire les substitutions de commandes qu’elle contient.

Deuxièmement, le frontmatter peut préautoriser des outils. allowed-tools accorde les outils indiqués sans demander d’autorisation pendant le tour qui a invoqué la compétence. La confiance accordée à l’espace de travail ne limite pas cette autorisation : Claude Code applique le allowed-tools d’une compétence de projet, même lors d’une exécution -p dans un dossier auquel personne n’a accordé sa confiance. La documentation de Claude Code énonce clairement la conséquence : une compétence peut s’accorder un accès étendu aux outils. Examinez donc le allowed-tools des compétences versionnées dans un dépôt avant d’y exécuter Claude Code. Une organisation peut empêcher les compétences de projet et les compétences personnelles d’utiliser ce champ en définissant allowManagedPermissionRulesOnly dans les paramètres gérés. Cette option nécessite Claude Code v2.1.282 ou une version ultérieure.

Traitez donc la mise à jour d’une compétence exactement comme la mise à jour d’une dépendance. Utilisez le commit exact lorsque 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 paramètres 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 les paramètres gérés, l’utilisateur ne peut pas le remplacer. Les compétences intégrées et les compétences gérées ne sont pas concernées par ce paramètre.

La même prudence s’applique aux éléments lus par une compétence. Une compétence qui exécute env ou ouvre un fichier de configuration récupère 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 expose ces mêmes informations vers l’extérieur : le texte récupéré arrive dans le contexte et ressemble exactement aux instructions que vous avez écrites. Il vaut mieux comprendre cette limite avant de rediriger 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 pour les versions, puis faites référencer un tag par chaque projet utilisateur 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 le charger comme une compétence de projet normale. Une marketplace de plugins fournit la même fonction via /plugin, avec le pin déclaré dans le .claude/settings.json du dépôt utilisateur. Dans les deux cas, la version apparaît dans l’historique git. Vous pouvez donc déterminer quelles instructions ont produit une exécution donnée de l’agent.

Puis-je associer une compétence d’agent à une version précise ?

Pas depuis SKILL.md, car cette frontmatter ne possède pas de clé version. Le pin doit être défini dans la couche qui entoure le fichier. Un sous-module git associe par conception la dépendance à 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 marketplace elle-même accepte uniquement ref. Préférez le pin vers 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 un fixture contenant un problème connu, puis vérifiez qu’un identifiant précis apparaît dans la sortie. Il peut s’agir, par exemple, de 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 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 via la forme de substitution de commande !, et le champ de frontmatter allowed-tools peut autoriser à l’avance des outils sans demander de confirmation. Examinez le diff à chaque mise à jour, utilisez un pin vers 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 l’exécution des substitutions de commande dans les compétences utilisateur, de projet, de plugin et de répertoire supplémentaire. Les compétences intégrées et administrées ne sont pas concernées.

Une compétence partagée fonctionnera-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 avec 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 ne font pas partie de 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.