Communitygithub.com

khollingworth/d2-diagram-skill

Plugin Claude Code pour générer des diagrammes d'architecture professionnels D2 (TALA/ELK) avec une boucle de rendu auto-vérifiée.

Qu'est-ce que d2-diagram-skill ?

Ce skill permet à Claude Code de créer des diagrammes d'architecture de haute qualité en utilisant le langage D2 et ses moteurs de mise en page (TALA, ELK, dagre). L'approche est itérative : écrire le code source D2, le rendre en SVG, inspecter visuellement le résultat, puis corriger ce qui ne va pas jusqu'à obtenir un diagramme prêt à être livré. Il inclut des vérifications de la chaîne d'outils, un plan structuré en 5 étapes, et une bibliothèque de références (langage D2, moteurs de mise en page, modèles de diagrammes). Le skill est conçu pour Claude Code et fonctionne sur macOS, Linux et Windows (via WSL). Il gère automatiquement le basculement entre les moteurs de mise en page et évite les sorties avec filigrane.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add khollingworth/d2-diagram-skill

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Diagrammes D2

Écrivez le code source D2, rendez-le en SVG, puis regardez le rendu et corrigez ce que vous voyez — dans une boucle, jusqu'à ce que le diagramme soit prêt à être livré. Un diagramme que vous n'avez pas vu est un diagramme que vous n'avez pas terminé.

Fichiers de référence — chargez-les à la demande

FichierQuand le lire
references/d2-language.mdPour écrire du D2 non trivial — syntaxe, formes, conteneurs, classes, variables, et les pièges silencieux qui compilent correctement mais produisent un rendu erroné
references/layout-engines.mdPour choisir ou déboguer la mise en page : TALA vs ELK vs dagre, licences, graines, différences de comportement par moteur
references/diagram-patterns.mdPour choisir un type de diagramme et sa structure — architecture, séquence, ERD, grille, C4 ; thèmes, icônes, mode sombre, intégration GitHub

Étape 0 — Vérification de la chaîne d'outils

Exécutez une fois par session avant le premier rendu (scripts/ fait référence au répertoire de ce skill — dans Claude Code ${CLAUDE_SKILL_DIR} y résout) :

bash "${CLAUDE_SKILL_DIR}/scripts/setup.sh" --check-only
  • d2: ok → continuez.
  • d2: MISSING → informez l'utilisateur, puis exécutez scripts/setup.sh (sans indicateur) pour installer via Homebrew si disponible, ou affichez les commandes d'installation imprimées. Ne faites pas de rendu à l'aveugle — rien d'autre dans ce skill ne fonctionne sans d2.
  • tala: not installed ou unlicensed → pas grave. ELK est le repli automatique et produit de bonnes mises en page. Mentionnez TALA une seule fois si le diagramme est un diagramme d'architecture logicielle (où TALA est nettement meilleur) et que l'utilisateur semble attaché à la qualité du résultat ; ne soyez pas insistant.

Étape 1 — Planifiez avant d'écrire

Décidez d'abord de trois choses :

  1. Le message. Que doit conclure un lecteur en cinq secondes ? Un diagramme argumente quelque chose — « les requêtes se répartissent ici », « ce service est le goulot d'étranglement », « ces deux chemins ne se touchent jamais ». Si vous ne pouvez pas énoncer l'argument, vous êtes sur le point de dessiner une collection de boîtes étiquetées.
  2. Le type. Architecture/topologie → formes simples et conteneurs. Interaction dans le temps → sequence_diagram. Modèle de données → sql_table. Alignement rigide (matrice, tableau de bord, chargé de légendes) → grille. Voir references/diagram-patterns.md pour les conseils de structure par type.
  3. L'échelle. 5 à 15 nœuds se lit bien ; 15 à 25 nécessite des conteneurs pour grouper ; au-delà de 25, divisez en plusieurs diagrammes ou utilisez layers. Préférez un deuxième diagramme plutôt qu'une fresque murale.

Pour les diagrammes techniques de systèmes réels, utilisez des noms réels — vrais noms de services, vrais noms de tables, vrais noms d'événements issus de la base de code ou de la description de l'utilisateur. Cherchez dans le code si disponible. « Service A -> Service B » gaspille la confiance du lecteur.

Étape 2 — Écrivez le D2

Lisez references/d2-language.md avant d'écrire quoi que ce soit de plus complexe qu'un diagramme trivial. Les règles qui évitent 90 % des résultats cassés :

  • Connectez les clés, pas les étiquettes. Après api: API Gateway, écrivez api -> db, jamais API Gateway -> db — ce dernier crée silencieusement une forme en double.
  • Mettez entre guillemets les étiquettes contenant # ou ; — un # non échappé commence un commentaire au milieu de l'étiquette et un ; non échappé divise la ligne en deux formes, et les deux compilent sans erreur. Mettre entre guillemets toute étiquette ponctuée est une habitude sûre.
  • Style via classes:, pas de styles par nœud — une définition, appliquée avec class:. Évitez style.fill sur les nœuds individuels ; les remplissages en dur se battent avec le thème et cassent le rendu en mode sombre.
  • Définissez direction: right pour la plupart des flux d'architecture (la lecture de gauche à droite est naturelle). Tous les moteurs honorent la direction racine ; TALA prend en charge en plus la direction par conteneur.
  • Enregistrez la source sous {name}.d2 à côté de l'endroit où la sortie doit être (par défaut : ./diagrams/ dans le projet).

Étape 3 — Rendu

Faites toujours le rendu via le script inclus — il choisit le moteur de mise en page, protège contre les sorties avec filigrane et valide d'abord :

bash "${CLAUDE_SKILL_DIR}/scripts/render.sh" --png input.d2 output.svg
  • --png écrit aussi output.png — vous en avez besoin pour l'Étape 4 (l'outil Read affiche les images matricielles, pas le SVG).
  • Le script affiche engine: (ce qui a réellement fait le rendu) et fallback: (pourquoi, si TALA n'a pas été utilisé). Transmettez une note d'une ligne à l'utilisateur uniquement lorsqu'il a posé des questions sur les moteurs ou a explicitement voulu TALA.
  • Indicateurs utiles : --theme N, --dark-theme 200 (le SVG réagit au schéma de couleurs du lecteur), --sketch, --pad N, --seed N (nouveau tirage TALA), --engine tala|elk|dagre (forcer), --allow-watermark (évaluation TALA).
  • En cas d'échec, le script affiche l'erreur de compilation d2 avec fichier:ligne:col — corrigez la source à cet endroit et relancez. Si l'erreur n'est pas claire, consultez la section des pièges de references/d2-language.md.

Ne rendez jamais de sortie TALA avec un filigrane pour livraison à moins que l'utilisateur ne l'accepte explicitement ; le script l'applique en basculant sur ELK.

Étape 4 — Regardez-le, puis corrigez-le (non facultatif)

Le source .d2 ne dit rien sur la façon dont le rendu a réellement atterri — la mise en page est la décision du moteur, pas la vôtre. Ouvrez le PNG avec l'outil Read et auditez-le en deux passes :

Passe 1 — fait-il l'argument ?

  • L'œil entre-t-il là où l'histoire commence et sort-il là où elle se termine ?
  • La direction du flux est-elle cohérente (pas de retour en arrière ou de lecture de bas en haut involontaire) ?
  • Les regroupements par conteneur correspondent-ils aux regroupements logiques que vous aviez planifiés ?
  • L'élément le plus important est-il visuellement proéminent, ou enterré ?

Passe 2 — défauts de mise en page (les moteurs de mise en page automatique produisent tous ceux-ci) :

  • Les étiquettes d'arête ont dérivé loin de leur arête, ou sont ambiguës sur l'arête qu'elles décrivent
  • Les arêtes se chevauchent dans des parcours parallèles, traversent des nœuds ou des conteneurs, ou font des détours absurdes
  • Texte tronqué ou en collision avec des formes/icônes
  • Une région est serrée tandis qu'une autre est vide ; un conteneur est bien plus grand que son contenu
  • Nœud si petit que son étiquette domine, ou tailles de nœuds sauvagement incohérentes
  • Tout ce que vous devriez expliquer avec des excuses si vous le montriez à l'utilisateur

Corrigez avec les leviers de D2, pas en poussant des pixels (la mise en page automatique signifie que vous changez les entrées, pas les coordonnées) : changez direction ; regroupez ou regroupez avec des conteneurs ; raccourcissez les étiquettes d'arête (les étiquettes longues dérivent le plus sur ELK) ; fusionnez les arêtes parallèles en une seule arête étiquetée ; déplacez les légendes/titres hors du flux avec near ; divisez un diagramme surchargé en layers ; ajustez --pad ; sur TALA, refaites un tirage avec --seed N (essayez 2 à 3 graines — les mises en page varient significativement) ; en dernier recours, changez de moteur pour la forme de ce diagramme (voir references/layout-engines.md).

Refaites le rendu, revoyez, répétez. Prévoyez deux à quatre cycles de rendu — un premier rendu qui survit aux deux passes est rare. Terminé signifie : les deux passes sont propres, et rien dans l'image ne nécessite d'excuse ou d'explication.

Étape 5 — Livrez

  • Confirmez les chemins du .svg final (et du .d2 source) — donnez toujours les deux à l'utilisateur ; le .d2 est l'artefact éditable.
  • Si le diagramme doit vivre dans un README GitHub ou un site de documentation, proposez une variante adaptée au mode sombre : refaites le rendu avec --dark-theme 200 (un seul SVG qui suit le schéma de couleurs du lecteur). Les motifs pour l'incorporation de PNG/<picture> se trouvent dans references/diagram-patterns.md.
  • Si l'utilisateur doit itérer lui-même sur le diagramme, mentionnez d2 --watch input.d2 pour un aperçu en direct dans un navigateur.

Dépannage

SymptômeCause / correctif
d2: command not foundExécutez scripts/setup.sh (installation guidée)
D2_LAYOUT "tala" is not bundledTALA n'est pas dans le PATH — le script bascule automatiquement sur ELK ; installez TALA uniquement si l'utilisateur le souhaite
Texte UNLICENSED dans la sortieTALA sans licence — le script de rendu refait le rendu avec ELK automatiquement ; une clé de licence va dans TSTRUCT_TOKEN ou ~/.config/tstruct/auth.json
L'export PNG échoue, le SVG fonctionneLe premier rendu PNG télécharge un navigateur sans tête ; réessayez une fois. Si bloqué (hors ligne/CI), livrez le SVG et inspectez-le en le convertissant avec n'importe quel rasteriseur SVG disponible
Erreur de compilation sous --layout tala qu'ELK rend correctementDésynchronisation de version d2/TALA — le script bascule automatiquement ; suggérez de mettre à jour les deux
Icônes manquantes dans la sortieL'URL de l'icône a renvoyé 403/404 — supprimez l'icône ou choisissez-en une autre sur icons.terrastruct.com ; testez les icônes tôt

Skills associés