json-canvas

json-canvas 스킬 개요

json-canvas 스킬이 하는 일

json-canvas 스킬은 Obsidian 같은 다이어그램 도구에서 사용하는 JSON Canvas 형식에 맞는 유효한 .canvas 파일을 에이전트가 만들거나 수정하도록 도와줍니다. 이 스킬의 핵심은 “보기 좋게 그리기”가 아니라, 캔버스 앱이 실제로 열 수 있는 구조적으로 올바른 canvas JSON을 만드는 데 있습니다. 즉, 노드, 엣지, 그룹, 위치, 크기, 레이어 순서까지 포함해 형식에 맞게 생성하는 것이 목적입니다.

어떤 사용자가 json-canvas를 설치하면 좋은가

이 json-canvas skill은 보드에 어떤 내용을 담을지 이미 알고 있지만, 스키마를 직접 손으로 작성하고 싶지는 않은 사용자에게 특히 잘 맞습니다. 노트 정리, 마인드맵, 플로우차트, 아키텍처 스케치, 리서치 보드, 가벼운 다이어그램 작업처럼 결과물이 단순한 설명문이 아니라 실제 .canvas 파일이어야 하는 워크플로에 적합합니다.

왜 일반적인 프롬프트보다 나은가

일반 프롬프트는 형식을 거의 맞추다가도 필수 필드, 노드 타입, 배열 구조를 빠뜨리는 경우가 많습니다. json-canvas가 유용한 이유는 JSON Canvas의 객체 모델 자체를 중심에 두기 때문입니다. 최상위 nodes와 edges, 네 가지 노드 타입(text, file, link, group), 그리고 node 배열 순서에 따라 z-order가 달라지는 실무적인 디테일까지 반영합니다. 그래서 단순한 mock JSON이 아니라 Obsidian에서 바로 다이어그램으로 열 수 있는 결과가 필요할 때 후처리 부담을 줄여줍니다.

json-canvas 스킬 사용 방법

json-canvas를 설치할 상황과 호출해야 하는 시점

에이전트 플랫폼이 GitHub 스킬을 지원한다면, 평소 사용하던 스킬 설치 흐름으로 MarsWang42/OrbitOS의 json-canvas를 추가하면 됩니다. 저장소에서 확인되는 자료는 SKILL.md뿐이므로, 헬퍼 스크립트나 validator보다는 형식 가이드 중심의 간결한 스킬이라고 보는 편이 맞습니다. 작업 요청에 .canvas, JSON Canvas, Obsidian Canvas가 명시되거나, 최종 결과가 편집 가능한 canvas JSON이어야 하는 시각화 작업일 때 호출하는 것이 좋습니다.

어떤 입력이 json-canvas를 잘 활용하게 만드는가

이 스킬은 단순히 주제만 주는 것보다, 다이어그램의 의도를 함께 줄 때 가장 잘 작동합니다. 좋은 입력에는 보통 다음이 포함됩니다.

• 표현할 노드 목록 또는 섹션
• 노드 사이의 관계
• 원하는 노드 타입: text, file, link, group
• 대략적인 배치 방향: left-to-right, top-down, clustered
• 그룹이 관련 노드를 시각적으로 감싸야 하는지 여부
• file 또는 link 노드를 쓸 경우 파일 참조나 URL

약한 프롬프트:
“Make a canvas for my project.”

더 강한 프롬프트:
“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.”

대략적인 목표를 실제로 쓸 만한 프롬프트로 바꾸는 방법

안정적인 json-canvas usage를 원한다면, 내용과 구조를 함께 지정해야 합니다. 실전에서 쓰기 좋은 프롬프트 패턴은 다음과 같습니다.

1. 보드의 목적을 정의합니다.
2. 노드 카테고리를 나열합니다.
3. 핵심 엣지를 명시합니다.
4. 레이아웃 규칙을 지정합니다.
5. 유효한 .canvas JSON만 출력하라고 요청합니다.

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

먼저 읽어야 할 파일과 워크플로 팁

먼저 EN/.agents/skills/json-canvas/SKILL.md를 읽는 것이 좋습니다. 특히 다음 항목에 집중하세요.

• 최상위 파일 구조
• 노드 타입과 필수 필드
• 엣지 모델링 방식
• node 배열 순서를 통한 z-index 처리

실용적인 워크플로는 다음과 같습니다.

1. 먼저 노드 목록을 초안으로 정리합니다.
2. 최소한의 canvas를 생성합니다.
3. 캔버스 앱에서 직접 열어봅니다.
4. 두 번째 패스에서 레이아웃, 그룹, 누락된 링크를 수정합니다.

처음부터 완성도 높은 최종 보드를 한 번에 만들라고 하기보다, 이렇게 진행하는 편이 더 낫습니다. 시각적인 다듬기 전에 형식의 유효성을 검증하는 쪽이 훨씬 쉽기 때문입니다.

json-canvas 스킬 FAQ

json-canvas는 Obsidian 전용 다이어그램 스킬인가?

아니요. json-canvas for Diagramming은 대상 앱이 JSON Canvas 스펙을 읽을 수 있기만 하면 어디서든 잘 맞습니다. Obsidian이 가장 대표적인 사례이긴 하지만, 이 스킬의 본질적인 가치는 Obsidian 전용 스타일 트릭이 아니라 표준 기반의 .canvas 생성에 있습니다.

LLM에게 그냥 JSON을 직접 쓰라고 하는 것보다 나은가?

대체로 그렇습니다. 최종 결과물이 오류 없이 로드되어야 한다면 특히 더 그렇습니다. 아주 작은 예시는 일반 프롬프트로도 가능하지만, 이 스킬은 모델의 출력을 실제 canvas 스키마와 노드 의미론 쪽으로 더 좁혀 줍니다. 노드 타입이 여러 개 섞이거나, 그룹 영역이 들어가거나, 엣지가 많아지는 순간 이 차이가 커집니다.

json-canvas는 초보자에게도 적합한가?

네, 만들고 싶은 보드의 구조를 스스로 이해하고 있다면 충분히 적합합니다. 스펙을 깊이 알 필요는 없지만, 개체와 관계를 분명하게 설명할 수는 있어야 합니다. 아직 어떤 노드와 흐름이 필요한지 정리되지 않았다면 결과는 나오겠지만, 수작업으로 크게 손봐야 할 가능성이 높습니다.

언제는 json-canvas 스킬을 쓰지 않는 편이 좋은가?

정적인 이미지, Mermaid 다이어그램, Excalidraw export, 또는 일반 텍스트 아웃라인만 필요하다면 굳이 쓸 필요가 없습니다. 또한 기본 JSON Canvas 형식에 없는 고급 앱 전용 동작에 의존하는 다이어그램이라면 이 스킬은 잘 맞지 않습니다.

json-canvas 스킬을 더 잘 활용하는 방법

주제만 말하지 말고 보드 설계를 함께 주기

가장 큰 품질 향상은 노드와 엣지를 명시적으로 지정할 때 생깁니다. “make a system architecture canvas”라고만 하지 말고, 다음을 함께 주는 편이 좋습니다.

• 서비스 목록
• 의존 관계
• 외부 링크
• 그룹핑 기준
• 원하는 읽기 순서

이렇게 해야 유효성뿐 아니라 레이아웃 판단도 좋아지고, 실제 작업에서 json-canvas guide를 훨씬 바로 활용할 수 있게 됩니다.

json-canvas에서 자주 생기는 실패 패턴 줄이기

가장 흔한 문제는 필수 속성 누락, 모호한 그룹 구성, 읽기 어려운 레이아웃입니다. 이를 줄이려면 다음을 요청하세요.

• 유효한 .canvas JSON만 출력하기
• 고유한 node ID 사용하기
• 대략적인 canvas 진행 방향 지정하기
• 반드시 연결해야 하는 엣지와 선택적 시각 링크를 구분하기
• 그룹이 노드를 공간적으로 감싸야 하는지 명시하기

보드는 열리는데 모양이 이상하다면, 구조는 유효하지만 좌표 배치가 좋지 않은 경우일 수 있습니다.

더 나은 결과를 위해 두세 번 나눠서 반복하기

좋은 json-canvas install 판단은 이 스킬이 반복 수정에 얼마나 효율적인지도 좌우합니다. 이 스킬은 단계적으로 쓰면 그 장점이 분명합니다.

• 1차: 스키마에 맞는 nodes와 edges 생성
• 2차: 좌표, 너비, 높이, groups 다듬기
• 3차: 시각적 쌓임 순서가 중요하면 node 순서 재정렬

node 배열 순서가 z-index에 영향을 주므로, 그룹을 콘텐츠 뒤에 두고 싶은지, 라벨을 위로 올리고 싶은지처럼 원하는 시각적 우선순위를 구체적으로 요청하는 것이 좋습니다.

첫 초안 이후에는 무엇을 요청해야 하는가

초기 생성 후에는 전체를 다시 만들기보다, 목적이 분명한 수정 요청이 결과를 더 좋게 만듭니다.

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

이런 식의 제약 있는 후속 요청이, 보드를 처음부터 통째로 다시 생성하는 것보다 대체로 더 좋은 결과를 냅니다.