Créer un Agent Personnalisé avec Claude Code : Guide Pas à Pas

Mis à jour le 3 mars 2026

Les agents built-in de Claude Code (Explore, Plan, General-purpose) couvrent les cas génériques. Mais le vrai pouvoir, c'est de créer TES agents — spécialisés pour TON workflow. Un agent de code review. Un agent de test. Un agent de documentation. Chacun avec ses outils, ses permissions, et ses instructions. Ce guide te montre comment en créer un de zéro.

Un agent custom, c'est un sous-agent Claude Code que tu configures toi-même. Tu choisis quel modèle il utilise, quels outils il peut toucher, quel niveau de permission il a, et ce qu'il fait exactement. Le tout dans un simple fichier Markdown. Pas de SDK. Pas de code. Pas de déploiement. Tu crées le fichier, l'agent existe.

Si tu débutes avec Claude Code, commence par le guide complet Claude Code pour les fondamentaux. Si tu connais déjà les skills et commandes personnalisées, tu vas voir que les agents poussent le concept beaucoup plus loin — un agent a son propre contexte, sa propre mémoire, et ses propres restrictions.

Pourquoi créer un agent custom

Un agent custom est un sous-agent Claude Code taillé pour une tâche spécifique. Tu définis ses outils, son modèle, ses permissions, et ses instructions. Il fait exactement ce que tu veux, rien de plus.

La différence avec un skill (une commande personnalisée), c'est l'isolation. Un skill partage le contexte de ta session. Un agent a son propre contexte, sa propre fenêtre, ses propres limites. Quand il termine, seul le résultat remonte. Pas le bruit. Pas les fichiers intermédiaires. Pas les 47 commandes qu'il a exécutées pour arriver au résultat.

Quelques exemples concrets d'agents utiles :

• code-reviewer : analyse le code en lecture seule. Outils limités à Read, Grep, Glob. Ne peut rien modifier. Produit un rapport structuré avec les problèmes de sécurité, qualité et maintenabilité.
• deployer : vérifie les prérequis, lance le build, exécute les tests, et déploie. Outils spécifiques (Bash pour les commandes de deploy). Permissions élevées parce qu'il doit exécuter des scripts.
• documentation-writer : lit le code source et génère la documentation. Outils : Read pour lire, Write pour écrire les fichiers de doc. Modèle Sonnet parce que la documentation n'a pas besoin du raisonnement profond d'Opus.
• test-runner : lance les tests, analyse les échecs, propose des corrections. Outils : Bash pour exécuter les tests, Read et Grep pour comprendre les erreurs.

Chaque agent est un spécialiste. Au lieu d'avoir un assistant généraliste qui fait tout "à peu près bien", tu as une équipe d'agents qui font chacun une chose très bien. Claude Code orchestre ces agents automatiquement — il choisit le bon agent pour la bonne tâche en se basant sur la description que tu as écrite dans le frontmatter.

La structure d'un agent

Un agent Claude Code est un fichier Markdown avec un en-tête YAML. C'est le même principe que les skills, mais avec plus d'options de configuration. Voici où placer tes agents et comment les structurer.

Emplacement des fichiers

Deux options :

• Agents projet : .claude/agents/nom-agent/nom-agent.md — spécifiques à un projet, versionnés avec git, partagés avec l'équipe.
• Agents globaux : ~/.claude/agents/nom-agent/nom-agent.md — disponibles dans tous tes projets, personnels.

Le dossier de l'agent peut contenir des fichiers de support en plus du fichier principal : templates, scripts, exemples, fichiers de configuration. L'agent peut les référencer dans ses instructions.

Format du fichier

Le fichier agent est composé de deux parties :

1. Le frontmatter YAML (entre deux lignes ---) : la configuration technique — modèle, outils, permissions, mémoire.
2. Le corps Markdown : les instructions en langage naturel — ce que l'agent doit faire, comment il doit le faire, quel format de sortie il doit produire.

.claude/
  agents/
    code-reviewer/
      code-reviewer.md    ← fichier principal de l'agent
      checklist.md         ← fichier de support (optionnel)
    doc-writer/
      doc-writer.md
      template.md

Le nom du fichier .md doit correspondre au nom du dossier. C'est la convention que Claude Code utilise pour détecter les agents disponibles.

Le frontmatter YAML détaillé

Le frontmatter est le coeur de la configuration de ton agent. Chaque champ modifie son comportement. Voici chaque option avec des exemples concrets.

name (obligatoire)

Le nom d'affichage de l'agent. C'est ce qui apparaît dans les logs et les messages quand Claude Code délègue une tâche à cet agent.

name: code-reviewer

description (obligatoire)

La description de l'agent. Elle a un double rôle : elle apparaît dans la liste des agents disponibles, et elle permet à Claude Code de décider quand utiliser cet agent. Sois précis et spécifique — plus la description est claire, mieux Claude Code saura router les tâches.

description: "Analyse le code pour détecter les problèmes de sécurité, qualité et maintenabilité. Produit un rapport structuré. Ne modifie aucun fichier."

model

Le modèle IA utilisé par l'agent. Quatre options :

• opus — le plus puissant. Raisonnement profond, tâches complexes. Plus lent et plus coûteux.
• sonnet — l'équilibre qualité/vitesse. Le choix par défaut pour la plupart des agents.
• haiku — le plus rapide et économique. Parfait pour les tâches simples : recherche, exploration, formatage.
• inherit — utilise le même modèle que la session parente. Utile quand tu veux que l'agent s'adapte à ton choix de modèle.

model: sonnet

Règle simple : commence avec sonnet. Passe à opus si les résultats ne sont pas assez bons. Passe à haiku si la tâche est simple et que tu veux de la vitesse.

tools

La liste blanche des outils autorisés. Si tu spécifies ce champ, l'agent ne peut utiliser que les outils listés. C'est le principal levier de sécurité.

tools:
  - Read
  - Grep
  - Glob

Cet agent ne peut que lire. Pas de Write, pas de Edit, pas de Bash. Il est physiquement incapable de modifier quoi que ce soit. Les outils disponibles incluent : Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, NotebookEdit. Tu peux aussi autoriser des commandes Bash spécifiques avec la syntaxe Bash(git diff).

disallowedTools

L'inverse de tools — une liste noire. L'agent a accès à tout sauf ce que tu listes ici. Utile quand tu veux un agent presque complet, mais sans certaines capacités dangereuses.

disallowedTools:
  - Bash
  - Write

Cet agent peut lire, chercher, éditer des fichiers existants, mais ne peut pas exécuter de commandes shell ni créer de nouveaux fichiers. C'est plus permissif que tools mais avec des garde-fous.

permissionMode

Contrôle comment l'agent gère les demandes de permission. Cinq modes :

• default — comportement normal. Demande la permission pour les actions sensibles.
• acceptEdits — accepte automatiquement les modifications de fichiers. Demande encore la permission pour Bash.
• dontAsk — aucune demande de permission. L'agent agit en autonomie totale. A utiliser avec précaution.
• bypassPermissions — contourne toutes les restrictions de permission. Réservé aux agents de confiance sur des tâches contrôlées.
• plan — mode lecture seule. L'agent analyse, planifie, mais ne modifie rien. Parfait pour les agents de review ou d'audit.

permissionMode: plan

Pour un agent de review ou d'analyse, plan est le choix le plus sûr. L'agent ne peut que lire et produire un rapport. Aucun risque d'effet de bord. C'est la même logique que le système de permissions Claude Code.

maxTurns

Limite le nombre d'itérations (tours de boucle) de l'agent. Un "turn" correspond à un cycle complet : l'agent réfléchit, utilise un outil, analyse le résultat. Sans limite, un agent peut tourner indéfiniment s'il n'arrive pas à résoudre un problème.

maxTurns: 15

Pour un agent de review, 10-15 turns suffisent largement. Pour un agent de refactoring sur un gros projet, 30-50 peut être nécessaire. Commence bas et augmente si l'agent se coupe avant d'avoir terminé.

memory

Active la mémoire persistante entre les sessions. L'agent maintient un fichier MEMORY.md dans son dossier, et les 200 premières lignes sont chargées automatiquement au démarrage de chaque session.

• user — mémoire globale, partagée entre tous les projets. Stockée dans ~/.claude/agents/nom-agent/MEMORY.md.
• project — mémoire par projet. Stockée dans .claude/agents/nom-agent/MEMORY.md du projet.
• local — mémoire locale, ajoutée au .gitignore. Pour des notes personnelles non partagées avec l'équipe.

memory: project

Un agent de review avec mémoire projet peut se souvenir des patterns récurrents dans ton code, des conventions spécifiques, des décisions architecturales passées. A chaque review, il a plus de contexte.

background

Permet à l'agent de s'exécuter en arrière-plan pendant que tu continues à travailler. Le résultat apparaît quand l'agent termine.

background: true

isolation

Exécute l'agent dans un git worktree isolé. L'agent travaille sur une copie séparée du code, sans affecter ton working directory. Utile pour des agents qui font des modifications exploratoires — si ça ne marche pas, rien n'est touché.

isolation: worktree

skills

Précharge des skills spécifiques dans le contexte de l'agent. L'agent démarre avec ces connaissances déjà chargées.

skills:
  - owasp-security
  - coding-conventions

hooks et mcpServers

Tu peux attacher des hooks spécifiques à un agent (des actions automatiques qui se déclenchent à certains événements) et connecter des serveurs MCP pour lui donner accès à des outils externes (bases de données, APIs, services tiers).

hooks:
  PostToolUse:
    - command: "echo 'Agent a utilisé un outil'"
mcpServers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]

Tutoriel : créer un agent code-reviewer

Passons à la pratique. On va créer un agent code-reviewer de A à Z — un agent qui analyse ton code en lecture seule et produit un rapport de review structuré.

Etape 1 : Créer la structure de fichiers

Crée le dossier et le fichier de l'agent dans ton projet :

mkdir -p .claude/agents/code-reviewer
touch .claude/agents/code-reviewer/code-reviewer.md

Etape 2 : Ecrire le frontmatter

Ouvre le fichier code-reviewer.md et ajoute la configuration YAML :

---
name: code-reviewer
description: "Analyse le code pour détecter les problèmes de sécurité, qualité et maintenabilité. Mode lecture seule — ne modifie aucun fichier. Produit un rapport structuré."
model: sonnet
tools:
  - Read
  - Grep
  - Glob
  - Bash(git diff)
  - Bash(git log)
  - Bash(git status)
permissionMode: plan
maxTurns: 15
memory: project
---

Décodage des choix :

• model: sonnet — assez puissant pour une review de qualité, assez rapide pour ne pas attendre 2 minutes.
• tools limités à Read, Grep, Glob et quelques commandes git — l'agent peut lire et chercher dans le code, voir les changements récents, mais ne peut rien modifier.
• permissionMode: plan — double sécurité. Même si un outil d'écriture se glissait dans la liste, le mode plan empêche toute modification.
• maxTurns: 15 — suffisant pour analyser un diff de taille moyenne. Empêche l'agent de tourner en boucle.
• memory: project — l'agent se souvient des reviews précédentes et des patterns spécifiques à ce projet.

Etape 3 : Ecrire les instructions

Après le frontmatter, ajoute les instructions en Markdown :

# Code Review Agent

Tu es un code reviewer expert. Ton rôle est d'analyser le code pour détecter les problèmes AVANT qu'ils n'arrivent en production.

## Process

1. Lance `git diff --staged` pour voir les changements staged
2. Si rien n'est staged, lance `git diff` pour les changements non-staged
3. Si rien non plus, lance `git diff HEAD~1` pour le dernier commit
4. Lis les fichiers modifiés en entier pour comprendre le contexte

## Critères d'analyse

### Sécurité (priorité 1)
- Secrets ou credentials exposés (clés API, mots de passe, tokens)
- Injections (SQL, XSS, command injection)
- Permissions trop larges, CORS mal configuré
- Données utilisateur non validées/sanitizées

### Qualité (priorité 2)
- Nommage clair et explicite
- Fonctions courtes, une seule responsabilité
- Error handling systématique (pas de catch vide)
- Edge cases non gérés

### Maintenabilité (priorité 3)
- Code dupliqué
- Couplage fort entre modules
- Abstractions prématurées ou manquantes
- Tests manquants pour le code critique

## Format de sortie

Produis un rapport structuré :
- **Résumé** : 1-2 phrases sur l'état général
- **Problèmes critiques** : à corriger AVANT merge (bloquants)
- **Suggestions** : améliorations non-bloquantes
- **Score** : note sur 10 avec justification
- **Bilan** : GO ou NO-GO pour le merge

Etape 4 : Tester l'agent

Lance une session Claude Code dans ton projet et demande simplement :

Fais une review du dernier commit

Claude Code va détecter que ton agent code-reviewer correspond à cette tâche (grâce à la description) et le déléguer automatiquement. Tu peux aussi le forcer explicitement :

Utilise l'agent code-reviewer pour analyser les changements staged

Vérifie que l'agent respecte ses contraintes : il ne doit utiliser que Read, Grep, Glob et les commandes git autorisées. Il ne doit rien modifier. Le rapport doit suivre le format que tu as défini.

3 agents utiles à créer

Maintenant que tu maîtrises la structure, voici 3 templates d'agents concrets à copier et adapter. Chacun couvre un besoin différent.

1. doc-writer — Agent de documentation

Cet agent lit ton code source et génère la documentation technique. Il peut créer des fichiers de doc, ajouter des commentaires inline, ou produire un README complet.

---
name: doc-writer
description: "Génère la documentation technique à partir du code source. Crée des fichiers de documentation, des commentaires JSDoc/TSDoc, et des README."
model: sonnet
tools:
  - Read
  - Write
  - Edit
  - Grep
  - Glob
permissionMode: acceptEdits
maxTurns: 20
---

# Documentation Writer

Tu es un rédacteur de documentation technique.

## Principes

- Lis le code source AVANT d'écrire quoi que ce soit
- Documentation claire, concise, orientée usage
- Exemples de code pour chaque fonction publique
- JSDoc pour JavaScript, TSDoc pour TypeScript
- README structuré : installation, usage, API, exemples

## Process

1. Analyse la structure du projet (dossiers, fichiers principaux)
2. Identifie les fonctions/classes/modules publics
3. Lis le code pour comprendre le comportement réel
4. Génère la documentation adaptée au format demandé
5. Vérifie que les exemples de code sont corrects

Usage : "Utilise doc-writer pour documenter le module src/utils/". L'agent scanne le code, comprend chaque fonction, et produit une documentation propre. permissionMode: acceptEdits lui permet de créer et modifier les fichiers de doc sans te demander à chaque fois.

2. test-runner — Agent de tests

Cet agent lance les tests, analyse les échecs, et propose des corrections. Il combine la lecture du code, l'exécution des tests, et l'analyse des résultats.

---
name: test-runner
description: "Lance les tests, analyse les échecs, identifie les causes et propose des corrections. Couvre les tests unitaires et d'intégration."
model: sonnet
tools:
  - Read
  - Grep
  - Glob
  - Bash(npm test)
  - Bash(npm run test)
  - Bash(npx jest)
  - Bash(npx vitest)
maxTurns: 20
---

# Test Runner Agent

Tu es un spécialiste des tests logiciels.

## Process

1. Lance la suite de tests complète
2. Si des tests échouent, analyse chaque échec :
   - Lis le fichier de test pour comprendre l'intention
   - Lis le code source testé pour comprendre le comportement réel
   - Identifie si le bug est dans le test ou dans le code
3. Produis un rapport avec :
   - Nombre de tests passés / échoués / skippés
   - Pour chaque échec : cause probable et correction suggérée
   - Tests manquants pour le code non couvert

## Règles

- Ne modifie JAMAIS un test sans explication
- Si un test échoue, le bug est dans le code jusqu'à preuve du contraire
- Propose la correction, attends la validation avant d'appliquer

Note que les tools incluent plusieurs variantes de commandes de test (npm test, npx jest, npx vitest) pour couvrir les différents frameworks. L'agent détecte automatiquement lequel utiliser en analysant le package.json.

3. security-auditor — Agent d'audit de sécurité

Cet agent scanne ton codebase pour détecter les vulnérabilités. Mode lecture seule strict — il analyse sans toucher à rien.

---
name: security-auditor
description: "Audit de sécurité complet du codebase. Détecte les vulnérabilités OWASP Top 10, les secrets exposés, les dépendances à risque. Mode lecture seule."
model: sonnet
tools:
  - Read
  - Grep
  - Glob
  - Bash(git log)
  - Bash(npm audit)
permissionMode: plan
maxTurns: 25
memory: project
skills:
  - owasp-security
---

# Security Auditor

Tu es un auditeur de sécurité spécialisé en applications web.

## Checklist OWASP Top 10

1. **Injection** : recherche les requêtes SQL/NoSQL construites par concaténation, les commandes shell non sanitizées
2. **Broken Auth** : vérification des tokens, sessions, mots de passe hashés
3. **Sensitive Data Exposure** : secrets dans le code, .env versionnés, logs avec données personnelles
4. **XXE** : parsing XML non sécurisé
5. **Broken Access Control** : vérifications de permissions manquantes
6. **Security Misconfiguration** : headers manquants, CORS trop permissif, debug activé en prod
7. **XSS** : inputs non échappés dans le HTML, innerHTML, dangerouslySetInnerHTML
8. **Insecure Deserialization** : JSON.parse sur des données non validées
9. **Known Vulnerabilities** : lance npm audit, vérifie les dépendances
10. **Insufficient Logging** : error handling sans logging, catch vides

## Format du rapport

- **Score de risque** : Critique / Elevé / Modéré / Faible
- **Vulnérabilités trouvées** : classées par sévérité
- **Recommandations** : correction pour chaque vulnérabilité
- **Prochaines étapes** : actions prioritaires

Cet agent combine permissionMode: plan (lecture seule) avec le skill owasp-security préchargé pour avoir les connaissances de sécurité dès le démarrage. La memory: project lui permet de se souvenir des vulnérabilités précédemment identifiées et de vérifier qu'elles ont été corrigées. C'est exactement le type d'agent qu'on peut coupler avec les hooks d'automatisation pour lancer un audit avant chaque deploy.

Bonnes pratiques

Après avoir créé et testé plusieurs dizaines d'agents, voici les règles qui font la différence entre un agent utile et un agent qui te fait perdre du temps.

Commence restrictif, élargis ensuite. Donne le minimum d'outils nécessaires. Un agent avec Read + Grep suffit pour 80% des tâches d'analyse. Ajoute Write seulement s'il doit créer des fichiers. Ajoute Bash seulement s'il doit exécuter des commandes. Chaque outil ajouté est une surface d'erreur en plus.

Utilise plan pour les agents de lecture. Tout agent qui analyse sans modifier devrait être en permissionMode: plan. C'est une double sécurité : même si tu oublies de restreindre les outils, le mode plan empêche toute modification. C'est le même principe de défense en profondeur qu'on applique au système de permissions en général.

Fixe toujours maxTurns. Un agent sans limite de turns peut tourner en boucle pendant des minutes (et consommer du budget) s'il rencontre un problème qu'il n'arrive pas à résoudre. 15 turns pour un agent simple, 25-30 pour un agent complexe. Tu peux toujours augmenter si nécessaire.

Active memory pour les agents récurrents. Un agent de review que tu utilises tous les jours devrait avoir memory: project. Il accumule du contexte sur ton projet — les conventions, les patterns, les décisions passées. Sa qualité augmente avec le temps. C'est la même logique que la configuration mémoire avec CLAUDE.md, mais appliquée à un agent spécifique.

Teste sur une tâche simple d'abord. Avant de lâcher un agent sur ton projet en production, teste-le sur un cas trivial. Vérifie qu'il respecte les contraintes d'outils. Vérifie que le format de sortie correspond à tes attentes. Ajuste le frontmatter et les instructions jusqu'à ce que le comportement soit stable.

Une responsabilité par agent. Ne crée pas un "super-agent" qui fait le review, les tests, la doc et le déploiement. Crée 4 agents spécialisés. Chacun fait une chose bien. Claude Code les orchestre automatiquement en fonction de la tâche. C'est plus simple à maintenir, plus facile à debugger, et plus fiable. Si tu veux comprendre comment cette orchestration fonctionne, le guide complet Claude Code détaille le système de sub-agents.

Ecris des descriptions précises. La description dans le frontmatter est le critère que Claude Code utilise pour choisir quel agent déléguer. "Analyse le code" est trop vague — Claude Code ne saura pas si c'est un review de sécurité, un audit de performance, ou une vérification de style. "Analyse le code pour détecter les vulnérabilités OWASP Top 10, les secrets exposés et les dépendances à risque" est précis — Claude Code sait exactement quand utiliser cet agent.

Pour un usage plus avancé, les agents se combinent avec les autres briques de l'écosystème. Tu peux créer un dashboard IA avec Claude Code et utiliser des agents custom pour automatiser des tâches spécifiques de ton workflow. Un agent peut appeler un skill. Un hook peut déclencher un agent. Le guide Claude Code pour entrepreneurs montre comment assembler ces briques pour des workflows complets.

Meydeey — Architecte IA & Automatisation

+110 entrepreneurs formés au Vibe Coding et à l'automatisation IA avec N8N. Fondateur du Labo IA.