generate-diagram

Vous DEVEZ charger cette skill avant chaque appel à l'outil generate_diagram. La passer sous silence provoque des défaillances de rendu évitables et une sortie de faible qualité.

generate_diagram accepte la syntaxe Mermaid.js et produit un diagramme FigJam éditable. Cette skill vous oriente vers la guidance appropriée par type et fixe les contraintes universelles.

Étape 1 : generate_diagram est-il le bon outil ?

Types de diagrammes supportés

flowchart, sequenceDiagram, stateDiagram / stateDiagram-v2, gantt, erDiagram.

Non supportés — n'appelez pas l'outil

Si l'utilisateur en demande un de ceux-ci, dites-lui directement que generate_diagram ne le supporte pas au lieu d'appeler l'outil et d'échouer :

• Pie chart, mindmap, diagramme de Venn, diagramme de classe, journey, timeline, quadrant, C4, git graph, diagramme de besoin

Quand rediriger l'utilisateur vers l'édition dans Figma

L'outil ne peut pas :

• Modifier les polices d'un diagramme existant
• Déplacer des formes individuelles
• Éditer un diagramme nœud par nœud après sa génération

Si l'utilisateur demande l'un de ceux-ci sur un diagramme existant, recommandez-lui d'ouvrir le diagramme dans Figma et de l'éditer là-bas. Pour des modifications au niveau du contenu, il est généralement plus rapide de régénérer.

Étape 2 : Choisir le type de diagramme

Routage léger — utilisez le premier match.

Si un flowchart est demandé et qu'il décrit une infrastructure logicielle (services, magasins de données, files d'attente, intégrations externes), routez vers architecture.md — pas flowchart.md. En cas de doute, posez la question à l'utilisateur.

Étape 3 : Contraintes universelles (appliquer à chaque type de diagramme)

1. Pas d'emojis dans aucune partie de la source Mermaid. L'outil les rejette.
2. Pas de \n dans les libellés. Utilisez les sauts de ligne uniquement si absolument nécessaire et seulement via des sauts de ligne réels (pas la séquence d'échappement).
3. Pas de balises HTML dans les libellés.
4. Mots réservés — n'utilisez pas end, subgraph, graph comme IDs de nœuds.
5. IDs de nœuds : camelCase (userService), sans espaces. Les underscores peuvent casser le routage des arêtes dans certains processeurs.
6. Caractères spéciaux dans les libellés doivent être entre guillemets : A["Process (main)"], -->|"O(1) lookup"|.
7. Sequence diagrams — n'utilisez pas les notes.
8. Gantt charts — n'utilisez pas la coloration stylée.

Étape 4 : Garbage in, garbage out

La qualité du diagramme généré est limitée par la qualité du Mermaid que vous produisez, qui est limitée par le contexte dont vous disposez. Avant d'écrire du Mermaid, assurez-vous d'avoir suffisamment d'informations réelles pour décrire le sujet avec précision — et utilisez tout ce que l'environnement actuel vous donne pour les rassembler.

Selon ce qui est disponible, les sources de contexte utiles incluent :

• Code source — grep/lisez les fichiers pertinents pour que le diagramme reflète les vrais noms de services, les vrais libellés d'arêtes, les vrais magasins de données, les vrais points d'entrée. Parcourir les routes/handlers/consumers réels vaut mieux que recréer de mémoire.
• Documents fournis par l'utilisateur — un PRD, spécification, notes de réunion, transcription, synthèse de recherche, doc d'onboarding, description de processus. Demandez à l'utilisateur de coller ou joindre si le sujet n'est pas du code.
• Fichiers Figma ou FigJam existants — si le nouveau diagramme devrait s'aligner avec un que l'utilisateur a déjà, lisez-le avec get_figjam ou get_design_context (voir les skills figma-use et figma-use-figjam).
• Autres serveurs ou outils MCP que vous avez — suivi de problèmes, sites de docs, CRM, analyse, wikis internes, systèmes de design, schémas de bases de données, etc. Si un outil connecté détient la source de vérité pour ce que vous diagrammez, tirez-la plutôt que de deviner.
• L'utilisateur lui-même — quand la description est mince ou ambiguë (direction du flux peu claire, périmètre flou, incertitude sur les entités qui importent), posez une ou deux questions ciblées avant de générer. Exemples : « Quelles sont les 3–5 principales étapes ? », « Qui est propriétaire de chaque étape ? », « Qu'est-ce qui déclenche l'étape suivante ? ». Une bonne question vaut mieux qu'un diagramme gaspillé.

N'inventez pas d'arêtes, de libellés ou d'entités pour « compléter » un diagramme. L'information manquante est mieux qu'une information hallucée — laissez une lacune et signalez-la à l'utilisateur.

Étape 5 : Le diagramme aura-t-il besoin de plus que ce que Mermaid peut exprimer ?

Mermaid ne peut pas tout faire. Les annotations de sticky-notes liées à des nœuds spécifiques, la coloration par domaine par nœud sur les ERD, les callouts avec données attachées — tout cela nécessite de composer generate_diagram avec use_figma (via la skill figma-use-figjam). C'est le workflow hybride.

C'est une question de jugement, pas un défaut. Déployez-le quand la demande de l'utilisateur en bénéficie clairement — passer au crible quand le diagramme de base est manifestement suffisant. Les signaux qui disent oui : l'utilisateur a explicitement demandé des notes, des couleurs, des callouts ou « X attaché à chaque nœud » ; il a partagé des données qui correspondent à des nœuds spécifiques ; le diagramme est un artefact partageable, pas un sketch de réflexion. Les signaux qui disent non : demande courte/auto-explicative, petit diagramme, l'utilisateur explore ou teste.

Si le workflow hybride est justifié, lisez references/workflow.md avant d'appeler generate_diagram — cela couvre le pattern, deux recettes principales (annotations + colour-coding), le style de communication et la gestion des défaillances. Sinon, procédez directement à l'étape 6.

Étape 6 : Appeler l'outil

Requis :

• name : un titre descriptif (affiché à l'utilisateur)
• mermaidSyntax : la source Mermaid

Optionnel :

• userIntent : une courte phrase décrivant ce que l'utilisateur essaie d'accomplir — aide la télémétrie et le tuning en aval
• useArchitectureLayoutCode : seulement pour les diagrammes d'architecture ; la valeur est spécifiée dans references/architecture.md
• fileKey : si l'utilisateur veut ajouter le diagramme à un fichier FigJam existant au lieu d'un nouveau

Ne pas appeler create_new_file avant generate_diagram — l'outil crée son propre fichier.

Étape 7 : Après la génération

• L'outil retourne un lien (ou widget) sur lequel l'utilisateur peut cliquer pour ouvrir le diagramme dans FigJam. Affichez-le en tant que lien markdown sauf si le client rend un widget inline.
• Si des extensions sont justifiées (voir l'étape 5), composez avec use_figma maintenant — le pattern et les recettes sont dans references/workflow.md.
• Si l'utilisateur n'est pas satisfait après 2 tentatives du même diagramme, arrêtez de régénérer. Demandez ce qui ne va pas précisément, ou suggérez-lui d'ouvrir dans Figma et d'éditer manuellement plutôt que de gaspiller d'autres appels d'outil.

Réutiliser le même fichier lors de l'itération ou l'ajout de diagrammes connexes

Chaque appel à generate_diagram sans fileKey crée un nouveau fichier FigJam dans les brouillons de l'utilisateur. Régénérer 4 fois = 4 fichiers brouillon à nettoyer. Préférez réutiliser le fichier existant quand :

• L'utilisateur itère sur le même diagramme (« essayez à nouveau avec… », « changez les libellés… »).
• L'utilisateur veut un diagramme de suivi qui coexiste avec le premier (ex : un sequence diagram à côté d'un flowchart du même système).

Comment réutiliser :

1. Passez fileKey sur les appels generate_diagram suivants. Extrayez-le d'une URL figma.com/board/{fileKey}/.... Le diagramme est ajouté au fichier existant au lieu de créer un nouveau.
2. Si vous voulez remplacer le diagramme précédent plutôt que d'ajouter à côté, utilisez l'outil use_figma (voir la skill figma-use-figjam) pour supprimer d'abord les nœuds du vieux diagramme, puis appelez generate_diagram avec le même fileKey. Ou laissez le vieux diagramme et placez le nouveau à côté — les lecteurs bénéficient souvent de voir l'historique des tentatives.

Demandez à l'utilisateur ce qu'il préfère la première fois que vous itérez — « régénérer sur l'ancien, ou garder les deux côte à côte ? » — et souvenez-vous de sa réponse pour les itérations suivantes dans la session.