Skip to content
Floskool

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

Free lesson 10 minGroup Claude Code & IA

Follow this course in your space: your progress is saved, and the community answers your questions.

Follow for free

Un 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 agent = un fichier

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

ChampObligatoireRôle
nameOuiLe nom unique de l'agent, en minuscules avec des tirets
descriptionOuiQuand l'utiliser : c'est ce que Claude lit pour décider de déléguer
toolsNonLa liste des outils autorisés. Sans ce champ, l'agent hérite de tous les outils disponibles
modelNonLe 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 name sans description ;
  • 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 : name et description obligatoires, tools et model facultatifs.
  • 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.