Files

T

2026-06-02 23:24:21 +02:00

8.3 KiB

Raw Blame History

Comprendre la découverte des skills Claude dans les grands monorepos

Quand tu travailles avec Claude Code dans un monorepo, comprendre comment les skills sont découverts et chargés en contexte est crucial pour organiser efficacement les capacités propres à ton projet.

← Retour à Claude Code Best Practice

Différence importante avec CLAUDE.md

Les skills N'ONT PAS le même comportement de chargement que les fichiers CLAUDE.md. Alors que les fichiers CLAUDE.md remontent l'arborescence (chargement des ancêtres), les skills utilisent un mécanisme de découverte différent, centré sur les répertoires imbriqués au sein de ton projet.

Comment les skills sont découverts

1. Emplacements de skills standard

Les skills sont chargés depuis ces emplacements fixes selon la portée :

Emplacement	Chemin	S'applique à
Entreprise	Managed settings	Tous les utilisateurs de l'organisation
Personnel	`~/.claude/skills/<skill-name>/SKILL.md`	Tous tes projets
Projet	`.claude/skills/<skill-name>/SKILL.md`	Ce projet uniquement
Plugin	`<plugin>/skills/<skill-name>/SKILL.md`	Là où le plugin est activé

2. Découverte automatique depuis les répertoires imbriqués

Quand tu travailles sur des fichiers dans des sous-répertoires, Claude Code découvre automatiquement les skills depuis les répertoires .claude/skills/ imbriqués. Par exemple, si tu édites un fichier dans packages/frontend/, Claude Code cherche aussi des skills dans packages/frontend/.claude/skills/.

Cela supporte les configurations de monorepo où les packages ont leurs propres skills.

Exemple de structure de monorepo

Considère un monorepo typique avec des packages séparés :

/mymonorepo/
├── .claude/
│   └── skills/
│       └── shared-conventions/SKILL.md    # Skill au niveau projet
├── packages/
│   ├── frontend/
│   │   ├── .claude/
│   │   │   └── skills/
│   │   │       └── react-patterns/SKILL.md  # Skill spécifique au frontend
│   │   └── src/
│   │       └── App.tsx
│   ├── backend/
│   │   ├── .claude/
│   │   │   └── skills/
│   │   │       └── api-design/SKILL.md      # Skill spécifique au backend
│   │   └── src/
│   └── shared/
│       ├── .claude/
│       │   └── skills/
│       │       └── utils-patterns/SKILL.md  # Skill d'utilitaires partagés
│       └── src/

Scénario 1 : Claude vient de démarrer à la racine (aucun fichier édité)

Quand tu lances Claude Code depuis /mymonorepo/ et n'as encore édité aucun fichier :

cd /mymonorepo
claude
# Vient de démarrer - aucun fichier édité pour l'instant

Skill	En contexte ?	Raison
`shared-conventions`	Oui	Skill au niveau projet dans `.claude/skills/` racine
`react-patterns`	Non	Non découvert - tu n'as pas travaillé avec des fichiers de `packages/frontend/`
`api-design`	Non	Non découvert - tu n'as pas travaillé avec des fichiers de `packages/backend/`
`utils-patterns`	Non	Non découvert - tu n'as pas travaillé avec des fichiers de `packages/shared/`

Scénario 2 : Après avoir édité des fichiers dans un package

Après que tu as demandé à Claude d'éditer packages/frontend/src/App.tsx :

Skill	En contexte ?	Raison
`shared-conventions`	Oui	Skill au niveau projet dans `.claude/skills/` racine
`react-patterns`	Oui	Découvert en éditant des fichiers de `packages/frontend/`
`api-design`	Non	Toujours pas découvert - tu n'as pas travaillé avec des fichiers de `packages/backend/`
`utils-patterns`	Non	Toujours pas découvert - tu n'as pas travaillé avec des fichiers de `packages/shared/`

Idée clé : les skills imbriqués sont découverts à la demande quand tu travailles avec des fichiers dans ces répertoires. Ils ne sont pas préchargés au début de la session.

Comportement clé : Description vs contenu complet

Les descriptions de skills sont chargées en contexte pour que Claude sache ce qui est disponible, mais le contenu complet du skill ne se charge qu'à l'invocation. C'est une optimisation importante :

Descriptions : toujours en contexte (dans la limite de caractères)
Contenu complet : chargé à la demande quand le skill est invoqué

Note : les sous-agents avec skills préchargés fonctionnent différemment — le contenu complet du skill est injecté au démarrage.

Ordre de priorité (quand des skills partagent un nom)

Quand des skills partagent le même nom entre niveaux, les emplacements de plus haute priorité l'emportent :

Priorité	Emplacement	Portée
1 (la plus haute)	Entreprise	Toute l'organisation
2	Personnel (`~/.claude/skills/`)	Tous tes projets
3 (la plus basse)	Projet (`.claude/skills/`)	Ce projet uniquement

Les skills de plugin utilisent un espace de noms plugin-name:skill-name, ils ne peuvent donc pas entrer en conflit avec les autres niveaux.

Pourquoi ce design fonctionne pour les monorepos

Les skills propres à un package restent isolés — Les développeurs frontend travaillant dans packages/frontend/ obtiennent les skills frontend sans que les skills backend encombrent le contexte.
La découverte automatique réduit la configuration — Pas besoin d'enregistrer explicitement les skills au niveau package ; ils sont découverts quand tu travailles dans ces répertoires.
Le contexte est optimisé — Seules les descriptions de skills se chargent initialement, et les skills imbriqués sont découverts à la demande.
Les équipes peuvent maintenir leurs propres skills — Chaque équipe de package peut définir des skills propres à son domaine sans se coordonner avec les autres équipes.

Considérations sur la limite de caractères

Les descriptions de skills sont chargées en contexte jusqu'à une limite de caractères (défaut 15 000 caractères). Dans les grands monorepos avec de nombreux packages et skills, tu peux atteindre cette limite.

Lance /context pour voir les avertissements concernant les skills exclus
Définis la variable d'environnement SLASH_COMMAND_TOOL_CHAR_BUDGET pour augmenter la limite

Bonnes pratiques

Mets les workflows partagés dans .claude/skills/ racine — Conventions valables pour tout le dépôt, workflows de commit et patterns partagés.
Mets les skills propres à un package dans le .claude/skills/ du package — Patterns propres au framework, conventions de composants, utilitaires de test uniques à ce package.
Utilise disable-model-invocation: true pour les skills dangereux — Les skills de déploiement ou destructeurs devraient requérir une invocation explicite de l'utilisateur.
Garde les descriptions de skills concises — Les descriptions sont toujours en contexte (dans la limite de caractères), donc des descriptions verbeuses gaspillent de l'espace de contexte.
Utilise des espaces de noms dans les noms de skills — Envisage de préfixer avec les noms de packages (par ex. frontend-review, backend-deploy) pour éviter la confusion.

Comparaison : chargement Skills vs CLAUDE.md

Comportement	CLAUDE.md	Skills
Chargement des ancêtres (vers le HAUT de l'arborescence)	Oui	Non
Découverte imbriquée/descendante (vers le BAS de l'arborescence)	Oui (paresseux)	Oui (découverte automatique)
Emplacement global	`~/.claude/CLAUDE.md`	`~/.claude/skills/`
Emplacement projet	`.claude/` ou racine du dépôt	`.claude/skills/`
Chargement du contenu	Contenu complet	Description seule (complet à l'invocation)

8.3 KiB Raw Blame History