Communitygithub.com

CoderMoray/SkillFlowChart

Générateur de diagrammes de flux décisionnels — L'IA extrait la sémantique, le script calcule la géométrie.

Qu'est-ce que SkillFlowChart ?

SkillFlowChart est un compétence pour agents IA (comme Claude Code, Cursor ou Codex) qui génère des diagrammes de flux décisionnels à partir d'un fichier `SKILL.md`. Le processus est divisé en deux étapes clairement séparées : l'IA lit le fichier `SKILL.md` et extrait les données structurées au format `nodes.json` (en comprenant la sémantique et les relations logiques), puis un script Python déterministe lit ce JSON et génère un fichier HTML autonome contenant le diagramme. Cette séparation garantit que l'IA ne s'occupe que de la compréhension sémantique (types de nœuds, rôles, directions des arêtes), tandis que le script gère tous les calculs géométriques (positionnement, alignement, routage des lignes) de manière reproductible et sans ambiguïté. La compétence prend en charge les points de décision (losanges), les processus, les entrées/sorties, les boucles de rétroaction (flèches en pointillés), et gère automatiquement la mise en page avec légende. Elle est particulièrement utile pour documenter visuellement des workflows complexes, des pipelines de données ou des processus de décision multi-étapes.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add CoderMoray/SkillFlowChart

Demander à votre IA préférée

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

Documentation

Compétence Générateur de diagrammes de flux décisionnels

Lit un fichier SKILL.md, extrait les données structurées nodes.json, et génère de manière déterministe un diagramme de flux HTML via un script.

Répartition

ÉtapeQui faitPourquoi
SKILL.md → nodes.jsonIASKILL.md est en langage naturel, la sémantique est instable ; l'IA comprend le contexte
nodes.json → HTMLScriptLes calculs de coordonnées doivent être déterministes, reproductibles et alignés sur les pixels

L'IA ne produit que des données structurées, jamais de coordonnées ou de SVG ; le script ne fait que de la géométrie, il ne devine jamais la sémantique.

Étapes d'exécution

1. Lire SKILL.md

Lire le SKILL.md spécifié par l'utilisateur. S'il n'est pas trouvé, demander à l'utilisateur de fournir le chemin.

2. L'IA extrait nodes.json

Produire un JSON selon le schéma ci-dessous. Chaque arête sortante doit explicitement annoter le champ side — c'est le jugement sémantique de l'IA, le script ne le devine pas.

Structure racine

{
  "title": "Nom de la compétence",
  "subtitle": "Description optionnelle",
  "nodes": [ ... ],
  "edges": [ ... ],
  "loops": [ ... ],
  "legend": [ ... ]
}
  • nodes : obligatoire, tableau de nœuds
  • edges : obligatoire, tableau d'arêtes orientées
  • loops : optionnel, boucles de rétroaction en pointillés (voir ci-dessous)
  • legend : généralement laissé vide [], utilise la légende par défaut

Type de nœud

typeSignificationForme
entryPoint d'entrée du fluxRectangle arrondi
decisionPoint de décision (oui/non, présent/absent)Losange
processÉtape de traitementRectangle arrondi
outputRapport / sortie de fichierRectangle arrondi
terminalTerminaison / sortie sur erreurRectangle arrondi

Rôle du nœud (couleur)

roleSignificationfill / stroke
aiInférence IA / appel LLM#E6F1FB / #185FA5
outputRapport / sortie de fichier#EEEDFE / #534AB7
decisionPoint de décision#FAEEDA / #854F0B
scriptExécution de script#E1F5EE / #0F6E56
terminalTerminaison / erreur#FCEBEB / #A32D2D

Un nœud ne peut avoir qu'un seul rôle. Si une étape implique plusieurs types de travaux de nature différente (correspondant à des rôles différents), elle doit être divisée en plusieurs nœuds en série. Par exemple, « Script de récupération de base + analyse complémentaire par IA » ne peut pas être fusionné en un seul nœud role=ai ; il doit être divisé en un nœud role=script et un nœud role=ai.

Côté de l'arête (critique !)

sideSignificationComportement de mise en page
bottomFlux principal vers le basLa cible est au niveau inférieur du from, cx hérité de from
leftBranche gauche de décision / bifurcation gaucheDécision → même niveau, connexion horizontale ; Normal → niveau inférieur, ligne brisée orthogonale
rightBranche droite de décision / bifurcation droiteIdem, direction opposée

Le jugement sémantique de side est effectué par l'IA :

  • Losange de décision (type=decision) avec left/right → même niveau que la décision, connexion horizontale
  • Rectangle normal (type=process/output) avec left/right → niveau inférieur, ligne brisée orthogonale (vertical → horizontal → vertical, pas de diagonale)

Boucles (loops, optionnel, pointillés)

Utilisé lorsqu'il y a une logique de « retour à une étape précédente », par exemple :

  • Révision après correction (apply_fix → entry)
  • Nouvelle tentative (retry → checkpoint)
  • Boucle jusqu'à satisfaction de condition (recheck → validate)
{ "from": "apply_fix", "to": "entry", "label": "Révision après correction", "path": "left_edge" }

Description des champs :

  • from : ID du nœud de début de boucle (généralement la dernière étape)
  • to : ID du nœud de fin de boucle (généralement le point d'entrée ou un point de contrôle)
  • label : Étiquette de la boucle, affichée à côté des pointillés
  • path : fixé à "left_edge" (routage le long du bord gauche du diagramme)

Remarque :

  • Ne pas dupliquer l'arête entre le début et la fin de la boucle dans edges, sinon elle sera rendue deux fois
  • Les nœuds from/to dans loops ne participent pas au calcul de la profondeur (depth)

Légende

Généralement laissée vide [], le script utilisera la légende par défaut à 5 couleurs. Pour une personnalisation :

[
  { "label": "Exécution IA",   "fill": "#E6F1FB", "stroke": "#185FA5" },
  { "label": "Sortie/Rapport", "fill": "#EEEDFE", "stroke": "#534AB7" },
  { "label": "Point de décision", "fill": "#FAEEDA", "stroke": "#854F0B" },
  { "label": "Script",         "fill": "#E1F5EE", "stroke": "#0F6E56" },
  { "label": "Terminaison",   "fill": "#FCEBEB", "stroke": "#A32D2D" }
]

3. Appeler le script pour générer le HTML

python3 <skill_dir>/scripts/flowchart.py <nodes.json> --out docs/decision-flowchart.html

Le script va :

  • Valider l'unicité des ID, la validité de side/type/role, et la validité des références from/to
  • Calculer automatiquement les niveaux (branche latérale de décision au même niveau / bifurcation normale au niveau inférieur / point de jonction = max(arêtes entrantes)+1)
  • Calculer automatiquement x (déterminé par side) et y (selon le niveau + hauteur du nœud)
  • Rendre les connexions (branches latérales horizontales / lignes brisées orthogonales / flux principal vertical / jonction en trois segments / boucles en pointillés)
  • Ajuster automatiquement le viewBox + légende en bas
  • Produire un HTML autonome

Exemples de nodes.json

  • docs/halucatch-v2-nodes.json — Exemple complet (avec boucle loop, branchement à trois voies, point de jonction)
  • docs/halucatch-nodes.json — Exemple de base
  • docs/security-review-nodes.json — Exemple avec plusieurs points de décision
  • docs/self-nodes.json — Exemple minimal (9 nœuds)

Liste de vérification

  • Le nœud d'entrée type=entry est tout en haut
  • Chaque arête a un champ side (bottom/left/right)
  • Les side=left/right d'un losange de décision sont des branches latérales (connexion horizontale au même niveau)
  • Les side=left/right d'un rectangle normal sont des bifurcations (ligne brisée orthogonale au niveau inférieur)
  • Un seul rôle par nœud, les étapes mixtes ont été divisées
  • Les points de jonction (plusieurs arêtes entrantes vers le même nœud) n'ont pas besoin de traitement spécial, le script les reconnaît automatiquement
  • Les boucles sont déclarées dans le champ loops, pas dupliquées dans edges
  • Tous les ID de nœuds sont référencés dans les from/to des edges (pas de nœud isolé)
  • Légende laissée vide []

Questions fréquentes

Q : Que faire si les nœuds se chevauchent ? Vérifiez si le champ side manque. Les branches de décision doivent avoir un side (left/right/bottom), sinon les deux nœuds cibles hériteront de la même position.

Q : La boucle en pointillés ne s'affiche pas ? Les boucles sont déclarées dans le tableau loops (pas dans edges), et les nœuds from/to ne doivent pas être dupliqués dans edges. Le path est fixé à "left_edge".

Q : Le script signale une erreur de format JSON ? Le JSON ne supporte pas les commentaires ni les guillemets simples. Problèmes courants : virgules manquantes, virgules supplémentaires (en fin de tableau), guillemets simples.

Pour plus de questions, voir docs/FAQ.md.

Skills associés