Mermaid Diagrams

**Judgement:** A strong, focused skill for generating professional Mermaid diagrams from textual descriptions of software systems. Well-suited for architecture, flows, and data modeling when the user explicitly asks for a diagram or visualization of system behavior/structure. **What it does well** - Produces Mermaid syntax for many key diagram types (class, sequence, flowchart, ERD, C4, state, git graph, Gantt). - Encourages good documentation practices: titles/captions, labeled arrows, comments, and version control of `.mmd` files. - Provides examples and configuration patterns (themes, layouts, hand-drawn look) for consistent, readable diagrams. - Helps keep diagrams small and focused (≤ ~15 nodes) to avoid unreadable or cluttered outputs. **Key risks / limitations** - Mermaid is sensitive to typos and unknown tokens; invalid or misspelled syntax can fail silently, so outputs may render partially or not at all if not carefully formed. - Overly complex systems are hard to capture in a single diagram; the skill must respect the “never more than 15 nodes” rule and split views, or the result becomes noisy and unhelpful. - Diagrams can become misleading if not updated when the underlying architecture or schema changes; the assistant must avoid treating diagrams as immutable truth. - Not suitable for numeric or business data visualization (charts/graphs) – Mermaid should be used only for architecture/flow-style diagrams. **Recommended scenarios** - A user asks to “diagram”, “visualize”, “map out”, or “show the flow” of an API, service interaction, or user journey. - Designing or documenting system architecture with C4-style views for onboarding, ADRs, or technical specs. - Modeling domain entities, object relationships, or database schemas while planning or refactoring a system. - Creating living documentation (in Markdown, wikis, or code repos) where Mermaid can be rendered (GitHub, GitLab, VS Code, Notion, Confluence, Obsidian).