draw-io

Visión general de la skill draw-io

La skill draw-io es un flujo de trabajo enfocado en crear, editar y revisar diagramas .drawio como XML, y luego exportarlos a .drawio.png para documentación o presentaciones. Está especialmente pensada para desarrolladores, redactores técnicos, arquitectos de soluciones y usuarios de IA que necesitan actualizar diagramas de forma repetible sin tener que ir haciendo clic manualmente en la interfaz de draw.io.

Para qué funciona mejor draw-io

Esta draw-io skill destaca sobre todo cuando necesitas:

• editar archivos .drawio existentes de forma segura
• hacer cambios precisos de layout ajustando coordenadas XML
• aplicar estándares de diagramación, como configuraciones de fuente
• generar PNG transparentes en alta resolución
• usar iconos de arquitectura de AWS con los identificadores correctos mxgraph.aws4.*

El trabajo real que resuelve

La mayoría de los usuarios no necesitan “generación de diagramas” en abstracto. Necesitan un agente que actualice diagramas de arquitectura de forma fiable, mantenga el estilo consistente y produzca recursos listos para exportar que encajen en un flujo de documentación. draw-io resulta útil porque convierte eso en un proceso concreto, no en un prompt ambiguo.

Qué diferencia a draw-io de un prompt genérico

Un prompt normal puede darte una idea de diagrama. Esta skill añade reglas operativas prácticas:

• editar el XML de .drawio, no el .drawio.png generado
• exportar PNG con ajustes de CLI conocidos
• aplicar configuraciones explícitas de font-family para compatibilidad con slides
• seguir pautas de layout sobre agrupación, dirección del flujo y legibilidad
• consultar iconos de AWS desde una referencia local en lugar de adivinar nombres

Quién debería instalarla

Instala draw-io si ya trabajas con archivos draw.io en Git, generas documentación o presentaciones a partir de fuentes, o necesitas actualizar diagramas de arquitectura de forma programática. Si solo buscas una lluvia de ideas visual puntual dentro de una GUI, probablemente este enfoque tenga más proceso del que necesitas.

Cómo usar la skill draw-io

Instalar la skill draw-io

Usa tu gestor de skills para añadirla desde el repositorio:

npx skills add softaworks/agent-toolkit --skill draw-io

Si tu entorno usa otro instalador, lo importante es la ruta de la skill skills/draw-io dentro de softaworks/agent-toolkit.

Confirmar los requisitos locales previos

Antes de apoyarte en draw-io install, comprueba que tu entorno tenga:

• un CLI drawio disponible para exportar
• bash para el script de conversión
• git si quieres que los PNG generados se añadan automáticamente al staging
• opcionalmente mise y pre-commit si tu repositorio usa ese flujo

El script de conversión incluido ejecuta:

drawio -x -f png -s 2 -t -o output.drawio.png input.drawio

Eso significa modo de exportación, formato PNG, escala 2x, fondo transparente y ruta de salida explícita.

Lee primero estos archivos

Para adoptarla más rápido, revisa estos archivos en este orden:

1. skills/draw-io/SKILL.md
2. skills/draw-io/README.md
3. skills/draw-io/references/layout-guidelines.md
4. skills/draw-io/references/aws-icons.md
5. skills/draw-io/scripts/convert-drawio-to-png.sh
6. skills/draw-io/scripts/find_aws_icon.py

Este orden importa porque la skill es más operativa que conceptual: las reglas, las convenciones de layout y los scripts auxiliares concentran la mayor parte de su valor.

Conoce primero la regla operativa clave de draw-io

La restricción de uso más importante es simple:

• edita archivos .drawio
• no edites directamente archivos .drawio.png

El PNG se trata como un artefacto generado. Si tu repositorio versiona tanto la fuente como la exportación, tu agente debe modificar el XML de origen y regenerar el PNG después.

Qué entrada necesita la skill

La calidad de draw-io usage depende mucho de la información que proporciones. Las buenas entradas suelen incluir:

• la ruta del archivo objetivo
• si vas a crear o editar
• el tipo de diagrama: arquitectura, flujo, flujo tipo secuencia, etc.
• la dirección de lectura prevista: de izquierda a derecha o de arriba abajo
• servicios, nodos, etiquetas y conexiones obligatorias
• cualquier restricción de presentación o documentación
• si se requieren iconos oficiales de AWS
• si hace falta exportar el PNG en ese momento

Sin esos detalles, el agente tiene que adivinar la estructura, el espaciado y los nombres.

Convertir un objetivo difuso en un prompt sólido para draw-io

Prompt débil:

“Actualiza nuestro diagrama de AWS.”

Mejor prompt:

“Edit assets/system.drawio. Add Amazon S3 on the left as the ingestion source, route data to AWS Lambda, then to Amazon RDS. Keep a left-to-right flow. Preserve existing group structure. Use official AWS icons, avoid crossing arrows, and regenerate assets/system.drawio.png.”

Por qué funciona mejor:

• indica el archivo
• especifica los componentes que hay que añadir
• define la dirección del flujo
• pide fidelidad en los iconos
• incluye un objetivo de layout
• solicita el artefacto exportado

Usa draw-io para ediciones precisas, no solo para generar

Esta skill resulta especialmente útil cuando ya tienes un diagrama y necesitas cambios concretos como:

• mover un clúster para evitar solapamientos de líneas
• alinear horizontalmente cajas de servicios
• sustituir una etiqueta genérica por el nombre oficial de un servicio de AWS
• cambiar fuentes para compatibilidad con presentaciones
• regenerar el PNG tras editar el XML

Ahí es donde editar directamente el XML suele ser más rápido y reproducible que hacerlo manualmente en la UI.

Sigue la configuración de fuentes si las slides importan

Si el diagrama se usa en slides de Quarto o en entornos con problemas de renderizado de fuentes, la skill recomienda definir:

• defaultFontFamily en mxGraphModel
• fontFamily en elementos de texto individuales

El repositorio señala explícitamente Noto Sans JP como fuente recomendada para soporte en japonés. Aunque no necesites japonés, la lección general es importante: especifica las fuentes de forma explícita cuando necesites una salida consistente entre distintas máquinas y pasos de exportación.

Usa la ruta de conversión que encaje con tu repositorio

La skill admite varias formas de exportar PNG:

• todos los archivos con pre-commit: mise exec -- pre-commit run --all-files
• un archivo con pre-commit: mise exec -- pre-commit run convert-drawio-to-png --files assets/my-diagram.drawio
• uso directo del script: bash ~/.claude/skills/draw-io/scripts/convert-drawio-to-png.sh assets/diagram1.drawio

Elige según el flujo de tu repositorio. Si tu proyecto ya usa pre-commit, esa es la ruta adecuada. Si solo necesitas una exportación local puntual, el script es la opción más rápida.

Usa la referencia de iconos de AWS en lugar de adivinar

Si estás haciendo draw-io for Design Implementation en diagramas con mucho AWS, la referencia de iconos es una de las partes más valiosas de la skill. Ahí se documentan:

• nombres oficiales de servicios como Amazon ECS y AWS Lambda
• convenciones actuales de estilo de iconos con mxgraph.aws4.*
• patrones de iconos de recursos y productos

El script auxiliar incluido puede buscar en la referencia:

python ~/.claude/skills/draw-io/scripts/find_aws_icon.py lambda

Eso es mucho más seguro que inventarse nombres de resIcon de memoria.

Aplica las pautas de layout de forma intencional

La guía de layout del repositorio no está de adorno. Aporta valores por defecto prácticos que mejoran la calidad del resultado:

• agrupar con claridad los límites de nube y las subredes
• mantener el flujo principal de izquierda a derecha cuando sea posible
• usar distintos estilos de línea para diferentes tipos de flujo
• mantener cerca los elementos relacionados
• reducir los cruces de flechas
• dejar suficiente espacio en blanco para la legibilidad

Si quieres una primera versión útil, indícale al agente cuál de estos principios importa más en tu diagrama.

Preguntas frecuentes sobre la skill draw-io

¿draw-io es buena opción para principiantes?

Sí, si ya tienes archivos draw.io y quieres ayuda para editarlos. La skill reduce la improvisación porque aporta reglas y scripts concretos. Es menos ideal para alguien completamente nuevo que solo quiere explorar conceptos de diagramación sin un flujo basado en archivos.

¿Cuándo es mejor draw-io que un prompt normal?

draw-io es mejor cuando necesitas ediciones reproducibles, manejo correcto de archivos, pasos de exportación o precisión en los iconos de AWS. Un prompt normal puede describir bien un diagrama, pero normalmente no hará cumplir la edición del origen .drawio, los comandos de exportación, la configuración de fuentes y el uso de scripts auxiliares.

¿draw-io requiere la GUI de draw.io?

No necesariamente. La skill está diseñada alrededor de la edición de archivos fuente y la exportación de PNG basada en CLI. Eso la hace útil en flujos centrados en código, diffs revisables y pipelines de documentación.

¿Cuándo no debería usar draw-io?

Sáltate esta draw-io guide si necesitas:

• pizarras libres sin estructura
• mockups de diseño pulidos fuera de draw.io
• edición puramente visual en una GUI
• generación de diagramas para formatos no relacionados con .drawio

Esta skill está especializada en XML de draw.io y operaciones de exportación, no en diseño gráfico general.

¿draw-io puede ayudar con diagramas de arquitectura AWS?

Sí. Es una de sus fortalezas más claras. La referencia de iconos de AWS y el script de búsqueda te ayudan a usar nombres oficiales e iconos mxgraph.aws4.*, algo muy valioso cuando importan la consistencia y el reconocimiento visual.

¿draw-io corrige automáticamente un mal layout?

No de forma automática ni “mágica”. La skill ofrece un método para ajustar coordenadas y layout de manera deliberada. Mejora mucho los resultados cuando indicas con claridad la intención de colocación, como agrupación, dirección del flujo, espaciado y prioridades para evitar solapamientos.

Cómo mejorar la skill draw-io

Dale a draw-io entradas estructurales más sólidas

La forma más rápida de mejorar draw-io usage es aportar estructura, no adjetivos. En lugar de decir “hazlo más limpio”, di:

• mueve la base de datos debajo de la capa de aplicación
• mantén todas las fuentes de ingesta en la columna izquierda
• evita cruces de flechas si es posible
• agrupa por separado los recursos de subred pública y privada
• mantén las etiquetas lo bastante cortas como para que las cajas no se expandan

Ese tipo de instrucción se traduce directamente en decisiones de XML y layout.

Parte de un diagrama existente siempre que puedas

La skill funciona mejor cuando puede editar un archivo .drawio existente en vez de inventarlo todo desde cero. Los archivos existentes le aportan:

• IDs actuales de elementos
• patrones de layout
• convenciones de estilo
• estructura de agrupación
• destinos de exportación conocidos

Para equipos, esto suele producir resultados más fiables que pedir un diagrama totalmente nuevo cada vez.

Sé explícito con los nombres y la fidelidad de iconos

Un modo de fallo habitual es usar nombres de servicios vagos como “ECS” o “Lambda” sin decidir si las etiquetas deben mostrar los nombres oficiales completos. Si los diagramas de AWS importan, especifica ambas cosas:

• etiquetas visibles: Amazon ECS, AWS Lambda, Amazon RDS
• requisito de icono: usar iconos oficiales de servicio mxgraph.aws4.*

Así evitas mezclar estilos de nomenclatura y asignaciones incorrectas de iconos.

Pide edición y exportación como un solo flujo

Si quieres salidas utilizables, solicita tanto la edición del origen como el paso de exportación en una sola instrucción. Ejemplo:

“Update docs/arch.drawio, then regenerate docs/arch.drawio.png with the skill’s standard PNG export settings.”

Esto reduce el problema habitual de que el XML cambie pero el artefacto de vista previa quede desactualizado.

Vigila los principales modos de fallo

Los problemas comunes de draw-io suelen ser prácticos, no conceptuales:

• editar el PNG en lugar del .drawio
• olvidar la configuración de fuentes y obtener renderizado de texto inconsistente
• usar identificadores de iconos de AWS inventados
• saturar el diagrama con demasiados nodos y hacer que las etiquetas choquen
• crear conectores cruzados que perjudican la legibilidad
• cambiar el layout sin conservar el flujo general

Puedes evitar la mayoría de estos fallos si mencionas directamente los scripts y guías incluidos dentro de tu prompt.

Itera con cambios pequeños y fáciles de revisar

Para diagramas complejos, no pidas todo de una vez. Un patrón mejor es:

1. ajustar estructura y agrupación
2. revisar espaciado y conectores
3. corregir etiquetas y fuentes
4. exportar PNG
5. hacer una última pasada de legibilidad

Esto produce diffs más limpios y facilita detectar si un problema de layout viene de la agrupación, de la elección de iconos o del tamaño del texto.

Indica al agente los helpers del repositorio por nombre

Si tu agente admite prompts con conciencia de archivos, menciona las referencias exactas:

• references/layout-guidelines.md para espaciado y flujo
• references/aws-icons.md para nombres e iconos de AWS
• scripts/find_aws_icon.py para buscar iconos
• scripts/convert-drawio-to-png.sh para exportar

Ese pequeño paso suele mejorar la calidad de la primera pasada porque el agente usa las convenciones del repositorio en lugar de apoyarse en consejos genéricos sobre diagramación.