Guide · Agent skill
How to use the Excalidraw agent skill to sketch diagrams
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Excalidraw skill lets an AI agent draw hand-drawn style diagrams on a local Excalidraw canvas that you can watch update in your browser and then edit yourself. This guide explains what an agent skill is, how to install this one, how to ask for diagrams in plain language, and what it needs to run safely. By the end you will be able to sketch an architecture or flow from a description, read a rough canvas back, and produce a shareable link or file.
Excalidraw Diagram Sketcherdanielmiessler/LifeOS · MIT Download the skill Quick start
- 1Check the requirements. Confirm Bun is installed and that local port 3579 is free. Make sure you have internet access if you plan to share links.
- 2Install the skill folder. Download the ZIP from this page, unzip it so the folder is named Excalidraw, and place it in ~/.claude/skills/ or a project's .claude/skills/ folder. Or upload it under Settings, then Capabilities, then Skills in the Claude apps.
- 3Ask for a diagram. Describe what you want using a trigger phrase such as sketch a diagram or draw this on a canvas. The agent starts the canvas server if needed.
- 4Watch and edit on the canvas. Open the canvas address in your browser to watch the diagram draw. Move, retype or restyle elements by hand as needed.
- 5Check readability. Let the agent run the contrast check so every label is readable in light and dark mode before the diagram is treated as finished.
- 6Share or export. Create a share link for a scene without images, or send the exported .excalidraw file or a PNG when the diagram contains screenshots.
What the Excalidraw skill makes the agent do
An agent skill is a folder of instructions and helper scripts that an AI agent can load when a request matches it. This skill gives the agent a way to work with Excalidraw, a whiteboard-style drawing tool. It runs a local canvas server so the diagram draws itself in a browser tab while the agent works.
It works in two directions. The agent can sketch ideas onto the canvas from a description, and it can read a rough diagram you drew back into structured data so it can tidy or extend it. The skill also converts Mermaid diagrams, embeds screenshots, checks text readability, and produces excalidraw.com share links or .excalidraw files.
- Sketch a diagram from a description on a live local canvas
- Read a human's rough canvas back as structured data
- Convert Mermaid diagrams to Excalidraw
- Embed a real screenshot as a diagram node
- Check that text is readable against its background
- Export a shareable excalidraw.com link or a .excalidraw file
Install the Excalidraw skill from the download ZIP
Download the ZIP for this skill from this page and unzip it. The folder must be named Excalidraw so that the agent finds the SKILL.md file inside it. For a personal install on your machine, place the folder in ~/.claude/skills/. To limit the skill to one project, place it in that project's .claude/skills/ folder instead.
If you use the Claude apps rather than a folder-based setup, you can upload the skill instead under Settings, then Capabilities, then Skills. Either way, the skill only works after its requirements are in place, so check the requirements section below before your first request.
- Personal install: ~/.claude/skills/Excalidraw/
- Project install: .claude/skills/Excalidraw/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload
bun ~/.claude/skills/Excalidraw/Tools/Canvas.ts statusWhat you need before it runs
The scripts run with Bun, so Bun must be installed. The helper uses bunx to fetch a pinned version of the community package mcp-excalidraw-server, which is MIT licensed. The canvas server listens on local port 3579, so that port must be free. Sharing links and opening shared files need internet access to excalidraw.com.
Browser-based features such as screenshots, Mermaid conversion, image export and viewport control need an open canvas tab. Creating and editing elements, describing the scene, and exporting or importing work without one.
- Bun runtime installed
- Permission for bunx to fetch the pinned mcp-excalidraw-server package
- Local port 3579 available
- Internet access to excalidraw.com for share links and shared files
- A browser tab on the canvas for screenshots and Mermaid conversion
Trigger the skill with natural requests
You do not need special syntax. Describe what you want in ordinary words and include a trigger word such as excalidraw, whiteboard, canvas, sketch a diagram, or hand-drawn diagram. The agent matches your request to either sketching a new diagram or refining an existing one.
Requests to read or tidy your own drawing, or to edit a .excalidraw file, go to the refinement workflow. Requests for polished artwork or marketing visuals are outside this skill and are better handled by a different skill.
- Sketch a diagram: 'Sketch a diagram of our login flow on the whiteboard.'
- Architecture sketch: 'Draw an architecture sketch of a web app, a queue and a database on a canvas.'
- Read my canvas: 'Read my canvas and tell me which boxes are not connected.'
- Organize: 'Organize my whiteboard into clusters and connect related items.'
- Convert: 'Turn this Mermaid diagram into an Excalidraw file.'
Walk through a sketch from start to finish
Ask for a diagram and the agent starts the canvas server if it is not already running. Open the canvas address in your browser to watch the diagram draw itself. When the agent stops, you can drag, retype or restyle elements by hand on the same canvas.
Before the agent declares a diagram finished, it runs a contrast check on every text element. This catches labels that would be hard to read in light or dark mode. When you are done drawing, the agent can stop the server unless you want to keep using it.
- Open the canvas address to watch live and hand-edit
- The contrast check must pass before a diagram is called done
- The server is stopped when drawing work finishes, unless you keep using it
bun ~/.claude/skills/Excalidraw/Tools/ContrastCheck.ts
bun ~/.claude/skills/Excalidraw/Tools/Canvas.ts stopShare a diagram or embed a screenshot
To share a diagram by link, use the share helper rather than the built-in share command, because the helper keeps the canvas background dark by default. Share links upload the scene to excalidraw.com, so do not use them for sensitive diagrams. When someone opens a shared link, excalidraw.com asks them to click Replace my content, which overwrites their previous scene there.
Embedded images do not survive a share link. They show as broken-image placeholders. For a diagram that contains screenshots, send the exported .excalidraw file instead, which keeps the picture. You can also send a PNG flattened from that file.
- Share link: bun ~/.claude/skills/Excalidraw/Tools/Share.ts <scene.excalidraw>
- Embed an image: bun ~/.claude/skills/Excalidraw/Tools/AddImage.ts <image> --x N --y N
- Scenes with screenshots: send the .excalidraw file or a PNG, not a link
bun ~/.claude/skills/Excalidraw/Tools/Share.ts <scene.excalidraw> --bg #111114Safety notes on scripts and the network
The skill runs scripts and uses the network. The canvas runs locally, but share links and shared files go through excalidraw.com, so anything you share leaves your machine. The skill drives the canvas only through its wrapper script, which pins the package version and port, and it does not register an MCP server of its own.
Refinement is designed to protect your work. Risky changes are snapshotted first, and your own elements are reorganized rather than replaced. Still, review any scene before you share it outside your team.
- Local canvas stays on your machine; share links upload the scene
- Use the wrapper script rather than running the package directly
- Do not share sensitive diagrams by link without thought
Tips and troubleshooting
If a fresh browser tab shows an empty canvas, the agent can repaint the tab from the server's copy of the scene. Do not click the app's Sync to Backend button in a blank tab, because it can push the empty scene over the server. Text on the local canvas may look larger or clipped because of a known upstream bug, so use the share link or exported file as the final view.
If a command fails, check the exit code. Code 2 means a usage error, 3 means the canvas cannot be reached, and 4 means a browser tab is required.
- Exit 3: the canvas cannot be reached; start the server and check port 3579
- Exit 4: open the canvas in a browser tab for that feature
- Set a default export folder or palette in your customizations PREFERENCES.md file if you want consistent output
What people use it for
- Turn a written description of a system into a hand-drawn architecture sketch for a design review.
- Convert a Mermaid flow chart into an Excalidraw file you can keep editing by hand.
- Ask the agent to read a rough whiteboard you drew and organize it into clusters with connected items.
- Embed a dashboard screenshot as a labelled node in a process diagram.
- Create a shareable excalidraw.com link for a diagram that has no images, to send to a colleague.
Frequently asked questions
Is the Excalidraw agent skill free?
The skill is published under the MIT licence, and the underlying mcp-excalidraw-server package is also MIT licensed and community maintained. Check the licence file included with the skill for the full terms before you reuse it.
What do I need to install the Excalidraw skill?
You need Bun installed, permission for bunx to fetch the pinned mcp-excalidraw-server package, local port 3579 free, and internet access if you want share links. Then place the unzipped Excalidraw folder in ~/.claude/skills/ or a project's .claude/skills/ folder.
Where do I upload an agent skill in the Claude apps?
In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill there. The skill still needs Bun and the other requirements on the machine that runs its scripts.
Why do my images disappear when I share an Excalidraw link?
Embedded images do not survive an anonymous excalidraw.com share link and show as broken-image placeholders. Images are kept in the exported .excalidraw file, so send that file or a PNG flattened from it for diagrams with screenshots.
Can the agent edit a diagram I drew by hand?
Yes. The refinement workflow can read your rough canvas into structured data and reorganize it while keeping your own elements. Changes are made by element ID, and risky changes are snapshotted first.
How is this different from using Mermaid or the Excalidraw website directly?
Mermaid writes diagrams as text and the Excalidraw website is a manual drawing tool. This skill lets an agent create and edit the hand-drawn canvas for you from a description, while you can still watch it live and adjust elements yourself.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you want quick, hand-drawn style architecture or flow sketches from a description, or if you already use Excalidraw and want an agent to tidy or extend your diagrams. Pick a different tool if you need polished final artwork or marketing visuals, if you cannot run Bun or free port 3579, or if your diagrams are too sensitive to upload through a share link.
Download the skill