TL;DR

markdown-viewer/skills là bộ skills mã nguồn mở dành riêng cho AI coding agents, giúp Claude Code, Codex và Cursor vẽ sơ đồ phức tạp trực tiếp trong file Markdown. Repo đạt 2.7k stars chỉ sau 4 tháng ra mắt (tháng 2/2026), với contributor chính là xicilion (响马). Điểm nổi bật là skill architecture - dùng HTML/CSS thuần thay vì PlantUML hay Mermaid - cho phép vẽ sơ đồ kiến trúc hệ thống nhiều layer với màu sắc và layout có cấu trúc rõ ràng.

Vẽ sơ đồ kiến trúc - công việc tốn thời gian

Với bất kỳ dự án phần mềm nào, sơ đồ kiến trúc là tài liệu quan trọng nhất - nhưng cũng là thứ dễ bị bỏ qua nhất vì tốn thời gian. Các công cụ như draw.io hay Lucidchart yêu cầu kéo thả thủ công. Mermaid thì phù hợp cho flowchart đơn giản nhưng khi hệ thống có nhiều layer, nhiều microservices và cross-cutting concerns, output trở nên rối loạn khó đọc.

Câu hỏi đặt ra: liệu AI có thể tự sinh ra một sơ đồ kiến trúc có cấu trúc, dễ đọc và chuyên nghiệp từ một câu mô tả không? markdown-viewer/skills trả lời là có.

Cách hoạt động: 14 skills, 5 rendering engines

Repo cung cấp 14 skills chia theo 5 rendering engines:

  • HTML/CSS embedded (không cần code fence): architecture, infocard
  • PlantUML (dùng fence ```plantuml): uml, cloud, network, security, archimate, bpmn, data-analytics, iot, mindmap
  • Vega/Vega-Lite (fence ```vega): vega cho bar chart, heatmap, scatter
  • Infographic YAML (fence ```infographic): 70+ templates cho KPI cards, roadmaps, SWOT
  • JSON Canvas (fence ```canvas): canvas cho mind map tự do

Mỗi skill là một folder chứa SKILL.md với hướng dẫn chi tiết, ví dụ và các quy tắc syntax. AI agent đọc SKILL.md khi được trigger, sau đó sinh ra output đúng format để Markdown Viewer Extension render.

Cài đặt trong 2 phút

Repo hỗ trợ nhiều cách cài đặt tùy agent:

  • Claude Code: dùng Quick Install (recommend) hoặc manual - thêm vào project knowledge, hoặc paste nội dung SKILL.md vào conversation
  • GitHub Copilot / VS Code: đặt skill folder vào .github/skills/ - agent tự động detect
  • claude.ai: paste SKILL.md trực tiếp vào conversation là xong

Để render diagram, bạn cần cài thêm Markdown Viewer Extension - có trên Chrome, Edge, Firefox và VS Code.

Skill architecture: HTML/CSS không cần engine

Đây là skill được cộng đồng nhắc đến nhiều nhất. Khác với các skill khác dùng PlantUML, skill architecture sinh ra raw HTML/CSS nhúng trực tiếp vào Markdown - không cần code fence, không cần engine ngoài.

Cấu trúc hỗ trợ 13 layout frameworks và 12 styles, bao gồm:

  • Single column: cho kiến trúc đơn giản
  • Two column: main content + một sidebar
  • Three column: left sidebar (monitoring, ops) + main content + right sidebar (security, compliance)

Color coding có quy ước rõ ràng cho từng layer:

  • User Layer: blue gradient (#dbeafe → #bfdbfe)
  • Application Layer: yellow/orange (#fef3c7 → #fde68a)
  • AI/Logic Layer: green (#dcfce7 → #bbf7d0)
  • Data Layer: pink (#fce7f3 → #fbcfe8)
  • Infrastructure Layer: purple (#e0e7ff → #c7d2fe)
  • External Services: gray với dashed border

Có hai quy tắc kỹ thuật quan trọng: HTML phải nhúng trực tiếp (KHÔNG dùng fence ```html), và toàn bộ khối HTML phải liên tục không có empty line để tránh lỗi parsing.

14 skills trong markdown-viewer/skills

Các skills khác đáng dùng ngay

UML là skill mạnh nhất trong bộ PlantUML - hỗ trợ 14 loại diagram (Class, Sequence, State Machine, Component, Deployment...) kết hợp với hơn 9500 mxgraph stencil icons cho AWS, Azure, Cisco, Kubernetes. Đủ để cover gần như mọi nhu cầu technical documentation.

Cloud dành riêng cho AWS, Azure, GCP, Alibaba Cloud, IBM và Kubernetes - mỗi provider có icon set riêng từ PlantUML stdlib, giúp vẽ cloud architecture diagram chuẩn theo notation chính thức.

Infographic với 70+ templates YAML cho phép AI tạo KPI dashboard, roadmap dự án, SWOT analysis hay org chart chỉ từ dữ liệu dạng text.

Khi nào nên dùng - và khi nào không

Dùng architecture khi cần vẽ:

  • Kiến trúc microservices với service boundaries rõ ràng
  • Multi-tier enterprise application (User → App → Data → Infra)
  • AI/ML system với data flow và processing layers
  • Security architecture hoặc DevOps/CI-CD pipeline tổng quan

Không nên dùng skill architecture cho flowchart đơn giản (dùng Mermaid), pixel-perfect custom diagram (dùng draw.io), hay data visualization (dùng vega).

Điểm yếu cần lưu ý: vì HTML/CSS sinh ra bởi AI không phải lúc nào cũng nhất quán 100%, các diagram phức tạp đôi khi cần chỉnh sửa thủ công sau khi generate. Ngoài ra, cần Markdown Viewer Extension để render - không xem được trên GitHub preview hay các editor thông thường.

Kết

markdown-viewer/skills đang nhanh chóng trở thành bộ toolkit tiêu chuẩn cho ai làm technical documentation với AI agents. 2.7k stars sau 4 tháng là con số ấn tượng, và cộng đồng trên X đang chia sẻ rộng rãi sau khi @libapi_ giới thiệu với 39.6K lượt xem.

Nếu bạn đang dùng Claude Code, Codex hay Cursor và thường xuyên cần vẽ sơ đồ kiến trúc cho tài liệu kỹ thuật, đây là skill đáng cài ngay. via github.com/markdown-viewer/skills