Agent skill · writing content · aiskillstore
mermaid
Guide for creating beautiful Mermaid diagrams with proper styling for GitHub markdown (dark/light mode compatible, no icons).
Why this skill is useful
Provides specific styling guidelines and rendering techniques for Mermaid diagrams that enhance readability on GitHub, which the AI may not generate independently.
What it needs
Requires @mermaid-js/mermaid-cli installed locally. About 5k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
Mermaid Diagram Skill This skill provides guidance on creating beautiful, professional Mermaid diagrams that render correctly on GitHub and work well in both light and dark mode. Core Principles 1. Use dark fills with light strokes — Ensures readability in both light and dark mode 2. Set subgraph fills to none — Allows subgraphs to adapt to any background 3. Use rounded shapes — ([text]) for stadium shapes, ((text)) for circles 4. No Font Awesome icons — GitHub doesn't support fa:fa- icons, they render as text 5. Quote subgraph labels — Use subgraph Name["Label Text"] syntax 6. Define classDef styles at the top — Keep all styling together for maintainability 7. Render and self-check: auto-layout makes its own routing choices, so always preview the rendered image and iterate until the lines are easy to follow Render, check, and iterate (do this every time) Writing valid Mermaid is not the goal; producing a diagram a person can actually follow is. Mermaid's auto-layout (dagre) decides where nodes sit and how edges route, so a diagram that looks fine in source often renders as spaghetti. Always render it, look at it as a reader, and iterate before you ship. 1. Render to an image and open it. Mermaid-cli with a dark background mimics GitHub: Put just the Mermaid code in diagram.mmd (the diagram only, no surrounding fence markers). mermaid.live works for a quick paste-and-preview too. 2. Judge it as a reader, not the author: Is the start obvious, and the end? Can you trace every arrow from tail to head without losing it in a crossing? Are related nodes near each other, and does nothing float unconnected? 3. If the lines tangle, fix the layout, not just the colours. Techniques that work: Lay the main flow out as lanes (flowchart LR with direction TB inside each subgraph) so it reads start-to-end in one direction. Cut secondary edges that create a web (test-coverage arrows, every cross-reference). Show the primary flow and put the rest in prose. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/mermaid