generate-diagram

Vous DEVEZ charger cette skill avant chaque appel à l'outil generate_diagram. L'ignorer 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 modifiable. Cette skill vous oriente vers les conseils appropriés par type et établit des contraintes universelles.

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

Types de diagrammes pris en charge

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

Non pris en charge — n'appelez pas l'outil

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

• Pie chart, mindmap, venn diagram, class diagram, journey, timeline, quadrant, C4, git graph, requirement diagram

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

L'outil ne peut pas :

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

Si l'utilisateur demande l'une de ces modifications sur un diagramme existant, recommandez-lui d'ouvrir le diagramme dans Figma et de l'éditer là. Pour les 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 la première correspondance.

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

Étape 3 : Contraintes universelles (s'appliquent à tout 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 des 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 ID de nœud.
5. ID de nœud : camelCase (userService), pas d'espaces. Les underscores peuvent casser le routage des arêtes dans certains processeurs.
6. Caractères spéciaux dans les libellés doivent être mis entre guillemets : A["Process (main)"], -->|"O(1) lookup"|.
7. Sequence diagrams — Mermaid Note over X / Note left of X / Note right of X sont silencieusement supprimés par le moteur de rendu ; ne les mettez pas dans la source. Si l'utilisateur veut des annotations sur un sequence diagram, générez d'abord le diagramme de base et ajoutez des stickies/texte via le workflow hybride (references/workflow.md).
8. Gantt charts — classDef, class et tout autre style sont supprimés par le prétraitement ; le graphique rendu n'aura pas de couleurs. Si l'utilisateur veut des phases, jalons ou tâches en couleur, générez d'abord le graphique de base et ajoutez couleur/annotations via le workflow hybride (references/workflow.md) — ou, pour les diagrammes qui ont fondamentalement besoin de style, construisez la chronologie directement avec use_figma à la place (voir references/gantt.md §11).
9. Utilisez uniquement les APIs FigJam dans toute extension use_figma. La sortie de generate_diagram atterrit dans un fichier FigJam (figma.com/board/...), les extensions hybrides doivent donc respecter les APIs prises en charge par FigJam. N'appelez PAS figma.createPage() — c'est Design-only (figma.com/design/...) et lève TypeError: figma.createPage no such property 'createPage' on the figma global object dans FigJam. Organisez le contenu avec les sections FigJam à la place (voir figma-use-figjam).

Étape 4 : Poubelle entrante, poubelle sortante

La qualité du diagramme généré est limitée par la qualité du Mermaid que vous produisez, laquelle est limitée par le contexte dont vous disposez. Avant d'écrire du Mermaid, assurez-vous d'avoir assez d'informations réelles pour décrire le sujet avec précision — et utilisez tout ce que votre environnement actuel peut vous donner 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 datastores, 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, une spec, des notes de réunion, une transcription, une synthèse de recherche, un document d'onboarding, un guide de processus. Demandez à l'utilisateur de coller ou joindre le document si le sujet n'est pas du code.
• Fichiers Figma ou FigJam existants — si le nouveau diagramme doit s'aligner avec un que l'utilisateur possède déjà, lisez-le avec get_figjam ou get_design_context (voir les skills figma-use et figma-use-figjam).
• Autres serveurs MCP ou outils disponibles — systèmes de suivi, sites de docs, CRMs, analytics, wikis internes, systèmes de design, schémas de base de données, etc. Si un outil connecté détient la vérité de ce que vous diagrammez, tirez-en plutôt que de deviner.
• L'utilisateur lui-même — quand la description est mince ou ambiguë (direction de flux peu claire, périmètre peu clair, entités pertinentes peu claires), posez une ou deux questions ciblées avant de générer. Exemples : « Quelles sont les 3–5 étapes principales ? », « Qui en est propriétaire à chaque étape ? », « Qu'est-ce qui déclenche l'étape suivante ? ». Une bonne question vaut un diagramme gaspillé.

N'inventez pas d'arêtes, libellés ou entités pour « arrondir » un diagramme. L'information manquante est préférable à l'information halluccinée — laissez un trou et signalez-le à 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 par sticky-note attachées à des nœuds spécifiques, la coloration par domaine par nœud sur les ERDs, les légendes 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 un jugement, pas un défaut. Déployez-le quand la demande de l'utilisateur en bénéficie clairement — ignorez-le quand le diagramme de base est clairement suffisant. Les signaux qui disent oui : l'utilisateur a explicitement demandé des notes, des couleurs, des légendes, ou « X attaché à chaque nœud » ; ils ont partagé des données qui correspondent à des nœuds spécifiques ; le diagramme est un artefact partageable, pas un croquis de réflexion. Les signaux qui disent non : demande courte/auto-explicite, 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 motif, deux recettes principales (annotations + codage en couleur), le style de communication et la gestion des défaillances. Sinon, procédez directement à l'étape 6.

Étape 6 : Appel de l'outil

Requis :

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

Optionnel :

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

N'appelez PAS 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) que l'utilisateur peut cliquer pour ouvrir le diagramme dans FigJam. Affichez-le comme un lien markdown sauf si le client affiche un widget en ligne.
• Si des extensions sont justifiées (voir étape 5), composez avec use_figma maintenant — le motif et les recettes sont dans references/workflow.md.
• Si l'utilisateur n'est pas satisfait après 2 tentatives sur le même diagramme, arrêtez la régénération. 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 plus d'appels aux outils.

Réutilisez le même fichier lors de l'itération ou de 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 (« réessayez avec… », « changez les libellés… »).
• L'utilisateur veut un diagramme de suivi qui vit aux côtés du premier (par exemple 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 d'une URL figma.com/board/{fileKey}/.... Le diagramme est ajouté au fichier existant plutôt que d'en créer un nouveau.
2. Si vous voulez remplacer le diagramme précédent plutôt que l'ajouter à côté, utilisez l'outil use_figma (voir la skill figma-use-figjam) pour supprimer d'abord les nœuds de l'ancien diagramme, puis appelez generate_diagram avec le même fileKey. Ou laissez l'ancien diagramme et placez le nouveau à côté — les lecteurs bénéficient souvent de voir l'historique des tentatives.

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