json-canvas

json-canvas 스킬 개요

json-canvas 스킬이 하는 일

json-canvas 스킬은 AI 에이전트가 Obsidian 스타일의 비주얼 보드에서 사용하는 JSON Canvas 1.0 구조를 따르는 .canvas 파일을 만들고 수정하도록 돕습니다. 핵심 가치는 단순히 “다이어그램을 그려준다”는 데 있지 않습니다. 파일이 미묘하게 깨지지 않고 정상적으로 열리도록, 올바른 ID·좌표·참조를 갖춘 유효한 nodes 및 edges JSON을 생성하는 데 있습니다.

json-canvas를 설치하면 좋은 사람

이 json-canvas skill은 결과물이 어떤 형태여야 하는지 이미 알고 있는 사용자에게 가장 잘 맞습니다. 예를 들어 마인드맵, 플로우차트, 프로젝트 보드, 개념도, 노트 캔버스를 만들고 싶지만 스키마를 직접 손으로 작성하고 싶지는 않은 경우입니다. 특히 Obsidian을 쓰거나, .canvas 파일을 repo에서 관리하거나, 일회성 시각화 제안보다 기존 캔버스를 AI로 반복 가능하게 수정하고 싶은 경우에 유용합니다.

일반 프롬프트보다 나은 이유

일반 프롬프트도 박스와 화살표를 설명할 수는 있지만, 실제로 중요한 포맷 세부사항은 자주 놓칩니다. 예를 들면 고유한 16자리 hex ID, 유효한 fromNode 및 toNode 참조, 겹치지 않는 배치, 텍스트 노드와 그룹 노드의 차이 같은 요소입니다. json-canvas 스킬은 에이전트에게 구체적인 대상 포맷과 예시를 제공하므로, 생성 후 수작업으로 고쳐야 하는 일을 줄여줍니다.

도입 전에 알아둘 점

이 스킬은 의도적으로 범위가 좁습니다. .canvas 파일 구조와 자주 쓰는 편집 워크플로에는 강하지만, 완전한 비주얼 레이아웃 엔진이나 의미 중심의 다이어그램 도구, 자동 디자인 최적화 도구를 대체하지는 않습니다. 주된 요구가 세련된 스타일링이나 여러 다이어그램 포맷으로의 내보내기라면 json-canvas for Diagramming은 너무 저수준으로 느껴질 수 있습니다. 반대로, 유효한 canvas JSON을 빠르게 얻는 것이 목적이라면 잘 맞는 선택입니다.

json-canvas 스킬 사용 방법

설치 맥락과 먼저 읽어야 할 파일

skills-enabled 환경에서 json-canvas install을 사용하려면 kepano/obsidian-skills repository에서 해당 스킬을 추가한 뒤, 먼저 skills/json-canvas/SKILL.md를 읽고 그다음 skills/json-canvas/references/EXAMPLES.md를 확인하세요. 이 두 파일이 실질적인 핵심입니다. 앞의 파일은 필요한 구조와 워크플로를 설명하고, 뒤의 파일은 그대로 패턴을 참고할 수 있는 완성 예제를 보여줍니다.

스킬이 잘 작동하려면 어떤 입력이 필요한가

json-canvas usage의 품질은 요청을 얼마나 구체적으로 주느냐에 달려 있습니다. 가능하면 다음을 함께 제공하세요.

• 대상 파일 경로 또는 기존 .canvas 내용
• 새 캔버스를 만들지, 기존 것을 수정할지
• 필요한 노드 타입(text, group 등)
• left-to-right 흐름이나 kanban 컬럼 같은 대략적인 레이아웃 의도
• 노드 간 원하는 연결 관계
• 크기나 간격에 대한 기대치

약한 요청은 “프로젝트 캔버스를 만들어줘”입니다. 더 강한 요청은 다음과 같습니다. “새 .canvas를 만들고, To Do, In Progress, Done이라는 라벨의 그룹 컬럼 3개를 각각 300x500 크기로 배치해. 컬럼 간 간격은 50px로 두고, 앞의 두 그룹 안에는 text 작업 노드 3개를 추가해.”

대략적인 목표를 좋은 프롬프트로 바꾸는 법

좋은 json-canvas guide를 위해서는 생성과 검증을 함께 요청하는 것이 좋습니다. 효과적인 프롬프트 패턴은 다음과 같습니다.

1. 목표를 평이한 영어로 설명합니다.
2. 새로 만들지 수정할지 지정합니다.
3. 필요한 노드 목록과 관계를 정의합니다.
4. 최종 출력 전에 JSON과 edge 참조를 검증하라고 요청합니다.

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

작업 시간을 줄여주는 실전 워크플로 팁

더 나은 json-canvas usage를 원한다면, 처음부터 크게 만들기보다 단순하게 시작한 뒤 점진적으로 다듬는 편이 낫습니다.

• 먼저 구조적으로 유효한 최소 캔버스를 요청합니다.
• 파일을 열어보거나 내용을 확인합니다.
• 그다음 한 번에 하나씩만 변경합니다: 노드 추가, 재그룹화, 재연결, 위치 조정.

기존 파일을 수정할 때는 무엇을 추가하기 전에 현재 ID부터 파싱하라고 에이전트에 명시하세요. 가장 흔한 오류는 ID 충돌과 존재하지 않는 노드를 가리키는 edge입니다. 레이아웃이 중요하다면 간격 규칙을 명확히 요청해야 합니다. 그렇지 않으면 JSON 자체는 유효해도 화면상으로는 지저분하게 배치될 수 있습니다.

json-canvas 스킬 FAQ

json-canvas는 초보자에게도 괜찮은가요?

네, 캔버스에 무엇이 들어가야 하는지만 알고 있다면 충분히 유용합니다. 이 스킬은 스키마를 추측해야 하는 부담을 크게 줄여주기 때문에, 초보자도 명세를 외우지 않고 유효한 .canvas 파일을 만들 수 있습니다. 다만 다이어그램의 논리 자체를 아직 정하지 못한 단계라면 최적의 선택은 아닐 수 있습니다. 이 스킬은 구조를 인코딩하는 데 강하지, 전체 정보 설계를 대신 발명해주지는 않습니다.

일반 AI 프롬프트 대신 언제 json-canvas를 써야 하나요?

출력이 실제로 동작하는 .canvas 파일이어야 할 때, 특히 기존 캔버스를 수정할 때 json-canvas를 쓰는 것이 좋습니다. 일반 프롬프트도 구조를 브레인스토밍하는 데는 도움이 되지만, 정확성이 중요할 때는 이 스킬이 더 낫습니다. 예를 들어 고유 ID, 유효한 배열, 실제 노드 참조, Obsidian 호환 포맷 같은 부분입니다.

json-canvas가 모든 다이어그램 작업을 처리하나요?

아니요. json-canvas for Diagramming은 노드-엣지 기반 캔버스, 단순 보드, 노트 연결형 시각 정리에 가장 적합합니다. BPMN 도구, 발표용으로 다듬어진 그래픽, 고급 자동 레이아웃 시스템의 대체재는 아닙니다. 폭넓은 다이어그램 표준이나 풍부한 스타일 제어가 필요하다면 다른 도구를 쓰고, 필요한 경우에만 변환하는 편이 낫습니다.

주요한 한계나 맞지 않는 경우는 무엇인가요?

대상 결과물이 .canvas 파일이 아니거나, 강한 자동 레이아웃 최적화가 필요하거나, Mermaid·Excalidraw·스프레드시트 같은 다른 형식이 source of truth로 남아 있어야 한다면 이 스킬은 건너뛰는 편이 좋습니다. “예쁘게 만들어줘”처럼 모호한 프롬프트도 피하는 것이 좋습니다. 이 스킬은 구조와 배치 의도가 명확할수록 성능이 좋습니다.

json-canvas 스킬 개선 방법

더 강한 구조 입력을 제공하세요

출력 품질을 가장 크게 끌어올리는 방법은 처음부터 구조 정보를 더 잘 주는 것입니다. 원하는 노드 이름, 노드 사이의 연결, 의도한 공간 배치 패턴을 명시하세요. 예를 들어 “hub-and-spoke”, “three-column board”, “timeline from left to right” 같은 표현은 에이전트가 억지로 추측하지 않고 노드를 더 자연스럽게 배치할 수 있게 해줍니다.

json-canvas의 흔한 실패 패턴을 미리 막으세요

대부분의 json-canvas 문제는 구조적이기보다 기계적인 오류입니다.

• 중복된 ID
• 존재하지 않는 노드를 가리키는 edge
• 겹치는 좌표
• type, x, y, width, height 같은 필수 필드 누락

파일을 반환하기 전에 모든 ID와 참조를 검증하라고 에이전트에 요청하세요. 기존 캔버스를 수정하는 경우에는 새 노드나 edge가 꼭 필요한 상황이 아니라면 기존 ID를 유지하라고 지시하는 것이 좋습니다.

첫 결과물 이후에 단계적으로 다듬으세요

첫 결과물은 완성본이 아니라 발판으로 보는 편이 좋습니다. 그다음 한 층씩 개선하세요.

• 간격과 정렬 조정
• 그룹 추가
• 라벨과 텍스트 내용 다듬기
• 연결 추가 또는 제거

처음부터 복잡한 최종 캔버스를 한 번에 요청하는 것보다 이 방식이 더 잘 작동합니다. 시각 구조의 오류는 큰 결과물을 만든 뒤보다 초기에 훨씬 발견하기 쉽기 때문입니다.

예제와 repository 패턴을 의도적으로 활용하세요

json-canvas skill 결과를 더 좋게 만들고 싶다면 모든 것을 추상적으로 설명하기보다 references/EXAMPLES.md의 패턴을 적극적으로 빌려 쓰세요. 원하는 출력이 프로젝트 보드에 가깝다면 group 기반 패턴을 따르라고 요청하고, 개념도에 가깝다면 단순하게 연결된 text-node 패턴을 요청하세요. repository에서 이미 쓰는 패턴을 재사용하면 JSON이 더 깔끔해지고, 호환성 문제도 줄어드는 경우가 많습니다.