xiaopixuan/drawio-diagram-skill

Draw.io Diagram Skill

개요

draw.io Desktop 앱의 CLI를 사용하여 .drawio XML 파일을 생성하고 로컬에서 PNG/SVG/PDF/JPG로 내보냅니다.

지원 형식: PNG, SVG, PDF, JPG — 브라우저 자동화 불필요

PNG, SVG, PDF 내보내기는 --embed-diagram (-e)를 지원합니다. 내보낸 파일에 전체 다이어그램 XML이 포함되므로, draw.io에서 열면 편집 가능한 다이어그램이 복구됩니다. 확장명을 두 번 사용(name.drawio.png)하여 XML이 포함되었음을 나타냅니다.

공유 시 설치 참고 사항

이 스킬을 다른 사용자와 공유할 때는 SKILL.md뿐만 아니라 전체 drawio-diagram-skill/ 폴더를 포함해야 합니다. 참조되는 scripts/, references/, 스타일 및 번들 도우미가 워크플로우의 일부이기 때문입니다.

이 스킬은 로컬 PNG/SVG/PDF 내보내기를 위해 draw.io Desktop이 필요합니다. diagrams.net 웹 앱만으로는 로컬 CLI 내보내기에 충분하지 않습니다.

권장 설치:

brew install --cask drawio
drawio --version

Homebrew 또는 명령줄 다운로드가 느린 경우, GitHub Releases에서 draw.io Desktop을 수동으로 다운로드하세요:

https://github.com/jgraph/drawio-desktop/releases

운영 체제에 맞는 설치 프로그램을 선택하세요:

• macOS: .dmg
• Windows: .exe
• Linux: .deb 또는 .rpm (가능하면 snap은 피하세요)

설치 후 CLI를 확인하세요:

drawio --version

macOS에서 drawio가 PATH에 없으면 다음을 시도해 보세요:

/Applications/draw.io.app/Contents/MacOS/draw.io --version

Graphviz는 선택 사항이며, 일부 자동 레이아웃 워크플로우에만 필요합니다:

brew install graphviz

샌드박스 환경에서 draw.io CLI를 사용할 수 없거나 충돌하는 경우, 이 스킬은 여전히 .drawio XML과 diagrams.net 편집 링크를 생성할 수 있지만, 로컬 이미지/PDF 내보내기는 샌드박스 외부에서 수행해야 할 수 있습니다.

draw.io 사용자 프롬프트 누락 시

의존성 검사에서 draw.io Desktop이 설치되지 않았거나 drawio / draw.io 명령을 찾을 수 없는 경우, 단순히 "내보내기 불가"라고 말하지 마세요. 사용자에게 명확히 알리세요:

你现在没有安装 draw.io Desktop，或当前环境找不到 drawio 命令。我可以给你的 Agent 发送安装命令来安装，也可以由你手动安装。

그런 다음 다음 옵션을 제시하세요:

• Agent 설치 명령: macOS에서 brew install --cask drawio
• 수동 설치: https://github.com/jgraph/drawio-desktop/releases에서 draw.io Desktop을 다운로드한 후, 사용자 OS에 맞는 .dmg, .exe, .deb 또는 .rpm을 설치하세요.
• 내보내기 없이 계속: .drawio XML과 diagrams.net 편집 링크를 생성한 후, 사용자가 draw.io를 설치한 후 PNG/SVG/PDF로 내보내도록 합니다.

예상 출력

저장된 .drawio 소스 경로와 모든 내보내기 아티팩트 경로를 반환합니다. 내보내기를 사용할 수 없는 경우 .drawio XML 경로와 사용된 특정 대체 방법을 반환합니다. 사용자 검토를 위해 다이어그램 유형, 주요 레이아웃 선택, 그리고 내보내기 또는 유효성 검사 제한 사항에 대한 간단한 메모를 포함합니다.

사용 시기 / 사용하지 않아야 할 시기

이 스킬을 사용해야 하는 경우: 정교하고 정확한 다이어그램(아키텍처, 네트워크, 엄격한 UML, ERD), 단색 불투명 채움, 10,000개 이상의 스톡/브랜드 셰이프, 스윔레인, 사용자 정의 지오메트리가 필요하고 편집 가능한 PNG/SVG/PDF로 내보내야 하는 경우.

사용하지 말고 다른 곳으로 안내해야 하는 경우:

• 캐주얼한 손그림/화이트보드 스타일 → excalidraw 또는 tldraw
• Git에 저장되고 Markdown에서 렌더링되는 다이어그램을 코드로 → mermaid(일반) 또는 plantuml(UML)
• 자유로운 무한 캔버스 스케치 또는 자유형 선 → tldraw

보고서 스타일 / 경영진 다이어그램

사용자가 汇报型流程架构图, 方案图, 管理闭环图, 领导汇报图 또는 리터럴한 시스템이나 데이터 흐름보다는 조직/역할/메커니즘을 설명하는 다이어그램을 요청할 때 이 모드를 사용하세요.

규칙:

• 다이어그램을 단순한 순서도가 아닌 섹션으로 나누어진 내러티브로 취급하세요.
• 그리기 전에 요약, 역할 흐름, 공통 기반, 메커니즘과 같은 2-4개의 수평 밴드를 계획하세요.
• 각 밴드 내에서 균일한 카드 크기를 사용하고, 카드의 x/y 위치를 정렬하며 간격을 일관되게 유지하세요.
• 하나의 큰 단락 대신 정렬된 셀에 카드 제목, 설명, 글머리 기호 점 및 글머리 기호 텍스트를 분리하세요.
• 카드를 배치하기 전에 행과 열 사이에 명시적인 화살표 통로를 확보하세요.
• 행 간 화살표는 행 사이의 빈 밴드를 통해 라우팅하고, 웨이포인트를 사용하여 선이 레이블과 카드 내용물에서 멀어지도록 유지하세요.
• 내보내기 전에 시각적 계층 구조를 검증하세요: 페이지 제목 > 섹션 제목 > 카드 제목 > 본문 > 글머리 기호.
• 절제된 보고서 스타일을 선호하세요: 깔끔한 채움, 명확한 섹션 표시, 크고 읽기 쉬운 텍스트, 장식적인 복잡함 없음.

번들 리소스

워크플로우가 다음 중 하나를 참조하는 경우, 필요할 때 읽으세요 — 미리 컨텍스트에 둘 필요는 없습니다.

파일	읽는 시점
references/toolbox.md	어떤 번들 스크립트가 요청에 적합한지 확신이 없거나 여러 개를 연결하고 싶을 때 — 모든 31개 스크립트를 사용 사례별로 그룹화한 맵(작성 / 코드 가져오기 / IaC 가져오기 / API 스펙 가져오기 / 라이브 인프라 / 비교 / 주석 / 역내보내기 / 유틸리티)과 "X가 있고, Y를 원한다 → Z 사용" 가이드
references/xml-authoring.md	.drawio XML을 수동으로 작성하려고 할 때(워크플로우 3단계) — 파일 스켈레톤, 셰이프/엣지 셀, 컨테이너, 연결 분배, 팔레트, 간격/그리드 규칙. 번들 생성기가 XML을 작성할 때는 필요하지 않음
references/mermaid-authoring.md	다이어그램이 사용자 정의 스타일링/아이콘이 필요 없는 표준 유형이고(순서도, 상태, 간트, 마인드맵, 타임라인, 저니, 파이 등) CLI가 ≥ v30인 경우 — Mermaid 텍스트로 작성하고 CLI가 네이티브 .drawio로 변환하도록 함(구조만, 레이아웃은 자유). 또한 XML에 대한 CLI의 ELK --layout 패스를 문서화함
references/diagram-types.md	사용자가 특정 다이어그램 유형(ERD, UML 클래스, 시퀀스, C4, 아키텍처, ML/DL, 순서도, SysML, BPMN, 네트워크 토폴로지, 스윔레인)을 지정할 때
references/shapes.md + scripts/shapesearch.py	다이어그램이 특정 셰이프를 필요로 할 때 — 클라우드 아이콘(AWS/Azure/GCP), Cisco/Kubernetes/네트워크 기호, UML/BPMN/ER/전기/P&ID 요소 — 또는 다른 방법으로 style= 문자열을 추측할 때. shapesearch.py "<keywords>"는 10,000개 이상의 셰이프에 대한 공식 스타일을 반환함
scripts/aiicons.py	다이어그램에 AI/LLM 브랜드가 포함될 때(OpenAI, Claude, Gemini, Mistral, Llama, HuggingFace, Ollama, LangChain 등) — aiicons.py "<brand>"는 브랜드 로고에 대한 draw.io image 스타일을 반환함(CDN을 통한 lobe-icons; 인라인하려면 --embed). draw.io에는 내장 AI 로고가 없음. references/shapes.md → "AI / LLM brand logos" 참조
references/style-presets.md	사용자가 스타일 프리셋을 학습 / 저장 / 나열 / 기본 설정 / 삭제하도록 요청하거나, 활성 프리셋을 확인하고 적용 규칙이 필요할 때
references/style-extraction.md	학습 흐름 내에서 추출 절차가 필요할 때(style-presets.md에서 호출됨)
references/troubleshooting.md	내보내기가 실패하거나, 비전이 PNG를 거부하거나, 렌더링이 잘못 보일 때
scripts/repair_png.py	모든 -e PNG 내보내기 후 — draw.io의 잘린 IEND 청크 수정(이슈 #8)
scripts/encode_drawio_url.py	CLI를 사용할 수 없고 브라우저 대체 diagrams.net URL이 필요할 때(--edit는 편집 가능한 편집기 URL)
references/autolayout.md	다이어그램이 크거나 레이아웃이 복잡할 때(의존성/호출 그래프, 코드 구조, >~15개 노드) — 좌표를 수동으로 배치하는 대신 Graphviz가 노드를 배치하고 엣지를 라우팅하도록 하고 싶을 때
scripts/pyimports.py · jsimports.py · goimports.py · rustimports.py	사용자가 Python, JS/TS, Go 또는 Rust 프로젝트 구조를 시각화하려고 할 때 — 가져오기 그래프 추출(전이적 축소, 선택적 --group 컨테이너, 하위 패키지별 중첩)하여 자동 레이아웃에 사용
scripts/pyclasses.py	사용자가 Python 클래스 계층 구조 / 클래스 다이어그램을 원할 때 — 클래스 + 상속 엣지 추출(--group으로 모듈별로 상자 표시)하여 자동 레이아웃에 사용
scripts/tfimports.py · k8simports.py · composeimports.py	사용자가 선언된 인프라(Terraform .tf, Kubernetes 매니페스트 또는 docker-compose)를 시각화하려고 할 때 — 리소스/서비스 참조 그래프 추출(tf/k8s의 경우 공식 AWS/Azure/GCP/K8s 아이콘; compose의 경우 서비스 상자 + 볼륨 실린더)하여 자동 레이아웃에 사용
scripts/tfstate.py · dockerimports.py (+ k8simports.py)	사용자가 실제로 실행 중이거나 배포된 것을 그리고 싶을 때 — terraform show -json(배포된 상태), docker inspect $(docker ps -q)(실행 중인 컨테이너) 또는 kubectl get all,ing,cm,secret,pvc -o json(실행 중인 클러스터, k8simports 통해)을 파이프로 연결하고 동일한 공식 아이콘으로 실제 토폴로지를 얻음. references/live-infra.md 참조
scripts/drawiodiff.py	사용자가 두 다이어그램 또는 두 스냅샷을 비교/차이(diff) 하고 싶을 때("무엇이 변경되었는지", 인프라 드리프트) — drawiodiff.py old.drawio new.drawio -o diff.json은 컬러 코드 그래프(추가=녹색, 제거=빨간색, 변경=주황색, 동일=회색)를 생성하여 자동 레이아웃에 사용. 셀 ID(임포터/라이브 스냅샷 출력) 또는 --by-label(수동 그림)로 일치시킴
scripts/timelapse.py	사용자가 아키텍처 타임랩스 / git 히스토리를 통해 코드베이스 구조가 어떻게 진화했는지 보고 싶을 때 — timelapse.py <dir> --importer pyimports는 샘플링된 각 커밋에서 임포터를 재실행하고 자체 포함된 HTML 플레이어(내장 프레임, 재생/스텝 컨트롤)를 조립함. 실제 가져오기 엣지가 있는 패키지에 가장 적합함(<dir>을 모듈 루트로 지정)
scripts/explain.py	사용자가 기존 .drawio를 글로 설명 / 문서화 / 요약하고 싶을 때(생성의 역) — explain.py diagram.drawio는 구조화된 Markdown을 출력함: 컨테이너/계층별로 그룹화된 구성 요소, 관계(A —label→ B), 다중 페이지/C4의 경우 페이지별 섹션. README/PR 요약 또는 텍스트 전용 읽기에 적합함
scripts/drawio2pptx.py	사용자가 다이어그램에서 PowerPoint 슬라이드를 원할 때 — drawio2pptx.py diagram.drawio -o deck.pptx는 각 페이지를 자체 16:9 슬라이드(페이지 이름이 제목)에 배치하므로, 다중 페이지 C4 모델이 바로 발표 가능한 데크가 됨. python-pptx 필요(pip install python-pptx) + draw.io CLI
scripts/drawiohtml.py	사용자가 다이어그램의 공유 가능한 대화형 뷰어를 원할 때(이동/확대/검색, draw.io 불필요) — drawiohtml.py diagram.drawio -o viewer.html은 각 페이지의 SVG를 하나의 자체 포함 HTML에 인라인으로 포함하고 페이지 탭, 드래그 패닝, 휠 줌, 노드 검색(Enter로 순환 및 일치 항목 중앙에 배치) 및 작동하는 드릴다운 링크(C4 모델의 data:page/id 링크가 탭 전환)를 제공함. 서버, 외부 요청 없음 — 파일을 누구에게나 보낼 수 있음
scripts/svgflow.py	사용자가 애니메이션 / "흐르는" 다이어그램을 원할 때(데이터 흐름, 이동 엣지) — svgflow.py diagram.drawio -o flow.svg는 SVG로 내보내고 모든 엣지를 행진하는 개미 애니메이션(대시가 화살표를 따라 이동)으로 만듦. GitHub / 모든 브라우저에서 렌더링되는 자체 포함 루핑 .svg; --speed / --dash / --reverse 지원
scripts/drawio2mermaid.py	사용자가 .drawio를 Mermaid 텍스트로 변환하고 싶을 때(GitHub에서 렌더링하는 Markdown 파일용 다이어그램을 코드로) — drawio2mermaid.py diagram.drawio는 flowchart를 출력함(컨테이너 → subgraph, 엣지 레이블 유지, 실린더/마름모 셰이프 매핑); --fenced는 ```mermaid로 감싸고, 다중 페이지는 페이지당 하나의 그래프. 구조만 해당(스타일링/아이콘은 유지되지 않음)
scripts/sqlerd.py	사용자가 SQL DDL에서 ER 다이어그램을 원할 때 — CREATE TABLE 문을 파싱하여 테이블별 노드(PK/FK 마커가 있는 열)와 까마귀발 FK 엣지를 생성하여 자동 레이아웃에 사용
scripts/ciimports.py	사용자가 CI 파이프라인 다이어그램을 원할 때(GitHub Actions 워크플로우 또는 GitLab CI) — ciimports.py <repo-root>는 .github/workflows/*.yml + .gitlab-ci.yml을 읽고 작업(러너, 매트릭스 크기, 재사용 가능한 워크플로우 호출), needs: 의존성 엣지, 워크플로우별 트리거 노드 및 스테이지/워크플로우 컨테이너를 추출하여 자동 레이아웃에 사용. PyYAML 필요
scripts/openapiimports.py	사용자가 OpenAPI / Swagger 스펙에서 API 다이어그램을 원할 때 — openapiimports.py spec.yaml은 각 작업을 HTTP 메서드별로 색상화된 노드(GET 파란색, POST 녹색, PUT/PATCH 주황색, DELETE 빨간색)에 매핑하고, 컴포넌트 스키마당 하나의 노드를 추가하며, 작업이 사용하는 스키마와 중첩 스키마 간의 엣지를 추가함. --group은 태그별로 상자 표시, --no-schemas는 엔드포인트 표면만 표시; 자동 레이아웃에 사용
scripts/heatmap.py	사용자가 데이터로 기존 .drawio를 색상화하고 싶을 때(비용/지연 시간/트래픽/오류율 히트 맵) — heatmap.py diagram.drawio -m metrics.csv는 각 메트릭(CSV key,value 또는 JSON {key:value})을 ID 또는 레이블로 노드에 일치시키고 그라데이션에 따라 다시 색칠함(`--palette heat
scripts/seqlayout.py	사용자가 시퀀스 다이어그램을 원할 때 — 참가자 + 메시지를 JSON으로 설명하면 스크립트가 모든 라이프라인/활성화/화살표 지오메트리를 결정적으로 계산함(수동 배치 좌표 불필요, Graphviz 불필요)
scripts/c4.py	사용자가 C4 모델을 원할 때(System Context / Container / Component) — 레벨 JSON을 입력으로 받아 하나의 다중 페이지 .drawio를 출력하며, 공식 C4 셰이프/색상과 레벨 간 클릭하여 드릴다운하는 링크 포함
scripts/relabel.py	사용자가 기존 .drawio의 언어 변형 또는 대량 텍스트 교체를 원할 때(예: 이중 언어 README를 위해 영어 다이어그램을 중국어로 다시 레이블링) — relabel.py diagram.drawio --extract -o labels.json은 모든 레이블을 ID JSON 맵으로 덤프함; 값만 번역(키는 유지), 그런 다음 relabel.py diagram.drawio --map labels.json -o diagram_cn.drawio는 레이아웃/스타일/ID를 그대로 두고 교체함
scripts/restyle.py	사용자가 기존 .drawio를 리테마하고 싶을 때("어둡게 만들어 줘", "이 다이어그램에 내 회사 스타일을 적용해 줘") — restyle.py diagram.drawio --preset <name>은 모든 정점 채우기/선을 색조별로 프리셋 팔레트에 다시 매핑하고, 글꼴/추가 기능(어두운 fontColor, 엣지 색상, 배경)을 적용하며, 레이아웃, 셰이프 및 엣지 라우팅은 그대로 둠. 프리셋은 Step 0과 같이 해석됨(사용자 디렉토리, 그 다음 내장)
scripts/validate.py	.drawio를 생성한 후(특히 자동 레이아웃 또는 대규모 수동 배치 다이어그램의 경우) 내보내기 전에 빠른 결정적 구조 린트를 원할 때(매달린 엣지, 중복/예약된 id, 깨진 부모, 겹침) — validate.py diagram.drawio는 JSON 리포트를 출력함(--quiet는 오류만, --fix는 일부(중복 id, 깨진 부모) 자동 수정). 사람이 한눈에 알아차리지 못할 문제를 잡아내므로, 항상 내보내기 직전에 실행하는 것을 권장함

스크립트 실행

모든 번들 스크립트는 이 스킬의 scripts/ 디렉토리에 있습니다. 스크립트가 종속성을 위해 다른 곳에서 모듈/패키지를 가져오는 경우를 제외하고는 python3 scripts/<script_name>.py를 사용하여 실행해야 합니다.

스크립트가 scripts/ 내부 또는 외부의 다른 파일을 참조하는 경우, SKILL.md 디렉토리를 기준으로 하는 절대 경로를 사용하세요(<skill_dir>은 이 파일이 있는 디렉토리를 나타냄).

모든 스크립트는 python3 <skill_dir>/scripts/<script_name>.py를 사용하여 어디서나 실행할 수 있습니다.