# 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.

<table width="100%">
<tr>
<td><a href="../">← Retour à Claude Code Best Practice</a></td>
<td align="right"><img src="../../!/claude-jumping.svg" alt="Claude" width="60" /></td>
</tr>
</table>

## 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 :

```bash
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

1. **Mets les workflows partagés dans `.claude/skills/` racine** — Conventions valables pour tout le dépôt, workflows de commit et patterns partagés.

2. **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.

3. **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.

4. **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.

5. **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) |

---

## Sources

- [Documentation Claude Code - Étendre Claude avec les skills](https://code.claude.com/docs/en/skills)
- [Documentation Claude Code - Découverte automatique depuis les répertoires imbriqués](https://code.claude.com/docs/en/skills#automatic-discovery-from-nested-directories)
