Communitygithub.com

khollingworth/d2-diagram-skill

Plugin para Claude Code que genera diagramas de arquitectura profesionales con D2 (TALA/ELK) y un bucle de revisión automática.

¿Qué es d2-diagram-skill?

Esta habilidad convierte a Claude Code en un asistente de diagramación profesional utilizando el lenguaje D2. Está diseñada para desarrolladores que necesitan crear diagramas de arquitectura de software, secuencias, modelos de datos o diagramas C4 de alta calidad de forma iterativa y precisa. La habilidad integra un flujo de trabajo completo: desde la verificación de herramientas (D2, TALA, ELK), planificación del mensaje y tipo de diagrama, escritura del código fuente D2 con reglas que evitan errores comunes, renderizado a SVG/PNG mediante un script optimizado que selecciona el motor de diseño adecuado, hasta un proceso de revisión visual que fuerza al asistente a inspeccionar el resultado con el usuario y corregir problemas de diseño automáticamente. Soporta los motores de diseño TALA (para diagramas de arquitectura), ELK (fallback automático) y dagre. Incluye referencias detalladas sobre sintaxis D2, motores de diseño y patrones de diagramas. Funciona exclusivamente dentro de Claude Code, aprovechando su capacidad de leer archivos y ejecutar scripts. Su principal ventaja es que no solo genera el diagrama, sino que lo revisa y lo corrige iterativamente hasta que está listo para producción.

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

Preguntar en tu IA favorita

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

Documentación

Diagramas D2

Escribe código fuente D2, transfórmalo a SVG y luego mira el resultado y arregla lo que veas — en un bucle, hasta que el diagrama esté listo para enviar. Un diagrama que no has visto es un diagrama que no has terminado.

Archivos de referencia — cargar bajo demanda

ArchivoCuándo leerlo
references/d2-language.mdAl escribir cualquier D2 no trivial — sintaxis, formas, contenedores, clases, variables, y los peligros silenciosos que compilan bien pero se renderizan mal
references/layout-engines.mdAl elegir o depurar el diseño: TALA vs ELK vs dagre, licencias, semillas, diferencias de comportamiento por motor
references/diagram-patterns.mdAl seleccionar un tipo y estructura de diagrama — arquitectura, secuencia, ERD, cuadrícula, C4; temas, iconos, modo oscuro, incrustación en GitHub

Paso 0 — Verificación de herramientas

Ejecutar una vez por sesión antes del primer renderizado (scripts/ aquí significa el propio directorio de esta skill — en Claude Code ${CLAUDE_SKILL_DIR} resuelve a él):

bash "${CLAUDE_SKILL_DIR}/scripts/setup.sh" --check-only
  • d2: ok → continuar.
  • d2: MISSING → informar al usuario, luego ejecutar scripts/setup.sh (sin banderas) para instalar mediante Homebrew donde esté disponible, o mostrarle los comandos de instalación impresos. No renderices a ciegas — nada más en esta skill funciona sin d2.
  • tala: not installed o unlicensed → está bien. ELK es la alternativa automática y produce buenos diseños. Menciona TALA solo una vez si el diagrama es un diagrama de arquitectura de software (donde TALA es significativamente mejor) y el usuario parece interesado en la calidad del resultado; nunca insistas.

Paso 1 — Planificar antes de escribir

Decide tres cosas primero:

  1. El mensaje. ¿Qué debería concluir un lector en cinco segundos? Un diagrama argumenta algo — "las solicitudes se ramifican aquí", "este servicio es el cuello de botella", "estas dos rutas nunca se tocan". Si no puedes enunciar el argumento, estás a punto de dibujar una colección de cajas etiquetadas.
  2. El tipo. Arquitectura/topología → formas y contenedores simples. Interacción en el tiempo → sequence_diagram. Modelo de datos → sql_table. Alineación rígida (matriz, panel de control, con muchas leyendas) → cuadrícula. Consulta references/diagram-patterns.md para orientación estructural por tipo.
  3. La escala. 5–15 nodos se lee bien; 15–25 necesita contenedores para agrupar; más allá de ~25, divide en múltiples diagramas o usa layers. Prefiere un segundo diagrama antes que un mural.

Para diagramas técnicos de sistemas reales, usa nombres reales — nombres de servicios reales, nombres de tablas reales, nombres de eventos reales del código base o la descripción del usuario. Busca en el código si está disponible. Servicio A -> Servicio B desperdicia la confianza del lector.

Paso 2 — Escribir el D2

Lee references/d2-language.md antes de escribir cualquier cosa más allá de un diagrama trivial. Las reglas que evitan el 90% de las salidas rotas:

  • Conecta claves, no etiquetas. Después de api: API Gateway, escribe api -> db, nunca API Gateway -> db — esto último crea silenciosamente una forma duplicada.
  • Pon entre comillas las etiquetas que contengan # o ; — un # sin comillas inicia un comentario en medio de la etiqueta y un ; sin comillas divide la línea en dos formas, y ambos compilan sin error. Poner entre comillas cualquier etiqueta con puntuación es el hábito seguro.
  • Aplica estilo a través de classes:, no con estilos por nodo — una definición, aplicada con class:. Evita style.fill en nodos individuales; los rellenos codificados luchan contra el tema y rompen el renderizado en modo oscuro.
  • Establece direction: right para la mayoría de los flujos de arquitectura (de izquierda a derecha se lee de forma natural). Todos los motores respetan la dirección raíz; TALA además admite direction por contenedor.
  • Guarda el código fuente como {nombre}.d2 junto a donde pertenece la salida (por defecto: ./diagrams/ en el proyecto).

Paso 3 — Renderizar

Renderiza siempre a través del script incluido — selecciona el motor de diseño, protege contra salidas con marca de agua y valida primero:

bash "${CLAUDE_SKILL_DIR}/scripts/render.sh" --png input.d2 output.svg
  • --png también escribe output.png — lo necesitas para el Paso 4 (la herramienta Read ve imágenes rasterizadas, no SVG).
  • El script imprime engine: (lo que realmente renderizó) y fallback: (por qué, si TALA no se usó). Transmite una nota de una línea al usuario solo cuando preguntó sobre motores o quería TALA explícitamente.
  • Banderas útiles: --theme N, --dark-theme 200 (el SVG responde al esquema de color del lector), --sketch, --pad N, --seed N (reintento de TALA), --engine tala|elk|dagre (forzar), --allow-watermark (evaluación de TALA).
  • En caso de fallo, el script imprime el error de compilación de d2 con archivo:línea:col — corrige el código fuente en esa ubicación y vuelve a ejecutar. Si el error no está claro, consulta la sección de peligros de references/d2-language.md.

Nunca renderices la salida de TALA para entrega con una marca de agua a menos que el usuario la acepte explícitamente; el script lo impone al recurrir a ELK.

Paso 4 — Míralo, luego arréglalo (no opcional)

El código fuente .d2 no dice nada sobre cómo quedó realmente el renderizado — el diseño es decisión del motor, no tuya. Abre el PNG con la herramienta Read y examínalo en dos pasadas:

Pasada 1 — ¿transmite el argumento?

  • ¿Entra el ojo donde comienza la historia y sale donde termina?
  • ¿Es consistente la dirección del flujo (no retrocede ni se lee de abajo arriba involuntariamente)?
  • ¿Las agrupaciones de contenedores coinciden con las agrupaciones lógicas que planificaste?
  • ¿El elemento más importante es visualmente prominente, o está enterrado?

Pasada 2 — defectos de diseño (los motores de diseño automático producen todos estos):

  • Etiquetas de borde que se han alejado mucho de su borde, o son ambiguas sobre qué borde describen
  • Bordes que se superponen en recorridos paralelos, cruzan a través de nodos o contenedores, o toman desvíos absurdos
  • Texto truncado o colisionando con formas/iconos
  • Una región apretada mientras otra está vacía; un contenedor vastamente más grande que su contenido
  • Nodo tan pequeño que su etiqueta domina, o tamaños de nodo salvajemente inconsistentes
  • Cualquier cosa que tendrías que explicar con disculpas si se lo mostraras al usuario

Arregla con las palancas de D2, no moviendo píxeles (el diseño automático significa que cambias entradas, no coordenadas): cambia direction; agrupa o reagrupa con contenedores; acorta las etiquetas de borde (las etiquetas largas se desvían peor en ELK); fusiona bordes paralelos en un solo borde etiquetado; mueve leyendas/títulos fuera del flujo con near; divide un diagrama sobrecargado en layers; ajusta --pad; en TALA, reintenta con --seed N (prueba 2–3 semillas — los diseños varían significativamente); como último recurso, cambia de motor para la forma de este diagrama (consulta references/layout-engines.md).

Vuelve a renderizar, vuelve a revisar, repite. Presupuesta de dos a cuatro ciclos de renderizado — un primer renderizado que sobreviva a ambas pasadas es raro. Terminado significa: ambas pasadas limpias, y nada en la imagen necesita una disculpa o una explicación.

Paso 5 — Entregar

  • Confirma las rutas finales del .svg (y del código fuente .d2) — da siempre ambos al usuario; el .d2 es el artefacto editable.
  • Si el diagrama vivirá en un README de GitHub o sitio de documentación, ofrece una variante compatible con modo oscuro: vuelve a renderizar con --dark-theme 200 (un solo SVG que sigue el esquema de color del lector). Los patrones para incrustación PNG/<picture> están en references/diagram-patterns.md.
  • Si el usuario va a iterar sobre el diagrama por sí mismo, menciona d2 --watch input.d2 para vista previa en vivo en un navegador.

Solución de problemas

SíntomaCausa / solución
d2: command not foundEjecuta scripts/setup.sh (instalación guiada)
D2_LAYOUT "tala" is not bundledTALA no está en PATH — el script recurre automáticamente a ELK; instala TALA solo si el usuario lo desea
Texto UNLICENSED en la salidaTALA sin licencia — el script de renderizado vuelve a renderizar con ELK automáticamente; una clave de licencia va en TSTRUCT_TOKEN o ~/.config/tstruct/auth.json
La exportación PNG falla, SVG bienEl primer renderizado PNG descarga un navegador sin cabeza; reintenta una vez. Si está bloqueado (sin conexión/CI), entrega SVG e inspecciónalo convirtiendo con cualquier rasterizador SVG disponible
Error de compilación bajo --layout tala que ELK renderiza bienDesfase de versión d2/TALA — el script recurre automáticamente; sugiere actualizar ambos
Faltan iconos en la salidaLa URL del icono devolvió 403/404 — elimina el icono o elige otro de icons.terrastruct.com; prueba los iconos al principio

Skills relacionados