213 — Distribuer ses primitives — APM, plugins, symlink, outils tiers

Durée estimée : 25 min

Tu sais créer des primitives. Mais quand l’équipe grandit, comment les partager sans copier-coller ? Quatre modes répondent à cette envie — APM, plugin, git clone + symlink, et les outils tiers comme skill.sh. Aucun n’est universellement meilleur : ils troquent différemment portée, version et tokens.

Pourquoi ce module

Réutiliser des primitives sans les recopier à la main : c’est le même besoin pour les quatre modes. Ce qui change, c’est le compromis.

• APM — déclare les primitives par projet (apm.yml + apm.lock.yaml). Qui clone obtient la config exacte.
• Plugin — un bundle installé sur la machine du dev. Une fois posé, il le suit partout.
• Git clone + symlink — un dépôt partagé cloné une fois, lié par symlink dans le dépôt de travail. Un git pull garde tout à jour.
• Outils tiers légers (ex. skill.sh) — un installeur de skills en shell, scriptable.

Ce choix décide de qui voit quoi, de qui reste synchronisé, et de combien de tokens tu paies à chaque tour de conversation. Ce module met les quatre modes sur la même ligne et les confronte à quatre scénarios d’équipe.

Pré-requis

• Module 207 — APM — installer et partager — tu dois savoir lire un apm.yml et un lockfile.
• Module 209 — Plugins — découvrir et installer — tu dois savoir installer un plugin et distinguer les scopes user/project.
• Module 105 — Hooks — pour le volet sécurité en fin de module.

Rappel express des primitives en jeu :

• Un skill : un dossier de connaissances/procédures chargé à la demande quand sa description matche la tâche.
• Un agent : une persona avec ses outils et son périmètre, invoquée explicitement ou par dispatch.
• Un hook : un script déclenché par un événement (avant commit, après édition…), qui ne consomme pas la fenêtre de contexte tant qu’il ne s’exécute pas.
• Un plugin : un bundle qui empaquette plusieurs de ces primitives (skills + agents + hooks + MCP) et s’installe d’un bloc.

Concepts clés

Les quatre modes de distribution

APM orchestre la distribution de toutes les primitives, versionnée et lockée par projet. Tu déclares une dépendance dans apm.yml :

dependencies:
  - AxaFrance/design-system/plugins/canopee-distributeur

Plugin : un mode de packaging et d’installation, souvent global à la machine. Tu l’installes une fois depuis le marketplace, puis il se met à jour automatiquement.

Git clone + symlink : tu clones une fois le dépôt partagé, puis tu poses un symlink dans le dépôt de code où tu travailles (son dossier .agents/ ou .github/) — pas dans la config user. Un git pull sur le clone propage la dernière version à tous les projets liés.

# 1. Cloner le dépôt partagé une fois sur la machine
git clone git@github.com:axafrance/shared-skills.git ~/.copilot-skills

# 2. Le lier DANS le dépôt de travail courant (pas dans la config user)
cd ~/work/mon-projet
ln -s ~/.copilot-skills/.agents/skills .agents/skills

# 3. Rester à jour : un pull sur le clone suffit pour tous les projets liés
git -C ~/.copilot-skills pull

Outils tiers légers (ex. skill.sh) : un installeur de skills en shell, à mi-chemin entre le plugin et APM. L’interface exacte dépend de l’outil ; l’idée est un script minimaliste qui récupère un skill depuis un dépôt.

# Exemple d'outil tiers léger (l'interface exacte dépend de l'outil)
skill.sh install axafrance/design-system

Vue d’ensemble :

Comment les tokens se consomment

Rappelle-toi ce qui entre dans la fenêtre de contexte à chaque tour.

flowchart TD
    A[Tour de conversation] --> B[Toujours chargé]
    A --> C[Chargé à la demande]
    B --> B1[Descriptions des skills installés]
    B --> B2[Front-matter des agents]
    B --> B3[Instructions globales]
    C --> C1[Corps d'un skill si sa description matche]
    C --> C2[Fichiers references/ sur trigger]
    B1 --> D[Coût tokens fixe par tour]
    C1 --> E[Coût tokens ponctuel]

Le point décisif : les descriptions sont toujours chargées, le corps ne l’est qu’au déclenchement. La règle vaut pour les quatre modes :

• Tout ce qui est installé largement (plugin user, symlink dans la config user, outil tiers global) rend ses descriptions candidates dans tous tes dépôts, même hors sujet. C’est un coût « partout » : tu le payes dans chaque repo, même là où la primitive ne sert à rien.
• Tout ce qui est déclaré par projet (APM, symlink dans le dépôt de travail, outil tiers en mode projet) ne charge que les descriptions pertinentes → contexte ciblé.

Retiens : plus une primitive est installée largement, plus elle pèse sur des tâches où elle est inutile. Ce n’est donc pas « plugin vs APM » qui décide des tokens, mais la portée de l’installation — où et à quel point tu l’installes largement.

Combien coûte une en-tête de skill, en tokens ?

Ce qui est « toujours chargé », c’est le nom + la description de chaque skill (sa frontmatter). On peut le chiffrer avec deux repères :

• règle de conversion : ~4 caractères = 1 token ;
• plafond canonique d’une description de skill : 1024 caractères.

Une en-tête de skill coûte donc entre ~35 et ~300 input tokens, à chaque tour. Multiplie par le nombre de skills installés : 20 skills à ~150 tokens en moyenne = ~3000 input tokens fixes ajoutés à chaque message — qu’ils servent ou non.

Ces tokens sont des input tokens : ils font partie du prompt envoyé au modèle à chaque interaction. Leur coût n’est pas la facture en elle-même mais le budget de contexte — la place qu’ils occupent dans la fenêtre et qu’ils retirent à ton code et à ta question. Plus tu installes large, plus cette part fixe grossit, utile ou non.

Démonstration — quatre scénarios d’équipe

Pour chaque scénario, les quatre modes sont comparés (positif / négatif / impact tokens), puis une reco.

Scénario A — Équipe multi-repo, développeur full-stack

Le dev jongle entre un repo front, un repo back, un repo infra.

Recommandation : full-stack multi-repo → APM pour la cohérence et des tokens ciblés. Le symlink dépanne un dev solo qui veut le dernier HEAD sans cérémonie.

À l’échelle de la squad : si d’autres membres sont mono-stack et ne touchent qu’front ou back, APM par repo les sert encore mieux — chacun ne charge que son repo, et la full-stack obtient le bon contexte en passant de l’un à l’autre. Le profil mixte plaide pour APM.

Scénario B — Équipe mono-repo, front et back ensemble

Front et back vivent dans le même dépôt, un périmètre unique.

Recommandation : mono-repo → APM gagne nettement. Un manifeste, un lockfile, et tout nouvel arrivant obtient la config exacte au clone. Exemple : partager le skill maison du design system, hébergé dans axafrance/design-system, en une ligne d’apm.yml — le skill vit dans son dépôt source, le projet consommateur ne fait que le déclarer.

À l’échelle de la squad : le dépôt unique aligne d’office tout le monde, quel que soit le profil (full-stack ou spécialisé) — un seul manifeste sert toute la squad. C’est le cas le plus robuste aux profils mixtes.

Scénario C — Plusieurs équipes dans un même monorepo

Un seul stack, un monorepo, mais découpé en domaines appartenant chacun à une équipe différente. Concrètement, un dossier par domaine, chacun avec ses propres besoins :

monorepo/
  paiement/      ← équipe Paiement
  catalogue/     ← équipe Catalogue
  compte/        ← équipe Compte

Chaque équipe a ses propres skills/agents ; personne n’a besoin de ceux des deux autres au quotidien.

Recommandation : plusieurs équipes dans un monorepo → APM pour isoler le contexte par domaine. Les autres modes conviennent surtout pour une baseline strictement commune à toutes les équipes.

À l’échelle de la squad : ici une squad = une équipe (un domaine du monorepo). La plupart des devs restent dans leur domaine, mais certains sont transverses et passent d’un domaine à l’autre. Si tu isoles tout strictement par domaine, ceux-là doivent recharger une config à chaque changement. La parade tient en deux couches : (1) une baseline commune — ce dont tout le monde a besoin quel que soit le domaine — installée pour tous ; (2) les primitives propres à chaque domaine, déclarées en APM dans son dossier. Résultat : chacun charge baseline + domaine courant, jamais le catalogue de toutes les équipes réunies.

Scénario D — Développeur mono-stack, multi-repo

Le dev ne touche qu’un seul stack (ex. React) mais le répartit sur plusieurs dépôts : front-app-1, front-app-2, design-system. C’est le cas qui réhabilite le plugin.

Recommandation : mono-stack multi-repo → c’est le scénario où plugin (ou symlink user) redevient compétitif : comme tous les repos partagent le stack, l’argument « coût partout » tombe. Le choix se joue alors sur version épinglée + cohérence (→ APM) contre simplicité du geste unique (→ plugin). Si la reproductibilité d’équipe prime, garde APM ; pour un dev solo, le plugin suffit.

À l’échelle de la squad : c’est là que la nuance est décisive. Si une seule dev de la squad est full-stack et passe sur front-app-1 puis sur le back, la diversité de stacks réapparaît au niveau du groupe — et pour elle le plugin redevient « chargé partout ». Tranche au niveau squad, pas au dev : squad réellement 100 % mono-stack → plugin acceptable ; dès qu’un membre croise les stacks → APM par repo protège tout le monde sans imposer de coût « partout ».

Synthèse

Le critère reste le même pour les quatre : portée voulue (projet vs machine) et garantie de version (lockée vs HEAD). APM est le seul à offrir périmètre projet et version épinglée ; les trois autres troquent l’une contre la simplicité.

APM tout le temps ? Non

Les quatre scénarios penchent vers APM — mais ce n’est pas un réflexe universel. APM gagne dès qu’il y a diversité de profils ou besoin de version épinglée ; il cède la place quand :

• squad réellement 100 % mono-stack (Scénario D) → le plugin (ou un symlink user) suffit, sans coût « partout » puisque tout est pertinent ;
• outil transverse qui doit s’appliquer partout sans exception (secret-scan de sécurité, token killer comme SNIP) → côté machine, justement pour qu’aucun repo ne puisse y échapper (voir ci-dessous) ;
• dev solo ou prototypage → le geste unique d’un plugin ou d’un git clone + symlink évite la cérémonie du manifeste ;
• tu veux le dernier HEAD en continu plutôt qu’une version lockée → le symlink + git pull est plus direct ;
• tu as des tokens « illimités » (forfait sans facturation au token) → l’argument « coût partout » disparaît : tu peux te permettre d’installer large. Mais attention, ce n’est pas gratuit pour autant : charger des dizaines de descriptions inutiles dilue le contexte et peut dégrader la qualité des réponses (le modèle disperse son attention sur du bruit). Tu ne payes plus en euros, tu payes en pertinence — un nouveau souci qui remplace l’ancien.

Autrement dit : APM est le défaut raisonnable en équipe, pas une règle absolue. Garde les autres modes pour le transverse universel et le solo — ce que la section suivante illustre sur la sécurité et l’optimisation des tokens.

Exercice

Quatre parties indépendantes, de la plus simple à la plus exigeante.

Partie A — Mesure l’empreinte « toujours chargée » ⭐

Ce qui pèse à chaque tour, c’est la description de chaque skill/agent. Mesure-la sur un de tes projets, de façon déterministe. La commande ci-dessous ne suppose pas APM : elle cherche les emplacements courants (.github/, .agents/, .claude/) et tous les SKILL.md / *.agent.md où qu’ils soient.

# Empreinte de chaque description (≈ ce qui est toujours chargé), avec ou sans APM
{ find . -type f \( -name 'SKILL.md' -o -name '*.agent.md' \) 2>/dev/null
  find .github .agents .claude -type f -name '*.md' 2>/dev/null
} | sort -u | while read -r f; do
  chars=$(awk '/^description:/{flag=1} flag{print} /^---$/{if(flag) exit}' "$f" | wc -c)
  [ "$chars" -gt 1 ] && printf '%5d car  ~%4d tokens  %s\n' "$chars" $((chars / 4)) "$f"
done | sort -rn

Les plugins installés sur ta machine vivent hors du dépôt : cette commande ne les voit pas. Elle mesure l’empreinte portée par le projet ; pour les plugins machine, liste-les côté VS Code (Partie D, point 4).

Réponds : quel est le total approximatif en input tokens ? Quels sont les 3 plus gros contributeurs ? Si tu n’en utilises que la moitié au quotidien, combien de tokens une installation par projet te ferait-elle économiser à chaque message ?

Partie B — Le piège du mono-stack ⭐⭐

Une squad se présente comme « 100 % React » et veut donc installer ses skills en plugin (geste unique, tout est pertinent). Mais une de ses développeuses est en réalité full-stack : elle intervient sur front-app-1 et sur le service back en Java.

1. Où est le piège ? Qu’arrive-t-il à l’argument « coût partout » pour elle ?
2. Tranche au niveau squad (pas au dev moyen) : plugin ou APM ? Justifie avec un argument tokens et un argument cohérence.

Partie C — Place trois outils ⭐⭐

Pour chacun, dis côté machine (plugin / symlink user) ou APM (projet), en une phrase de justification :

1. CAVEMAN, instruction de réduction de token.
2. SNIP, le token killer, livré comme hook.
3. le design system, livré comme plugin, propre à l’app front-app-1.

Indice : repose-toi sur la question qui tranche — cet outil doit-il s’appliquer partout sans exception, ou son périmètre dépend-il du projet ? Et remarque que le type de primitive (hook ou plugin) ne décide pas du mode de distribution : un hook comme un plugin peut être posé côté machine ou déclaré côté projet — la vraie question reste « machine ou projet ? ».

Partie D — Audit d’un de tes vrais projets ⭐⭐⭐

Ouvre un projet réel sur lequel tu travailles et réponds, preuves à l’appui :

1. Coût des en-têtes : pour chaque skill dont tu as réellement besoin, mesure le coût de son en-tête (réutilise la commande de la Partie A). Quel est le total toujours chargé ?
2. Non versionné = potentiellement périmé : combien de skills/agents ne sont pas versionnés (installés hors APM, donc sans lockfile) ? Lesquels risquent d’être désynchronisés d’une machine à l’autre dans l’équipe ?
3. Tes skills de repo sont-ils trop larges ? : parmi les skills déclarés dans le repo, lesquels s’appliquent tout le temps, hors stack (universels) ? Ceux-là gagneraient peut-être à passer côté machine au lieu d’être redéclarés dans chaque repo.
4. Tes plugins machine sont-ils vraiment universels ? : à l’inverse, parmi les plugins installés sur ta machine, lesquels ne sont pas pertinents partout ? Ceux-là te coûtent « partout » pour rien → candidats à un passage en APM par projet.
5. Onboarding documenté ? : comme un plugin ne laisse aucune trace dans le repo, vérifie qu’un README (ou un guide de démarrage) existe et mentionne les skills/plugins utiles pour qu’un nouveau dev sache quoi installer. S’il manque, écris-le.

Validation

Tu as réussi si tu sais :

• citer les quatre modes de distribution et, pour chacun, sa portée et sa garantie de version ;
• expliquer pourquoi l’impact tokens dépend de la portée de l’installation (projet vs machine), pas du nom de l’outil ;
• trancher les quatre scénarios avec un argument tokens et un argument cohérence ;
• modérer chaque reco à l’échelle de la squad : reconnaître qu’un profil mixte (une full-stack qui passe sur front-app-1) déplace le bon choix vers une installation par projet ;
• justifier le placement d’un outil transverse (hook de sécurité, token killer comme SNIP) plutôt côté machine.

Pour aller plus loin — le cas du hook de sécurité

Question ouverte, à débattre dans ton équipe : un hook de sécurité — par exemple un scanner de secrets type gitleaks déclenché avant chaque commit — vaut-il mieux côté machine (plugin, symlink user) ou côté projet (APM) ?

• Côté machine : présent sur toutes les machines, indépendant du repo, difficile à contourner par oubli de déclaration. Idéal pour une règle non négociable qui doit s’appliquer partout.
• Côté projet (APM) : versionné, auditable, mais ne s’active que si le repo le déclare — un repo qui oublie la dépendance n’est pas protégé.

Le compromis :

• sécurité non négociable et universelle (secret-scan, blocage de push de credentials) → côté machine, pour qu’aucun repo ne puisse y échapper ;
• politique spécifique au projet (règles métier, conventions d’un domaine) → APM, pour la versionner et l’auditer avec le code.

Et côté tokens : un hook ne consomme la fenêtre de contexte que lorsqu’il s’exécute — son coût « toujours chargé » se limite à sa déclaration. C’est donc une primitive peu coûteuse à généraliser.

Deuxième cas : SNIP, un token killer transverse

SNIP est un outil de réduction de contexte — un token killer : il découpe et compresse ce qu’on envoie au modèle pour faire baisser la facture de tokens. Où le placer ?

• Côté machine (plugin) : tu veux qu’il agisse sur chaque session, dans chaque repo, sans que personne n’ait à y penser. Son bénéfice est transverse (il fait économiser des tokens partout) et son propre coût « partout » est négligeable. C’est le profil parfait du plugin.
• Côté projet (APM) : possible, mais tu limites l’outil aux seuls repos qui le déclarent — alors que son intérêt est justement d’être partout.

Recommandation : un outil d’optimisation transverse comme SNIP → plutôt côté machine. Même logique que la sécurité : ce qui doit s’appliquer universellement et sans oubli va sur la machine ; ce qui est spécifique à un projet va dans APM.

Pour creuser :

• Module 207 — APM — manifeste et lockfile.
• Module 209 — Plugins — scopes d’installation et sécurité d’un plugin.
• Module 105 — Hooks — déclencheurs et cycle de vie.