Create Agent

---
name: create-agent
description: "Créer un nouveau subagent Claude Code. Mots-clés : créer/ajouter/générer/rédiger un agent, subagent, assistant spécialisé, 'je veux un agent qui…'. Ne se charge PAS quand : on discute, modifie, documente ou review des agents existants."
---

# 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

```markdown
---
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

```yaml
# 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]`…).