Créer un sous-agent

Créer un sous-agent revient à écrire un fichier Markdown. Cette leçon montre les deux façons de le faire, le format du fichier, l’endroit où le ranger et les trois manières de l’appeler. Vous finirez par en créer un vous-même.

Mise à jour du 5 novembre 2026 — la commande /agents. Le cours officiel crée les sous-agents avec la commande /agents, qui ouvrait un assistant de création. Depuis la version 2.1.198 de Claude Code, /agents n’ouvre plus cet assistant : elle rappelle simplement de demander à Claude ou de modifier directement les dossiers .claude/agents/ et ~/.claude/agents/. Cette leçon suit la méthode actuelle.

Méthode 1 : demander à Claude

La plus simple. Décrivez le sous-agent voulu et l’endroit où l’enregistrer. Voici l’exemple de la documentation :

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude écrit le fichier avec un nom, une description, une liste d’outils, un modèle et des instructions. Relisez-le et vérifiez que l’en-tête correspond à ce que vous avez demandé :

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Testez-le : « Use the code-improver agent to suggest improvements in this project ». Dans la conversation, la délégation apparaît comme un appel d’outil avec le nom du sous-agent et une courte description de la tâche, par exemple code-improver(Suggest code improvements). Si Claude ne trouve pas le nouveau sous-agent, redémarrez Claude Code : cela n’arrive que si le dossier ~/.claude/agents/ n’existait pas au début de la session.

Méthode 2 : écrire le fichier

Un sous-agent, c’est un en-tête YAML entre deux lignes ---, puis un corps en Markdown qui devient son prompt système. Seuls deux champs sont obligatoires :

• name : un identifiant unique, comme code-reviewer (sans deux-points, réservés aux plugins) ;
• description : quand Claude doit lui déléguer une tâche.

Les champs facultatifs les plus utiles :

Attention à l’orthographe : les noms en plusieurs mots s’écrivent en camelCase (maxTurns, disallowedTools), et Claude Code ignore sans erreur un champ qu’il ne reconnaît pas. Pour retrouver une faute de frappe, lancez claude --debug et cherchez does not recognize or apply dans le journal de débogage.

Le corps du fichier est tout ce que le sous-agent reçoit comme instructions : il ne reçoit pas le prompt système de Claude Code, seulement le sien et quelques détails sur l’environnement, comme le dossier de travail.

Où le ranger

L’emplacement décide de la portée. Si deux sous-agents portent le même nom, celui de l’emplacement prioritaire l’emporte :

Les sous-agents de projet ont vocation à être commités : toute l’équipe en profite et peut les améliorer. Claude Code parcourt ces dossiers récursivement, ce qui permet de les ranger en sous-dossiers (agents/review/, agents/research/) ; l’identité vient du seul champ name. Les fichiers ajoutés ou modifiés sont pris en compte en quelques secondes, sans redémarrage, sauf pour le tout premier fichier d’un dossier agents qui n’existait pas au lancement.

Pour un essai ou un script, vous pouvez aussi définir des sous-agents le temps d’une session, en JSON :

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

L’appeler

Trois façons, de la plus souple à la plus contraignante :

• En langage courant : « Use the test-runner subagent to fix failing tests ». Claude décide de déléguer ou non.
• Par une mention : tapez @ et choisissez le sous-agent dans la liste, ce qui insère par exemple @"code-reviewer (agent)". Ce sous-agent sera bien utilisé pour cette tâche ; votre message reste transmis à Claude, qui rédige la consigne.
• Pour toute la session : claude --agent code-reviewer fait de la conversation principale elle-même ce sous-agent, avec ses outils et son modèle ; son prompt système remplace celui de Claude Code. Le réglage "agent": "code-reviewer" dans .claude/settings.json en fait le comportement par défaut du projet.

Enfin, Claude délègue aussi de lui-même quand une tâche correspond à la description. Pour l’y encourager, la documentation suggère d’ajouter une formule comme « use proactively » dans la description.

À vous de jouer

Votre premier sous-agent. Créez un sous-agent de projet test-runner dans .claude/agents/. Sa description doit dire quand l’utiliser (après une modification de code, pour lancer les tests). Donnez-lui seulement les outils Bash, Read et Grep, et des instructions qui lui demandent de lancer la suite de tests du projet et de ne rapporter que les tests en échec, avec leur message d’erreur. Testez-le en langage courant, puis avec une mention @.

Sources officielles : Creating a subagent (Claude Academy) · Create custom subagents (documentation Claude Code : format, champs, portées, invocation)

Points clés à retenir

• Un sous-agent est un fichier Markdown : un en-tête YAML (name et description obligatoires) et un corps qui devient son prompt système
• Le plus simple est de demander à Claude de l’écrire, puis de relire le fichier ; /agents n’ouvre plus d’assistant depuis la version 2.1.198
• .claude/agents/ pour un projet (à commiter), ~/.claude/agents/ pour tous vos projets
• Un champ mal orthographié est ignoré sans erreur : claude --debug aide à le repérer
• On l’appelle en langage courant, par une mention @, ou pour toute la session avec --agent