SamuelChien/mega-skills-collection

Développement d'agents pour les plugins Claude Code

Vue d'ensemble

Les agents sont des sous-processus autonomes qui gèrent des tâches complexes et multi-étapes de manière indépendante. Comprendre la structure des agents, les conditions de déclenchement et la conception des prompts système permet de créer des capacités autonomes puissantes.

Concepts clés :

• Les agents sont POUR le travail autonome, les commandes sont POUR les actions initiées par l'utilisateur
• Format de fichier Markdown avec entête YAML
• Déclenchement via le champ description avec des exemples
• Le prompt système définit le comportement de l'agent
• Personnalisation du modèle et de la couleur

Structure d'un fichier agent

Format complet

---
name: identifiant-agent
description: Utilisez cet agent lorsque [conditions de déclenchement]. Exemples :

<example>
Contexte : [Description de la situation]
user: "[Demande de l'utilisateur]"
assistant: "[Comment l'assistant doit répondre et utiliser cet agent]"
<commentary>
[Pourquoi cet agent doit être déclenché]
</commentary>
</example>

<example>
[Exemple supplémentaire...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

Vous êtes [description du rôle de l'agent]...

**Vos responsabilités principales :**
1. [Responsabilité 1]
2. [Responsabilité 2]

**Processus d'analyse :**
[Flux de travail étape par étape]

**Format de sortie :**
[Ce qui doit être retourné]

Champs de l'entête

name (obligatoire)

Identifiant de l'agent utilisé pour l'espace de noms et l'invocation.

Format : minuscules, chiffres, traits d'union uniquement Longueur : 3 à 50 caractères Modèle : Doit commencer et se terminer par un caractère alphanumérique

Bons exemples :

• code-reviewer
• test-generator
• api-docs-writer
• security-analyzer

Mauvais exemples :

• helper (trop générique)
• -agent- (commence/se termine par un trait d'union)
• my_agent (les underscores ne sont pas autorisés)
• ag (trop court, < 3 caractères)

description (obligatoire)

Définit quand Claude doit déclencher cet agent. C'est le champ le plus critique.

Doit inclure :

1. Conditions de déclenchement ("Utilisez cet agent lorsque...")
2. Plusieurs blocs <example> montrant l'utilisation
3. Contexte, demande de l'utilisateur et réponse de l'assistant dans chaque exemple
4. <commentary> expliquant pourquoi l'agent se déclenche

Format :

Utilisez cet agent lorsque [conditions]. Exemples :

<example>
Contexte : [Description du scénario]
user: "[Ce que dit l'utilisateur]"
assistant: "[Comment Claude doit répondre]"
<commentary>
[Pourquoi cet agent est approprié]
</commentary>
</example>

[Plus d'exemples...]

Bonnes pratiques :

• Inclure 2 à 4 exemples concrets
• Montrer un déclenchement proactif et réactif
• Couvrir différentes formulations de la même intention
• Expliquer le raisonnement dans le commentaire
• Être précis sur les cas où NE PAS utiliser l'agent

model (obligatoire)

Quel modèle l'agent doit utiliser.

Options :

• inherit - Utiliser le même modèle que le parent (recommandé)
• sonnet - Claude Sonnet (équilibré)
• opus - Claude Opus (le plus performant, coûteux)
• haiku - Claude Haiku (rapide, économique)

Recommandation : Utilisez inherit sauf si l'agent a besoin de capacités spécifiques d'un modèle.

color (obligatoire)

Identifiant visuel de l'agent dans l'interface utilisateur.

Options : blue, cyan, green, yellow, magenta, red

Directives :

• Choisir des couleurs distinctes pour différents agents dans un même plugin
• Utiliser des couleurs cohérentes pour des types d'agents similaires
• Bleu/cyan : Analyse, révision
• Vert : Tâches orientées vers le succès
• Jaune : Prudence, validation
• Rouge : Critique, sécurité
• Magenta : Créatif, génération

tools (facultatif)

Restreindre l'agent à des outils spécifiques.

Format : Tableau des noms d'outils

tools: ["Read", "Write", "Grep", "Bash"]

Par défaut : Si omis, l'agent a accès à tous les outils

Bonne pratique : Limiter les outils au strict nécessaire (principe du moindre privilège)

Ensembles d'outils courants :

• Analyse en lecture seule : ["Read", "Grep", "Glob"]
• Génération de code : ["Read", "Write", "Grep"]
• Tests : ["Read", "Bash", "Grep"]
• Accès complet : Omettre le champ ou utiliser ["*"]

Conception du prompt système

Le corps du Markdown devient le prompt système de l'agent. Rédigez à la deuxième personne, en vous adressant directement à l'agent.

Structure

Modèle standard :

Vous êtes [rôle] spécialisé(e) dans [domaine].

**Vos responsabilités principales :**
1. [Responsabilité principale]
2. [Responsabilité secondaire]
3. [Responsabilités supplémentaires...]

**Processus d'analyse :**
1. [Étape un]
2. [Étape deux]
3. [Étape trois]
[...]

**Normes de qualité :**
- [Norme 1]
- [Norme 2]

**Format de sortie :**
Fournissez les résultats dans ce format :
- [Ce qui doit être inclus]
- [Comment structurer]

**Cas particuliers :**
Gérez ces situations :
- [Cas particulier 1] : [Comment gérer]
- [Cas particulier 2] : [Comment gérer]

Bonnes pratiques

✅ À FAIRE :

• Rédigez à la deuxième personne ("Vous êtes...", "Vous allez...")
• Soyez précis sur les responsabilités
• Fournissez un processus étape par étape
• Définissez le format de sortie
• Incluez des normes de qualité
• Traitez les cas particuliers
• Restez sous les 10 000 caractères

❌ À NE PAS FAIRE :

• Rédiger à la première personne ("Je suis...", "Je vais...")
• Être vague ou générique
• Omettre les étapes du processus
• Laisser le format de sortie indéfini
• Ignorer les consignes de qualité
• Ignorer les cas d'erreur

Création d'agents

Méthode 1 : Génération assistée par IA

Utilisez ce modèle de prompt (extrait de Claude Code) :

Créez une configuration d'agent basée sur cette demande : "[VOTRE DESCRIPTION]"

Exigences :
1. Extraire l'intention principale et les responsabilités
2. Concevoir un persona expert pour le domaine
3. Créer un prompt système complet avec :
   - Limites comportementales claires
   - Méthodologies spécifiques
   - Gestion des cas particuliers
   - Format de sortie
4. Créer un identifiant (minuscules, traits d'union, 3 à 50 caractères)
5. Rédiger la description avec les conditions de déclenchement
6. Inclure 2 à 3 blocs <example> montrant quand l'utiliser

Retournez du JSON avec :
{
  "identifier": "nom-agent",
  "whenToUse": "Utilisez cet agent lorsque... Exemples : <example>...</example>",
  "systemPrompt": "Vous êtes..."
}

Convertissez ensuite au format de fichier agent avec entête.

Voir examples/agent-creation-prompt.md pour le modèle complet.

Méthode 2 : Création manuelle

1. Choisir un identifiant d'agent (3 à 50 caractères, minuscules, traits d'union)
2. Rédiger la description avec des exemples
3. Sélectionner le modèle (généralement inherit)
4. Choisir une couleur pour l'identification visuelle
5. Définir les outils (si restriction d'accès)
6. Rédiger le prompt système avec la structure ci-dessus
7. Enregistrer sous agents/nom-agent.md

Règles de validation

Validation de l'identifiant

✅ Valide : code-reviewer, test-gen, api-analyzer-v2
❌ Invalide : ag (trop court), -start (commence par un trait d'union), my_agent (underscore)

Règles :

• 3 à 50 caractères
• Uniquement lettres minuscules, chiffres, traits d'union
• Doit commencer et se terminer par un caractère alphanumérique
• Pas d'underscores, d'espaces ou de caractères spéciaux

Validation de la description

Longueur : 10 à 5 000 caractères Doit inclure : Conditions de déclenchement et exemples Idéal : 200 à 1 000 caractères avec 2 à 4 exemples

Validation du prompt système

Longueur : 20 à 10 000 caractères Idéal : 500 à 3 000 caractères Structure : Responsabilités claires, processus, format de sortie

Organisation des agents

Répertoire des agents du plugin

nom-plugin/
└── agents/
    ├── analyseur.md
    ├── relecteur.md
    └── générateur.md

Tous les fichiers .md dans agents/ sont automatiquement découverts.

Espace de noms

Les agents sont automatiquement placés dans un espace de noms :

• Plugin unique : nom-agent
• Avec sous-répertoires : plugin:sous-repertoire:nom-agent

Test des agents

Test de déclenchement

Créez des scénarios de test pour vérifier que l'agent se déclenche correctement :

1. Rédiger un agent avec des exemples de déclenchement spécifiques
2. Utiliser une formulation similaire aux exemples dans le test
3. Vérifier que Claude charge l'agent
4. Vérifier que l'agent fournit les fonctionnalités attendues

Test du prompt système

Assurez-vous que le prompt système est complet :

1. Donner à l'agent une tâche typique
2. Vérifier qu'il suit les étapes du processus
3. Vérifier que le format de sortie est correct
4. Tester les cas particuliers mentionnés dans le prompt
5. Confirmer que les normes de qualité sont respectées

Référence rapide

Agent minimal

---
name: agent-simple
description: Utilisez cet agent lorsque... Exemples : <example>...</example>
model: inherit
color: blue
---

Vous êtes un agent qui [fait X].

Processus :
1. [Étape 1]
2. [Étape 2]

Sortie : [Ce qui doit être fourni]

Résumé des champs de l'entête

Champ	Obligatoire	Format	Exemple
name	Oui	minuscules-traits-dunion	code-reviewer
description	Oui	Texte + exemples	Utiliser quand... ...
model	Oui	inherit/sonnet/opus/haiku	inherit
color	Oui	Nom de couleur	blue
tools	Non	Tableau de noms d'outils	["Read", "Grep"]

Bonnes pratiques

À FAIRE :

• ✅ Inclure 2 à 4 exemples concrets dans la description
• ✅ Rédiger des conditions de déclenchement spécifiques
• ✅ Utiliser inherit pour le modèle sauf besoin spécifique
• ✅ Choisir les outils appropriés (moindre privilège)
• ✅ Rédiger des prompts système clairs et structurés
• ✅ Tester minutieusement le déclenchement de l'agent

À NE PAS FAIRE :

• ❌ Utiliser des descriptions génériques sans exemples
• ❌ Omettre les conditions de déclenchement
• ❌ Donner la même couleur à tous les agents
• ❌ Accorder un accès inutile aux outils
• ❌ Rédiger des prompts système vagues
• ❌ Sauter les tests

Ressources supplémentaires

Fichiers de référence

Pour des directives détaillées, consultez :

• references/system-prompt-design.md - Modèles complets de prompts système
• references/triggering-examples.md - Formats d'exemples et bonnes pratiques
• references/agent-creation-system-prompt.md - Le prompt exact de Claude Code

Exemples de fichiers

Exemples fonctionnels dans examples/ :

• agent-creation-prompt.md - Modèle de génération d'agent assistée par IA
• complete-agent-examples.md - Exemples complets d'agents pour différents cas d'utilisation

Scripts utilitaires

Outils de développement dans scripts/ :

• validate-agent.sh - Valider la structure du fichier agent
• test-agent-trigger.sh - Tester si l'agent se déclenche correctement

Flux de travail de mise en œuvre

Pour créer un agent pour un plugin :

1. Définir le but de l'agent et les conditions de déclenchement
2. Choisir la méthode de création (assistée par IA ou manuelle)
3. Créer le fichier agents/nom-agent.md
4. Rédiger l'entête avec tous les champs obligatoires
5. Rédiger le prompt système en suivant les bonnes pratiques
6. Inclure 2 à 4 exemples de déclenchement dans la description
7. Valider avec scripts/validate-agent.sh
8. Tester le déclenchement avec des scénarios réels
9. Documenter l'agent dans le README du plugin

Concentrez-vous sur des conditions de déclenchement claires et des prompts système complets pour un fonctionnement autonome.