json-canvas

Visión general de la skill json-canvas

Qué hace la skill json-canvas

La skill json-canvas ayuda a un agente a crear o editar archivos .canvas válidos para el formato JSON Canvas que usan Obsidian y otras herramientas de diagramación similares. Su función real no es “dibujar algo bonito”, sino “generar un JSON de canvas estructuralmente correcto, con nodos, aristas, grupos, posiciones, tamaños y capas que una app de canvas pueda abrir de verdad”.

Quién debería instalar json-canvas

La json-canvas skill encaja mejor con usuarios que ya saben qué contenido quieren poner en un tablero, pero no quieren escribir el esquema a mano. Va bien para toma de notas, mapas mentales, diagramas de flujo, bocetos de arquitectura, tableros de investigación y flujos de diagramación ligeros en los que la salida debe ser un archivo .canvas real, no una descripción en prosa de cómo sería.

Por qué es mejor que un prompt genérico

Un prompt normal suele acertar casi todo el formato, pero se equivoca en campos obligatorios, tipos de nodo o estructura de arrays. json-canvas resulta útil porque se centra en el modelo de objetos de JSON Canvas: nodes y edges en el nivel superior, cuatro tipos de nodo (text, file, link, group) y detalles prácticos como el orden z en función del orden del array de nodos. Eso reduce la limpieza posterior si tu objetivo es diagramar en Obsidian en lugar de generar un JSON de ejemplo.

Cómo usar la skill json-canvas

Contexto de instalación y cuándo invocar json-canvas

Si tu plataforma de agentes admite skills de GitHub, añade json-canvas desde MarsWang42/OrbitOS con tu flujo habitual de instalación de skills. La evidencia del repositorio solo muestra SKILL.md, así que conviene esperar una skill compacta, centrada en pautas de formato más que en scripts auxiliares o validadores. Invócala cuando la tarea mencione explícitamente .canvas, JSON Canvas, Obsidian Canvas o diagramación visual que deba terminar como JSON de canvas editable.

Qué entradas producen un buen uso de json-canvas

La skill funciona mejor cuando le das intención de diagrama, no solo un tema. Una buena entrada normalmente incluye:

• lista de nodos o secciones que representar
• relaciones entre nodos
• tipos de nodo deseados: text, file, link, group
• dirección aproximada del diseño: de izquierda a derecha, de arriba abajo, agrupado
• si los grupos deben contener visualmente nodos relacionados
• referencias de archivos o URLs si usas nodos file o link

Un prompt débil: “Make a canvas for my project.”
Un prompt más sólido: “Create a .canvas for a project roadmap with three groups: planning, build, launch. Use text nodes for tasks, link nodes for docs URLs, connect task dependencies with edges, and arrange groups left to right.”

Cómo convertir una idea general en un prompt usable

Para un json-canvas usage fiable, especifica tanto el contenido como la estructura. Un patrón de prompt práctico es:

1. Define el propósito del tablero.
2. Enumera las categorías de nodos.
3. Indica las aristas clave.
4. Da reglas de diseño.
5. Pide solo JSON .canvas válido.

Ejemplo:
“Use the json-canvas skill to generate valid .canvas JSON for diagramming a hiring pipeline. Include groups for sourcing, screening, interview, and offer. Add text nodes for each stage, link nodes for ATS and policy docs, and edges showing candidate flow. Keep nodes spaced for readability and place groups in process order.”

Qué leer primero y consejos de flujo de trabajo con json-canvas

Lee primero EN/.agents/skills/json-canvas/SKILL.md. Céntrate en:

• estructura general del archivo
• tipos de nodo y campos obligatorios
• modelado de aristas
• orden de z-index mediante el orden del array de nodos

Flujo de trabajo práctico:

1. Haz un borrador del inventario de nodos.
2. Genera un canvas mínimo.
3. Ábrelo en tu app de canvas.
4. Corrige el diseño, la agrupación o los enlaces que falten en una segunda pasada.

Esto funciona mejor que pedir desde el principio un tablero final ya pulido, porque la corrección del formato es más fácil de validar antes de afinar la parte visual.

Preguntas frecuentes sobre la skill json-canvas

¿json-canvas sirve solo para diagramar en Obsidian?

No. json-canvas for Diagramming encaja bien en cualquier caso en el que la app de destino lea la especificación JSON Canvas. Obsidian es el ejemplo más evidente, pero el valor real está en generar .canvas basados en un estándar, no en algún truco de estilo específico de Obsidian.

¿Es mejor que pedirle a un LLM que escriba JSON directamente?

Por lo general sí, si el resultado final tiene que cargar sin problemas. Un prompt genérico puede servir para ejemplos pequeños, pero esta skill orienta el modelo hacia el esquema real de canvas y la semántica de los nodos. Eso importa en cuanto aparecen varios tipos de nodo, regiones agrupadas o muchas aristas.

¿json-canvas es adecuada para principiantes?

Sí, siempre que entiendas el tablero que quieres. No necesitas conocer la especificación en profundidad, pero sí describir con claridad las entidades y sus relaciones. Si todavía no puedes enumerar los nodos o los flujos, la skill seguirá generando algo, pero es probable que el resultado necesite bastante revisión manual.

¿Cuándo no debería usar la skill json-canvas?

Sáltatela si solo necesitas una imagen estática, un diagrama Mermaid, una exportación de Excalidraw o un esquema en texto plano. También encaja mal si tu diagrama depende de comportamientos avanzados y específicos de una app que no estén representados en el formato base de JSON Canvas.

Cómo mejorar la skill json-canvas

Dale al modelo un plan de tablero, no solo un tema

La mayor mejora de calidad llega cuando nombras explícitamente nodos y aristas. En lugar de “make a system architecture canvas,” proporciona:

• servicios
• dependencias
• enlaces externos
• lógica de agrupación
• orden de lectura preferido

Esto mejora tanto la validez como las decisiones de diseño, y hace que la json-canvas guide resulte más accionable en la práctica.

Evita los fallos habituales de json-canvas

Los problemas más comunes son atributos obligatorios ausentes, agrupaciones vagas y diseños difíciles de leer. Para reducirlos:

• pide solo JSON .canvas válido
• solicita IDs de nodo únicos
• especifica una dirección aproximada del canvas
• separa las aristas que “deben conectarse” de los enlaces visuales opcionales
• indica si los grupos deben contener nodos espacialmente

Si tu tablero se abre pero se ve mal, puede que la estructura sea válida aunque el posicionamiento sea deficiente.

Itera en dos pasadas para obtener mejores resultados

Una buena decisión de json-canvas install suele depender de si la skill permite iterar con eficiencia. Aquí sí, siempre que la uses por etapas:

• pasada 1: nodos y aristas correctos a nivel de esquema
• pasada 2: ajustar coordenadas, anchuras, alturas y grupos
• pasada 3: reordenar nodos si el apilado visual importa

Como el orden del array de nodos afecta al z-index, pídelo de forma explícita cuando quieras grupos detrás del contenido o etiquetas por encima.

Qué pedir después del primer borrador

Tras la generación inicial, mejora el resultado con ediciones concretas:

• “Convert these URLs to link nodes.”
• “Wrap these five nodes in a group node.”
• “Reposition nodes to reduce edge crossings.”
• “Keep the same IDs but add missing dependency edges.”
• “Put groups on lower z-index than text nodes.”

Ese tipo de seguimiento acotado da mejores resultados que regenerar todo el tablero desde cero.