draw-io

draw-io 스킬 개요

draw-io 스킬은 .drawio 다이어그램을 XML 수준에서 만들고, 수정하고, 검토한 뒤 문서나 슬라이드에 쓸 수 있도록 .drawio.png로 내보내는 데 초점을 맞춘 워크플로입니다. draw.io UI를 일일이 클릭하지 않고도 반복 가능하게 다이어그램을 업데이트해야 하는 개발자, 기술 문서 작성자, 솔루션 아키텍트, AI 사용자에게 특히 잘 맞는 draw-io 스킬입니다.

draw-io가 가장 잘하는 일

이 draw-io skill은 다음과 같은 상황에서 특히 강합니다.

• 기존 .drawio 파일을 안전하게 수정하기
• XML 좌표를 조정해 레이아웃을 정밀하게 바꾸기
• 글꼴 설정 같은 다이어그램 표준을 일관되게 적용하기
• 고해상도 투명 PNG 생성하기
• 올바른 mxgraph.aws4.* 식별자로 AWS 아키텍처 아이콘 사용하기

실제로 해결하는 핵심 작업

대부분의 사용자는 추상적인 의미의 “다이어그램 생성”을 원하는 것이 아닙니다. 필요한 것은 아키텍처 다이어그램을 신뢰성 있게 업데이트하고, 스타일을 일관되게 유지하며, 문서화 파이프라인에 바로 넣을 수 있는 내보내기 결과물을 만드는 일입니다. draw-io가 유용한 이유는 이 과정을 막연한 프롬프트가 아니라 구체적인 워크플로로 바꿔주기 때문입니다.

일반적인 프롬프트와 draw-io가 다른 점

보통 프롬프트는 다이어그램 아이디어 정도는 만들어낼 수 있습니다. 하지만 이 스킬은 실제 운영에 필요한 규칙까지 포함합니다.

• 생성된 .drawio.png가 아니라 .drawio XML을 수정하기
• 검증된 CLI 설정으로 PNG 내보내기
• 슬라이드 호환성을 위해 font-family를 명시적으로 적용하기
• 그룹화, 흐름 방향, 가독성에 대한 레이아웃 가이드를 따르기
• 아이콘 이름을 추측하지 말고 로컬 참조에서 AWS 아이콘 찾기

어떤 사용자가 설치하면 좋은가

이미 Git에서 draw.io 파일을 관리하고 있거나, 소스에서 문서나 슬라이드를 생성하거나, 아키텍처 다이어그램을 프로그래밍 방식으로 업데이트해야 한다면 draw-io를 설치할 가치가 큽니다. 반대로 GUI에서 한 번 가볍게 시각적 브레인스토밍만 하고 싶다면, 이 스킬은 필요 이상으로 절차적일 수 있습니다.

draw-io 스킬 사용 방법

draw-io 스킬 설치

스킬 매니저를 사용해 저장소에서 추가하세요.

npx skills add softaworks/agent-toolkit --skill draw-io

환경에 따라 설치 방식이 다르더라도 핵심은 softaworks/agent-toolkit 안의 스킬 경로가 skills/draw-io라는 점입니다.

로컬 선행 조건부터 확인하기

draw-io install에 의존하기 전에, 현재 환경에 다음이 있는지 먼저 확인하세요.

• 내보내기용 drawio CLI
• 변환 스크립트 실행용 bash
• 생성된 PNG를 자동으로 스테이징하려면 git
• 저장소 워크플로에 따라 선택적으로 mise와 pre-commit

제공된 변환 스크립트는 아래 명령을 호출합니다.

drawio -x -f png -s 2 -t -o output.drawio.png input.drawio

즉, export 모드, PNG 형식, 2배 스케일, 투명 배경, 명시적인 출력 경로를 사용한다는 뜻입니다.

먼저 읽어야 할 파일

빠르게 도입하려면 아래 순서대로 확인하는 것이 좋습니다.

1. skills/draw-io/SKILL.md
2. skills/draw-io/README.md
3. skills/draw-io/references/layout-guidelines.md
4. skills/draw-io/references/aws-icons.md
5. skills/draw-io/scripts/convert-drawio-to-png.sh
6. skills/draw-io/scripts/find_aws_icon.py

이 순서가 중요한 이유는, 이 스킬의 가치는 개념 설명보다 실제 운영 규칙, 레이아웃 관례, 보조 스크립트에 더 많이 담겨 있기 때문입니다.

draw-io의 가장 중요한 운영 규칙

사용 시 가장 중요한 제약은 단순합니다.

• .drawio 파일을 수정하기
• .drawio.png 파일을 직접 수정하지 않기

PNG는 생성 산출물로 취급합니다. 저장소가 소스 파일과 내보내기 결과를 둘 다 추적한다면, 에이전트는 XML 소스를 수정한 다음 PNG를 다시 생성해야 합니다.

draw-io가 필요로 하는 입력 정보

draw-io usage의 품질은 어떤 입력을 주느냐에 크게 좌우됩니다. 좋은 입력에는 보통 다음이 포함됩니다.

• 대상 파일 경로
• 새로 만드는지, 기존 파일을 수정하는지
• 다이어그램 유형: architecture, flowchart, sequence-like flow 등
• 읽는 방향: left-to-right 또는 top-to-bottom
• 반드시 들어가야 할 서비스, 노드, 라벨, 연결 관계
• 슬라이드나 문서화 관련 제약
• 공식 AWS 아이콘 사용 여부
• 지금 PNG 내보내기까지 필요한지 여부

이 정보가 없으면 에이전트는 구조, 간격, 명명 방식을 추측할 수밖에 없습니다.

대략적인 목표를 강한 draw-io 프롬프트로 바꾸는 법

약한 프롬프트:

“Update our AWS diagram.”

더 좋은 프롬프트:

“Edit assets/system.drawio. Add Amazon S3 on the left as the ingestion source, route data to AWS Lambda, then to Amazon RDS. Keep a left-to-right flow. Preserve existing group structure. Use official AWS icons, avoid crossing arrows, and regenerate assets/system.drawio.png.”

이 프롬프트가 더 잘 작동하는 이유:

• 파일을 명시합니다
• 추가할 구성 요소를 지정합니다
• 흐름 방향을 지정합니다
• 아이콘 정확성을 요구합니다
• 레이아웃 목표를 포함합니다
• 내보내기 결과물까지 요청합니다

draw-io는 생성용보다 정밀 수정에 더 강하다

이 스킬은 처음부터 다이어그램을 만드는 경우보다, 이미 있는 다이어그램에 정확한 수정이 필요할 때 특히 유용합니다. 예를 들면 다음과 같습니다.

• 선이 겹치지 않도록 특정 클러스터 하나 이동하기
• 서비스 박스를 가로로 정렬하기
• 일반 라벨을 공식 AWS 서비스 이름으로 바꾸기
• 슬라이드 호환성을 위해 글꼴 바꾸기
• XML 수정 후 PNG 다시 생성하기

이런 작업에서는 직접 XML을 수정하는 편이 수작업 UI 편집보다 더 빠르고, 재현성도 높습니다.

슬라이드가 중요하다면 글꼴 설정을 따르기

다이어그램을 Quarto 슬라이드나 글꼴 렌더링 이슈가 있는 환경에서 사용할 예정이라면, 이 스킬은 다음 설정을 권장합니다.

• mxGraphModel의 defaultFontFamily
• 개별 텍스트 요소의 fontFamily

저장소에서는 일본어 지원을 위해 Noto Sans JP를 권장 글꼴로 명시하고 있습니다. 일본어가 필요하지 않더라도 핵심 교훈은 같습니다. 여러 머신과 내보내기 단계에서 결과를 일관되게 유지하려면 글꼴을 명시적으로 지정해야 합니다.

저장소 워크플로에 맞는 변환 경로 사용하기

이 스킬은 PNG 내보내기에 여러 경로를 지원합니다.

• 전체 파일 대상 pre-commit: mise exec -- pre-commit run --all-files
• 단일 파일 대상 pre-commit: mise exec -- pre-commit run convert-drawio-to-png --files assets/my-diagram.drawio
• 스크립트 직접 실행: bash ~/.claude/skills/draw-io/scripts/convert-drawio-to-png.sh assets/diagram1.drawio

선택 기준은 저장소 워크플로입니다. 프로젝트가 이미 pre-commit을 쓰고 있다면 그 경로를 따르는 편이 낫고, 로컬에서 한 번만 빠르게 내보내면 된다면 스크립트 직접 실행이 가장 빠릅니다.

추측하지 말고 AWS 아이콘 참조 사용하기

AWS 비중이 큰 다이어그램에서 draw-io for Design Implementation을 쓴다면, 아이콘 참조는 이 스킬에서 가장 가치 있는 요소 중 하나입니다. 여기에는 다음이 정리되어 있습니다.

• Amazon ECS, AWS Lambda 같은 공식 서비스 명칭
• mxgraph.aws4.*를 사용하는 최신 아이콘 스타일 관례
• 리소스 및 제품 아이콘 패턴

포함된 보조 스크립트로 참조를 검색할 수도 있습니다.

python ~/.claude/skills/draw-io/scripts/find_aws_icon.py lambda

기억에 의존해 resIcon 이름을 만들어내는 것보다 훨씬 안전합니다.

레이아웃 가이드는 의도적으로 적용해야 한다

저장소의 레이아웃 가이드는 형식적인 문서가 아닙니다. 실제 출력 품질을 높여주는 실전 기본값을 제공합니다.

• cloud boundary와 subnet을 명확히 그룹화하기
• 가능하면 주요 흐름을 left-to-right로 유지하기
• 흐름 종류에 따라 다른 선 스타일 사용하기
• 관련 요소끼리는 가깝게 배치하기
• 화살표 교차 줄이기
• 가독성을 위한 여백 충분히 두기

처음 결과물부터 쓸 만한 수준을 원한다면, 이 원칙들 중 어떤 것이 가장 중요한지 에이전트에 분명히 알려주는 것이 좋습니다.

draw-io 스킬 FAQ

draw-io는 초보자에게도 괜찮은가?

네, 이미 draw.io 파일을 가지고 있고 그 파일을 수정하는 데 도움을 받고 싶다면 충분히 유용합니다. 이 스킬은 구체적인 규칙과 스크립트를 제공해 추측을 줄여줍니다. 다만 파일 기반 워크플로 없이 다이어그램 개념만 가볍게 탐색하려는 완전 초보자에게는 그다지 이상적이지 않습니다.

언제 일반 AI 프롬프트보다 draw-io가 더 낫나?

draw-io는 재현 가능한 수정, 올바른 파일 처리, 내보내기 단계, AWS 아이콘 정확성이 필요할 때 더 낫습니다. 일반 프롬프트도 다이어그램을 그럴듯하게 설명할 수는 있지만, .drawio 소스 수정, 내보내기 명령, 글꼴 설정, 보조 스크립트 사용까지 일관되게 강제해주지는 못하는 경우가 많습니다.

draw-io를 쓰려면 draw.io GUI가 꼭 필요한가?

반드시 그렇지는 않습니다. 이 스킬은 소스 파일 편집과 CLI 기반 PNG 내보내기를 중심으로 설계되어 있습니다. 그래서 코드 중심 워크플로, diff 리뷰, 문서화 파이프라인 같은 환경에서도 잘 맞습니다.

언제는 draw-io를 쓰지 말아야 하나?

다음이 필요하다면 이 draw-io guide는 건너뛰는 편이 낫습니다.

• 자유형 화이트보딩
• draw.io 밖에서 만드는 완성형 디자인 목업
• GUI에서의 순수 시각 편집
• .drawio와 무관한 포맷용 다이어그램 생성

이 스킬은 일반 그래픽 디자인 도구가 아니라, draw.io XML과 내보내기 작업에 특화되어 있습니다.

draw-io로 AWS 아키텍처 다이어그램도 도와줄 수 있나?

그렇습니다. 오히려 가장 분명한 강점 중 하나입니다. AWS 아이콘 참조와 조회 스크립트 덕분에 공식 명칭과 mxgraph.aws4.* 아이콘을 정확하게 사용할 수 있어, 일관성과 인지성이 중요한 경우 특히 유용합니다.

draw-io가 나쁜 레이아웃을 자동으로 고쳐주나?

마법처럼 자동으로 해결해주지는 않습니다. 이 스킬은 좌표와 레이아웃을 의도적으로 조정하는 방법을 제공합니다. 그룹화, 흐름 방향, 간격, 겹침 우선순위처럼 배치 의도를 명확히 전달할수록 결과가 좋아집니다.

draw-io 스킬을 더 잘 활용하는 방법

draw-io에 구조적인 입력을 더 강하게 주기

draw-io usage를 가장 빨리 개선하는 방법은 형용사가 아니라 구조를 주는 것입니다. “더 깔끔하게 만들어줘”라고 하기보다 이렇게 말하세요.

• 데이터베이스를 앱 계층 아래로 이동하기
• 모든 ingestion source를 왼쪽 열에 유지하기
• 가능하면 화살표가 교차하지 않게 만들기
• public subnet과 private subnet 리소스를 따로 그룹화하기
• 박스가 지나치게 커지지 않도록 라벨 길이를 짧게 유지하기

이런 지시는 XML과 레이아웃 결정에 직접 연결됩니다.

가능하면 기존 다이어그램에서 시작하기

이 스킬은 완전히 새로 만들어내는 것보다, 기존 .drawio 파일을 수정할 때 가장 좋은 성능을 냅니다. 기존 파일이 있으면 다음 정보들을 활용할 수 있습니다.

• 현재 요소 ID
• 기존 레이아웃 패턴
• 스타일 규칙
• 그룹 구조
• 이미 정해진 내보내기 대상

팀 단위 작업에서는 매번 새 다이어그램을 처음부터 만들게 하는 것보다 이 방식이 보통 더 안정적입니다.

이름과 아이콘 정확성을 명시적으로 요구하기

흔한 실패 패턴 중 하나는 ECS, Lambda처럼 모호한 서비스 이름만 주고, 라벨을 공식 서비스 이름으로 표시할지 결정하지 않는 경우입니다. AWS 다이어그램이 중요하다면 둘 다 명시하세요.

• 표시 라벨: Amazon ECS, AWS Lambda, Amazon RDS
• 아이콘 요구 사항: 공식 mxgraph.aws4.* 서비스 아이콘 사용

이렇게 해야 명명 스타일이 뒤섞이거나 아이콘 매핑이 틀어지는 일을 막을 수 있습니다.

수정 후 내보내기까지 한 번에 요청하기

실제로 바로 쓸 수 있는 결과물이 필요하다면, 소스 수정과 내보내기 단계를 한 지시 안에 함께 넣으세요. 예:

“Update docs/arch.drawio, then regenerate docs/arch.drawio.png with the skill’s standard PNG export settings.”

이렇게 하면 XML만 바뀌고 미리보기 산출물은 오래된 상태로 남는 흔한 문제를 줄일 수 있습니다.

주요 실패 패턴을 미리 점검하기

흔한 draw-io 문제는 개념적인 것보다 실무적인 경우가 대부분입니다.

• .drawio 대신 PNG를 수정하는 경우
• 글꼴 설정을 빼먹어 텍스트 렌더링이 들쭉날쭉해지는 경우
• AWS 아이콘 식별자를 추측해서 쓰는 경우
• 노드를 너무 빽빽하게 배치해 라벨이 충돌하는 경우
• 연결선이 서로 교차해 가독성을 해치는 경우
• 전체 흐름을 유지하지 않은 채 레이아웃만 바꾸는 경우

이 문제 대부분은 프롬프트에서 제공된 스크립트와 가이드를 직접 참조하도록 하면 예방할 수 있습니다.

큰 다이어그램일수록 작고 검토 가능한 변경으로 나누기

복잡한 다이어그램이라면 한 번에 모든 것을 요청하지 마세요. 더 좋은 패턴은 다음과 같습니다.

1. 구조와 그룹화 조정
2. 간격과 연결선 검토
3. 라벨과 글꼴 수정
4. PNG 내보내기
5. 가독성 기준으로 마지막 점검

이 방식은 diff를 더 깔끔하게 만들고, 레이아웃 문제가 그룹화 때문인지, 아이콘 선택 때문인지, 텍스트 크기 때문인지 파악하기도 쉬워집니다.

저장소 보조 파일을 이름까지 정확히 지정해주기

에이전트가 파일 인식 프롬프팅을 지원한다면, 아래 참조를 정확한 이름으로 언급하세요.

• 간격과 흐름 기준: references/layout-guidelines.md
• AWS 명명과 아이콘 기준: references/aws-icons.md
• 아이콘 조회: scripts/find_aws_icon.py
• 내보내기: scripts/convert-drawio-to-png.sh

이 작은 습관만으로도 첫 결과물의 품질이 좋아지는 경우가 많습니다. 에이전트가 일반적인 다이어그램 조언이 아니라, 저장소가 이미 정해둔 규칙을 따르게 되기 때문입니다.