2.088 estrellas en GitHub y 1.300 instalaciones en skills.sh en su primera semana. stack-diagram se publicó el 1 de noviembre de 2026 con una promesa sencilla: describes tu stack en una frase y el agente devuelve un diagrama de arquitectura con los logos oficiales de cada tecnología. Funciona con Claude Code, Codex, Cursor y el resto de agentes compatibles con Agent Skills, y tiene licencia MIT.
Qué hace cuando le pides un diagrama
La skill se activa en cuanto pides un diagrama de arquitectura, de infraestructura o de topología de servicios, aunque no digas en qué formato lo quieres. A partir de ahí el SKILL.md marca siete pasos:
- Decide el contenido: un nodo por tecnología (nombre y un rol corto, como
http server), grupos para lo que comparte runtime, proveedor o repositorio, y tres tipos de flecha: el flujo principal, conexiones internas y relaciones de despliegue o CI (discontinuas). - Descarga los iconos con
fetch_icons.py: primero svgl, después devicon y gilbarbara/logos. AWS, Google Cloud y Azure usan los paquetes oficiales de cada proveedor, y si un servicio no está, el script falla en vez de tirar de una copia de terceros. Los logos nunca se recolorean. - Planifica las coordenadas con una referencia de geometría cuya regla principal es que ninguna flecha atraviese el texto de un nodo.
- Construye un HTML autocontenido con
build.py, con logos y fuentes incrustados. - Renderiza un PNG y lo revisa con Playwright antes de entregarlo: flechas sobre etiquetas, iconos blancos sobre fondo blanco, nodos que se salen de su grupo.
- Entrega HTML (por defecto), PNG en tema claro y oscuro, un componente React sin dependencias o un artifact.
- Ofrece publicarlo en una galería pública, solo una vez por conversación.
Lo que más me ha gustado está en los detalles de proveedor. En AWS dibuja subredes públicas y privadas dentro de la VPC cuando puede deducirlas; en Google Cloud pone la región dentro de la VPC y no al revés, porque la VPC es global; en Azure la VNet va dentro de su región y App Service queda fuera salvo en un App Service Environment. Son las correcciones que haría cualquiera que conozca esas nubes al revisar un diagrama.
Cómo instalarla y usarla
npx skills add caru-ini/stack-diagramEn las apps de Claude se sube como skill el stack-diagram.zip de la última release. Después basta con describir el sistema; el ejemplo del README es:
Diagram our stack: Next.js and a Hono API on Vercel. Postgres on Neon, auth with Clerk, payments with Stripe. GitHub Actions deploys.
Los scripts de iconos, construcción y publicación solo usan la librería estándar de Python 3.9+. Para el PNG hace falta Playwright con Chromium, y el comando que propone la propia skill es este:
pip install playwright && python3 -m playwright install --with-deps chromium--with-deps instala paquetes del sistema operativo, así que en un portátil corporativo o en un runner compartido es mejor quitar esa opción y resolver las librerías de Chromium por tu cuenta. Sin PNG la skill sigue sirviendo, pero se salta el paso en el que se revisa a sí misma.
Riesgos y límites
- Red: necesita salida a svgl.app, raw.githubusercontent.com, cdn.jsdelivr.net, los dominios de iconos de AWS, Google y Microsoft, y la web o el repositorio de cualquier marca que no esté en esos catálogos. En un entorno con lista blanca de salida hay que abrirlos todos.
- La galería pública:
share.pysube los dos PNG, un título, la lista de tecnologías y un nombre visible astacks.caru.moe. La skill obliga a enseñar todo antes, a avisar de nombres de host, IP o servicios internos y a pedir dos confirmaciones explícitas. Aun así, un diagrama de arquitectura interna es información sensible: la respuesta segura en una empresa es no. La clave para borrar el post se guarda en~/.config/stack-diagram/gallery.json, y el destino se puede cambiar con la variableSTACK_DIAGRAM_GALLERY. - Marcas: los logos no van en el repositorio, se descargan al construir, y el README recuerda que Microsoft solo permite sus iconos en diagramas de arquitectura, formación y documentación.
- Madurez: el repositorio tiene una semana y su último push es del 3 de noviembre de 2026. Con un proyecto tan joven, lee el
SKILL.mdy los scripts de la versión que instales: lo descrito aquí puede cambiar en la siguiente.
stack-diagram frente a diagrams
La referencia para dibujar arquitecturas cloud sin herramientas de diseño es diagrams (mingrammer/diagrams), la librería de "diagram as code" en Python.
| stack-diagram | diagrams | |
|---|---|---|
| Enfoque | Describes el sistema en lenguaje natural y el agente maqueta | Escribes el diagrama en código Python |
| Motor | HTML con coordenadas fijas, PNG con Chromium | Graphviz |
| Proveedores | AWS, Google Cloud y Azure con iconos oficiales, más logos de cualquier marca | AWS, Azure, GCP, Kubernetes, Alibaba Cloud, Oracle Cloud, on-premises y SaaS |
| Licencia | MIT | MIT |
| Madurez | Una semana, 2.088 estrellas | 42.796 estrellas, push del 2 de noviembre de 2026 |
diagrams gana cuando el diagrama tiene que vivir en el repositorio: el código Python se revisa en un PR y el resultado es reproducible. stack-diagram gana en acabado y en rapidez para un diagrama de una presentación, un README o un documento de diseño, y en algo que Graphviz no resuelve bien: controlar dónde va cada flecha. Para documentación que cambia con el sistema seguiría con diagrams; para explicar un stack a otro equipo en cinco minutos, probaría stack-diagram.