Beautiful Mermaid
Generate valid Mermaid diagram syntax for architecture, flows, and sequences in READMEs and specs without broken renders.
Overview
Beautiful Mermaid is an agent skill most often used in Build (also Validate, Ship) that supplies authoritative Mermaid syntax patterns so agents emit render-safe diagram code in markdown.
Install
npx skills add https://github.com/intellectronica/agent-skills --skill beautiful-mermaidWhat is this skill?
- Flowchart directions (TD/LR) with rectangle, diamond, cylinder, and stadium node shapes
- Sequence diagram participants and solid/dashed arrow types
- Edge labels via pipe syntax -->|label| to avoid incomplete Mermaid renders
- Subgraph grouping patterns for grouped flows
- Quick-reference coverage across major Mermaid diagram families
Adoption & trust: 1.4k installs on skills.sh; 270 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need architecture or flow diagrams in docs but agent-generated Mermaid often uses invalid edge labels or shapes that fail to render.
Who is it for?
Solo builders documenting systems, onboarding flows, or API interactions in-repo with Mermaid-backed markdown.
Skip if: Teams that only need auto-generated diagrams from live code tracing or a dedicated diagramming SaaS with no markdown workflow.
When should I use this skill?
User or agent needs to author or fix Mermaid diagram blocks in markdown documentation.
What do I get? / Deliverables
After the skill runs, markdown contains valid flowchart and sequence-diagram snippets with correct -->|label| edge syntax and consistent node notation.
- Valid Mermaid code blocks for flowcharts or sequence diagrams
- Syntax-correct subgraph and edge-label patterns
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is build/docs because the skill is a syntax reference for embedding diagrams in project documentation and technical write-ups. Docs is where flowcharts, sequence diagrams, and subgraph syntax land in markdown and agent outputs during implementation.
Where it fits
Sketch a signup funnel as a Mermaid flowchart before building the landing wireframe.
Add a service topology diagram to the README using subgraphs and labeled edges.
Document a auth handshake as a sequence diagram in the PR description.
How it compares
Use as an in-agent syntax cookbook instead of guessing Mermaid from memory or generic chat examples.
Common Questions / FAQ
Who is beautiful-mermaid for?
Indie developers and agent users who embed Mermaid in READMEs, specs, and PR descriptions and want consistent, valid syntax from their coding agent.
When should I use beautiful-mermaid?
During build/docs when writing technical documentation; in validate/prototype when sketching user or data flows; and in ship/review when attaching sequence diagrams to change summaries.
Is beautiful-mermaid safe to install?
It is reference-only procedural knowledge with no shell or network requirements; review the Security Audits panel on this Prism page before installing from any marketplace source.
SKILL.md
READMESKILL.md - Beautiful Mermaid
# Mermaid Syntax Reference Quick reference for generating valid Mermaid diagram code. ## Flowchart ```mermaid graph TD A[Start] --> B{Decision} B -->|Yes| C[Action 1] B -->|No| D[Action 2] C --> E[End] D --> E ``` ### Direction - `TD` / `TB` - Top to bottom - `BT` - Bottom to top - `LR` - Left to right - `RL` - Right to left ### Node Shapes - `A[Text]` - Rectangle - `A(Text)` - Rounded rectangle - `A([Text])` - Stadium/pill - `A[[Text]]` - Subroutine - `A[(Text)]` - Cylinder (database) - `A((Text))` - Circle - `A>Text]` - Asymmetric - `A{Text}` - Diamond (decision) - `A{{Text}}` - Hexagon - `A[/Text/]` - Parallelogram - `A[\Text\]` - Parallelogram alt - `A[/Text\]` - Trapezoid - `A[\Text/]` - Trapezoid alt ### Edge Styles - `A --> B` - Arrow - `A --- B` - Line - `A -.-> B` - Dotted arrow - `A ==> B` - Thick arrow - `A -->|text| B` - Arrow with label (preferred) - `A ---|text| B` - Line with label (preferred) **Important**: Always use pipe syntax `-->|label|` for edge labels. The space-dash syntax `-- label -->` can cause incomplete renders. ### Subgraphs ```mermaid graph TD subgraph Group1 [Label] A --> B end subgraph Group2 C --> D end B --> C ``` ## Sequence Diagram ```mermaid sequenceDiagram participant A as Alice participant B as Bob A->>B: Hello B-->>A: Hi there A->>+B: Start process B-->>-A: Done ``` ### Arrow Types - `->>` - Solid arrow - `-->>` - Dashed arrow - `-x` - Solid with x - `--x` - Dashed with x - `-)` - Solid open arrow - `--)` - Dashed open arrow ### Activations - `+` after arrow activates participant - `-` after arrow deactivates participant ### Notes and Boxes ```mermaid sequenceDiagram Note over A,B: Shared note Note right of A: Side note rect rgb(200, 220, 255) A->>B: In a box end ``` ### Loops and Conditionals ```mermaid sequenceDiagram loop Every minute A->>B: Ping end alt Success B-->>A: Pong else Failure B-->>A: Error end opt Optional A->>B: Extra step end ``` ## State Diagram ```mermaid stateDiagram-v2 [*] --> Idle Idle --> Processing : start Processing --> Done : complete Processing --> Error : fail Error --> Idle : reset Done --> [*] ``` ### Composite States ```mermaid stateDiagram-v2 state Active { [*] --> Running Running --> Paused : pause Paused --> Running : resume } Idle --> Active : activate Active --> Idle : deactivate ``` ### Notes ```mermaid stateDiagram-v2 State1 : Description here note right of State1 Additional info end note ``` ## Class Diagram ```mermaid classDiagram class Animal { +String name +int age +makeSound() void } class Dog { +bark() void } Animal <|-- Dog : extends ``` ### Relationships - `<|--` - Inheritance - `*--` - Composition - `o--` - Aggregation - `-->` - Association - `--` - Link (solid) - `..>` - Dependency - `..|>` - Realisation - `..` - Link (dashed) ### Cardinality ```mermaid classDiagram Customer "1" --> "*" Order Order "1" --> "1..*" LineItem ``` ### Visibility - `+` Public - `-` Private - `#` Protected - `~` Package/Internal ## Entity-Relationship Diagram ```mermaid erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE-ITEM : contains PRODUCT }|..|{ LINE-ITEM : "ordered in" ``` ### Relationship Types - `||` - Exactly one - `|{` - One or more - `o{` - Zero or more - `o|` - Zero or one ### Identifying vs Non-identifying - `--` - Identifying (solid) - `..` - Non-identifying (dashed) ### Attributes ```mermaid erDiagram CUSTOMER { string id PK string name string email UK } ORDER { int id PK string customer_id FK date created_at } ``` ## Styling ### CSS Classes ```mermaid graph TD A:::highlight --> B classDef highlight fill:#f96,stroke:#333 ```