Excalidraw

Excalidraw

Purpose

• Use this skill to create lightweight diagrams, sketches, and whiteboard-style visuals quickly.
• Prefer Excalidraw when the output should feel hand-drawn, fast to edit, and easy to embed into notes or design docs.
• This skill works well for architecture reviews, brainstorming, flowcharts, and teaching visuals.
• In this environment, Excalidraw MCP tooling is already available.

Core Mental Model

• Describe the diagram you want in plain language.
• Claude can translate that description into an Excalidraw JSON scene specification.
• The scene can then be rendered in a view, exported, saved as a checkpoint, or shared through Excalidraw.
• Treat the JSON spec as the source of truth for reproducible diagram generation.

MCP Integration

• Use mcp__claude_ai_excalidraw__create_view to generate or render a diagram view from a structured scene.
• Use mcp__claude_ai_excalidraw__export_to_excalidraw to export the scene into a format compatible with Excalidraw workflows.
• Use save_checkpoint to preserve an intermediate diagram state before large edits.
• Use read_checkpoint to reload a previously saved scene when you need to continue, branch, or recover.
• A good workflow is: describe -> generate JSON -> create view -> inspect -> checkpoint -> revise -> export.

What To Ask For

• "Draw a system architecture diagram for a FastAPI app backed by Postgres and Redis."
• "Create a flowchart for user sign-up with email verification."
• "Sketch an ERD with users, teams, memberships, and permissions."
• "Make a sequence diagram for browser -> API -> worker -> database."
• "Turn this process into a whiteboard-style diagram with short labels and arrows."

Describe First, Then Refine

• Start with the intent of the diagram, not low-level coordinates.
• Include the major entities, the relationships, and the desired reading direction.
• Mention whether you want a rough sketch, a cleaner box-and-arrow layout, or a board-like visual.
• If the first result is too dense, ask for fewer labels or more spacing.
• If the first result is too vague, specify grouping, order, and arrow directions.

Scene Building Blocks

• rectangle: best for services, systems, containers, and grouped components.
• ellipse: useful for external actors, start/end states, or soft conceptual nodes.
• arrow: best for directional relationships, calls, control flow, and data movement.
• line: useful for visual separators, boundaries, or non-directional links.
• text: labels, notes, titles, annotations, and step numbers.
• diamond: decision points in a flowchart or branching logic.

Common Diagram Types

System Architecture

• Use rectangles for services, databases, queues, and external providers.
• Use arrows to show request flow, event flow, and data movement.
• Group related services into logical zones such as frontend, backend, storage, and third-party systems.
• Add short text notes for protocols like HTTP, gRPC, Kafka, or WebSocket.

Flowchart

• Use rectangles for actions.
• Use diamonds for decisions.
• Use arrows for the main control path.
• Keep text short and action-oriented.
• Prefer top-to-bottom or left-to-right consistency.

ERD

• Use rectangles to represent tables or entities.
• Put the entity name at the top and key fields below as text.
• Use arrows or simple connecting lines to show relationships.
• Label one-to-many or many-to-many edges with short text if needed.
• Keep column lists focused on primary keys, foreign keys, and the fields relevant to the explanation.

Sequence Diagram

• Use text labels for actors across the top.
• Use vertical lines or repeated arrows to indicate message order.
• Use arrows with labels like POST /login, enqueue job, or ACK.
• Number key steps if the interaction is long.
• Keep parallel flows separated visually rather than forcing too many crossing arrows.

Practical Prompt Patterns

• "Create a whiteboard-style architecture diagram with six boxes and directional arrows."
• "Make the frontend, API, and worker visually separated into columns."
• "Use a decision diamond after payment validation."
• "Add labels to arrows showing request type and payload."
• "Keep the style sketchy and informal, suitable for an engineering design note."

Suggested JSON Planning

• Think in terms of elements, labels, and relationships.
• Define each node first.
• Define the connectors second.
• Add titles and notes last.
• Keep IDs stable if you expect to revise the same diagram repeatedly.

Revision Workflow

• Generate the initial scene from a natural-language description.
• Render it with mcp__claude_ai_excalidraw__create_view.
• Inspect for overlap, unclear labels, and missing relationships.
• Save the working state with save_checkpoint.
• Make incremental changes rather than regenerating from scratch if the structure is already mostly right.
• If a revision goes sideways, recover the previous state using read_checkpoint.