yctimlin/excalidraw-skill

Skill de Excalidraw

Paso 0: Elige una Interfaz

Tres interfaces controlan el mismo lienzo en vivo. Elige la primera que aplique:

1. Herramientas MCP — si las herramientas excalidraw/* (ej. batch_create_elements) están en tu lista de herramientas, prefierelas: los resultados llegan directamente a tu contexto y las capturas de pantalla vuelven como imágenes sin tocar el disco.
2. CLI (por defecto cuando no hay herramientas MCP presentes):

   npx -y mcp-excalidraw-server <comando>
   

   No requiere configuración: cualquier comando que toque el lienzo inicia automáticamente el servidor del lienzo en http://127.0.0.1:3000 (la primera ejecución de npx descarga el paquete). Si la CLI está instalada globalmente (npm i -g mcp-excalidraw-server), también funciona el alias más corto excalidraw-canvas <comando>.
3. API REST (último recurso, por ejemplo, desde código de aplicación): endpoints HTTP en http://127.0.0.1:3000 — consulta references/cheatsheet.md para los payloads. El servidor ya debe estar en ejecución.

La URL del lienzo se obtiene de EXPRESS_SERVER_URL (por defecto http://127.0.0.1:3000). Recuérdale al usuario que abra esa URL en un navegador: las capturas de pantalla, la exportación de imágenes, la conversión de Mermaid y el control de la ventana gráfica necesitan una pestaña abierta (la CLI sale con código 4 cuando falta).

Referencia Rápida de la CLI

Los resultados son JSON en stdout — excepto describe (texto plano) y la salida de contenido sin procesar cuando se omite --out (export escena JSON, screenshot --format svg SVG sin procesar). Diagnósticos en stderr. Códigos de salida: 0 ok, 1 error, 2 uso, 3 lienzo inalcanzable, 4 pestaña del navegador requerida.

Tarea	Comando
Iniciar / detener / inspeccionar servidor	start, stop, status
Crear elementos (por lotes)	add elements.json o `echo '[...]'
Parche multioperación en una sola llamada	apply patch.json — {"create":[...],"update":[{"id":"a","set":{...}}],"delete":[...]}
Leer uno / consultar varios	get <id>, query [--type t] [--bbox x0,y0,x1,y1] [--filter k=v] [--filter-json '{...}']
Actualizar / eliminar	update <id> --set '{...}', delete <id> [...]
Entender la escena	describe (resumen en texto plano: ids, posiciones, etiquetas, conexiones)
Ver la escena	screenshot [--out f.png] (PNG sin --out → ruta de archivo temporal en JSON; SVG sin --out → SVG sin procesar)
Operaciones de diseño	`arrange align
Archivos de escena	export [--out scene.excalidraw], `import [scene.excalidraw
Mermaid → lienzo	`mermaid [diagram.mmd
Instantáneas	`snapshot save
Enlace compartido	share (subida encriptada → URL de excalidraw.com)
Limpiar lienzo	clear --yes
Instalar / actualizar este skill	install-skill --dir <raíz-skills> (el agente elige la raíz del proyecto/global)

Formato de Elementos (CLI y MCP)

La CLI y las herramientas MCP aceptan el mismo formato amigable para el agente y lo normalizan automáticamente:

• Etiquetas: pon "text": "Mi Etiqueta" en cualquier forma — se convierte al formato de etiqueta vinculada de Excalidraw.
• Vinculación de flechas: "startElementId": "a" / "endElementId": "b" — las flechas se enrutan automáticamente a los bordes de los elementos.
• fontFamily: pasa un nombre de cadena ("helvetica", "cascadia", "excalifont", ...) o un número de cadena "1"–"8".
• points: se aceptan tanto tuplas [[x,y], ...] como objetos [{"x":..,"y":..}].
• Actualizaciones de parche: en apply, las entradas de actualización pueden usar campos directos ({"id":"a","x":120}) o un objeto set ({"id":"a","set":{"x":120}}). No mezcles ambas formas en una entrada de actualización.

La API REST sin procesar es más estricta: las etiquetas deben ser "label": {"text": "..."}, los enlaces deben ser "start": {"id": "..."} / "end": {"id": "..."}. Solo preocúpate por esto al hacer POST directamente a la API.

---

Sistema de Coordenadas

El lienzo usa una cuadrícula de coordenadas 2D: (0, 0) es el origen, x aumenta hacia la derecha, y aumenta hacia abajo. Planifica tu diseño antes de escribir cualquier JSON.

Pautas generales de espaciado:

• Espaciado vertical entre niveles: 80–120px (suficiente para que las flechas no amontonen las etiquetas)
• Espaciado horizontal entre hermanos: mínimo 40–60px; da a las flechas etiquetadas 120px+
• Ancho de forma: max(160, cantidadCaracteresEtiqueta * 12) para mantener la etiqueta en una línea
• Alto de forma: 60px para una línea, 80px para etiquetas de dos líneas
• Relleno de fondo/zona: 50px en todos los lados alrededor de los elementos contenidos

Estilo para un aspecto profesional:

• "fillStyle": "solid" en las formas da rellenos planos nítidos — el valor predeterminado es un patrón de rayado esbozado
• Combina rellenos de backgroundColor pastel con su strokeColor más oscuro (paleta en la hoja de trucos)
• "strokeStyle": "dashed" en bordes de zona y flechas asíncronas se lee como "límite / fondo"

---

Anti-Patrones de Diseño (Críticos para Diagramas Complejos)

Estos son los errores más comunes que producen diagramas ilegibles. Evítalos todos.

1. NO uses label.text (o text) en rectángulos de zonas de fondo grandes

Cuando pones una etiqueta en un rectángulo de fondo, Excalidraw crea un elemento de texto vinculado centrado en el medio de esa forma, justo donde se colocarán tus cajas de servicio. El texto se superpone a todo lo que hay dentro de la zona y no se puede reposicionar.

Incorrecto:

{"id": "vpc-zona", "type": "rectangle", "x": 50, "y": 50, "width": 800, "height": 400, "text": "VPC (10.0.0.0/16)"}

Correcto — usa un elemento de texto independiente anclado en la parte superior de la zona:

{"id": "vpc-zona", "type": "rectangle", "x": 50, "y": 50, "width": 800, "height": 400, "backgroundColor": "#e3f2fd"},
{"id": "vpc-etiqueta", "type": "text", "x": 70, "y": 60, "width": 300, "height": 30, "text": "VPC (10.0.0.0/16)", "fontSize": 18}

El elemento de texto independiente se sitúa en la esquina superior de la zona y no interfiere con los elementos colocados dentro.

2. Evita flechas entre zonas en diagramas complejos

Una flecha desde un elemento en una zona de diseño hasta un elemento en una zona distante dibujará una larga línea diagonal que atraviesa todo lo que hay en medio. En un diagrama de infraestructura de múltiples zonas, esto produce una maraña ilegible de espaguetis.

Regla de diseño: Mantén las flechas dentro de la misma zona o nivel. Para mostrar relaciones entre zonas, usa texto de anotación o separa las zonas para que sus bordes sean adyacentes (sin elementos entre ellos) y enruta la flecha a lo largo del borde.

Si debes conectar entre zonas, usa una flecha acodada que viaje a lo largo del perímetro, nunca a través del medio de otra zona.

3. Usa las etiquetas de flecha con moderación

Las etiquetas de flecha se colocan en el punto medio de la flecha. En flechas cortas, se superponen a las formas en ambos extremos. En diagramas con muchas flechas, chocan con elementos cercanos.

• Solo agrega una etiqueta de flecha cuando el nombre de la relación sea realmente esencial (por ejemplo, protocolo, número de puerto, dirección de datos).
• Si estás agregando una etiqueta a cada flecha, reconsideralo — generalmente agrega ruido visual, no claridad.
• Mantén las etiquetas de flecha en ≤ 12 caracteres. Prefiere omitirlas por completo en diagramas densos.

---

Calidad: Por Qué es Importante (y Cómo Verificarla)

Los diagramas de Excalidraw son comunicación visual. Si el texto está cortado, los elementos se superponen o las flechas cruzan formas no relacionadas, el diagrama se vuelve confuso y poco profesional — contradice todo el propósito de dibujarlo. Por lo tanto, después de cada lote de elementos, verifica antes de agregar más.

Lista de Verificación de Calidad

Después de cada add / apply / batch_create_elements, toma una captura de pantalla y verifica:

1. Corte de texto — ¿Todo el texto de la etiqueta es completamente visible? El texto cortado significa que la forma es demasiado pequeña. Aumenta el width y/o height.
2. Superposición — ¿Alguna forma comparte el mismo espacio? Las zonas de fondo deben contener completamente a los hijos con relleno.
3. Cruce de flechas — ¿Las flechas atraviesan elementos no relacionados? Si es así, enrútense alrededor usando flechas curvas o acodadas (ver Enrutamiento de Flechas a continuación).
4. Superposición de etiqueta de flecha — Las etiquetas de flecha se encuentran en el punto medio. Si se superponen a una forma, acorta la etiqueta o ajusta la trayectoria de la flecha.
5. Espaciado — Al menos 40px de espacio entre elementos. Los diseños apretados son difíciles de leer.
6. Legibilidad — Tamaño de fuente ≥ 16 para texto del cuerpo, ≥ 20 para títulos.
7. Colocación de etiqueta de zona — Si usaste text/label.text en un rectángulo de zona de fondo, la etiqueta de la zona estará centrada en el medio de la zona, superponiéndose a todo lo que hay dentro. Solución: elimina el elemento de texto vinculado y agrega un elemento de texto independiente en la parte superior de la zona (ver Anti-Patrones de Diseño arriba).

Si encuentras algún problema: detente, arréglalo, vuelve a tomar la captura de pantalla y luego continúa. Di "Veo [problema], lo estoy arreglando" en lugar de pasar por alto los problemas. Solo continúa una vez que todas las verificaciones pasen.

---

Flujo de Trabajo: Dibujar un Nuevo Diagrama

Mermaid vs. Creación Directa — ¿Cuál Usar?

Usa mermaid / create_from_mermaid cuando: el usuario ya tiene un diagrama Mermaid, o la estructura se asigna limpiamente a un diagrama de flujo/secuencia/ER con sintaxis Mermaid estándar. Es rápido y maneja la conversión automáticamente, aunque tienes menos control sobre el diseño exacto.

Crea elementos directamente cuando: necesitas un control preciso del diseño, el tipo de diagrama no se asigna bien a Mermaid (por ejemplo, arquitectura personalizada, diagramas de nube anotados), o deseas elementos colocados en una cuadrícula de coordenadas específica.

Pasos (CLI mostrada; las herramientas MCP son 1:1 — consulta la hoja de trucos)

1. Planifica tu cuadrícula de coordenadas — mapea niveles y posiciones-x antes de escribir JSON. (Modo MCP: llama a read_diagram_guide para colores/tamaños; la misma guía está en references/cheatsheet.md).
2. Inicio fresco opcional: npx -y mcp-excalidraw-server clear --yes
3. Crea formas y flechas en una sola llamada. Los campos id personalizados (ej. "id": "auth-svc") facilitan las actualizaciones posteriores:

   npx -y mcp-excalidraw-server add - <<'EOF'
   [
     {"id": "lb", "type": "rectangle", "x": 300, "y": 50, "width": 180, "height": 60, "text": "Balanceador de Carga"},
     {"id": "svc-a", "type": "rectangle", "x": 100, "y": 200, "width": 160, "height": 60, "text": "Servidor Web 1"},
     {"id": "svc-b", "type": "rectangle", "x": 450, "y": 200, "width": 160, "height": 60, "text": "Servidor Web 2"},
     {"id": "db", "type": "rectangle", "x": 275, "y": 350, "width": 210, "height": 60, "text": "PostgreSQL"},
     {"type": "arrow", "x": 0, "y": 0, "startElementId": "lb", "endElementId": "svc-a"},
     {"type": "arrow", "x": 0, "y": 0, "startElementId": "lb", "endElementId": "svc-b"},
     {"type": "arrow", "x": 0, "y": 0, "startElementId": "svc-a", "endElementId": "db"},
     {"type": "arrow", "x": 0, "y": 0, "startElementId": "svc-b", "endElementId": "db"}
   ]
   EOF
   

   (El - posicional es opcional — sin argumento de archivo, add lee de stdin.)
4. Establece los anchos de forma usando max(160, longitudEtiqueta * 12).
5. screenshot → ver el archivo → ejecutar la Lista de Verificación de Calidad → corregir problemas antes del siguiente lote.

---

Enrutamiento de Flechas — Evita Superposiciones

Las flechas rectas pueden cruzar elementos en diagramas complejos. Usa flechas curvas o acodadas cuando sea necesario:

Flechas curvas (arco suave sobre obstáculos):

{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0, 0], [50, -40], [200, 0]],
  "roundness": {"type": 2}
}

El punto de paso intermedio [50, -40] levanta la flecha hacia arriba. roundness: {type: 2} la suaviza.

Flechas acodadas (enrutamiento en ángulo recto / forma de L):

{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0, 0], [0, -50], [200, -50], [200, 0]],
  "elbowed": true
}

Cuándo usar cada una:

• Abanico (un origen → muchos destinos): flechas curvas con puntos de paso para evitar superposiciones
• Cruzar carriles (conexión a paneles laterales): flechas acodadas que suben, cruzan y luego bajan
• Conexiones horizontales largas: flechas curvas con un ligero desplazamiento vertical

Regla: Si una flecha pasaría a través de una forma no relacionada, agrega un punto de paso para rodearla.

---

Flujo de Trabajo: Refinamiento Iterativo

Combinar describe con screenshot es lo que hace que este skill sea poderoso.

• describe (describe_scene en MCP) → texto estructurado: IDs de elementos, tipos, posiciones, etiquetas, conexiones. Úsalo para saber qué hay en el lienzo antes de hacer actualizaciones programáticas (encontrar IDs, entender cuadros delimitadores).
• screenshot (get_canvas_screenshot en MCP) → PNG del lienzo renderizado real. Úsalo para verificación visual de calidad — muestra exactamente lo que ve el usuario, incluyendo cortes, superposiciones y enrutamiento de flechas. La CLI imprime la ruta del archivo guardado como JSON; lee/visualiza ese archivo.

Bucle de retroalimentación:

add elementos
  → screenshot → ver → "texto cortado en auth-svc"
  → update auth-svc --set '{"width": 220}' → screenshot → "superposición entre auth-svc y rate-limiter"
  → update rate-limiter --set '{"x": 520}' → screenshot → "todas las verificaciones pasan"
  → continuar

Flujo de Trabajo: Refinar un Diagrama Existente

1. describe para entender el estado actual — anota los IDs y posiciones de los elementos.
2. Identifica los elementos por id o texto de etiqueta (no por coordenadas x/y — cambian).
3. update <id> --set '{...}' para redimensionar/recolorear/mover; delete <id> para eliminar; o agrupa todo en un solo parche apply. Las flechas vinculadas se re-enrutan automáticamente cuando mueves o redimensionas sus puntos finales — no es necesario eliminarlas y volver a crearlas.
4. screenshot para confirmar que el cambio se ve bien.
5. Si las actualizaciones fallan: verifica que el ID exista con get <id>; desbloquea con arrange unlock --ids <id> si está bloqueado.

Flujo de Trabajo: Conversión de Mermaid

echo 'graph TD
  A[Cliente] --> B[API]
  B --> C[(BD)]' | npx -y mcp-excalidraw-server mermaid

Requiere una pestaña del navegador abierta (la conversión se ejecuta en el frontend; el código de salida 4 te indica que abras la URL del lienzo). Después, screenshot para verificar el diseño. Si el diseño automático es deficiente (nodos apiñados, bordes que se cruzan), encuentra los elementos problemáticos con describe y reposiciónalos con update.

Flujo de Trabajo: Entrada/Salida de Archivos

• Exportar escena: export --out diagram.excalidraw (sin --out → JSON a stdout)
• Importar escena: import diagram.excalidraw (anexar) o import diagram.excalidraw --replace
• Imagen: screenshot --out diagram.png / screenshot --format svg --out diagram.svg (se requiere pestaña del navegador)
• Enlace compartido: share — encripta la escena y devuelve un enlace para compartir de exc

…

[truncado para traducción]