Distribution des compétences pour Claude : combler le vide laissé par Anthropic

Résumé

Anthropic fournit un répertoire — ~/.claude/skills/ — où les fichiers de compétences définissent le comportement de Claude dans des domaines spécifiques. La documentation dit « placez vos fichiers de compétences ici. » Pour un développeur, c’est suffisant. Pour une équipe, c’est un problème de distribution sans réponse prescrite.

Ce document compare trois approches pour combler ce vide : la copie manuelle, la distribution de fichiers groupés MCP (notre solution actuelle) et l’infrastructure réseau Windows. Nous décrivons aussi brièvement une quatrième approche — les compétences comme outils MCP — que nous avons essayée puis abandonnée.

1. Le vide : un répertoire sans mécanisme de livraison

Claude Code charge les fichiers de compétences depuis ~/.claude/skills/ au démarrage de la conversation. Les compétences de projet vivent dans .claude/skills/ à la racine d’un dépôt. Claude.ai lit depuis /mnt/skills/user/. Dans chaque cas, le mécanisme est le même : un répertoire sur le système de fichiers local avec des fichiers Markdown dedans.

Le système de fichiers est le mécanisme de livraison. Mais comment les fichiers y arrivent-ils ? Anthropic ne le prescrit pas. Pour un flux de travail de 50 lignes partagé entre deux développeurs, un message Slack avec un fichier joint fonctionne. Pour une procédure de 500 lignes avec des règles fiscales, des codes d’articles et des cas limites de contrats — distribuée à dix employés dont certains utilisent Claude Code et d’autres Claude.ai — le problème est réel.

Le problème se décompose en trois sous-problèmes :

• Distribution initiale. Comment la compétence arrive-t-elle sur la machine d’un nouvel employé ?
• Mises à jour. Quand la compétence change, comment le changement atteint-il tous les utilisateurs ?
• Synchronisation des versions. Quand une compétence référence un outil MCP par nom, comment s’assurer que l’outil existe dans la version installée ?

2. Ce que nous avons essayé d’abord : les compétences comme outils MCP

Notre première approche était élégante en théorie. Nous avons implémenté trois outils MCP — list_skills, get_skill et get_skill_detail — qui servaient le contenu des compétences à la demande avec un chargement par niveaux. Le résumé compact se chargeait en premier (~500 tokens). Les sections détaillées ne se chargeaient que sur demande. La propriété intellectuelle était protégée dans du JavaScript compilé.

En pratique, cette approche a échoué pour une raison simple : la boucle d’itération. Chaque modification de compétence — une règle fiscale corrigée, un format de référence ajusté, un nouveau cas limite ajouté — exigeait de recompiler le serveur MCP, de republier le paquet npm et de redémarrer Claude Desktop. Aucun raccourci n’existait. Les constantes TypeScript sont immuables après compilation.

Pour un produit stable et gelé, cela pourrait être acceptable. Pour des compétences en développement actif — où vous affinez les règles sur des semaines de production réelle — c’est un obstacle majeur. Nous avons abandonné cette approche après deux semaines.

3. Ce qui fonctionne : distribution de fichiers groupés MCP

La solution que nous utilisons maintenant est plus simple. Les compétences sont des fichiers Markdown stockés dans le dépôt du serveur MCP, dans un répertoire skills/. Au moment de la compilation, ils sont copiés dans le répertoire de sortie. Au démarrage du serveur MCP, ils sont copiés vers ~/.claude/skills/ sur la machine locale.

L’intégralité du mécanisme de distribution tient dans une seule fonction :

// src/helpers/install-skills.ts
import { copyFileSync, existsSync, mkdirSync, readdirSync } from "fs";
import { homedir } from "os";
import { join } from "path";

export function installSkills(): void {
  const srcDir = join(__dirname, "..", "claude-skills");
  const destDir = join(homedir(), ".claude", "skills");
  if (!existsSync(srcDir)) return;
  const files = readdirSync(srcDir).filter((f) => f.endsWith(".md"));
  if (files.length === 0) return;
  mkdirSync(destDir, { recursive: true });
  for (const file of files) {
    copyFileSync(join(srcDir, file), join(destDir, file));
  }
}

L’entrée du serveur appelle installSkills() avant d’enregistrer les outils MCP. Quand un employé exécute npx @dibblee/dibblee-xero-core, les compétences sont installées automatiquement. Quand le paquet est mis à jour via npm update, les compétences sont remplacées au prochain démarrage.

4. L’alternative entreprise : infrastructure réseau Windows

Pour les organisations avec des postes de travail joints à Active Directory, Windows dispose déjà de mécanismes de distribution de fichiers matures : les partages réseau (chemins UNC), les stratégies de groupe (GPO), les scripts de connexion et SCCM/Intune. N’importe lequel de ces mécanismes peut placer des fichiers dans le répertoire ~/.claude/skills/ d’un utilisateur.

Cette approche a du sens lorsque l’organisation possède déjà l’infrastructure, que l’équipe IT gère les déploiements logiciels et que tous les postes de travail sont joints au domaine. Elle présente des avantages réels : les mises à jour ne nécessitent aucune compilation, aucun redémarrage de Claude Desktop, et le ciblage par groupe de sécurité permet des permissions granulaires (compétences comptables pour la comptabilité, compétences d’approvisionnement pour les achats).

L’inconvénient : les compétences et les outils MCP sont découplés. L’IT déploie les fichiers de compétences. npm déploie le serveur MCP. Il n’y a aucune garantie que la version de la compétence correspond à la version du serveur. De plus, cette approche ne fonctionne que sur Windows — les employés sur macOS ou Linux nécessitent un mécanisme de distribution séparé.

5. Comparaison

6. Quand utiliser quelle approche

• Un développeur, compétences simples. Copie manuelle. Un fichier dans ~/.claude/skills/. Rien de plus.
• Équipe, compétences couplées aux outils MCP. Distribution groupée MCP. Les compétences voyagent avec les outils. La synchronisation des versions est automatique. Les éditions locales sont possibles pendant le développement.
• Grande organisation, AD existant, compétences indépendantes des outils. Infrastructure réseau Windows. L’IT gère le déploiement. Le ciblage par groupe de sécurité est intégré. Mais la synchronisation des versions entre compétences et outils n’est pas garantie.
• Compétences gelées, protection IP critique. Les compétences comme outils MCP. La seule approche qui protège véritablement le contenu. Mais seulement si le contenu change rarement.

7. Détail du pipeline de compilation

Le mécanisme complet implique deux étapes coordonnées dans package.json et l’entrée du serveur :

// package.json — build script
"build": "tsc && shx chmod +x dist/*.js && shx cp -r skills dist/claude-skills"

// src/index.ts — server entry point
import { installSkills } from "./helpers/install-skills.js";

async function main() {
  installSkills();  // copy skills before anything else
  const server = XeroMcpServer.GetServer();
  const factory = new ToolFactory(server);
  factory.registerAll();
  // ... connect to stdio transport
}

La commande shx garantit la compatibilité multiplateforme pour les opérations de fichiers. Le répertoire skills/ du dépôt contient les fichiers Markdown source. Ils sont copiés dans dist/claude-skills/ pendant la compilation, puis dans ~/.claude/skills/ à l’exécution.

Les fichiers de compétences utilisent un format frontmatter YAML standard :

---
name: dnd-xero-workflow
description: Parse DND procurement contracts and create invoices or
  purchase orders in Xero with correct tax mapping and item codes
---

## Workflow Steps
1. Receive a DND contract document...

Claude Code lit le nom et la description du frontmatter pour déterminer quand invoquer la compétence. Le corps n’est chargé que lorsque le modèle décide que la compétence est pertinente pour la tâche en cours.

Conclusion

Anthropic a construit un système de compétences puissant avec une hypothèse de déploiement simple : un développeur, un système de fichiers. Le système fonctionne remarquablement bien dans ce contexte. Mais l’instant où vous avez deux personnes qui doivent utiliser la même compétence, le vide de distribution apparaît.

Nous avons essayé l’approche élégante. Elle était trop rigide. Nous utilisons maintenant l’approche pragmatique : empaquetez les compétences avec le serveur MCP, copiez-les sur le système de fichiers local au démarrage, et laissez les développeurs éditer localement quand ils ont besoin d’itérer. Quinze lignes de code Node.js. Pas de framework. Pas d’infrastructure.

Pour les organisations avec une infrastructure Windows existante, les partages réseau et les GPO sont une alternative viable — particulièrement pour les compétences qui ne sont pas couplées à des outils MCP spécifiques. Mais pour la plupart des équipes, le paquet npm est le bon mécanisme de livraison. Il est déjà là. Il fonctionne sur toutes les plateformes. Et il synchronise les compétences avec les outils qu’elles référencent.