/excalidraw

name: excalidraw
description: Create and export diagrams with Excalidraw - whiteboard-style sketches, flowcharts, architecture diagrams via MCP or CLI.
version: 1.0.0
author: hermes-CCC (ported from Hermes Agent by NousResearch)
license: MIT
metadata:
  hermes:
    tags: [Creative, Excalidraw, Diagrams, Visualization, Whiteboard]
    related_skills: []

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`.

Checkpoints

• Use `save_checkpoint` before major layout changes.
• Use `save_checkpoint` before adding dozens of new elements.
• Use `read_checkpoint` when you need to compare alternative diagram versions.
• Use checkpoints to maintain a clean "baseline" for architecture documents.
• Checkpoints are especially useful for iterative design sessions with multiple stakeholders.

Export Workflow

• Use `mcp__claude_ai_excalidraw__export_to_excalidraw` when you want a portable Excalidraw artifact.
• Export to Excalidraw format when the diagram should remain editable in the Excalidraw ecosystem.
• Export as PNG when you need a static