Communitygithub.com

SkillFlowChart — Generador de Diagramas de Decisión

Skill generador de diagramas de flujo de decisión — la IA extrae la semántica, el script calcula la geometría.

¿Qué es SkillFlowChart — Generador de Diagramas de Decisión?

SkillFlowChart es una habilidad para agentes de IA (compatible con Claude Code, Cursor, Codex y otras herramientas similares) que automatiza la generación de diagramas de flujo de decisión a partir de archivos `SKILL.md`. Su flujo de trabajo se divide en dos fases claramente separadas: primero, la IA lee el `SKILL.md` y extrae la información semántica en un archivo JSON estructurado (`nodes.json`); luego, un script Python (determinista y reproducible) utiliza ese JSON para generar un archivo HTML autocontenido con el diagrama de flujo. Esta separación de responsabilidades asegura que la IA se encargue exclusivamente de la interpretación semántica (asignando tipos de nodo, roles, direcciones de aristas, bucles, etc.) mientras que el script maneja todo el cálculo geométrico (coordenadas, niveles, enrutamiento de líneas) sin adivinar significados. El resultado es un diagrama visual preciso, renderizado con formas y colores estandarizados (entrada, decisión, proceso, salida, terminal) y soporte para bucles de retroalimentación (líneas punteadas), ramificaciones izquierda/derecha y puntos de convergencia.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Skill Generador de Diagramas de Decisión

Lee un archivo SKILL.md, extrae los datos estructurados en nodes.json y, mediante un script determinista, genera el diagrama de flujo en HTML.

División del trabajo

FaseQuién lo hacePor qué
SKILL.md → nodes.jsonIASKILL.md está en lenguaje natural, la semántica es inestable; la IA comprende el contexto
nodes.json → HTMLScriptEl cálculo de coordenadas debe ser determinista, reproducible y alineado con los píxeles

La IA solo produce datos estructurados, nunca coordenadas ni SVG; el script solo hace geometría, nunca adivina semántica.

Pasos de ejecución

1. Leer SKILL.md

Lee el SKILL.md especificado por el usuario. Si no se encuentra, pregunta al usuario la ruta.

2. La IA extrae nodes.json

Genera el JSON según el siguiente esquema. Cada arista saliente debe etiquetarse explícitamente con el campo side — esto es una decisión semántica de la IA, el script no la adivinará.

Estructura raíz

{
  "title": "Nombre del Skill",
  "subtitle": "Descripción opcional",
  "nodes": [ ... ],
  "edges": [ ... ],
  "loops": [ ... ],
  "legend": [ ... ]
}
  • nodes: obligatorio, array de nodos
  • edges: obligatorio, array de aristas dirigidas
  • loops: opcional, bucles en línea discontinua (ver más abajo)
  • legend: normalmente se deja vacío [] para usar la leyenda por defecto

type de nodo

typeSignificadoForma
entryPunto de entradaRectángulo redondeado
decisionPunto de decisión (sí/no, tiene/no tiene)Rombo
processPaso de procesoRectángulo redondeado
outputSalida de informe/archivoRectángulo redondeado
terminalTerminación/salida por errorRectángulo redondeado

role de nodo (esquema de colores)

roleSignificadofill / stroke
aiRazonamiento de IA / llamada a LLM#E6F1FB / #185FA5
outputInforme / salida de archivo#EEEDFE / #534AB7
decisionPunto de decisión#FAEEDA / #854F0B
scriptEjecución de script#E1F5EE / #0F6E56
terminalTerminación / error#FCEBEB / #A32D2D

Un nodo solo puede tener un role. Si un paso involucra múltiples tipos de trabajo de diferente naturaleza (que corresponden a diferentes roles), debe dividirse en varios nodos en serie. Por ejemplo, «Script toma línea base + IA completa análisis» no puede fusionarse en un solo nodo con role=ai, debe dividirse en dos nodos: role=script y role=ai.

side de arista (¡Clave!)

sideSignificadoComportamiento en el layout
bottomFlujo principal hacia abajotarget está en la siguiente capa de from, cx hereda de from
leftRama izquierda de decisión / bifurcación izquierdaDecisión → misma capa, línea horizontal; normal → siguiente capa, línea poligonal ortogonal
rightRama derecha de decisión / bifurcación derechaIgual que arriba, pero en dirección opuesta

La interpretación semántica de side la realiza la IA:

  • Rombo de decisión (type=decision) con side=left/right → misma capa que la decisión, línea horizontal
  • Rectángulo normal (type=process/output) con side=left/right → siguiente capa, línea poligonal ortogonal (vertical → horizontal → vertical, sin diagonales)

loops (Bucle, opcional, línea discontinua)

Se usa cuando el flujo contiene lógica de «volver a un paso anterior», por ejemplo:

  • Revisar después de aplicar una corrección (apply_fix → entry)
  • Reintentar (retry → checkpoint)
  • Iterar hasta que se cumpla una condición (recheck → validate)
{ "from": "apply_fix", "to": "entry", "label": "Revisar tras corrección", "path": "left_edge" }

Campos:

  • from: id del nodo de inicio del bucle (normalmente el último paso)
  • to: id del nodo de fin del bucle (normalmente el punto de entrada o un punto de verificación)
  • label: etiqueta del bucle, mostrada junto a la línea discontinua
  • path: fijo en "left_edge" (enrutamiento por el borde izquierdo del diagrama)

Nota:

  • No repitas la arista del bucle en el array edges entre el mismo from y to, o se renderizará duplicada.
  • Los nodos from/to de loops no participan en el cálculo de profundidad (depth).

legend

Normalmente se deja vacío [] para que el script use la leyenda por defecto de 5 colores. Si se desea personalizar:

[
  { "label": "Ejecución IA",    "fill": "#E6F1FB", "stroke": "#185FA5" },
  { "label": "Salida/Informe",  "fill": "#EEEDFE", "stroke": "#534AB7" },
  { "label": "Punto de decisión", "fill": "#FAEEDA", "stroke": "#854F0B" },
  { "label": "Script",          "fill": "#E1F5EE", "stroke": "#0F6E56" },
  { "label": "Terminación",     "fill": "#FCEBEB", "stroke": "#A32D2D" }
]

3. Ejecutar script para generar HTML

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

El script:

  • Valida unicidad de id, legalidad de side/type/role y referencias from/to
  • Calcula automáticamente niveles (ramas de decisión en misma capa / bifurcaciones normales en capa inferior / punto de convergencia = max(aristas entrantes)+1)
  • Calcula automáticamente x (determinado por side) e y (según nivel + altura de nodo)
  • Renderiza líneas (ramas laterales horizontales / líneas poligonales ortogonales / flujo principal vertical / convergencia en tres segmentos / bucles en línea discontinua)
  • Ajusta automáticamente viewBox + leyenda inferior
  • Genera HTML autocontenido

Ejemplos de nodes.json

  • docs/halucatch-v2-nodes.json — Ejemplo completo (con bucle loop, rama triple, punto de convergencia)
  • docs/halucatch-nodes.json — Ejemplo básico
  • docs/security-review-nodes.json — Ejemplo con múltiples puntos de decisión
  • docs/self-nodes.json — Ejemplo mínimo (9 nodos)

Lista de autoverificación

  • El nodo de entrada type=entry está en la parte superior
  • Cada arista tiene el campo side (bottom/left/right)
  • Las aristas side=left/right de un rombo de decisión son ramas laterales (misma capa, línea horizontal)
  • Las aristas side=left/right de un rectángulo normal son bifurcaciones (capa inferior, línea poligonal ortogonal)
  • Un nodo, un role; los pasos mixtos ya se han dividido
  • Los puntos de convergencia (múltiples aristas entrantes al mismo nodo) no requieren tratamiento especial, el script los reconoce automáticamente
  • Los bucles se declaran en el campo loops, no se repiten en edges
  • Todos los id de nodo en from/to de edges están referenciados (sin nodos aislados)
  • Leyenda se deja vacía []

Preguntas frecuentes

P: ¿Qué hago si los nodos se superponen? Verifica si falta el campo side. Las ramas de decisión deben tener side (left/right/bottom); de lo contrario, los dos nodos destino heredarían la misma posición.

P: ¿El bucle en línea discontinua no se dibuja? El bucle se declara en el array loops (no en edges), y from/to no deben repetirse en edges. El campo path debe ser "left_edge".

P: ¿El script reporta un error de formato JSON? JSON no admite comentarios ni comillas simples. Problemas comunes: falta de coma, coma extra (al final de un array), comillas simples.

Para más preguntas, consulta docs/FAQ.md.

Skills relacionados