System Diagram Generator Skill for Claude

System Diagram Generator

Generate clear, accurate visual representations of system structure using text-based diagram formats.

Quick Start

When a user requests a system diagram:

• Understand the system: Ask clarifying questions about components, relationships, and scope
• Choose the format: Select based on user preference or context (default to Mermaid for versatility)
• Select diagram type: Match the visualization to the information being conveyed
• Generate the diagram: Create the diagram code with clear labels and structure
• Provide context: Include a brief explanation of what the diagram shows

Format Selection

Mermaid (Default)

Use for most cases - renders in Markdown, GitHub, GitLab, and many documentation tools.

Best for:

• Quick visualizations
• Documentation in Markdown files
• GitHub/GitLab README files
• General-purpose diagrams

See: mermaid-patterns.md for examples

PlantUML

Use when detailed UML diagrams are needed or when working with Java/enterprise systems.

Best for:

• Detailed UML diagrams
• C4 architecture models
• Complex component relationships
• Enterprise documentation

See: plantuml-patterns.md for examples

Graphviz/DOT

Use for complex network topologies or when fine-grained layout control is needed.

Best for:

• Network diagrams
• Complex hierarchies
• Graph structures
• Custom layout requirements

See: graphviz-patterns.md for examples

Diagram Types

Architecture Diagrams

Show system components, services, databases, and their relationships.

Use when:

• Explaining system structure
• Documenting microservices
• Showing component dependencies
• Illustrating system boundaries

Key elements:

• Services/components (boxes)
• Databases (cylinders)
• External systems
• Communication protocols
• Data stores

Data Flow Diagrams

Illustrate how data moves through the system.

Use when:

• Explaining data processing pipelines
• Documenting ETL processes
• Showing transformation steps
• Illustrating validation flows

Key elements:

• Data sources
• Processing steps
• Transformations
• Data stores
• Outputs

Deployment Diagrams

Show infrastructure, servers, containers, and deployment topology.

Use when:

• Documenting cloud infrastructure
• Explaining deployment architecture
• Showing network topology
• Illustrating container orchestration

Key elements:

• Cloud providers/regions
• Networks/subnets
• Servers/containers
• Load balancers
• Databases and caches

Sequence Diagrams

Visualize API calls, user interactions, and process flows over time.

Use when:

• Documenting API interactions
• Explaining authentication flows
• Showing request/response cycles
• Illustrating multi-step processes

Key elements:

• Actors/participants
• Messages/calls
• Time sequence (top to bottom)
• Return values
• Conditional logic

Best Practices

Clarity

• Use descriptive, meaningful names for all components
• Keep diagrams focused on one aspect of the system
• Avoid overcrowding - split complex systems into multiple diagrams
• Use consistent naming conventions

Structure

• Group related components using subgraphs/clusters
• Show clear directional flow (left-to-right or top-to-bottom)
• Use appropriate shapes for different component types
• Include relevant protocols and technologies

Context

• Add a title or caption explaining what the diagram shows
• Include legends for non-obvious symbols or colors
• Provide brief explanations of key components
• Note any assumptions or simplifications

Format-Specific

• Mermaid: Use standard graph types (flowchart, sequence, C4)
• PlantUML: Leverage UML stereotypes and C4 includes
• Graphviz: Use clusters for grouping and rankdir for layout

Workflow

• Gather requirements
• What system or process needs visualization?
• What level of detail is needed?
• Who is the audience?
• Any format preferences?

• Choose format and type
• Select diagram format (Mermaid/PlantUML/Graphviz)
• Select diagram type (architecture/data flow/deployment/sequence)
• Load relevant reference file if needed

• Create diagram
• Define all components/nodes
• Establish relationships/edges
• Add grouping/structure
• Include labels and protocols

• Validate and refine
• Ensure all components are labeled
• Verify relationships are clear
• Check for visual balance
• Add explanatory text

• Deliver
• Provide the diagram code in a code block
• Include brief explanation
• Suggest improvements or variations if relevant

Example Usage Patterns

User: "Show me the architecture of our authentication system"

→ Create Mermaid architecture diagram showing auth components

User: "Diagram the data flow for user registration"

→ Create Mermaid flowchart showing registration data flow

User: "Visualize our AWS deployment"

→ Create Mermaid or Graphviz deployment diagram with AWS infrastructure

User: "Show the sequence of API calls for checkout"

→ Create Mermaid sequence diagram showing checkout flow

User: "I need a detailed UML component diagram"

→ Create PlantUML component diagram with stereotypes

User: "Map out our network topology"

→ Create Graphviz network diagram with clusters