json-canvas

Visão geral da skill json-canvas

O que a skill json-canvas faz

A skill json-canvas ajuda um agente a criar ou editar arquivos .canvas válidos no formato JSON Canvas usado pelo Obsidian e por ferramentas semelhantes de diagramação. O trabalho real dela não é “desenhar algo bonito”, e sim “produzir um JSON de canvas estruturalmente correto, com nodes, edges, groups, posições, tamanhos e camadas que um app de canvas consiga abrir de verdade”.

Quem deve instalar json-canvas

A json-canvas skill é mais indicada para quem já sabe qual conteúdo quer colocar em um board, mas não quer escrever o schema manualmente. Ela se encaixa bem em fluxos de anotações, mapas mentais, fluxogramas, esboços de arquitetura, boards de pesquisa e diagramas leves em que a saída precisa ser um arquivo .canvas real, e não uma descrição em texto de como ele seria.

Por que ela é melhor do que um prompt genérico

Um prompt comum costuma acertar “quase” o formato, mas deixa passar campos obrigatórios, tipos de node ou a estrutura correta dos arrays. json-canvas é útil porque parte do modelo de objetos do JSON Canvas: nodes e edges no nível superior, quatro tipos de node (text, file, link, group) e detalhes práticos como a ordem visual depender da ordem dos nodes no array. Isso reduz o retrabalho quando o objetivo é diagramar no Obsidian, em vez de apenas gerar um JSON de fachada.

Como usar a skill json-canvas

Contexto de instalação e quando acionar json-canvas

Se a sua plataforma de agente oferece suporte a skills do GitHub, adicione json-canvas a partir de MarsWang42/OrbitOS usando o fluxo normal de instalação de skills. Pelas evidências do repositório, só há o arquivo SKILL.md, então espere uma skill enxuta, focada em orientar o formato, e não em fornecer scripts auxiliares ou validadores. Acione a skill quando a tarefa mencionar explicitamente .canvas, JSON Canvas, Obsidian Canvas ou diagramação visual que precise terminar em JSON de canvas editável.

Que tipo de entrada gera um bom uso de json-canvas

A skill funciona melhor quando você fornece a intenção do diagrama, e não apenas o tema. Uma boa entrada normalmente inclui:

• lista de nodes ou seções a representar
• relações entre os nodes
• tipos de node desejados: text, file, link, group
• direção aproximada do layout: da esquerda para a direita, de cima para baixo, em clusters
• se os groups devem conter visualmente os nodes relacionados
• referências de arquivo ou URLs, caso use nodes file ou link

Um prompt fraco: “Make a canvas for my project.”
Um prompt melhor: “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.”

Como transformar um objetivo vago em um prompt utilizável

Para um json-canvas usage confiável, especifique tanto o conteúdo quanto a estrutura. Um padrão prático de prompt é:

1. Defina o objetivo do board.
2. Liste as categorias de nodes.
3. Indique os principais edges.
4. Dê regras de layout.
5. Peça apenas um JSON .canvas válido.

Exemplo:
“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.”

O que ler primeiro e dicas de workflow

Leia primeiro EN/.agents/skills/json-canvas/SKILL.md. Foque em:

• estrutura do arquivo no nível superior
• tipos de node e campos obrigatórios
• modelagem de edge
• ordenação de z-index pela ordem dos nodes no array

Workflow prático:

1. Faça um rascunho do inventário de nodes.
2. Gere um canvas mínimo.
3. Abra o arquivo no seu app de canvas.
4. Corrija layout, agrupamentos ou links faltantes em uma segunda passada.

Isso funciona melhor do que pedir um board finalizado e polido logo de cara, porque a correção do formato é mais fácil de validar antes do refinamento visual.

FAQ da skill json-canvas

json-canvas serve só para diagramar no Obsidian?

Não. json-canvas for Diagramming funciona bem em qualquer contexto em que o app de destino leia a especificação JSON Canvas. Obsidian é o caso mais óbvio, mas o valor central aqui é a geração de arquivos .canvas baseada em padrão, e não algum truque de estilo específico do Obsidian.

Isso é melhor do que pedir para um LLM escrever JSON direto?

Na maioria dos casos, sim, se o produto final precisar abrir sem problemas. Prompt genérico pode funcionar em exemplos pequenos, mas esta skill direciona o modelo para o schema real do canvas e para a semântica dos nodes. Isso faz diferença quando você tem vários tipos de node, regiões agrupadas ou muitas edges.

json-canvas é adequada para iniciantes?

Sim, desde que você entenda o board que quer montar. Não é necessário conhecer a spec em profundidade, mas você precisa descrever com clareza as entidades e os relacionamentos. Se você ainda não consegue listar os nodes ou os fluxos, a skill até vai gerar alguma coisa, mas o resultado pode exigir bastante revisão manual.

Quando eu não devo usar a skill json-canvas?

Evite usar se você só precisa de uma imagem estática, um diagrama Mermaid, uma exportação do Excalidraw ou um outline em texto puro. Ela também é uma escolha fraca se o seu diagrama depender de comportamentos avançados específicos de um app que não estão representados no formato base do JSON Canvas.

Como melhorar a skill json-canvas

Dê ao modelo um plano de board, não só um tema

O maior salto de qualidade vem de nomear nodes e edges de forma explícita. Em vez de “make a system architecture canvas”, forneça:

• serviços
• dependências
• links externos
• lógica de agrupamento
• ordem de leitura preferida

Isso melhora tanto a validade quanto as decisões de layout, e torna o json-canvas guide mais acionável na prática.

Como evitar falhas comuns de json-canvas

Os problemas mais comuns são atributos obrigatórios ausentes, agrupamento vago e layouts difíceis de ler. Para reduzir isso:

• peça apenas JSON .canvas válido
• solicite IDs únicos para os nodes
• especifique a direção aproximada do canvas
• separe edges “obrigatórios” de links visuais opcionais
• diga explicitamente se os groups devem conter os nodes espacialmente

Se o board abre, mas parece errado, a estrutura pode estar válida enquanto o posicionamento continua ruim.

Itere em duas etapas para um resultado melhor

Uma boa decisão de json-canvas install muitas vezes depende de a skill permitir iteração eficiente. Aqui, permite, desde que você use em etapas:

• etapa 1: nodes e edges corretos no schema
• etapa 2: refinamento de coordenadas, larguras, alturas e groups
• etapa 3: reordenação dos nodes se a sobreposição visual importar

Como a ordem dos nodes no array afeta o z-index, peça isso explicitamente quando quiser groups atrás do conteúdo ou labels acima dos demais elementos.

O que pedir depois do primeiro rascunho

Depois da geração inicial, melhore o resultado com edições direcionadas:

• “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.”

Esse tipo de ajuste restrito costuma dar resultados melhores do que regenerar o board inteiro do zero.