OpenParable
Skip to content
← Back to skills

Sc Mermaid

Design
sc-mermaid

Sc Mermaid is an Agent Skill for design published in the kylesnowschwartz/SimpleClaude repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Generate mermaid diagrams — flowcharts for architecture, sequence diagrams for interactions. This skill SHOULD be used when the user asks to "create a diagram", "draw an architecture diagram", "sequence diagram", "flowchart", "visualize the system", or "generate mermaid".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/kylesnowschwartz/SimpleClaude/blob/HEAD/plugins/sc-skills/skills/sc-mermaid/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/sc-mermaid, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

sc-mermaid: Mermaid Diagram Generator

Generate mermaid diagrams for architecture visualization and interaction flows.

Input: $ARGUMENTS

Mode Detection

Parse $ARGUMENTS to determine diagram type:

SignalMode
flowchart, architecture, system, component relationshipsFlowchart
sequence, flow, interaction, request/response patternsSequence
AmbiguousAsk the user or infer from context

Flowchart Mode

Investigation

  1. Scope identification: Determine which components, services, and relationships to include
  2. Architecture analysis: Read relevant files and understand data/control flow
  3. Validation: Cross-reference findings against codebase to ensure accuracy

Diagram Requirements

  • Use TB (top-bottom) or LR (left-right) direction based on flow complexity
  • Apply the neutral theme for professional rendering
  • Use semantic node shapes:
    • [Rectangle] — services, applications
    • [(Database)] — data stores (PostgreSQL, Redis, OpenSearch)
    • ((Circle)) — external services, APIs
    • [[Subroutine]] — modules, workers, background jobs
    • {Rhombus} — decision points, routing logic
    • {{Hexagon}} — gateways, proxies, middleware
  • Style nodes and links using CSS classes for visual grouping
  • Label every relationship with meaningful text
  • Group related components with subgraphs (quote subgraph titles)

Deliverables

  1. Mermaid diagram file ({descriptive-name}.mmd)
  2. Syntax validation: mmdc -i <file>.mmd --parseOnly (fix errors if any)
  3. Bulleted architectural explanation
  4. Validation report with file path references
  5. Viewing instructions (optionally render: mmdc -i <file>.mmd -o preview.png)

Sequence Mode

Generate diagrams compatible with mermaid-ascii for terminal rendering.

Syntax Reference (mermaid-ascii parser)

Works:

sequenceDiagram           # REQUIRED first line
participant A as Alice    # aliases (optional)
"Quoted Name"             # spaces in names
A->>B: message            # solid arrow (colon REQUIRED)
A-->>B: message           # dotted arrow (colon REQUIRED)
A->>A: self               # self-message (use for notes)
%% comment                # ignored by parser

Fails:

A->B: msg     # wrong arrow (needs ->>)
A-->B: msg    # wrong arrow (needs -->>)
A->>B         # missing colon
Note over A   # not implemented
loop/alt/opt  # not implemented
activate A    # not implemented

Design Rules

  1. Colon is mandatory: A->>B: text works, A->>B fails
  2. Only ->> and -->>: No other arrow types parse
  3. Self-messages for notes: A->>A: (thinking) instead of Note
  4. Comments for structure: %% Phase 1: or %% alt: if X then Y
  5. Short labels: ASCII rendering is wide; keep messages brief
  6. Limit participants: 4-6 max for terminal readability

Workflow

  1. Understand the flow from $ARGUMENTS or ask clarifying questions
  2. Identify actors — use clear short names
  3. Map interactions between them
  4. Generate diagram following the template
  5. Validate: cat <file> | mermaid-ascii -f -
  6. Save file and show both source and ASCII render

Template

%% Flow: [title]
%% Render: cat <file> | mermaid-ascii -f -

sequenceDiagram
    participant A as ActorOne
    participant B as ActorTwo

    %% Phase 1: [description]
    A->>B: request
    B-->>A: response

Example: API Request Flow

%% Flow: API authentication
%% Render: cat api-auth.mmd | mermaid-ascii -f -

sequenceDiagram
    participant C as Client
    participant G as Gateway
    participant A as Auth
    participant S as Service

    C->>G: POST /api/data
    G->>A: validate token
    A-->>G: valid
    G->>S: forward request
    S-->>G: response
    G-->>C: 200 OK

    %% alt: invalid token
    %% A-->>G: 401
    %% G-->>C: 401 Unauthorized

Validation

Before saving, ALWAYS test with:

cat <<'EOF' | mermaid-ascii -f -
[your diagram here]
EOF

If it errors, fix the syntax. Common fixes:

  • Add missing colon after target: A->>B -> A->>B:
  • Fix arrow type: A->B: -> A->>B:
  • Remove unsupported syntax (Notes, loops, etc.)

Output

Write diagram to {descriptive-name}.mmd in the current directory (or ask user for location).

Include in the file:

  • Diagram code
  • Architectural explanation as markdown comments
  • Validation notes with file path references

$ARGUMENTS