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 image for reports, PRs, slides, or issue comments.
• Export as SVG when you need scalable vector output for documents or web embedding.
• Prefer SVG when crisp text and resizable diagrams matter.

PNG vs SVG

• PNG is easy to paste into chat, docs, and presentations.
• PNG is better when consumers do not need to edit the figure.
• SVG is better for documentation sites, architecture handbooks, and print-quality scaling.
• SVG is easier to version in some documentation pipelines.
• If unsure, export both.

Sharing

• Excalidraw scenes can be shared via https://excalidraw.com/ workflows after export.
• This is useful when collaborators want to tweak the drawing manually in the browser.
• Excalidraw sharing is convenient for design reviews and async comments.
• Keep exported scene files with the related document so the diagram is reproducible.

Style Guidance

• Keep node labels short.
• Avoid paragraphs inside shapes.
• Use whitespace aggressively to reduce overlap.
• Use consistent arrow direction when possible.
• Put titles outside the main node grid.
• Group annotations near the edge instead of in the center of the flow.

Good Defaults

• System diagrams: left-to-right flow, clear zones, arrows labeled only when needed.
• Flowcharts: top-to-bottom, one decision per diamond, one short phrase per node.
• ERDs: entity name plus only important fields.
• Sequence diagrams: ordered messages with minimal crossings.
• Whiteboard sketches: rough but readable beats pixel-perfect precision.

Example Requests

Create a system architecture diagram for a RAG application with:
- Browser client
- FastAPI gateway
- Retrieval service
- Vector database
- Background worker
- External LLM API
Use rectangles for systems, arrows for data flow, and a handwritten whiteboard feel.

Create a flowchart for password reset:
- User requests reset
- System validates account
- If invalid, show error
- If valid, send email
- User clicks token link
- System verifies token
- If token expired, restart flow
- If valid, allow password update

When Excalidraw Fits Best

• Early-stage architecture thinking
• Fast diagrams during debugging
• Design docs that need quick visuals
• Workshop and brainstorming artifacts
• Teaching and onboarding materials

When To Use Something Else

• Use Mermaid when you need diagram-as-code in Markdown-first pipelines.
• Use Graphviz when you need algorithmic layouts for large graphs.
• Use presentation tools when heavy branding matters more than editability.
• Use CAD or vector illustration tools when exact geometry matters.

Operational Tips

• Keep diagram generation prompts close to the engineering language of the system.
• Name services exactly as they appear in the codebase when possible.
• Reuse checkpointed scenes for versioned architecture docs.
• Export to SVG for stable documentation output.
• Export to Excalidraw format when team members want browser editing.

Summary

• Describe what you want as a diagram and Claude can generate the JSON spec.
• Render scenes with mcp__claude_ai_excalidraw__create_view.
• Export editable artifacts with mcp__claude_ai_excalidraw__export_to_excalidraw.
• Save progress with save_checkpoint and recover with read_checkpoint.
• Use Excalidraw for system architecture, flowcharts, ERDs, sequence diagrams, and sketch-style visuals.