Casi 58.000 estrellas en GitHub y una regla de diseño que cabe en una frase: "la mejor decisión suele ser borrar". diagram-design, de Cathryn Lavery, es una Agent Skill que convierte una petición en lenguaje natural ("hazme un diagrama de arquitectura con frontend, backend, base de datos y Redis") en un único fichero HTML con SVG inline. Entre el 20 de agosto y el 9 de octubre de 2026 pasó de la versión 2.6.0 a la 2.6.70, y el plugin ya va por la 2.6.110.
Qué hace: un sistema de diseño escrito para el agente
La skill se activa cuando pides un diagrama y cubre 45 tipos según su README: arquitectura, secuencia, máquina de estados, modelo ER, esquema de base de datos, despliegue, grafo de dependencias, swimlane, Gantt, Sankey o Wardley map, entre otros. Lo que aporta no es el dibujo, que el modelo ya sabe hacer, sino el criterio que el SKILL.md le impone:
- Densidad objetivo 4/10. Cada nodo es una idea distinta y cada línea transmite información; por encima de 9 nodos, probablemente son dos diagramas.
- Un solo color de acento para uno o dos nodos focales, líneas de 1 px, sin sombras.
- Todo en una rejilla de 4 px, con una lista de comprobación final que incluye solapes de etiquetas y contenido fuera del
viewBox. - Patrones semánticos antes que forma: si lo que importa es un cuello de botella, una frontera de confianza o el ciclo de vida de una petición, la skill elige primero el patrón y después el tipo visual que mejor lo expresa.
La primera vez que se usa en un proyecto, el agente se para y pregunta si quieres adaptar la guía de estilo a tu marca (a partir de una web, una carpeta local, tokens pegados o un perfil guardado) o seguir con la paleta por defecto. Los perfiles se guardan en ~/.diagram-design/profiles/.
También redibuja diagramas existentes: scripts de Python extraen nodos, aristas y contenedores de ficheros draw.io, Mermaid o Excalidraw, y el SKILL.md indica tratar sus etiquetas como datos no confiables, nunca como instrucciones.
Cómo instalarla
Con el CLI de skills, válido para Claude Code, Cursor, Codex, Copilot y otros agentes compatibles:
npx skills add cathrynlavery/diagram-designEn Claude Code, el marketplace añade además los comandos /export-diagram, /import-mermaid y /doctor:
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-designClaude Code deja desactivada por defecto la actualización automática de marketplaces de terceros; el README explica cómo activarla desde /plugin. Después basta con pedir el diagrama en lenguaje natural.
Riesgos y límites
La skill es sobre todo texto: instrucciones, referencias por tipo y plantillas HTML. Lo que ejecuta son scripts locales de Python (self_check.py para validar el resultado, los extractores de importación y export_svg.py / export_png.py), y su política de privacidad declara que no tiene servidor, cuentas ni telemetría. La red aparece en tres puntos:
- Google Fonts. Los diagramas generados cargan sus fuentes desde
fonts.googleapis.comal abrirlos. Si un diagrama va a documentación interna, existe la opción de fuentes del sistema (--system-fontsen la exportación a SVG). - Onboarding desde una web. El agente descarga páginas del sitio que indiques, pero el
SKILL.mdle obliga a avisar y esperar tu confirmación antes de hacerlo. - Exportación a PNG. Necesita Playwright y un navegador; la skill no los instala por su cuenta.
El límite importante lo reconoce el propio README: la calidad depende del modelo, el mismo prompt puede dar dos composiciones distintas y el resultado no es un formato fuente editable. No hay texto que revisar en un diff.
Frente a Mermaid y draw.io
| Mermaid | draw.io / Excalidraw | diagram-design | |
|---|---|---|---|
| Cómo se crea | Escribiendo texto | Arrastrando formas | Describiéndolo al agente |
| Composición | Automática | Manual | La coloca el agente en la rejilla de 4 px |
| Resultado | Texto que GitHub renderiza | Fichero editable | HTML con SVG inline, exportable a SVG o PNG |
| Cambiarlo después | Editar el texto | Editar el lienzo | Volver a pedírselo o editar el SVG |
El README lo resume con honestidad: para documentación que vive en Git y cambia cada sprint, Mermaid sigue siendo mejor opción. diagram-design es para el diagrama que vas a publicar: el de un postmortem, una propuesta de arquitectura o una presentación, donde importa que se lea bien a la primera. Lo más útil, en mi opinión, es su importador: partir del Mermaid que ya tienes en el repositorio y obtener una versión cuidada para el documento que va a leer otra gente.