Chapter 3 · Chapitre 3 · Définir le rôle, les instructions et les limites d'un agent
3.1 Anatomie d'un fichier d'agent
Follow this course in your space: your progress is saved, and the community answers your questions.
Follow for freeUn agent, c'est un fichier Markdown composé de deux parties : un en-tête (le « frontmatter ») entre deux lignes ---, puis le corps, qui contient ses consignes.

Un exemple minimal
---
name: critique
description: Relit un script avant publication et signale les problèmes sans le réécrire.
tools: Read, Grep, Glob
model: inherit
---
Tu es un relecteur exigeant. Tu signales, tu ne réécris pas.
Les champs de l'en-tête
| Champ | Obligatoire | Rôle |
|---|---|---|
name | Oui | Le nom unique de l'agent, en minuscules avec des tirets |
description | Oui | Quand l'utiliser : c'est ce que Claude lit pour décider de déléguer |
tools | Non | La liste des outils autorisés. Sans ce champ, l'agent hérite de tous les outils disponibles |
model | Non | Le modèle : sonnet, opus, haiku, inherit (le même que ta conversation) ou un identifiant complet |
La documentation décrit d'autres champs plus avancés, comme disallowedTools (une liste d'outils interdits), permissionMode ou maxTurns (un nombre maximal d'étapes). Tu n'en as pas besoin pour débuter.
Le corps : le prompt système
Tout ce qui suit l'en-tête devient le prompt système de l'agent, c'est-à-dire ses instructions permanentes. D'après la documentation, le subagent reçoit ce prompt et quelques informations d'environnement (comme le dossier de travail), mais pas le prompt système complet de Claude Code. Ce que tu écris dans le corps est donc déterminant.
Les pièges de format
La documentation liste des cas où Claude Code ignore un fichier sans prévenir :
- pas de champ
name; - la première ligne
---n'est pas tout en haut du fichier ; - un
namesansdescription; - un en-tête mal formé (YAML illisible).
Les noms des champs doivent être écrits exactement comme ci-dessus : un champ inconnu est simplement ignoré.
À retenir
- En-tête :
nameetdescriptionobligatoires,toolsetmodelfacultatifs. - Corps : les consignes permanentes de l'agent.
- Un fichier mal formé est ignoré en silence : vérifie toujours que ton agent apparaît dans la liste.