- markdown-viewer/skills là bộ 15 skill mã nguồn mở cho Claude Code, Cursor và các AI coding agent, cho phép vẽ biểu đồ kiến trúc, UML, BPMN, cloud trực tiếp trong Markdown bằng lệnh văn bản.
- Bộ skill bao phủ 5 rendering engine với 9.500+ mxgraph stencil icon cho UML và 70+ template YAML cho infographic.
- Cài một lần, dùng được trên Claude Code, Cursor, Codex CLI, Gemini CLI và GitHub Copilot.
TL;DR
markdown-viewer/skills là bộ 15 skill mã nguồn mở cho phép AI coding agent vẽ biểu đồ kiến trúc chuyên nghiệp trực tiếp trong Markdown - không cần mở Lucidchart hay draw.io. Từ UML class diagram, cloud architecture AWS/Azure, đến BPMN workflow và Zero Trust security - mỗi loại biểu đồ có một skill riêng, tương ứng với một rendering engine tối ưu. Hỗ trợ Claude Code, Cursor, Codex CLI, Gemini CLI và GitHub Copilot.
Vấn đề: tài liệu kỹ thuật thiếu cấu trúc, không phải thiếu nội dung
Tác giả @libapi_ nói đúng một điều: "nhiều tài liệu không thiếu nội dung, mà thiếu cấu trúc."
Khi cần vẽ sơ đồ kiến trúc cho buổi review, quy trình thông thường là: mở draw.io hoặc Lucidchart, kéo thả từng component thủ công, căn chỉnh màu sắc và icon, export rồi nhúng vào tài liệu. Mất 30-60 phút chỉ để có một sơ đồ tàm tạm.
Với bộ skill này, bạn gõ lệnh vào Claude Code: "vẽ cho tôi kiến trúc Zero Trust bảo vệ hệ thống thanh toán" - AI sinh PlantUML với đúng icon IAM, firewall, encryption, render thành SVG ngay trong Markdown. Toàn bộ dưới 30 giây.
Cách hoạt động: progressive disclosure + 5 rendering engine
Bộ skill dùng kiến trúc progressive disclosure: khi khởi động, AI chỉ đọc khoảng 100 tokens mô tả của mỗi skill. Khi bạn đưa ra yêu cầu liên quan (ví dụ: "vẽ BPMN workflow"), AI mới load full nội dung skill tương ứng - tối đa 5.000 tokens. Điều này cho phép cài 50+ skill mà không ảnh hưởng hiệu năng các tác vụ không liên quan.
5 rendering engine được sử dụng:
- PlantUML - engine chính cho UML, Cloud, Network, Security, ArchiMate, BPMN, Data Analytics, IoT, Mindmap
- Vega/Vega-Lite - biểu đồ dữ liệu (bar, line, scatter, heatmap, radar)
- JSON Canvas - mind map với vị trí tự do, knowledge graph
- Infographic YAML - 70+ template pre-designed cho KPI, timeline, roadmap, SWOT
- HTML/CSS trực tiếp - Architecture layers và Infocard với typography chất lượng cao
15 skill và tình huống thực tế
Bộ skill hiện bao gồm 15 loại biểu đồ, mỗi skill có bộ stencil icon riêng theo chuẩn ngành:
| Skill | Dùng cho | Highlight |
|---|---|---|
uml | Class diagram, sequence, state machine, component | 14 loại UML + 9.500+ stencil icon |
cloud | AWS, Azure, GCP, Alibaba, IBM, Kubernetes | Icon stdlib chính thức từng provider |
architecture | Kiến trúc phân lớp User/App/Data/Infra | 13 layouts x 12 styles HTML/CSS |
security | Zero Trust, threat model, compliance audit | IAM, firewall, encryption icons |
archimate | Enterprise architecture, chuyển đổi số | ArchiMate 3 layered modeling |
bpmn | Business process, EIP, value stream mapping | BPMN notation + swim lanes |
data-analytics | ETL/ELT pipeline, data warehouse, ML workflow | Warehouse/lake/lakehouse models |
network | LAN/WAN, data center, campus network | Cisco/Citrix device icons |
iot | Sensor network, cold chain, edge computing, digital twin | IoT device + edge/cloud patterns |
mindmap | Brainstorm, knowledge base outline | PlantUML syntax, auto-layout |
canvas | Mind map tự do, knowledge graph | JSON Canvas, spatial positioning |
vega | Bar, line, scatter, heatmap, radar chart | Vega/Vega-Lite, data-driven |
infographic | KPI dashboard, timeline, roadmap, SWOT | 70+ YAML template |
infocard | Knowledge summary card, event announcement | 13 layouts x 14 styles |
graphviz | Module dependency, package relationship graph | Graphviz DOT syntax |
Cài đặt nhanh
Cách đơn giản nhất là clone repo và copy vào thư mục skills của Claude Code:
git clone https://github.com/markdown-viewer/skills
cp -r skills/* ~/.claude/skills/Với Claude Code, bạn cũng có thể dùng /plugin trong terminal session để tìm và cài từ marketplace. Với GitHub Copilot/VS Code, đặt thư mục skill vào .github/skills/ - tự động được nhận diện.
Để thấy output biểu đồ, cần cài thêm Markdown Viewer Extension (Chrome, Firefox hoặc VS Code) - đây là rendering engine thực sự parse các code fence và sinh SVG/HTML.
Bộ skill này còn được tích hợp sẵn trong Hermes Web UI - dashboard self-hosted cho AI agent với chat streaming, Kanban board, usage analytics và web terminal. Hermes Web UI v0.6.0 vừa ra ngày 24/05/2026, đạt 6k stars trên GitHub. Cài bằng: npm install -g hermes-web-ui && hermes-web-ui start (via ekkolearnai.com).
So sánh với draw.io và Lucidchart
Điểm khác biệt cốt lõi so với công cụ kéo-thả truyền thống:
- In-workflow: không cần rời khỏi terminal/chat - biểu đồ sinh ngay trong conversation
- Dynamic context: AI có thể inject dữ liệu thực (
git diff, PR data) vào prompt để sinh biểu đồ chính xác với codebase thực - Version control: output là text-based (PlantUML, Vega JSON, HTML) - commit được lên Git, diff được, review được
- Domain icon library: 9.500+ stencil icon được pre-loaded theo chuẩn ngành, không cần tự tìm icon AWS hay Cisco
draw.io vẫn tốt hơn cho biểu đồ cần căn chỉnh thủ công rất phức tạp hoặc collaboration real-time nhiều người. Nhưng với tài liệu kỹ thuật thông thường - README, proposal, architecture review - bộ skill này nhanh hơn nhiều.
Hạn chế cần biết
Một số điểm cần lưu ý trước khi cài:
- Cần Markdown Viewer Extension: nếu không cài extension, bạn chỉ thấy code fence raw, không thấy biểu đồ render
- Token budget: khi session bị compaction (lịch sử dài), tất cả skill đang active chia nhau tối đa 25.000 tokens - skill nào invoke sau cùng được ưu tiên
- Trigger phụ thuộc description: skill không tự động load nếu description trong SKILL.md quá mơ hồ; description được truncate tại 1.536 ký tự
- Tên folder case-sensitive: phải là kebab-case và file phải tên chính xác là
SKILL.md- sai tên thì AI bỏ qua hoàn toàn
Dành cho ai
Bộ skill này phù hợp nhất với developer, software architect, product manager và technical writer thường xuyên phải tạo tài liệu kỹ thuật, proposal, hoặc báo cáo kiến trúc. Đặc biệt hữu ích khi làm README, design doc, hoặc slide cho architecture review meeting.
Nếu bạn dùng Claude Code hoặc Cursor hằng ngày và phải vẽ biểu đồ thủ công - đây là bộ skill nên cài ngay. Mã nguồn mở, miễn phí, cài một lần dùng trên tất cả agent. via markdown-viewer/skills.