json-canvas

Visión general de la skill json-canvas

Qué hace la skill json-canvas

La skill json-canvas ayuda a un agente de IA a crear y editar archivos .canvas que siguen la estructura JSON Canvas 1.0 usada por tableros visuales al estilo Obsidian. Su valor real no está en “hacer diagramas en general”, sino en generar JSON válido de nodes y edges con los IDs, coordenadas y referencias correctos para que el archivo se abra bien y no falle de formas sutiles.

Quién debería instalar json-canvas

Esta json-canvas skill encaja mejor con usuarios que ya saben qué resultado quieren —un mapa mental, diagrama de flujo, tablero de proyecto, mapa conceptual o lienzo de notas— pero no quieren escribir el esquema a mano. Resulta especialmente útil si trabajas en Obsidian, mantienes archivos .canvas en un repositorio o buscas ediciones repetibles asistidas por IA sobre canvases existentes, en lugar de sugerencias visuales puntuales.

Por qué es mejor que un prompt genérico

Un prompt normal puede describir cajas y flechas, pero a menudo pasa por alto detalles de formato que sí importan: IDs hexadecimales únicos de 16 caracteres, referencias válidas en fromNode y toNode, colocación sin solapamientos y la diferencia entre nodos de texto y nodos de grupo. La skill json-canvas le da al agente un formato objetivo concreto y ejemplos, lo que reduce el trabajo de reparación después de generar el archivo.

Lo que conviene saber antes de adoptarla

Esta skill es intencionalmente específica. Ayuda con la estructura de archivos .canvas y con flujos comunes de edición; no sustituye a un motor completo de maquetación visual, una herramienta de diagramación semántica ni un optimizador automático de diseño. Si tu necesidad principal es un estilo visual pulido o exportar a muchos formatos de diagrama, json-canvas for Diagramming puede resultarte demasiado de bajo nivel. Si lo que necesitas es JSON de canvas válido y rápido, entonces sí es una buena opción.

Cómo usar la skill json-canvas

Contexto de instalación y por dónde empezar a leer

Para usar json-canvas install en un entorno con skills habilitadas, añade la skill desde el repositorio kepano/obsidian-skills y luego lee primero skills/json-canvas/SKILL.md y después skills/json-canvas/references/EXAMPLES.md. Esos dos archivos son el núcleo práctico: el primero explica la estructura obligatoria y los flujos de trabajo, y el segundo muestra ejemplos completos que puedes usar como referencia.

Qué entrada necesita la skill para funcionar bien

La calidad de json-canvas usage depende de lo específico que sea tu pedido. Indica:

• la ruta de archivo de destino o el contenido .canvas existente
• si quieres un canvas nuevo o una edición
• los tipos de nodo que necesitas, como text o group
• la intención general de layout, como flujo de izquierda a derecha o columnas tipo kanban
• las conexiones deseadas entre nodos
• cualquier expectativa de tamaño o espaciado

Una solicitud débil sería “haz un canvas de proyecto”. Una más sólida sería: “Create a new .canvas with three group columns labeled To Do, In Progress, Done, each 300x500, spaced 50px apart, and add three text task nodes inside the first two groups.”

Cómo convertir una idea general en un prompt sólido

Para obtener mejor calidad con json-canvas guide, pide tanto generación como validación. Un patrón de prompt sólido es:

1. Expón el objetivo en lenguaje claro.
2. Especifica si hay que crear o modificar.
3. Define el inventario de nodos y sus relaciones.
4. Pide al agente que valide el JSON y las referencias de edges antes de devolver el resultado final.

Ejemplo:
“Use the json-canvas skill to create a new .canvas file for a product launch plan. Add one central text node, four supporting text nodes around it, connect each support node to the center, keep 100px spacing to avoid overlap, generate unique 16-character hex IDs, and return valid JSON only.”

Consejos prácticos de flujo de trabajo que ahorran tiempo

Para un mejor json-canvas usage, conviene empezar simple y luego iterar:

• Primero pide un canvas mínimo pero estructuralmente válido.
• Ábrelo o revísalo.
• Luego solicita un cambio cada vez: añadir nodos, reagrupar, reconectar o recolocar.

Si vas a editar un archivo existente, indica al agente que analice primero los IDs actuales antes de añadir nada. La rotura más habitual viene de colisiones de IDs y de edges que apuntan a nodos inexistentes. Si el layout importa, pide reglas explícitas de espaciado; si no, el JSON puede ser válido pero quedar visualmente desordenado.

Preguntas frecuentes sobre la skill json-canvas

¿json-canvas es buena opción para principiantes?

Sí, siempre que ya tengas claro qué debería contener el canvas. La skill elimina gran parte de la incertidumbre del esquema, así que los principiantes pueden obtener archivos .canvas válidos sin memorizar la especificación. Es menos ideal si todavía estás definiendo la lógica del diagrama en sí; la skill ayuda a codificar la estructura, no a inventar por ti todo el diseño de la información.

¿Cuándo conviene usar json-canvas en lugar de un prompt normal?

Usa json-canvas cuando la salida tenga que ser un archivo .canvas funcional, especialmente si vas a editar un canvas existente. Un prompt genérico puede servir para pensar la estructura, pero esta skill funciona mejor cuando la corrección es importante: IDs únicos, arrays válidos, referencias reales entre nodos y formato compatible con Obsidian.

¿json-canvas cubre todas las necesidades de diagramación?

No. json-canvas for Diagramming funciona mejor para canvases de nodos y aristas, tableros simples y organización visual vinculada a notas. No sustituye herramientas BPMN, gráficos de presentación pulidos ni sistemas avanzados de auto-layout. Si necesitas estándares amplios de diagramación o controles de estilo más ricos, usa otra herramienta y convierte solo si hace falta.

¿Cuáles son los principales límites o casos donde no encaja?

Descarta esta skill si tu objetivo no es un archivo .canvas, si necesitas una optimización automática de layout intensiva o si la fuente de verdad debe seguir estando en otro formato como Mermaid, Excalidraw o una hoja de cálculo. También conviene evitar prompts vagos como “haz que se vea bonito”; la skill rinde mejor cuando la estructura y la intención de colocación están definidas de forma explícita.

Cómo mejorar la skill json-canvas

Da entradas estructurales más sólidas

La mayor mejora en la salida viene de aportar mejor estructura desde el principio. Nombra los nodos que quieres, las conexiones entre ellos y el patrón espacial esperado. Por ejemplo, “hub-and-spoke”, “three-column board” o “timeline from left to right” le dan al agente suficiente información para ubicar los nodos con criterio en lugar de adivinar.

Evita los fallos más comunes de json-canvas

La mayoría de los problemas de json-canvas son mecánicos:

• IDs duplicados
• edges que apuntan a nodos inexistentes
• coordenadas solapadas
• ausencia de campos obligatorios como type, x, y, width, height

Pide al agente que valide todos los IDs y referencias antes de devolver el archivo. Si está modificando un canvas, indícale que conserve los IDs existentes salvo que el cambio requiera un nodo o edge nuevo.

Itera después de la primera salida

Trata el primer resultado como un andamiaje. Después, mejora una capa cada vez:

• ajusta espaciado y alineación
• añade grupos
• afina etiquetas y contenido textual
• añade o elimina conexiones

Esto funciona mejor que pedir un canvas final denso de una sola vez, porque los errores de estructura visual se detectan antes y con más facilidad que después de una generación grande.

Usa ejemplos y patrones del repositorio de forma intencional

Para mejorar los resultados de json-canvas skill, toma como base las formas de references/EXAMPLES.md en lugar de describirlo todo de manera abstracta. Si la salida que buscas se parece a un tablero de proyecto, pide al agente que siga el patrón basado en grupos. Si se parece a un mapa conceptual, pídele el patrón simple de nodos de texto conectados. Reutilizar patrones nativos del repositorio suele producir JSON más limpio y menos sorpresas de compatibilidad.