Les sub-agents Claude Code : vos premiers employés virtuels

Skills ou agents ? Telle est la question. La confusion entre les deux vous coûte du temps et du contexte. Apprenez à créer vos agents et comment les combiner avec des skills.

TLDR;

• Un sub-agent est une instance Claude séparée, avec sa propre fenêtre de contexte, qui exécute une tâche en isolation complète

• Skills et agents répondent à deux besoins différents : les skills apportent de la connaissance, les agents exécutent du travail

• Vous pouvez créer vos propres agents en deux minutes via la commande /agents ou manuellement dans .claude/agents/

• Le champ context: fork dans une skill force son exécution dans un sub-agent, ce qui protège votre contexte principal de la pollution

• La progression naturelle du workflow : CLAUDE.md d’abord, puis skills, puis sub-agents quand le besoin se fait sentir

---

Je pense que le problème suivant est arrivé à quiconque a déjà travaillé avec une IA : votre agent de code lit tellement de fichiers pendant une session de travail que ses réponses commencent à ne plus être cohérentes. Il confond des variables de deux modules différents, oublie des contraintes que vous lui avez données 10 minutes plus tôt… Le fameux context rot dont on a déjà parlé plusieurs fois venait de frapper : la fenêtre de contexte se remplit, la qualité chute et vous finissez par taper /clear en soupirant (cette commande permet de nettoyer le contexte pour partir sur une conversation toute propre).

Il y a pourtant une solution à ce problème : les sub-agents. Des instances Claude séparées, chacune avec sa propre mémoire de travail, qui accomplissent une mission précise et reviennent avec un résumé. Après avoir étudié les hooks et les skills, voici comment fonctionnent les sub-agents, comment les créer et surtout quand les utiliser.

Le modèle mental : connaissance vs. travailleurs

Avant de foncer dans la technique, il y a une distinction à faire : Claude Code a deux mécanismes qui se ressemblent de loin mais qui font des choses très différentes : les skills et les agents.

Pensez à une cuisine de restaurant. Les skills, ce sont les fiches recettes accrochées au mur. Elles contiennent le savoir : comment dresser une assiette, quelles proportions respecter, quel assaisonnement utiliser. Un cuisinier les consulte quand il en a besoin, puis il les range.

Les agents, ce sont les cuisiniers. Chacun a son poste, son plan de travail (sa propre fenêtre de contexte), ses ustensiles (ses outils autorisés). Le chef d’orchestre (votre agent principal) leur confie une mission : “Prépare les entrées”, “Occupe-toi des desserts”. Ils travaillent en parallèle, en isolation, et rendent compte quand c’est terminé.

Concrètement, quand Claude charge une skill, il injecte son contenu dans la conversation en cours. Le contenu de la skill est lu à la demande (pas au démarrage) et vient enrichir le contexte existant. C’est du “chargement de connaissances à la demande”, comme l’explique la documentation officielle : le nom et la description de chaque skill sont indexés au lancement, mais le contenu complet n’est lu que quand Claude juge la skill pertinente pour la tâche en cours.

Un sub-agent, lui, tourne dans un processus séparé. Il a son propre contexte, reçoit des instructions via le Task tool, fait son travail et renvoie uniquement son résultat final à l’agent principal. Tout le bruit intermédiaire (les fichiers parcourus, les erreurs explorées, les pistes abandonnées…) reste dans sa bulle.

Vous voyez la différence ? La skill enrichit votre conversation. L’agent fait le travail ailleurs et vous rapporte un compte-rendu.

---

Créer un agent : 2 méthodes

Méthode manuelle

Un agent, c’est un fichier Markdown avec un frontmatter YAML. Vous le déposez dans .claude/agents/ (au niveau projet) ou ~/.claude/agents/ (au niveau global, pour tous vos projets).

Voici un exemple de fichier complet pour un agent spécialisé dans la revue de sécurité :

---
name: security-reviewer
description: Review code changes for security vulnerabilities and common attack vectors
tools: Read, Grep, Glob, Bash
model: sonnet
color: red
---

You are a security review specialist. Analyze code for:
- SQL injection, XSS, CSRF vulnerabilities
- Hardcoded secrets or API keys
- Improper authentication and authorization
- Insecure data handling

Report findings by priority:
- CRITICAL: Must fix before merge
- WARNING: Should fix soon
- INFO: Consider improving

Be specific: include file paths, line references, and suggested fixes.
Do NOT modify any files.

Les champs du frontmatter méritent une explication rapide. name et description permettent à Claude de savoir quand déléguer à cet agent. tools restreint ce que l’agent peut faire (ici, lecture seule). model vous permet de choisir entre haiku (rapide et peu coûteux), sonnet (bon compromis) et opus (puissance maximale), voire inherit (il utilisera alors le modèle utilisé dans la conversation en cours). color permet de définir une couleur de surlignage pour votre agent lorsqu’il s’affiche dans la conversation.

Si vous omettez tools, l’agent hérite de tous les outils disponibles. Si vous omettez model, il hérite du modèle parent. Et si vous oubliez color, il n’en aura tout simplement pas.

Un détail que beaucoup oublient : le scope compte. Si un agent projet et un agent global portent le même nom, c’est l’agent projet qui gagne.

Commande interactive

Vous pouvez aussi taper /agents directement dans Claude Code. La commande vous guide pas à pas : nom, description, modèle, outils autorisés, instructions, couleur. C’est la méthode recommandée par Anthropic. Vous pouvez aussi simplement demander à Claude de créer un agent pour vous en décrivant ce que vous voulez.

---

---

Agents sans skills vs. avec skills

Sans skills : l’agent généraliste

Claude Code est livré avec des sub-agents intégrés qui couvrent les cas d’usage les plus courants. Le plus courant, c’est Explore : un agent en lecture seule, spécialisé dans la recherche de code. Il utilise Glob, Grep et Read pour parcourir votre codebase sans jamais la modifier. Quand Claude a besoin de comprendre la structure d’un projet ou de trouver où une fonction est appelée, il lance un Explore en arrière-plan.

Il y a aussi le sub-agent general-purpose qui hérite de tous les outils et du contexte de la conversation parente. Celui-ci, c’est le couteau suisse : recherche complexe, modifications multi-fichiers, tâches nécessitant du raisonnement sur plusieurs étapes.

Et le sub-agent Plan, dédié à la phase de conception, qui fait de la recherche dans votre codebase pour proposer une stratégie d’implémentation avant d’écrire la moindre ligne.

Vous voyez ces agents au travail quand Claude affiche “Explore” ou “running in background” dans le terminal. Et vous pouvez les invoquer explicitement. Par exemple : “Lance un explore agent avec Sonnet pour chercher toutes les routes API du projet.” L’agent principal appelle le Task tool, spécifie le type d’agent et le modèle, et le sub-agent part faire son travail.

Avec skills : le câblage d’expertise

Les choses deviennent vraiment intéressantes quand vous câblez des skills à vos agents. Le champ skills dans le frontmatter de l’agent injecte automatiquement le contenu de skills spécifiques dans le contexte du sub-agent au démarrage.

---
name: api-builder
description: Build REST API endpoints following project conventions
tools: Read, Write, Edit, Bash, Grep, Glob
skills:
  - api-conventions
  - error-handling-patterns
---

Build the requested API endpoint following the project's conventions 
and error handling patterns. Run tests after implementation.

L’agent api-builder démarre avec les conventions API et les patterns de gestion d’erreur déjà chargés dans son contexte. Pas besoin de lui rappeler vos règles à chaque invocation. Il est opérationnel dès le démarrage.

C’est un gain réel. Sans skills, vous devriez inclure toutes ces instructions dans le prompt de l’agent (qui deviendrait énorme) ou espérer que l’agent aille les chercher lui-même (et consomme du contexte en chemin). De plus, la skill peut-être partagée entre plusieurs agents.

Le forking : protéger le contexte principal

Il y a un dernier mécanisme qui mérite votre attention. Quand vous ajoutez context: fork dans le frontmatter d’une skill, son exécution se fait automatiquement dans un sub-agent au lieu de s’injecter dans votre conversation principale.

---
name: codebase-audit
description: Run a comprehensive audit of the codebase
context: fork
agent: Explore
---

Analyze the entire codebase and report:
1. Files with more than 500 lines
2. Functions with cyclomatic complexity > 10
3. Unused exports
4. Missing test coverage for public APIs

Quand vous lancez /codebase-audit, Claude ne va pas parcourir 200 fichiers dans votre conversation en cours. Il fork le travail vers un agent Explore dédié. L’agent fait sa recherche, produit son rapport et seul le résultat final revient dans votre contexte.

Le problème que cela résout est concret : sans forking, une exploration intensive de codebase peut remplir votre fenêtre de contexte à 60-70% rien qu’avec les résultats de recherche. Après, il ne vous reste plus assez de place pour la vraie tâche que vous vouliez accomplir. Le forking garde votre contexte propre.

Attention cependant : context: fork n’a de sens que pour les skills qui contiennent des instructions explicites (une tâche à accomplir). Si votre skill ne contient que des guidelines (”utilise ces conventions API”), le sub-agent reçoit les guidelines mais aucun prompt d’action et revient alors les mains vides.

---

Cas d’usage et bénéfices

Isolation du contexte

C’est le bénéfice numéro un et la raison pour laquelle les sub-agents existent. Chaque sub-agent travaille dans sa propre fenêtre de contexte. Quand il recherche dans 50 fichiers pour trouver l’information dont il a besoin, ces 50 fichiers ne polluent pas votre conversation principale. Seul le résumé pertinent revient.

La documentation officielle le dit clairement : les sub-agents sont particulièrement adaptés aux tâches qui produisent beaucoup d’output dont la majorité ne sera pas utile au final. L’exécution de tests, la récupération de documentation, le traitement de fichiers de logs sont des cas typiques.

Exécution parallèle

Plusieurs sub-agents peuvent tourner en même temps. La skill intégrée /batch, par exemple, décompose un changement large en 5 à 30 unités indépendantes et lance des agents en parallèle, chacun dans son propre git worktree. Chaque agent implémente sa partie, lance les tests et peut même ouvrir une pull request.

Pour du travail moins ambitieux, vous pouvez aussi lancer manuellement plusieurs tâches en parallèle. Un agent qui audite la sécurité pendant qu’un autre vérifie la couverture de tests et qu’un troisième recherche les dépendances obsolètes. Au lieu de faire cela séquentiellement (avec le risque de saturer le contexte), vous obtenez trois résultats propres en une fraction du temps.

Spécialisation des instructions

Chaque sub-agent peut avoir des instructions taillées sur mesure pour son domaine. Un agent de review ne pense qu’à la qualité du code. Un agent de déploiement ne connaît que le pipeline CI/CD. Un agent de documentation ne se préoccupe que de la clarté des commentaires.

Cette spécialisation évite un problème courant : quand vous empilez trop d’instructions différentes dans un seul contexte, le modèle finit par en oublier certaines ou par faire des compromis. Avec des agents spécialisés, chacun a un mandat clair et des instructions focalisées.

---

Que faire à partir de maintenant ?

Si vous découvrez ces concepts, ne commencez surtout pas par créer 15 sub-agents personnalisés. Voici une exemple de progression :

Commencez par soigner votre CLAUDE.md (celui qui se situe dans le dossier .claude à la racine de votre projet), c’est la base. Les conventions de votre projet, les patterns que vous utilisez, les erreurs à éviter. Ce fichier est lu à chaque session et donne à Claude le contexte minimum pour travailler correctement.

Quand votre CLAUDE.md devient trop long ou que certaines instructions ne sont utiles que ponctuellement, extrayez-les dans des skills. Les skills ne consomment du contexte que quand elles sont chargées.

Et quand vous constatez que certaines tâches polluent votre contexte, prennent trop de temps séquentiellement ou nécessitent une expertise isolée, créez des sub-agents.

Cette semaine, faites un test simple. Prenez une tâche que vous faites régulièrement (audit de code, recherche dans la codebase, vérification de conventions) et créez un agent dédié avec /agents. Utilisez-le pendant une semaine. Vous verrez la différence sur la qualité de vos sessions longues.

Si cette newsletter vous a été utile, partagez-la à un collègue qui se bat avec des sessions Claude Code qui hallucinent au bout d’une heure.