# Mermaid

> Generates Mermaid diagrams from source files, schemas, or descriptions, with automatic diagram type detection. Use when the user wants to visualize code architecture, database schemas, request flows, or any system as a Mermaid diagram.

- Skill: `pavelsimo/mermaid` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add pavelsimo/mermaid`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pavelsimo/mermaid/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: pavelsimo (https://skillmd.com/u/pavelsimo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pavelsimo/mermaid

---


# mermaid skill

A Claude Code skill that analyzes source files, schemas, code, or a plain-text description and produces a Mermaid diagram — choosing the right diagram type automatically or using the one you specify.

## features

- auto-detects the best diagram type from context: SQL files → ER, request flows → sequence, class hierarchies → class, logic/process → flowchart
- accepts a target: a file, directory, glob, or free-text description
- supports forced type with `--type=<type>` when you know what you want
- writes to a file with `--output=<path>`, or prints to the terminal if omitted
- validates syntax with the mermaid CLI before saving when `npx` is available
- always shows a preview and waits for confirmation before writing any file

## usage

```
/mermaid                           # auto-detect diagram type from current context
/mermaid <description or file>     # target a specific area or describe what to diagram
/mermaid --type=<type>             # force a specific diagram type
/mermaid --output=<file>           # save diagram to a file (asks before writing)
/mermaid --type=<type> --output=<file> <target>  # combine all options
```

**examples**

```
/mermaid                           # infer from open files or recent context
/mermaid src/models/               # ER or class diagram from model files
/mermaid schema.sql                # ER diagram from SQL schema
/mermaid "user authentication flow"  # sequence diagram from a description
/mermaid --type=flowchart src/checkout.py  # force flowchart for a specific file
/mermaid --output=docs/arch.md     # save to file after confirmation
```


## diagram selection

- Treat a target as a file, directory, or glob when it resolves on disk; otherwise treat it as a free-text description.
- Use `--type=<type>` as an explicit override and validate it against [reference/diagram-selection.md](reference/diagram-selection.md).
- Without `--type`, infer from source signals: SQL/schema/model files -> ER, class/type hierarchies -> class, request interactions -> sequence, and processes/branches -> flowchart.
- Default to `flowchart` when signals are ambiguous, and tell the user about the fallback.

## output format

Diagrams are always shown in a fenced markdown code block:

````markdown
```mermaid
erDiagram
    USER {
        int id PK
        string email
        string name
    }
    ORDER {
        int id PK
        int user_id FK
        datetime created_at
    }
    USER ||--o{ ORDER : places
```
````

If `--output` is specified, the content saved to file is the fenced `mermaid` block. Plain `.mmd` output (no surrounding markdown) is used when the target file extension is `.mmd`.

## workflow

1. **parse arguments**: extract `--type`, `--output`, and the remaining target; if the target resolves to an existing file, directory, or glob, treat it as filesystem input, otherwise treat it as a free-text description
2. **gather context**:
   - if a file or directory was given: read the relevant source files (SQL schemas, model definitions, class files, route files); focus on structure, not implementation detail
   - if a description was given: use it as the primary specification
   - if no arguments: scan the current working directory for the strongest structural signals (schemas, models, routes, main entry point)
3. **determine diagram type**:
   - if `--type` was given, use it directly; validate that the value is one of the recognized keywords in [reference/diagram-selection.md](reference/diagram-selection.md); if not, show the table and ask the user to pick
   - otherwise, apply the auto-detection rules from [reference/diagram-selection.md](reference/diagram-selection.md) in order; if signals conflict or are absent, default to `flowchart` and note the fallback to the user
4. **extract entities and relationships** from the gathered context:
   - for `er`: tables/models → entities, foreign keys and associations → relationships with cardinality
   - for `class`: classes/interfaces/types → nodes, inheritance/composition/implementation → edges
   - for `sequence`: actors/services/components → participants, calls/events/responses → messages with labels
   - for `flowchart`: steps/conditions/branches → nodes, execution order and decision outcomes → edges
   - for other types: extract the relevant structural elements following the same principle
5. **draft the diagram**: write valid Mermaid syntax; apply best practices from the section below; for `flowchart` use `flowchart TD` (top-down) unless the layout is clearly left-to-right; keep the diagram focused — omit low-signal implementation details
6. **validate syntax** (when `npx` is available):
   - write the diagram to a temporary file
   - run: `npx -p @mermaid-js/mermaid-cli mmdc -i <temp>.md -o /tmp/mermaid-test-out.md`
   - if validation fails, read the error, fix the syntax, and re-validate; surface the error to the user if it cannot be resolved automatically
   - if `npx` is unavailable, skip validation and note this to the user
7. **show preview**: display the complete diagram in a fenced `mermaid` code block; state the detected or forced diagram type, the source analyzed, and whether validation passed
8. **ask for confirmation**: prompt — "save to `<output path>`?" — only when `--output` was given; if no output path was given, the diagram is already visible and no file action is needed
9. **on approval**: write the diagram to the specified output path; do not run any git commands unless the user explicitly asks
10. **on edit request**: ask what to change, apply edits, re-validate if possible, show the revised diagram, and return to step 8

## best practices

- **keep diagrams focused** — one diagram per concern; a 30-node diagram is usually too large; consider splitting
- **consistent naming** — use the same identifier style throughout a diagram (camelCase or snake_case, not mixed)
- **group with subgraphs** — in flowcharts, use `subgraph` to cluster related steps
- **label relationships** — always add a label to edges in ER diagrams (`USER ||--o{ ORDER : places`); add message labels in sequence diagrams
- **cardinality in ER** — always include cardinality markers (`||`, `o{`, `|{`, etc.) on ER relationships
- **top-down default** — prefer `flowchart TD` over `LR` unless the diagram is clearly a left-to-right pipeline
- **no implementation noise** — omit private helpers, internal variables, and low-level implementation details; diagram structure and behavior, not mechanics
- **valid identifiers** — avoid spaces in node IDs; use quotes for display labels that contain spaces: `A["User Service"]`
- **never auto-commit** — writing the diagram file is the final step; do not stage or commit unless the user asks