draw-io

Tổng quan về skill draw-io

Skill draw-io là một quy trình làm việc chuyên biệt để tạo, chỉnh sửa và rà soát sơ đồ .drawio ở dạng XML, sau đó xuất ra .drawio.png để dùng trong tài liệu hoặc slide. draw-io đặc biệt phù hợp với developer, technical writer, solution architect và người dùng AI cần cập nhật sơ đồ theo cách lặp lại được, ổn định, mà không phải bấm tay qua giao diện draw.io.

draw-io làm tốt nhất những việc gì

draw-io skill này phát huy hiệu quả nhất khi bạn cần:

• chỉnh sửa an toàn các file .drawio có sẵn
• thay đổi bố cục thật chính xác bằng cách chỉnh tọa độ trong XML
• áp chuẩn sơ đồ như thiết lập font
• tạo PNG nền trong suốt, độ phân giải cao
• dùng icon kiến trúc AWS với đúng định danh mxgraph.aws4.*

Nhu cầu thực tế mà draw-io giải quyết

Phần lớn người dùng không thật sự cần “tạo sơ đồ” theo nghĩa chung chung. Họ cần một agent có thể cập nhật sơ đồ kiến trúc đáng tin cậy, giữ style đồng nhất, và tạo ra asset sẵn sàng để đưa vào pipeline tài liệu. draw-io hữu ích vì nó biến nhu cầu đó thành một workflow cụ thể thay vì một prompt mơ hồ.

Điều khiến draw-io khác với một prompt chung chung

Một prompt thông thường có thể chỉ đưa ra ý tưởng sơ đồ. Skill này bổ sung các quy tắc vận hành thực tế:

• chỉnh sửa XML của .drawio, không chỉnh trực tiếp .drawio.png
• xuất PNG bằng các thiết lập CLI đã biết trước
• áp font-family rõ ràng để tương thích tốt với slide
• tuân theo hướng dẫn về nhóm, hướng luồng và độ dễ đọc của bố cục
• tra icon AWS từ tài liệu tham chiếu cục bộ thay vì đoán tên icon

Ai nên cài draw-io

Hãy cài draw-io nếu bạn đã làm việc với file draw.io trong Git, tạo docs hoặc slide từ source, hoặc cần cập nhật sơ đồ kiến trúc bằng quy trình lập trình được. Nếu bạn chỉ muốn brainstorming trực quan một lần trong GUI, thì workflow này có thể là nhiều bước hơn mức bạn cần.

Cách dùng skill draw-io

Cài skill draw-io

Dùng skill manager của bạn để thêm skill này từ repository:

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

Nếu môi trường của bạn dùng installer khác, phần quan trọng cần giữ đúng là đường dẫn skill skills/draw-io trong softaworks/agent-toolkit.

Xác nhận các điều kiện cục bộ cần có

Trước khi dựa vào draw-io install, hãy kiểm tra môi trường của bạn đã có:

• CLI drawio để xuất file
• bash cho script chuyển đổi
• git nếu bạn muốn tự động stage các file PNG được tạo ra
• tùy chọn mise và pre-commit nếu repo của bạn chạy theo workflow đó

Script chuyển đổi đi kèm sẽ gọi:

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

Điều này có nghĩa là chạy ở chế độ export, định dạng PNG, scale 2x, nền trong suốt, và ghi ra đường dẫn output được chỉ định rõ.

Hãy đọc các file này trước

Để vào việc nhanh nhất, hãy xem lần lượt các file sau:

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

Thứ tự này quan trọng vì skill này thiên về vận hành hơn là lý thuyết: phần giá trị lớn nhất nằm ở các rule, quy ước bố cục và script hỗ trợ.

Nắm quy tắc vận hành cốt lõi của draw-io trước

Ràng buộc sử dụng quan trọng nhất rất đơn giản:

• chỉnh file .drawio
• không chỉnh trực tiếp file .drawio.png

PNG được xem là artifact sinh ra từ source. Nếu repo của bạn lưu cả source lẫn bản export, agent nên sửa XML gốc trước rồi tạo lại PNG sau đó.

draw-io cần đầu vào gì

Chất lượng draw-io usage phụ thuộc rất nhiều vào đầu vào bạn cung cấp. Đầu vào tốt thường gồm:

• đường dẫn file đích
• bạn đang tạo mới hay chỉnh sửa
• loại sơ đồ: architecture, flowchart, sequence-like flow, v.v.
• hướng đọc mong muốn: trái sang phải hay trên xuống dưới
• các service, node, label và connection bắt buộc
• các ràng buộc liên quan đến slide hoặc tài liệu
• có cần icon AWS chính thức hay không
• có cần export PNG ngay bây giờ hay không

Nếu thiếu các chi tiết này, agent sẽ phải tự đoán cấu trúc, khoảng cách và cách đặt tên.

Biến một mục tiêu mơ hồ thành prompt draw-io mạnh hơn

Prompt yếu:

“Update our AWS diagram.”

Prompt tốt hơn:

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

Vì sao prompt này hiệu quả hơn:

• nêu rõ file cần sửa
• chỉ rõ các thành phần cần thêm
• xác định hướng luồng
• yêu cầu độ chính xác của icon
• đưa ra mục tiêu bố cục
• yêu cầu tạo artifact export

Dùng draw-io cho chỉnh sửa chính xác, không chỉ để tạo mới

Skill này đặc biệt hữu ích khi bạn đã có sơ đồ và chỉ cần những thay đổi có chủ đích như:

• di chuyển một cluster để tránh chồng lấn đường nối
• căn hàng ngang các service box
• thay một label chung chung bằng tên service AWS chính thức
• đổi font để tương thích tốt với slide
• tạo lại PNG sau khi sửa XML

Đó là lúc chỉnh trực tiếp XML thường nhanh hơn và tái lập được tốt hơn so với thao tác tay trên UI.

Nếu dùng cho slide, hãy tuân thủ thiết lập font

Nếu sơ đồ được dùng trong slide Quarto hoặc môi trường dễ phát sinh lỗi render font, skill khuyến nghị đặt:

• defaultFontFamily trên mxGraphModel
• fontFamily trên từng phần tử văn bản

Repository nêu rõ Noto Sans JP là font được khuyến nghị để hỗ trợ tiếng Nhật. Dù bạn không cần tiếng Nhật, bài học rộng hơn vẫn rất quan trọng: hãy chỉ định font một cách tường minh khi bạn cần đầu ra nhất quán giữa nhiều máy và nhiều bước export.

Chọn đường xuất file phù hợp với workflow của repo

Skill hỗ trợ nhiều cách để export PNG:

• tất cả file qua pre-commit: mise exec -- pre-commit run --all-files
• một file qua pre-commit: mise exec -- pre-commit run convert-drawio-to-png --files assets/my-diagram.drawio
• gọi script trực tiếp: bash ~/.claude/skills/draw-io/scripts/convert-drawio-to-png.sh assets/diagram1.drawio

Hãy chọn cách phù hợp với workflow của repo. Nếu project của bạn đã dùng pre-commit, hãy đi theo đường đó. Nếu bạn chỉ cần export cục bộ một lần, script trực tiếp là cách nhanh nhất.

Dùng tài liệu icon AWS của draw-io thay vì đoán

Nếu bạn đang dùng draw-io for Design Implementation cho các sơ đồ thiên về AWS, thì phần tham chiếu icon là một trong những phần giá trị nhất của skill này. Nó ghi lại:

• cách đặt tên service chính thức như Amazon ECS và AWS Lambda
• quy ước icon hiện tại dùng mxgraph.aws4.*
• các pattern icon cho resource và product

Script hỗ trợ đi kèm có thể tìm trong tài liệu tham chiếu:

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

Cách này an toàn hơn nhiều so với việc tự nghĩ ra tên resIcon theo trí nhớ.

Áp dụng hướng dẫn layout một cách có chủ đích

Hướng dẫn layout trong repository không phải phần cho có. Nó đưa ra những mặc định thực tế giúp cải thiện chất lượng đầu ra:

• nhóm ranh giới cloud và subnet rõ ràng
• giữ luồng chính theo hướng trái sang phải khi có thể
• dùng kiểu đường nối khác nhau cho các loại luồng khác nhau
• đặt các phần tử liên quan gần nhau
• giảm số đường mũi tên giao cắt
• chừa đủ khoảng trắng để tăng độ dễ đọc

Nếu muốn có bản nháp đầu tiên hữu ích, hãy nói rõ với agent nguyên tắc nào trong số này là quan trọng nhất với sơ đồ của bạn.

Câu hỏi thường gặp về skill draw-io

draw-io có phù hợp với người mới bắt đầu không?

Có, nếu bạn đã có file draw.io và muốn được hỗ trợ chỉnh sửa. Skill này giảm đáng kể phần đoán mò nhờ có rule và script cụ thể. Tuy nhiên, nó kém phù hợp hơn với người hoàn toàn mới chỉ muốn khám phá ý tưởng vẽ sơ đồ mà chưa có workflow dựa trên file.

Khi nào draw-io tốt hơn một prompt AI thông thường?

draw-io tốt hơn khi bạn cần chỉnh sửa có thể tái lập, xử lý file đúng cách, có bước export, hoặc cần icon AWS chính xác. Một prompt thông thường có thể mô tả sơ đồ khá tốt, nhưng thường sẽ không ép buộc việc sửa source .drawio, lệnh export, thiết lập font hay cách dùng script hỗ trợ.

draw-io có bắt buộc phải dùng GUI draw.io không?

Không hẳn. Skill này được thiết kế xoay quanh việc sửa file source và export PNG bằng CLI. Điều đó khiến nó phù hợp với workflow thiên về code, diff dễ review và pipeline tài liệu.

Khi nào không nên dùng draw-io?

Hãy bỏ qua draw-io guide này nếu bạn cần:

• whiteboarding tự do
• mockup thiết kế trau chuốt ngoài draw.io
• chỉnh sửa hoàn toàn bằng GUI
• tạo sơ đồ cho các định dạng không liên quan đến .drawio

Skill này chuyên cho XML của draw.io và các thao tác export, chứ không phải công cụ thiết kế đồ họa đa năng.

draw-io có hỗ trợ sơ đồ kiến trúc AWS không?

Có. Đây là một trong những điểm mạnh rõ ràng nhất của skill. Tài liệu tham chiếu icon AWS và script tra cứu giúp bạn dùng đúng tên chính thức và icon mxgraph.aws4.*, rất có giá trị khi bạn cần sự nhất quán và dễ nhận biết.

draw-io có tự động sửa bố cục xấu không?

Không phải theo kiểu “tự sửa bằng phép màu”. Skill này cung cấp một phương pháp để chỉnh tọa độ và bố cục có chủ đích. Kết quả sẽ tốt hơn khi bạn nêu rõ ý định sắp xếp, ví dụ như cách nhóm, hướng luồng, khoảng cách và mức ưu tiên tránh chồng lấn.

Cách cải thiện hiệu quả dùng skill draw-io

Cung cấp đầu vào cấu trúc mạnh hơn cho draw-io

Cách nhanh nhất để cải thiện draw-io usage là cung cấp cấu trúc, không phải tính từ. Thay vì nói “làm cho gọn hơn”, hãy nói:

• chuyển database xuống dưới app tier
• giữ tất cả nguồn ingestion ở cột bên trái
• để các mũi tên không giao cắt nếu có thể
• tách riêng resource trong public subnet và private subnet
• giữ label ngắn để tránh box bị nở rộng

Kiểu chỉ dẫn này ánh xạ trực tiếp sang quyết định về XML và layout.

Nếu có thể, hãy bắt đầu từ sơ đồ sẵn có

Skill này hoạt động tốt nhất khi có thể sửa một file .drawio hiện hữu thay vì phải dựng mọi thứ từ đầu. File sẵn có cung cấp cho nó:

• ID phần tử hiện tại
• pattern bố cục
• quy ước style
• cấu trúc nhóm
• đích export đã biết

Với team làm việc chung, cách này thường cho kết quả ổn định hơn so với việc mỗi lần đều yêu cầu một sơ đồ hoàn toàn mới.

Hãy nêu rõ cách đặt tên và mức độ chính xác của icon

Một lỗi rất hay gặp là gọi service một cách mơ hồ như “ECS” hoặc “Lambda” mà không quyết định label có nên dùng tên chính thức đầy đủ hay không. Nếu sơ đồ AWS quan trọng, hãy chỉ rõ cả hai:

• display labels: Amazon ECS, AWS Lambda, Amazon RDS
• icon requirement: dùng icon service chính thức mxgraph.aws4.*

Như vậy bạn sẽ tránh được tình trạng trộn lẫn kiểu đặt tên và map icon sai.

Yêu cầu chỉnh sửa rồi export trong cùng một workflow

Nếu bạn muốn đầu ra dùng được ngay, hãy yêu cầu cả bước sửa source lẫn bước export trong một chỉ dẫn. Ví dụ:

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

Cách này giảm khoảng trống rất thường gặp: XML đã đổi nhưng artifact preview vẫn cũ.

Theo dõi các lỗi chính dễ làm draw-io thất bại

Các vấn đề draw-io thường gặp hầu như là lỗi thao tác thực tế chứ không phải lỗi ý tưởng:

• sửa PNG thay vì .drawio
• quên thiết lập font nên render chữ không nhất quán
• dùng định danh icon AWS tự đoán
• nhồi quá nhiều node khiến label đè nhau
• tạo connector giao cắt làm giảm độ dễ đọc
• thay đổi layout mà không giữ được luồng tổng thể

Bạn có thể tránh phần lớn các lỗi này bằng cách dẫn chiếu trực tiếp đến script và guide đi kèm ngay trong prompt.

Lặp theo các thay đổi nhỏ, dễ review

Với sơ đồ phức tạp, đừng yêu cầu mọi thứ trong một lần. Mẫu làm việc tốt hơn là:

1. chỉnh cấu trúc và cách nhóm
2. rà lại khoảng cách và connector
3. sửa label và font
4. export PNG
5. làm một vòng cuối để tối ưu độ dễ đọc

Cách này tạo ra diff sạch hơn và giúp bạn dễ nhận ra vấn đề bố cục đến từ cách nhóm, chọn icon hay cỡ chữ.

Chỉ rõ helper trong repository bằng đúng tên file

Nếu agent của bạn hỗ trợ prompt có nhận biết file, hãy nêu chính xác các tài liệu tham chiếu:

• references/layout-guidelines.md cho khoảng cách và hướng luồng
• references/aws-icons.md cho cách đặt tên và icon AWS
• scripts/find_aws_icon.py cho tra cứu icon
• scripts/convert-drawio-to-png.sh cho export

Chỉ một bước nhỏ như vậy thường đã giúp chất lượng bản đầu tốt hơn, vì agent sẽ bám theo quy ước của repository thay vì lời khuyên vẽ sơ đồ chung chung.