Sous-agents, compétences et plugins

Une conversation Claude Code se dégrade quand son contexte se remplit — c’est le mécanisme du chapitre 3, appliqué au code. Une exploration qui lit trente fichiers remplit la fenêtre de résultats dont vous n’aurez plus jamais besoin.

Les sous-agents sont la réponse à ce problème. Les compétences et les plugins traitent une question différente : la réutilisation et la distribution.

Les sous-agents#

Un sous-agent est un exécutant distinct : son propre contexte, sa propre invite système, ses propres outils, éventuellement son propre modèle. Il reçoit une mission, travaille de son côté, et ne renvoie que sa conclusion.

Le gain principal n’est pas la parallélisation : c’est que les résultats intermédiaires ne polluent pas votre conversation.

Ceux qui existent déjà#

Claude Code en fournit plusieurs, utilisés automatiquement.

Explore — agent de recherche en lecture seule. Écriture et édition refusées. C’est lui qui part chercher dans le dépôt quand Claude a besoin de comprendre avant d’agir. On lui indique un niveau de profondeur, du repérage ciblé à l’analyse exhaustive.

Plan — agent de recherche utilisé pendant le mode plan, pour que l’exploration reste dans un contexte séparé et la conversation principale en lecture seule.

Général — agent complet, tous outils, pour les tâches à plusieurs étapes mêlant exploration et modification.

Explore et Plan ignorent délibérément vos CLAUDE.md pour rester rapides et légers. Les autres les chargent.

En écrire un#

Un sous-agent est un fichier Markdown avec un frontmatter YAML, dans .claude/agents/ pour le projet ou ~/.claude/agents/ pour tous vos projets.

---
name: auditeur-securite
description: Recherche les vulnérabilités courantes dans le code : injection, secrets en dur, validation d'entrée manquante, contrôle d'accès absent. À utiliser avant une mise en production ou sur une revue de code sensible.
tools: Read, Grep, Glob
model: sonnet
---

Tu es un auditeur de sécurité applicative. Tu ne modifies jamais de code :
tu signales.

Pour chaque problème trouvé, rends exactement :
- Fichier et ligne
- Nature du problème, en une phrase
- Le code concerné, recopié
- Gravité : critique, élevée, moyenne, faible
- La correction recommandée, décrite mais non appliquée

Ordre de priorité de ta recherche :
1. Secrets en dur : clés, mots de passe, jetons
2. Injection : SQL, commandes, chemins de fichiers
3. Validation d'entrée absente sur les points d'entrée externes
4. Contrôle d'accès manquant ou incohérent
5. Données sensibles en clair dans les journaux

Ne signale pas de problème théorique sans montrer le chemin par lequel
une entrée non maîtrisée l'atteint. Un signalement sans chemin
d'exploitation est du bruit.

Si tu ne trouves rien de sérieux, dis-le franchement. Ne remplis pas
ton rapport pour donner l'impression d'avoir travaillé.

Quatre champs comptent.

name — l’identifiant, utilisé pour l’invoquer explicitement.

description — c’est elle qui décide de la délégation automatique, exactement comme pour une compétence au chapitre 17. Nommez la tâche et les situations qui doivent la déclencher.

tools — la liste des outils autorisés. Sans ce champ, le sous-agent hérite de tout. Restreignez. Un auditeur qui ne peut pas écrire ne peut pas casser.

model — le modèle à utiliser. Un agent d’exploration mécanique peut tourner sur un modèle rapide ; un agent de revue mérite mieux.

Les deux dernières lignes de l’invite ci-dessus méritent d’être copiées partout : sans elles, un auditeur remplit son rapport pour justifier son existence.

Quand ça ne vaut pas le coup#

Un sous-agent repart de zéro. Il ne connaît ni votre conversation, ni ce que vous venez de décider.

Cela veut dire deux choses.

Sur une tâche courte, c’est perdant. Le coût de rétablissement du contexte dépasse le gain. Si la conversation principale peut le faire en deux ou trois appels d’outils, laissez-la faire.

Il faut le briefer complètement. Une mission floue produit un rapport à côté, et vous ne verrez pas pourquoi : le travail s’est déroulé ailleurs.

Le sous-agent devient rentable quand la tâche produit beaucoup de résultats intermédiaires dont vous n’aurez plus besoin. Recherche large, audit, lecture de journaux, exploration d’un dossier inconnu.

Les compétences dans Claude Code#

Les compétences du chapitre 17 fonctionnent ici aussi, et la distinction avec les sous-agents mérite d’être posée nettement.

Compétence : « voici comment on écrit un test dans ce projet ». Sous-agent : « va auditer ce dossier et reviens me dire ce que tu as trouvé ».

Les deux se combinent : un sous-agent peut disposer de compétences.

Les commandes personnalisées#

Un troisième mécanisme, plus simple et souvent suffisant : une commande de barre oblique définie par un fichier Markdown dans .claude/commands/.

---
description: Prépare une revue de la branche courante
---

Analyse les modifications de la branche courante par rapport à `main`.

1. `git diff main...HEAD --stat` pour voir l'étendue
2. Pour chaque fichier modifié de façon substantielle, lis-le en entier
3. Produis :
   - un résumé du changement, en trois phrases
   - les points qui méritent une attention en revue, avec fichier et ligne
   - ce qui manque : tests, documentation, gestion d'erreur
   - les questions à poser à l'auteur

N'utilise pas de sous-agent : je veux les détails dans cette conversation.

Le fichier .claude/commands/revue.md crée la commande /revue. C’est le moyen le plus léger de figer une demande longue que vous retapez souvent.

La règle de choix :

• une demande que vous retapez → une commande ;
• une méthode que Claude doit appliquer sans qu’on la demande → une compétence ;
• un travail qui doit se dérouler ailleurs → un sous-agent.

Les plugins#

Un plugin regroupe en un seul objet distribuable : commandes, sous-agents, compétences, hooks, serveurs MCP, réglages.

C’est le mécanisme de distribution. Il répond à une question précise : comment faire en sorte que les six personnes de l’équipe aient la même configuration, et qu’une amélioration profite à tout le monde ?

Sans plugin, une bonne configuration reste sur la machine de celui qui l’a écrite. Avec, elle s’installe, se met à jour et se versionne comme une dépendance.

L’architecture type d’un plugin d’équipe :

plugin-equipe/
├── .claude-plugin/
│   └── plugin.json          # nom, version, description
├── commands/
│   ├── revue.md
│   └── nouvelle-migration.md
├── agents/
│   ├── auditeur-securite.md
│   └── explorateur-api.md
├── skills/
│   └── conventions-tests/
│       └── SKILL.md
└── hooks/
    └── hooks.json           # formatage, garde-fous

Trois conseils tirés de ce qui rate.

Commencez par une seule chose. La commande que tout le monde retape. Un plugin adopté vaut mieux qu’un plugin complet et ignoré.

Versionnez. Un plugin sans version se met à jour en silence et casse les habitudes de tout le monde le même matin.

Documentez le pourquoi. Un sous-agent dont personne ne sait quand il sert ne sera jamais invoqué.

> Utilise l'agent auditeur-securite sur les fichiers modifiés dans
  cette branche par rapport à main.

Je veux uniquement son rapport, pas le détail de son exploration.

> Utilise l'agent auditeur-securite sur src/api/paiement/.

Contexte à lui transmettre : ce module vient d'être modifié pour
accepter des paiements en plusieurs fois. Les montants sont en centimes,
en entiers. L'authentification est faite en amont par un middleware,
il n'a pas à la chercher ici.

Ce qu’il faut retenir#