Skills, Hooks, Subagents : comment on monte une vraie équipe Claude Code

Je vais commencer par une statistique qui m'a surpris.

Sur les douze projets clients où on a intégré Claude Code depuis février, dix avaient déjà créé un Skill avant qu'on arrive. Mais aucun n'avait écrit un Hook. Et seulement deux utilisaient des Subagents — et chaque fois pour de mauvaises raisons.

Le problème, ce n'est pas que les Hooks sont compliqués. C'est qu'on parle peu de quand utiliser quoi, et que la doc officielle, aussi bonne soit-elle, ne dit pas explicitement "voilà comment vous devriez structurer votre .claude/ pour un repo de production".

C'est ce que cet article essaie de combler. Voilà ce qu'on a appris à monter, à débugger, et à expliquer aux clients.

Les trois choses à comprendre une bonne fois

Claude Code expose trois couches d'extensibilité. Elles ne servent pas du tout à la même chose, et c'est là que les gens se perdent.

Une Skill, c'est un fichier Markdown avec un frontmatter, que vous invoquez comme slash-command. Vous écrivez /review-component au lieu de retaper vos 200 mots de prompt à chaque fois. C'est un template de prompt versionné. Anthropic appelle ça "Skills" pour ne pas dire "macros de prompt", mais en pratique c'est exactement ça — et c'est très bien.

Un Hook, c'est un script (shell, Python, peu importe) qui se déclenche sur un événement Claude Code. PreToolUse, PostToolUse, Stop, etc. Contrairement à une Skill, ce n'est pas Claude qui décide d'exécuter le script — c'est le harness Claude Code. Si le script sort en code 2, l'action est bloquée. C'est votre garde-fou déterministe, qui marche même si Claude est mal-prompté ou en pleine hallucination.

Un Subagent, enfin, c'est une instance Claude séparée avec son propre context window, son propre prompt système, et son propre set de tools. Quand l'agent principal délègue, seul le résumé final remonte dans la conversation principale (doc officielle).

Si vous retenez une règle, retenez celle-là : commencez par les Skills (c'est le moins cher, le plus de valeur). Ajoutez des Hooks quand vous avez besoin d'une garantie déterministe que Claude ne peut pas contourner. Sortez les Subagents quand le parallélisme ou l'isolation contextuelle devient critique.

Les Skills, c'est votre bibliothèque commune

Une Skill, c'est l'équivalent d'un snippet ou d'une macro VS Code — sauf qu'au lieu de coller du texte, vous demandez à Claude d'exécuter un workflow.

Voilà à quoi ressemble une Skill qu'on déploie systématiquement chez nos clients, pour la review de composants React :

---
name: review-component
description: Audit complet d'un composant React (lisibilité, perf, a11y)
allowed-tools: Read, Grep, Bash
argument-hint: "[path/to/component.tsx]"
---

# Review Component

You are auditing a React component. Read the file at $ARGUMENTS, then:

1. **Lisibilité** : nommage, complexité cyclomatique, profondeur d'imbrication
2. **Performance** : memoization, re-renders, bundle impact
3. **Accessibilité** : ARIA, contraste, focus, sémantique
4. **Patterns** : conformité au style guide /docs/style-guide.md

Réponds en français, structuré par section. Sors la note /10 par axe + 3 fixes prioritaires.

Vous écrivez ça une fois, vous le versionnez dans le repo, et tout le monde dans l'équipe peut taper /review-component src/components/Button.tsx. Plus de "tu peux me passer ton prompt de review" sur Slack.

Une Skill est le bon outil quand vous répétez un prompt long plus de trois fois, quand le prompt évolue et que vous voulez le versionner, ou quand plusieurs personnes doivent l'invoquer de manière identique. Bref, quand vous voulez de la cohérence sans en payer le coût cognitif.

Là où ça pose problème : quand les gens mettent des règles de sécurité critiques dans une Skill. Genre "ne déploie jamais en prod sans tests verts". Une Skill, c'est un prompt — Claude peut l'interpréter avec créativité, voire l'ignorer si le contexte le pousse. Si c'est critique, c'est un Hook qu'il vous faut.

Les Hooks, c'est votre filet de sécurité

Là où une Skill demande gentiment, un Hook impose. Le harness Claude Code intercepte l'événement, exécute votre script, et si le script échoue, l'action est bloquée. Point.

Le cas d'usage qu'on déploie en priorité chez tous nos clients : bloquer les pushes directs vers main. Voilà à quoi ça ressemble :

#!/usr/bin/env bash
# .claude/hooks/pre-bash.sh — Triggered by PreToolUse on Bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "git push.*\bmain\b|git push.*\bmaster\b"; then
  echo "❌ Direct push to main/master is forbidden. Use a PR." >&2
  exit 2
fi
exit 0

Et le binding dans .claude/settings.json :

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": ".claude/hooks/pre-bash.sh" }] }
    ]
  }
}

L'agent peut être charmé, mal-prompté, jailbreaké par un coller-coller hasardeux d'un PR — le hook s'exécute. C'est votre dernière ligne de défense.

Les hooks qu'on met en place quasi systématiquement :

Un secret-guard qui scanne les diffs avant écriture, et bloque si on voit passer AWS_SECRET, API_KEY, ou un -----BEGIN PRIVATE KEY-----. Trois clients sur douze avaient déjà committé un secret dans leur historique avant qu'on arrive. Le hook en a sauvé deux pendant nos premières semaines.
Un format-on-edit qui lance prettier ou ruff format après chaque édition. Vous ne reverrez plus jamais de PR avec des espaces aléatoires.
Un test-on-stop qui lance les tests rapides à la fin de chaque session. Pas tous les tests — juste ceux qui touchent à des fichiers modifiés. C'est la version "test impact analysis" du pauvre, mais ça marche.

Là où les Hooks sont mal utilisés : quand on essaie de leur faire faire du jugement subjectif. "Le code est-il bien commenté ?" → ça, ce n'est pas un Hook, c'est une review. Si vous voulez automatiser ça, c'est un Subagent.

Les Subagents, c'est votre parallélisme et votre isolation

Et on arrive aux Subagents. C'est probablement la couche la plus puissante, et celle où on voit le plus d'erreurs.

Un Subagent, c'est une instance Claude avec son propre contexte. Quand l'agent principal lui délègue une tâche, il fait l'équivalent d'un await subagent.run("fais ça") — et il récupère uniquement le résumé final. Les 50K tokens de logs que le subagent a parsés pour trouver le bug ? Ils restent dans son contexte à lui. Le main agent n'en voit qu'un "j'ai trouvé : la race condition est sur la ligne 47, voici le diff proposé".

Trois bénéfices concrets :

D'abord, le context window du main agent reste propre. Vous tenez des sessions plus longues sans vous faire compactiifer. C'est énorme sur les projets gros où chaque token compte.

Ensuite, vous pouvez donner à chaque subagent des permissions différentes. Notre security-scanner a accès en Read et Grep mais pas en Write ni Bash — il peut auditer mais ne peut rien modifier. C'est le principe du moindre privilège appliqué aux agents.

Enfin, le parallélisme. C'est probablement le gain le plus visible. Sur nos PR clients, on lance en parallèle quatre subagents : code-reviewer, test-runner, a11y-auditor, security-scanner. Chacun fait son boulot dans son coin, le main agent synthétise les quatre résumés en un commentaire de PR final. Avant : cinq minutes en séquentiel. Après : 90 secondes en parallèle.

                Main Claude Agent (orchestrator)
                          │
       ┌──────────────────┼──────────────────┬────────────────┐
       ▼                  ▼                  ▼                ▼
  code-reviewer    test-runner         a11y-auditor     security-scanner
  Read, Grep       Read, Bash          Read, Bash       Read, Grep
       │                  │                  │                 │
       └──── résumé ──────┴──── résumé ──────┴──── résumé ─────┘
                          │
                  Main agent synthétise
                  → commentaire PR final

Là où les Subagents tournent mal, c'est quand on en abuse. Spawn un subagent ajoute environ trois à cinq secondes d'overhead — entre l'initialisation, le prompt système, et la génération du résumé final. Pour une opération de deux secondes, vous triplez la latence pour rien. La règle qu'on s'est donnée : si vous pouvez faire la tâche en moins de cinq secondes en direct, ne sortez pas un subagent.

La structure `.claude/` qu'on déploie

Voilà ce que ça donne en pratique sur un projet moyen. C'est devenu notre template de base :

.claude/
├── settings.json          # config + bindings hooks
├── CLAUDE.md              # spec du projet (chargé auto)
├── hooks/
│   ├── pre-bash.sh        # bloque git push main, rm -rf /, etc.
│   ├── secret-guard.sh    # PreToolUse Write/Edit — scan secrets
│   ├── format-on-edit.sh  # PostToolUse Edit — prettier/ruff
│   └── test-on-stop.sh    # Stop — tests rapides si touched
├── skills/
│   ├── review-component/SKILL.md
│   ├── new-route/SKILL.md
│   ├── debug-prod-incident/SKILL.md
│   └── deploy-staging/SKILL.md
└── agents/
    ├── code-reviewer.md
    ├── security-scanner.md
    ├── a11y-auditor.md
    └── test-runner.md

La règle qu'on se donne : un nouveau dev doit pouvoir lire ce dossier en 15 minutes et comprendre comment travailler sur ce repo. Pas seulement quoi faire, mais comment. Quels hooks vont l'engueuler, quelles Skills sont à sa disposition, quels subagents existent.

Les chiffres après six mois de déploiement

Quelques métriques agrégées sur les douze projets, parce que je sais que c'est ce que vous voulez voir.

Le temps moyen de review d'une PR est passé de 4 min 30 à 1 min 40 (oui, on a mesuré). Les incidents "j'ai oublié de formatter" sont passés de 12 par sprint à zéro grâce au format-on-edit. Les tokens consommés par session typique sont passés de 180K à 65K — le gain vient surtout de l'isolation des subagents.

Et le truc qui plaît le plus aux managers : zéro secret committé en six mois sur les douze repos. Avant, on avait eu trois incidents en deux ans. Le hook secret-guard tourne en silence, fait son boulot.

L'investissement initial — mise en place hooks, Skills, subagents — c'est environ deux jours sur un repo de taille moyenne. Le ROI est atteint sur trois à cinq sprints. Si vous comptez en heures-ingénieur économisées, c'est une des meilleures décisions d'outillage qu'on a vues passer chez nos clients cette année.

Pour aller plus loin

On met en place ces stacks pour des équipes produit qui veulent utiliser Claude Code sérieusement, pas comme un gadget. Si votre repo souffre d'oublis de format, de secrets ou de reviews lentes, écrivez-nous — l'audit initial est gratuit.