Une bibliothèque centrale pour ta config .claude

Dix dépôts sur ta machine. Chacun embarque un dossier .claude bourré d'agents, de skills, de commandes, de hooks, plus un CLAUDE.md. Quelques-uns restent à jour. La plupart ont commencé à dériver il y a des semaines. L'agent de code review que tu as corrigé le mois dernier vit dans un projet, pas dans les neuf autres. Ton collègue a livré une commande de planification que tu n'as jamais vue parce qu'elle est seulement dans son dépôt.

C'est le problème de distribution du dossier .claude. Ajoute un projet et ça empire.

Gain rapide : Monte un dépôt Git privé qui contient tout ton contenu .claude en un seul endroit, avec un map.json qui décide quel projet reçoit quels éléments :

{
  "projects": {
    "~/projects/webapp": {
      "claude-md": "web-full",
      "skills": ["git-commits", "react", "frontend-design"],
      "agents": ["visual-explainer"],
      "commands": ["team-plan", "build"]
    }
  }
}

Une commande lance la synchronisation, et le dossier .claude de chaque projet finit par correspondre à son entrée dans la map. Modifie un skill ou un agent sur place, renvoie-le en amont, et chaque autre projet qui référence cet élément hérite du correctif à sa prochaine synchro.

Pourquoi la gestion du dossier .claude est importante

Tu travailles dans un seul codebase ? Tes skills, agents et commandes sont juste à côté du code. Tout est à portée et tout est à jour.

Passe à cinq ou six projets et ça part en vrille :

• Duplication partout. Huit dépôts portent chacun leur propre copie de git-commits, et aucune n'est identique.
• Dérive de version. La mise à jour de la semaine dernière sur la commande de planification n'a atterri que dans un seul dépôt. Les autres tournent encore sur l'ancien code.
• Pas de coordination. Ton collègue a construit un agent de migration de base de données. Tu as refait le tien parce que sa version t'était invisible.
• Étalement de configuration. Les skills ne sont que le début. Hooks, settings.json, fichiers CLAUDE.md, définitions d'agents et slash commands s'accumulent. Chaque projet veut une combinaison différente.

Copier les fichiers est le premier réflexe. Ça semble rapide et ça tient un moment, puis ça s'effondre en moins d'un mois. Chaque ingénieur qui fait tourner des agents sur plusieurs dépôts connaît cette histoire.

IndyDevDan a repéré ça tôt et a livré un correctif purement agentique basé sur un catalogue YAML plein de références à des dépôts et chemins externes. Cette approche a prouvé que l'idée fonctionne. La faire tourner sur 10+ projets avec 30+ skills et 19 agents a révélé le besoin suivant : une structure plus solide. Une vraie gestion de fichiers. Support de variantes. Couverture complète du dossier .claude. Un moteur de synchronisation qui vaut son pesant.

L'architecture de la bibliothèque

La bibliothèque est un dépôt Git privé qui contient toute la configuration .claude. Pas des pointeurs ou des références vers d'autres dépôts. Les fichiers eux-mêmes. Une seule source de vérité pour chaque dossier de skill, chaque définition d'agent, chaque slash command, chaque hook, chaque CLAUDE.md, et chaque settings.json.

Un map.json à la racine indique quel projet reçoit quels éléments. Un script de synchronisation copie les bons fichiers aux bons endroits. Un manifeste dans chaque projet enregistre ce que la bibliothèque possède, pour que les fichiers locaux restent en sécurité.

your-library/
├── map.json                    # Which projects get what
├── sync.mjs                    # Node.js sync engine
│
├── skills/                     # All skill folders
│   ├── git-commits/
│   ├── agentic-builder/
│   ├── react/
│   ├── growth-kit/
│   ├── session-management/
│   └── ... (31 skills in my library)
│
├── agents/                     # All agent .md files
│   ├── frontend-specialist.md
│   ├── backend-engineer.md
│   ├── security-auditor.md
│   ├── master-orchestrator.md
│   └── ... (19 agents in my library)
│
├── commands/                   # All slash commands
│   ├── team-plan.md
│   ├── build.md
│   ├── team-build.md
│   └── ... (16 commands in my library)
│
├── hooks/                      # All hook folders
│   ├── SkillActivationHook/
│   ├── ContextRecoveryHook/
│   └── Validators/
│
├── claude-mds/                 # CLAUDE.md variants (full replacement per project)
│   ├── CLAUDE--web-full.md
│   └── CLAUDE--product.md
│
├── settings/                   # settings.json variants
│   ├── settings--web.json
│   └── settings--product.json
│
└── rules/                      # .claude/rules/ files
    ├── repo-primer--webapp.md
    └── repo-primer--product.md

Huit catégories de contenu (skills, agents, commandes, hooks, règles, claude-mds, settings et fichiers arbitraires), toutes gérées depuis un seul dépôt. Lors d'une synchro, le moteur ouvre map.json, trouve l'entrée du projet, et copie exactement ce que l'entrée liste. Rien de plus, rien de moins.

La map : contrôler ce qui va où

map.json est le cerveau. Chaque entrée de projet détaille les éléments que ce projet reçoit :

{
  "$schema": "library-map-v1",
  "projects": {
    "C:/Github/my-webapp": {
      "claude-md": "CLAUDE--web-full",
      "settings": "settings--web",
      "skills": [
        "git-commits",
        "react",
        "frontend-design",
        "session-management"
      ],
      "agents": ["frontend-specialist", "quality-engineer"],
      "commands": ["team-plan", "build", "team-build"],
      "hooks": ["SkillActivationHook", "Validators"],
      "rules": [],
      "files": {}
    }
  }
}

Un autre projet peut choisir un mélange totalement différent. Un dépôt SaaS tire les agents backend-engineer, supabase-specialist et security-auditor avec les skills postgres-best-practices et auth. Un dépôt axé marketing les échange contre growth-kit, seo-specialist et content-writer. Un dépôt produit reçoit un ensemble plus léger avec un CLAUDE.md différent et des hooks différents. La bibliothèque tient tout le catalogue et chaque projet choisit sa propre tranche.

Les profils regroupent des configurations partagées que plusieurs projets veulent utiliser :

{
  "profiles": {
    "web-default": {
      "claude-md": "CLAUDE--web-full",
      "settings": "settings--web",
      "skills": [
        "git-commits",
        "react",
        "frontend-design",
        "session-management"
      ],
      "agents": ["frontend-specialist", "quality-engineer"],
      "commands": ["team-plan", "build"],
      "hooks": ["SkillActivationHook", "Validators"]
    }
  }
}

Lance --profile web-default quand tu démarres un nouveau projet et toute la pile web atterrit en une seule commande.

Variantes : quand une version ne suffit pas

Les profils laissent un vide. Ton skill git-commits tourne bien dans la plupart des dépôts, alors que le dépôt de blog a besoin d'une version sur mesure qui reconnaît des patterns liés à l'écriture MDX. Le diviser en un nouveau skill est trop lourd. Ce que tu veux vraiment, c'est le même skill avec un chapeau par projet.

Le pattern de nommage est nom--variante, avec un double tiret entre le nom de base et le tag de variante :

skills/
├── git-commits/                    # Base version
│   └── SKILL.md
├── git-commits--blog/              # Variant for blog projects
│   ├── SKILL.md                    # Modified version
│   └── references/
│       └── mdx-patterns.md         # Extra file this variant needs

Dans map.json, la référence utilise le nom complet :

{
  "skills": ["git-commits--blog", "react", "frontend-design"]
}

Lors de la synchro, git-commits--blog se place à .claude/skills/git-commits/. Le suffixe --blog vit seulement dans la bibliothèque. Rien de tout ça n'atteint le projet. La variante est un dossier autonome. Fichiers différents, structure différente, contenu différent. La seule chose qu'elle partage avec la base est un nom de déploiement.

Le push est là où ça paye. Modifie .claude/skills/git-commits/ dans ton projet de blog. Lors du push, le moteur ouvre le manifeste, découvre que le git-commits local remonte à git-commits--blog, et route les modifications vers ce dossier. Les autres projets continuent de tirer depuis la base normale.

Opérations

Le moteur de synchronisation est un script Node.js sans dépendances externes. Huit opérations couvrent le cycle de vie complet :

Le démarrage passe par seed. Pointe-le vers n'importe quel dépôt dont le dossier .claude est déjà en bon état, et tout le dossier atterrit dans la bibliothèque. Une entrée est ajoutée à map.json. Un manifeste est écrit. À partir de là, la propriété canonique vit dans la bibliothèque.

Le hachage de contenu alimente l'opération diff. Elle compare les versions de la bibliothèque et du projet et étiquette chaque élément comme in-sync, local-changes ou library-ahead, pour que la dérive soit visible avant toute synchro ou push.

Le manifeste : suivre ce que la bibliothèque possède

Chaque projet synchronisé reçoit un .claude/.library-manifest.json :

{
  "library_path": "/path/to/your-library",
  "synced_at": "2026-03-24T10:30:00Z",
  "library_commit": "abc123",
  "managed": {
    "skills": {
      "git-commits": "git-commits--blog",
      "react": "react",
      "frontend-design": "frontend-design"
    },
    "agents": {
      "frontend-specialist": "frontend-specialist"
    },
    "claude-md": "CLAUDE--web-full",
    "settings": "settings--web"
  }
}

Dans le manifeste, chaque nom de déploiement est à côté de son nom dans la bibliothèque. Push travaille contre cette correspondance. Un dossier git-commits/ local remonte vers git-commits--blog/ plutôt que d'écraser la base normale.

Les fichiers que le manifeste ne liste pas sont entièrement hors de vue de la bibliothèque. Notes personnelles, sauvegardes, expériences ponctuelles dans .claude/ passent toutes une synchro sans une égratignure. Seuls les éléments que la bibliothèque a placés lui appartiennent.

Interface en langage naturel

Le système vient avec plus qu'une CLI. Une slash command /library se déploie dans chaque projet synchronisé. Oublie les flags et parle en français simple :

/library sync
/library I modified the blog command, push it back
/library add the payment-processing skill to this project
/library what's out of sync?
/library create a variant of react for this project
/library show me everything available

De l'autre côté de la commande, Claude ouvre le manifeste, va dans la bibliothèque, extrait l'intention de la phrase, et lance le moteur de synchronisation. Tout ce qui est destructif (suppressions, écrasements) demande une confirmation d'abord.

C'est le modèle d'interaction qui rend tout ça utilisable au quotidien. La session Claude Code n'a jamais besoin de se fermer pour le travail de bibliothèque. Dis le besoin à voix haute et la bibliothèque réagit.

Pour commencer

Construire ta propre bibliothèque prend environ 30 minutes :

1. Crée un dépôt privé structuré avec ces dossiers : skills/, agents/, commands/, hooks/, claude-mds/, settings/

2. Seed depuis ton meilleur projet. Prends le dépôt dont le dossier .claude est le plus riche aujourd'hui et tire son contenu dans la bibliothèque. Ce paquet devient le catalogue de départ.

3. Écris ton map.json. Commence avec un seul enregistrement de projet. Pour ce projet, détaille chaque élément dont il a besoin : chaque skill, chaque agent, chaque commande, chaque hook, et tout fichier de config.

4. Construis le script de synchronisation. Le cœur reste simple. Charge map.json. Parse les noms d'éléments, en découpant sur -- là où les variantes apparaissent. Copie les fichiers vers leurs destinations. Écris un manifeste. Tire depuis Git avant une synchro. Commit et push après un push.

5. Ajoute la commande /library dans la bibliothèque elle-même. Chaque projet synchronisé la récupère automatiquement, donc le contrôle en langage naturel est disponible dès le départ.

6. Ajoute un deuxième projet avec un mélange différent. Deux dépôts partageant une seule bibliothèque, c'est là que ça paye. Même source, configurations distinctes, sans dérive des deux côtés.

Un choix de conception compte le plus : stocke les vrais fichiers dans le dépôt, pas des pointeurs. L'indirection ajoute une couche qui transforme les variantes en travail supplémentaire et les pushs en nœud. Avec les fichiers directement dans la bibliothèque, synchroniser c'est copier, pusher c'est copier en sens inverse, et differ c'est une vérification de hash.

Pourquoi ça compte à grande échelle

Une fois la bibliothèque en marche, les habitudes changent. Pour référence, la configuration décrite dans ce post couvre 31 skills, 19 agents, 16 commandes, 4 systèmes de hooks, et des fichiers CLAUDE.md et settings.json spécifiques par projet sur 3 projets actifs. Voici comment ça se passe en pratique :

Les améliorations se propagent. Un correctif dans ton agent de code review va dedans une fois. Dès la prochaine synchro, chaque projet qui liste cet agent hérite du patch. Fini de chercher dans quel dépôt un correctif pourrait vivre.

Les nouveaux projets démarrent vite. Initialise un nouveau dépôt avec un profil et toute l'équipe d'agents, le paquet de hooks, les settings et le CLAUDE.md atterrissent en quelques secondes. Fini le rituel de la première heure à copier des fichiers de configuration.

Les variantes évitent les forks. Un projet qui a besoin d'une version modifiée prend maintenant une variante plutôt que de dériver en silence. Base et variante sont liées l'une à l'autre par un lien explicite dans la bibliothèque. Douze mois plus tard, tracer quels projets reposent sur quelles versions reste un travail d'une requête.

La bibliothèque se distribue elle-même. La commande /library vit dans la bibliothèque elle-même. Améliore-la et la mise à jour est embarquée lors de la prochaine synchro vers chaque projet. Le système de distribution est distribué par lui-même.

Le problème de distribution du dossier .claude est le signe d'un changement plus profond. À mesure que l'ingénierie agentique grandit, toute ta configuration .claude devient une vraie infrastructure : skills, agents, commandes, hooks, règles, CLAUDE.md et settings. Elle mérite le même soin que tu donnes au code applicatif. Une façon de le faire : une bibliothèque partagée, consciente des variantes, avec une synchronisation qui coule dans les deux sens.

Pour un bon départ sur ce qu'une bibliothèque peut distribuer, le ClaudeFast Code Kit embarque 20+ skills de production, 18 agents spécialisés (frontend-specialist, backend-engineer, security-auditor, quality-engineer et plus), un système d'orchestration d'équipe, et 5 hooks de production prêts à cataloguer et synchroniser sur tes projets.

Questions fréquentes

C'est quoi un système de bibliothèque Claude Code ?

Un dépôt Git privé qui possède chaque morceau de ton contenu .claude en un seul endroit : skills, agents, commandes, hooks, fichiers CLAUDE.md et settings. map.json décide quels éléments atterrissent dans quel projet. Un moteur de synchronisation navette les bons fichiers vers les bons répertoires.

Quelle est la différence avec the-library d'IndyDevDan ?

La configuration d'IndyDevDan garde des références dans un catalogue YAML, avec des pointeurs atteignant des dépôts GitHub ou des chemins locaux. Le pattern couvert ici stocke les vrais fichiers directement dans un dépôt. Un schéma de nommage de variantes supporte des versions par projet. Un manifeste active la synchronisation bidirectionnelle. Chaque catégorie de contenu .claude est dans le scope : skills, agents, commandes, hooks, règles, CLAUDE.md, settings et fichiers arbitraires.

La bibliothèque doit-elle être open source ?

Non. Un dépôt privé est le bon foyer. La bibliothèque porte des skills spécialisés, des fichiers CLAUDE.md par projet, et des instructions d'agents qui peuvent être sensibles. Garde les choses privées par défaut. Un skill que tu veux publier plus tard peut toujours être extrait dans son propre dépôt.

Comment fonctionnent les variantes ?

Le pattern de nommage nom--variante est l'idée centrale. Un dossier nommé react--strict/ dans la bibliothèque atterrit à .claude/skills/react/ dans le projet. Chaque variante est une copie autonome avec ses propres fichiers et sa propre organisation. Le manifeste enregistre la relation pour que les opérations push ramènent les modifications vers la variante correspondante.

Plusieurs personnes peuvent-elles partager une bibliothèque ?

Oui. Parce que c'est un dépôt Git, une équipe le clone et en tire. Les améliorations de skills remontent sur push. Chaque membre de l'équipe récupère ces correctifs à leur prochaine synchro. map.json peut lister des entrées couvrant les projets de tout le monde.