diagram-design: la skill que dibuja tu arquitectura

Pídele a tu agente un diagrama de la arquitectura de tu proyecto.

Ya lo tienes delante, ¿verdad?

Cajas con esquinas redondeadas, seis colores pastel, fondo oscuro con brillitos cian, flechas en diagonal que se cruzan como los cables que hay ahora mismo debajo de tu mesa. Y tipografía monoespaciada en absolutamente todo, porque eso es lo que hace “que parezca de programadores”.

Lo pegas en el README y te da un poco de vergüenza.

diagram-design es una skill open source con licencia MIT, publicada por Cathryn Lavery, que ataca ese problema por dos frentes: le da al agente 27 tipos de diagrama con reglas de maquetación estrictas, y le enseña a usar los colores y las tipografías de tu propia web.

Este post va de lo práctico: cómo dejarla funcionando y qué sale por el otro lado.

• La puesta en marcha completa, paso a paso, en Claude Code, Codex y Pi
• El onboarding de marca: darle una URL y que todos tus diagramas hereden tu paleta
• Dos ejemplos reales de principio a fin, con el prompt exacto que usé
• Cómo redibujar diagramas de draw.io o Mermaid que ya tengas
• Los límites con los que vas a chocar y cuándo mejor no dibujar nada

Encaja en la misma familia que las skills que aportan metodología en vez de capacidad: no le enseñan al agente a hacer algo nuevo, le enseñan a hacerlo con criterio. Y si vienes de la skill que convierte las salidas del agente en páginas HTML con diagramas Mermaid interactivos, el terreno es parecido pero el objetivo no. Aquello resuelve el ASCII art en el terminal. Esto resuelve que lo que publiques no desentone con el resto de tu sitio.

Qué obtienes al final ¶

Antes de instalar nada, conviene saber qué te va a devolver.

Un único fichero .html autocontenido: CSS embebido, SVG en línea, sin build, sin JavaScript, sin imágenes externas. Doble clic y se abre en cualquier navegador. La única petición de red que hace es a Google Fonts.

Nada de servidores, nada de npm install, nada de abrir Figma. Y como es SVG, se ve nítido a cualquier tamaño y lo puedes exportar a PNG cuando lo necesites para una presentación.

Guía interactiva gratis

Antes de instalar skills, ten claro cómo funciona tu agente

La parada 14 del curso explica qué es una skill y por qué es un prompt supervitaminado, después de haber pasado por el agente, el modo plan y la ventana de contexto. Son 17 paradas y eliges tú el camino.

Entra en el curso gratis →

Puesta en marcha en cinco pasos ¶

1. Instala el plugin ¶

En Claude Code son dos líneas: añades el marketplace y luego instalas el plugin.

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

En Codex el flujo es el mismo desde la terminal:

codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design

Y en Pi va por URL directa del repositorio:

pi install https://github.com/cathrynlavery/diagram-design

Si nunca has instalado una skill y todo esto te suena raro, tenemos una guía completa de Agent Skills donde explico el formato SKILL.md, el frontmatter YAML y cómo el agente decide cargarla o no. Y si tu agente principal es Codex, esta encaja bien al lado de las skills que mejor rinden en Codex que ya repasamos en su día.

2. Activa la actualización automática ¶

Este paso se salta todo el mundo y luego se queda con una versión de hace tres meses.

Claude Code desactiva por defecto la actualización automática de marketplaces de terceros. Entra en /plugin, ve a Marketplaces, selecciona diagram-design y activa Enable auto-update. A partir de ahí refresca en segundo plano tras arrancar. Cuando te lo pida, ejecuta /reload-plugins o deja que la siguiente sesión cargue la actualización.

Codex refresca sus marketplaces de Git al arrancar. Si quieres el cambio ya, codex plugin marketplace upgrade diagram-design y sesión nueva.

Pi no tiene refresco automático de paquetes. Ahí toca pi update --extensions a mano.

3. Decide si quieres una instalación editable ¶

Aquí hay una bifurcación que conviene tomar con la cabeza fría.

La instalación gestionada es cómoda, pero las actualizaciones del paquete pueden pisar los cambios que hagas en references/style-guide.md. Y ese fichero es justo donde vive tu marca.

Si vas a personalizar el sistema de estilos —y vas a hacerlo—, clona el repositorio y enlaza la carpeta interna:

git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design

# Claude Code: enlaza la skill que vive dentro del repositorio
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

⚠️ Si te saltas este paso y luego personalizas la guía de estilo, una actualización puede devolverte a la paleta de fábrica sin avisar. No es catastrófico —son treinta segundos de rehacerlo—, pero descubrirlo cuando ya has generado seis diagramas para un post da rabia.

4. Pasa el onboarding de marca ¶

Sin tocar nada, los diagramas salen en una paleta editorial neutra: papel blanco humo #f5f5f5, tinta negro azabache #2d3142, acento mandarina #eb6c36 y grises azulados para las flechas. Se pueden publicar tal cual.

Pero el onboarding cuesta unos 60 segundos y cambia el resultado por completo. Le das una URL y la skill hace esto:

1. Descarga la home (y dos o tres páginas más si merece la pena mezclar señales de color)
2. Extrae la paleta dominante y la pila de fuentes del CSS renderizado
3. Mapea lo detectado a roles semánticos: paper, ink, muted, accent, link
4. Verifica el contraste WCAG AA de ink sobre paper a tamaños de diagrama (9–12 px)
5. Te propone un diff sobre style-guide.md
6. Lo escribe cuando das el visto bueno

La invocación es tan simple como pedírselo con lenguaje natural: “aplica la marca de webreactiva.com a la guía de estilo de la skill”.

La correspondencia entre lo que hay en tu web y lo que acaba en el diagrama es directa:

Nunca se habla de hexadecimales en las referencias internas. Se habla de accent, no de #eb6c36. Por eso cambiar de marca es cambiar una tabla y que 27 tipos de diagrama hereden el cambio de golpe.

Si te suena el mecanismo es porque la skill frontend-design hace algo parecido con las interfaces: leer tu web para sacar la identidad visual antes de generar nada. La diferencia es que allí el resultado es una interfaz concreta y aquí es un sistema de tokens que sobrevive a todos los diagramas que hagas después.

Lo probé con Web Reactiva y el resultado fue este: terracota #e56a54 como accent, lila #9678d3 como link, base-200 #f2f2f2 como paper y base-content #1f2937 como ink. El amarillo mostaza #fed757 se quedó reservado, sin rol semántico asignado, porque en un diagrama compite con el terracota y no gana ninguno de los dos.

Dos cosas que no venían en el flujo automático y pedí a mano: las esquinas a radio 0, que es lo que usa el CSS de la web, y la revisión de la tipografía. La fuente de marca es SculpinWebRegular y no está en Google Fonts, así que propuso Space Grotesk como sustituta pública.

🔑 Y me lo dijo en la cara. Al terminar el onboarding se emite un recibo de fidelidad: URLs muestreadas, roles de color exactos, familias y pesos tipográficos, URLs de origen de las fuentes y cualquier fallback que haya usado. No te cambia tu tipografía por una genérica del sistema y se queda callada.

5. Verifica la salida ¶

La skill instalada trae su propio comprobador. Se lo pasas al fichero generado:

python3 <skill-dir>/scripts/self_check.py mi-diagrama.html

Devuelve OK o te dice qué falla: el contrato de SVG accesible, la seguridad de fichero único y los fundamentos de animación cuando la hay. Merece la pena ejecutarlo antes de mirar el diagrama, no después.

El first-run gate: la pregunta que te va a hacer ¶

La primera vez que pidas un diagrama en un proyecto nuevo, la skill se planta antes de dibujar.

Comprueba si style-guide.md sigue con los valores de fábrica y, si es así, pregunta si quieres personalizarlo: sacarlo de una URL, de otra skill instalada, de una carpeta local con tokens, pegarlos a mano o tirar con el estilo por defecto.

Es deliberado. Evita que se cuelen diagramas con la paleta genérica en un proyecto que tiene identidad propia. Una vez has contestado, no vuelve a preguntar.

Y hay otra pausa más, esta antes de cada diagrama: el agente tiene que decir en voz alta qué tipo visual ha elegido, qué preset de tamaño va a usar y qué va a recortar por presupuesto de complejidad. Te da la oportunidad de redirigirlo antes de que gaste tokens en algo que no querías.

Ejemplo 1: el ecosistema de contenidos en un solo prompt ¶

Vamos con lo que se puede lograr. Este fue el prompt entero:

Hazme un diagrama con diagram-design de webreactiva.com

Sin especificar tipo, ni paleta, ni número de nodos. Antes de dibujar me hizo dos preguntas: qué debía mostrar el diagrama y si aplicaba la marca a la guía de estilo. Contesté “ecosistema de contenidos” y “sí, marca WR”.

A partir de ahí eligió el tipo Loop: un flywheel con estaciones alrededor de un hub de estado compartido. Yo no sabía que ese tipo existía.

El resultado tiene seis estaciones en anillo horario —podcast, newsletter, blog y recursos, masterclases, suscripción, feedback y vuelta al podcast— con un hub central de Comunidad. Los radios que van de cada estación al hub son discontinuos: representan lo que cada pieza deposita ahí, no el flujo principal de contenido.

Y una sola caja en terracota: Suscripción.

Eso último es lo que me convenció del enfoque. Yo habría marcado cuatro cosas como importantes. El diagrama es mejor con una.

Tiempo total, incluida la aplicación de la marca a la guía de estilo: poco más de tres minutos.

Lo que hay que llevarse de este ejemplo: para conceptos abstractos —un modelo de negocio, un flujo de contenidos, un ciclo de producto— no hace falta que sepas qué tipo de diagrama pedir. Describe el sistema y deja que elija. Lo que sí conviene es contestar bien a la pregunta de qué debe mostrar, porque “webreactiva.com” a secas admite un funnel de descubrimiento a premium tanto como un bucle de comunidad. Son dos diagramas distintos y cuentan historias distintas.

Ejemplo 2: la arquitectura de un sistema de suscripción leída del código ¶

El segundo caso es donde una skill de diagramas se gana el sueldo o se cae con todo el equipo.

Le pedí la arquitectura del sistema de suscripción de un SaaS mío en Laravel, apuntando a la carpeta del proyecto y con una restricción: que ignorase la parte de equipos.

Lo que hizo antes de dibujar nada:

1. Listar la estructura del proyecto y leer el composer.json
2. Buscar por grep los ficheros que mencionan suscripciones en app, routes, config y las migraciones
3. Recorrer la carpeta de features de suscripciones entera: comandos, controladores, servicios, listeners, providers
4. Medir con wc -l qué ficheros merecían lectura completa y cuáles se podían despachar
5. Leer el service provider y el contexto de la ruta del webhook

Y solo entonces anunciar el plan: tipo Architecture, 8 nodos, 10 conexiones, foco en el controlador del webhook.

El diagrama final se lee en tres bandas. Arriba la compra: el frontend con React e Inertia manda un price_id al controlador de checkout, que decide entre formulario embebido y redirección y entre usuario autenticado o invitado, delega en un servicio que llama a Cashier, y este abre sesión en Stripe. La interfaz de pago vuelve al navegador por una flecha en lila, que es el color reservado para llamadas externas.

En el centro, el aprovisionamiento, con el controlador del webhook en terracota como único foco. Abajo, el acceso: el middleware consultando el estado de suscripción contra base de datos.

Todo eso está bien. Pero lo más valioso no fue el dibujo.

Fue el informe de lo que dejó fuera, con el motivo de cada descarte:

• Equipos, porque se lo pedí. Pero con un aviso por su cuenta: el método que decide si alguien tiene acceso incluye una comprobación de pertenencia a equipo activo, así que el gate real tiene una cuarta fuente de verdad que el diagrama no dibuja.
• Los emails de bienvenida, cancelación y pago fallido, que quedaron mencionados en la nota bajo el título en lugar de ocupar un nodo del presupuesto.
• Los casos límite del webhook: cliente de Stripe duplicado, reintento por violación de restricción única, activación manual. Sugirió un flowchart aparte para eso.

Ese primer punto es exactamente lo que quieres de una herramienta que dibuja tu sistema. No solo lo que enseña: el aviso de que está simplificando algo que a ti te importa.

Tiempo total, con toda la exploración del código incluida: poco más de cinco minutos.

🛡️ Un diagrama generado a partir del código envejece igual que el código. Si lo dibujas una vez y lo pegas en la wiki, en tres meses miente. Regenerarlo es barato —el prompt cabe en una línea— así que trátalo como artefacto derivado, no como documentación que se mantiene a mano.

De usar skills a fabricarlas

Y si en vez de instalar la skill de otro, escribes la tuya

Verás cómo se monta un SKILL.md con referencias y scripts, igual que hace diagram-design con su guía de estilo, y funciona en Claude Code, Codex, OpenCode y 25+ agentes más.

Destripar el método →

Plantillas SKILL.md descargables incluidas

Qué más puedes pedirle ¶

Los dos ejemplos anteriores usan dos tipos. Hay 27. Estos son los que más juego dan en el día a día de un proyecto de software:

• Architecture para componentes y conexiones de un sistema
• Sequence para mensajes ordenados en el tiempo entre actores
• State machine para estados, transiciones y guardas
• ER para entidades, campos y relaciones
• Flowchart para lógica de decisión con ramas
• Swimlane para procesos con traspasos entre equipos
• Quadrant para priorizar por impacto y esfuerzo
• Timeline y Gantt para fases y planificación
• Layer stack para capas de abstracción o controles de seguridad

Cuando el comportamiento es lo que carga el significado —colas, cumplimiento de políticas, fronteras de confianza, riesgo residual— la skill enruta primero por patrón semántico y después elige el tipo visual que le sirve de maquetación. Son siete patrones: cuellos de botella con profundidad de cola, etapas repetidas con huecos fijos, entrada suelta que se convierte en artefacto estructurado, trazas de reglas emparejadas, caminos de despliegue permitidos y prohibidos, catálogos de controles y capas de defensa compensatorias.

En la práctica esto significa que no tienes que traducir tu problema a un tipo de diagrama. Describe el problema y deja que él haga la traducción.

Redibujar lo que ya tienes ¶

Si arrastras diagramas de draw.io o bloques Mermaid en los README, la skill no los convierte. Los redibuja.

Lee .drawio, .drawio.xml, .drawio.png con el diagrama embebido y .drawio.svg, incluidas las cargas comprimidas que en un editor de texto parecen basura en base64. Para Mermaid acepta .mmd, .mermaid y uno o varios bloques con la valla mermaid dentro de un Markdown.

Un detalle de seguridad que conviene subrayar: solo analiza texto. No renderiza, no ejecuta JavaScript, no abre navegador, no hace peticiones de red y no sigue destinos de clic. Cada etiqueta y campo de metadatos del origen se trata como dato no confiable, nunca como instrucción.

Lo que no sobrevive: coordenadas del origen, su paleta, sus fuentes, el espagueti de conectores diagonales de draw.io y el layout automático de Mermaid. Lo que sí: componentes, relaciones, agrupaciones y dirección.

El objetivo no es la conversión, es ajustar la salida al sitio donde va. Para eso hay cuatro diales:

El dial de tamaño tiene una consecuencia que se pasa por alto siempre: una diapositiva proyectada recibe nombres de nodo a 16 px, no a 12 px. Escalar el lienzo sin escalar el texto es la receta clásica del diagrama ilegible en una sala de reuniones.

El de audiencia me gustó especialmente. El mismo nodo se escribe Auth Service / JWT · RS256 · :8443 para ingeniería, Auth Service / token check para audiencia mixta y Sign-in para dirección. Cambia la redacción, no el recuento de cajas.

/diagram-design:import platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:import-mermaid README.md --diagram=all

Cada importación termina con un libro mayor de fidelidad: qué se fusionó, qué se colapsó y qué se descartó. Tú conoces el origen y lo ibas a notar de todas formas, así que mejor que te lo cuente la herramienta.

Exportar para el blog o para una presentación ¶

La exportación es manual a propósito: la skill nunca genera ficheros de export sin que se los pidas.

/diagram-design:export mi-diagrama.html --png-only --scale=3

El SVG extrae el nodo <svg> e inyecta las Google Fonts para que se vea bien fuera del navegador, en Figma o en Illustrator. El PNG rasteriza con Playwright a 2× por defecto, lo que implica una instalación previa que solo se hace una vez:

pip install playwright && playwright install chromium

Ambos formatos entregan solo el diagrama. Las tarjetas editoriales y las cabeceras de la variante completa se quedan fuera por diseño. Si quieres capturar la maqueta entera, imprime a PDF desde el navegador.

Los límites con los que vas a chocar ¶

Toca la parte menos vendedora, que es la que decide si esto encaja contigo.

La calidad viene de la restricción, y la restricción molesta. Vas a pedir un diagrama con doce servicios y te va a devolver ocho con una nota explicando qué colapsó. El presupuesto es firme: 9 nodos máximo, 12 flechas, y el color de acento en 2 elementos como mucho.

Esa última regla es la que más cuesta aceptar y la que más mejora el resultado. Si pones el acento en cinco nodos, ya no señala nada: has borrado la señal con la propia señal.

También hay casos en los que directamente no deberías dibujar. La documentación lo dice sin rodeos:

• Diagramas rápidos en Unicode para un tuit o una salida de terminal: para eso hay skills de tipo wiretext
• Listas de cosas: una tabla o unas viñetas
• Comparativas antes/después: una tabla
• Diagramas de una sola forma: si es una caja con una etiqueta, escribe la frase

La pregunta que hay que hacerse antes de pedir nada cabe en una línea: ¿el lector aprendería más de esto que de un párrafo bien escrito? Si la respuesta es no, no dibujes.

Y si lo que necesitas es un mapa exhaustivo de infraestructura para una auditoría, esta no es tu herramienta. El modo faithful sube el techo a 24 nodos, pero exige zonificar el layout y, por encima de ahí, partir en dos diagramas.

Cómo lo he metido en mi flujo ¶

Tres usos que ya tengo rodados, por si te sirven de atajo:

1. Arquitectura al abrir un proyecto viejo. Antes de tocar nada, pido el diagrama del subsistema que voy a modificar. El informe de lo que deja fuera me sirve de checklist de lo que todavía no entiendo.
2. Ilustraciones para posts. Con la marca ya aplicada, el diagrama sale con los colores del blog. Exporto a SVG y queda nítido en cualquier pantalla.
3. Redibujar diagramas heredados. Todo README con un bloque Mermaid es candidato a un import-mermaid con --size=doc-inline.

Instálala, pásale el onboarding con la URL de tu web y pídele un diagrama de lo que estés tocando esta semana. Fíjate en una cosa concreta cuando termine: qué te dice que ha quitado.

Ahí es donde vas a aprender algo de tu propio sistema.

Preguntas frecuentes ¶

¿Cómo se instala diagram-design en Claude Code?

Con dos comandos: /plugin marketplace add cathrynlavery/diagram-design y /plugin install diagram-design@diagram-design. Después conviene activar la actualización automática desde /plugin → Marketplaces, porque Claude Code la desactiva por defecto en marketplaces de terceros.

¿Funciona en agentes que no sean Claude Code?

Sí. Codex la instala con codex plugin marketplace add y codex plugin add, y Pi con pi install apuntando a la URL del repositorio. La skill vive en la carpeta estándar skills/ del repositorio, así que cualquier agente compatible con el formato Agent Skills puede leerla.

¿Cómo hago que los diagramas usen los colores de mi web?

Pídele el onboarding indicando tu URL. La skill descarga la página, extrae paleta y tipografía, verifica el contraste WCAG AA, te propone un diff y escribe los valores en references/style-guide.md. Todos los diagramas heredan ese skin porque las referencias internas usan roles semánticos y no hexadecimales.

¿Y si mi tipografía de marca no está en Google Fonts?

Propone una sustituta pública y te lo dice en el recibo de fidelidad que emite al terminar, junto con las URLs muestreadas y los roles de color exactos. No sustituye la fuente en silencio por una genérica del sistema.

¿Puede leer mi código y dibujar la arquitectura real?

Sí, si tu agente tiene acceso al repositorio. En mi caso recorrió una carpeta de features de Laravel, leyó controladores, servicios, listeners y providers, y dibujó a partir de eso en lugar de fiarse de la documentación del proyecto. Al terminar reporta qué componentes dejó fuera y por qué.

¿Cuánto tarda en generar un diagrama?

En mis dos pruebas, poco más de tres minutos para un diagrama conceptual con onboarding de marca incluido, y algo más de cinco para una arquitectura que requirió explorar el código fuente antes de dibujar.

¿Qué pasa si mi diagrama necesita más de 9 nodos?

El presupuesto de complejidad fuerza a partirlo en un diagrama de visión general y otro de detalle. La única excepción documentada es el modo faithful en importaciones, que sube el techo a 24 nodos con la condición de zonificar el layout.

¿Qué diferencia hay entre diagram-design y Mermaid?

Mermaid es un lenguaje de marcado que renderiza diagramas con layout automático. diagram-design produce SVG editorial con maquetación decidida caso a caso, presupuesto de complejidad y tokens de marca. De hecho puede leer tus bloques Mermaid y redibujarlos descartando el layout del renderizador.

¿Los diagramas son accesibles para lectores de pantalla?

Sí, por defecto. Cada SVG lleva role="img", un aria-labelledby que resuelve a <title> y <desc>, el título como primer hijo del elemento y los identificadores prefijados por diagrama y variante para evitar colisiones al incrustar varios en la misma página.

¿Cómo compruebo que el diagrama generado está bien?

Ejecuta el comprobador que viene con la skill: python3 <skill-dir>/scripts/self_check.py fichero.html. Verifica el contrato de SVG accesible, la seguridad de fichero único y los fundamentos de animación cuando la hay. Si todo está correcto, imprime OK.

Fuentes ¶

• Cathryn Lavery, “Diagram Design” (repositorio en GitHub)
• Galería en vivo con los 27 tipos y sus tres variantes
• SKILL.md: filosofía, guía de selección y checklist de salida
• Referencia de onboarding: de una URL a los tokens de marca
• Especificación de salida: formato, tamaño, detalle y audiencia
• Procedimiento de exportación a SVG y PNG

🧨 Última oprtunidad para recibir la dinamita que mereces sobre programación con IA el próximo domingo: Suscríbete gratis a Web Reactiva en https://webreactiva.com/newsletter