create-agent

Create Agent — Créateur de subagents Claude Code

Guide la création de subagents spécialisés — de l'idée au fichier prêt à l'emploi.

Différence skill vs agent

	Skill	Agent
Exécution	Dans la conversation principale	Contexte isolé (fenêtre séparée)
Résultat	Guide le comportement de Claude	Retourne un résumé à la conversation
Outils	Aucun (instructions seulement)	Outils configurables (Read, Bash, etc.)
Modèle	Hérite toujours	Configurable (haiku, sonnet, opus, inherit)
Mémoire	Non	Persistante optionnelle (user, project, local)
Quand	Garde-fous, conventions, guidelines	Tâches autonomes, recherche, analyse, tests

Règle simple : si le besoin est de guider Claude → skill. Si le besoin est de déléguer une tâche autonome → agent.

Anatomie d'un agent

agents/
└── mon-agent.md    # Un seul fichier Markdown avec frontmatter YAML

Format

---
name: mon-agent
description: "Quand Claude doit déléguer à cet agent — inclure les triggers et contextes."
tools: Read, Grep, Glob, Bash
model: sonnet
---

Instructions que l'agent suivra (system prompt).

Champs du frontmatter

Champ	Obligatoire	Description
name	Oui	Identifiant unique, kebab-case
description	Oui	Quand Claude délègue à cet agent — inclure "Use proactively" si auto-déclenchement souhaité
tools	Non	Outils autorisés (hérite tous si omis)
disallowedTools	Non	Outils explicitement refusés
model	Non	haiku, sonnet, opus, ou inherit (défaut: inherit)
permissionMode	Non	default, acceptEdits, dontAsk, bypassPermissions, plan
maxTurns	Non	Nombre max de tours avant arrêt
skills	Non	Skills préchargées dans le contexte de l'agent
mcpServers	Non	Serveurs MCP disponibles pour l'agent
hooks	Non	Hooks de cycle de vie (PreToolUse, PostToolUse, Stop)
memory	Non	Mémoire persistante : user, project, ou local
background	Non	true pour exécution en arrière-plan par défaut
isolation	Non	worktree pour copie isolée du repo

Outils disponibles

Les agents peuvent utiliser tous les outils internes de Claude Code :

Catégorie	Outils
Lecture	Read, Grep, Glob
Écriture	Write, Edit
Exécution	Bash
Web	WebSearch, WebFetch
Orchestration	Agent(type) (seulement si agent principal via --agent)

Les agents ne peuvent PAS créer de sous-agents (pas d'imbrication).

Choix du modèle

Modèle	Coût	Quand
haiku	Bas	Recherche, lecture, tâches simples, économie de tokens
sonnet	Moyen	Analyse, génération de code, tests, bon rapport qualité/prix
opus	Haut	Raisonnement complexe, décisions architecturales
inherit	Comme parent	Quand l'agent doit utiliser le même modèle que la conversation

Mémoire persistante

Scope	Emplacement	Quand
user	~/.claude/agent-memory/<name>/	Apprentissages transversaux, tous projets
project	.claude/agent-memory/<name>/	Connaissances spécifiques au projet, versionnable
local	.claude/agent-memory-local/<name>/	Spécifique au projet, pas versionné

Quand activée, l'agent reçoit automatiquement les instructions pour lire/écrire sa mémoire + les 200 premières lignes de son MEMORY.md.

⚠️ À n'activer que si vraiment nécessaire. Les memory files ont un tradeoff important :

• ✅ Utile sur : gros projet (500+ fichiers), agent invoqué très fréquemment, connaissances non déductibles du code (décisions legal, incidents historiques, conventions tribales non documentées)
• ❌ Bruit sur : petit/moyen projet, structure découvrable en 2-3 Grep/Glob, projet qui évolue vite. Les memory files capturent un snapshot figé et rotrouillent — l'agent peut halluciner des "bugs connus" qui n'existent plus.

Pour les projets Codebloom, la capitalisation se fait via TODO.md avec tags ([review], [sec], [audit], etc.) — c'est le mécanisme officiel du plugin, lu par tous les agents et par la conversation principale. N'active memory: que si tu as un besoin explicite qui ne rentre pas dans TODO.md ; les agents natifs Codebloom n'utilisent pas memory:, ils passent tous par TODO.md. Exception : le tester ne capitalise rien — il écrit les tests manquants ou les laisse dans son rapport (pas de tag [test]).

Scope — Où créer l'agent

Scope	Chemin	Quand
Plugin codebloom	agents/<name>.md (racine codebloom)	Agent distribué avec le plugin
Projet	.claude/agents/<name>.md	Agent spécifique à ce projet
Utilisateur	~/.claude/agents/<name>.md	Agent disponible sur tous les projets

Par défaut, proposer le scope projet. Demander si l'utilisateur veut un autre scope.

Process

1. Interview — Comprendre le besoin

Poser ces questions (adapter selon le contexte) :

1. Quoi — Quelle tâche l'agent doit-il accomplir ? Quel résultat est attendu ?
2. Quand — Dans quels contextes doit-il se déclencher ? (automatique / sur demande / les deux)
3. Outils — A-t-il besoin de lire le code ? De le modifier ? D'exécuter des commandes ? D'accéder au web ?
4. Modèle — Tâche simple (haiku) ou complexe (sonnet/opus) ? Budget important ?
5. Scope — Projet, utilisateur, ou plugin codebloom ?

Creuser les cas limites :

• L'agent doit-il tourner en arrière-plan (background: true) ?
• A-t-il besoin de mémoire entre les sessions ?
• Quelles skills existantes pourraient le renforcer ?
• Interactions avec d'autres agents existants (complémentarité, chevauchement)

Est-ce vraiment un agent ? Si le besoin est de guider Claude (conventions, garde-fous, checklists) → c'est une skill, pas un agent. Proposer create-skill à la place.

2. Recherche — Vérifier le contexte

Avant d'écrire :

• Lister les agents existants dans le scope cible (éviter les doublons)
• Vérifier si un agent existant pourrait être étendu
• Identifier les skills à précharger (skills:)

3. Rédaction — Écrire l'agent

La description — C'est le trigger

Claude lit la description pour décider s'il délègue. C'est le champ le plus critique.

Structure efficace :

"[Rôle]. Use proactively [quand s'auto-déclencher]. Also use when [déclencheurs explicites]. [Capacités clés]."

Principes :

• "Use proactively" déclenche l'auto-délégation — l'inclure seulement si l'agent doit se déclencher sans demande
• Décrire les contextes concrets, pas des abstractions
• Inclure les variantes de formulation si invocation explicite attendue

Le system prompt — Ce sont les instructions

Règles d'écriture :

1. Tutoyer l'agent — "Tu es un reviewer senior" pas "L'agent est un reviewer"
2. Section "Au démarrage" — Première chose que l'agent fait (consulter mémoire, lire CLAUDE.md, etc.)
3. Process structuré — Étapes numérotées pour la tâche principale
4. Format de sortie — Décrire exactement le résumé que l'agent retourne
5. Contraintes — Ce que l'agent ne doit PAS faire (modifier le code source si read-only, etc.)

Restreindre les outils — Principe du moindre privilège

Profil	Outils recommandés	Cas d'usage
Read-only	Read, Grep, Glob, Bash + disallowedTools: Write, Edit	Review, audit, recherche
Writer	Read, Write, Edit, Grep, Glob, Bash	Tests, doc, génération
Researcher	Read, Grep, Glob, WebSearch, WebFetch	Recherche technique
Minimal	Read, Grep, Glob	Analyse simple, pas de Bash

Toujours limiter : un agent read-only ne doit pas pouvoir modifier le code par accident. Utiliser disallowedTools pour les exclusions explicites.

4. Création — Écrire le fichier

1. Écrire <name>.md dans le bon dossier selon le scope
2. Vérifier que le frontmatter est valide (YAML strict)

5. Vérification — Valider l'agent

Checklist avant de confirmer :

• name en kebab-case, unique parmi les agents existants
• description contient les déclencheurs ("Use proactively" si auto)
• tools restreints au minimum nécessaire (pas de Write si read-only)
• model adapté à la complexité de la tâche
• System prompt en français (conventions codebloom)
• Section "Au démarrage" présente
• Format de sortie décrit
• Pas de chevauchement majeur avec un agent existant

6. Documentation — Mettre à jour les références

Selon le scope :

• Plugin codebloom : Mettre à jour CLAUDE.md (tableau Subagents) et README.md
• Projet : Mentionner dans le CLAUDE.md du projet
• Utilisateur : Informer que l'agent est actif sur tous les projets

Exemples de bonnes descriptions

# Trop vague — Claude ne sait pas quand déléguer
description: "Un agent pour le code"

# Trop restrictive — ne se déclenche jamais automatiquement
description: "Exécuter uniquement quand l'utilisateur tape 'lance mon agent'"

# Juste — proactif avec contextes concrets
description: "Expert code review. Use proactively after writing or modifying code (new feature, bug fix, refactor), or when the user asks for a review. Analyzes: correctness, security, readability, tests. Returns a scored report."

Règles

• Agent vs Skill — Si le besoin est de guider → skill. Si le besoin est de déléguer → agent. Toujours vérifier.
• Moindre privilège — Donner uniquement les outils nécessaires. Un agent de recherche n'a pas besoin de Write.
• Enrichir > Créer — Vérifier si un agent existant peut absorber le besoin avant d'en créer un nouveau.
• La description fait le travail — "Use proactively" est la clé pour l'auto-déclenchement. Sans, l'agent n'est invoqué que sur demande explicite.
• Mémoire : par défaut non — N'active memory: que sur gros projet avec connaissances non-déductibles du code. Voir le warning détaillé dans le § Mémoire persistante ci-dessus. Pour les projets Codebloom standards, capitalise dans TODO.md avec tags ([review], [sec], [audit]…).