hand-drawn-diagrams

Overview of hand-drawn-diagrams skill

What hand-drawn-diagrams does

The hand-drawn-diagrams skill turns a plain-language request into a hand-drawn Excalidraw diagram, then validates it and can deliver an edit URL plus exportable image outputs. It is best for people who want diagrams that feel sketched and explanatory, not polished corporate vector art.

Who it is for

Use the hand-drawn-diagrams skill if you need fast Diagramming for teaching, UX flows, architecture explainers, funnels, or page mockups and you do not want to build the layout manually. It is a strong fit when the main goal is to communicate structure clearly and quickly, not to fine-tune every visual detail by hand.

Why it is different

The main differentiator is the workflow: the skill does not just “draw a diagram,” it routes the request to a diagram type, builds an Excalidraw file, and supports animation and export. That means the hand-drawn-diagrams guide is less about freeform sketching and more about producing a usable artifact from a prompt with fewer layout mistakes.

How to Use hand-drawn-diagrams skill

Install hand-drawn-diagrams

For a typical agent setup, install with:

npx skills add muthuishere/hand-drawn-diagrams --skill hand-drawn-diagrams

If you want faster PNG and animated SVG rendering, install chrome-devtools-mcp and add it to your Claude Code MCP config. Without it, rendering can fall back to Playwright, which is slower and may require a browser install.

Give the skill a better prompt

The skill works best when you specify the diagram’s job, audience, and route cues. A weak prompt like “make a diagram of my app” often produces generic structure. A stronger prompt looks like:

• “Create a UX flow for password reset on mobile. Show entry, verification, error recovery, and success.”
• “Make a technical explainer for event-driven order processing. Emphasize publish, queue, worker, retry, and notification.”
• “Build a page mockup for a SaaS analytics dashboard. Use restrained color only if it improves webpage-like fidelity.”

That wording helps the hand-drawn-diagrams usage path choose the right route and include the right elements.

Read these files first

Start with SKILL.md, then workflow.md, AGENTS.md, and references/index.md. For practical output quality, also inspect references/activation-routing.xml, references/fundamental-shapes.md, and the route-specific reference that matches your task. If you are debugging install or execution behavior, the steps/ files are more useful than the README.

Follow the 3-step workflow

This repository is opinionated: route first, draw second, validate and deliver last. The output files should be created in /tmp/hand-drawn-diagrams/<slug>/ by default, and the required artifacts are diagram.excalidraw and diagram.animationinfo.json. If either is missing, the workflow is not complete.

hand-drawn-diagrams skill FAQ

Is hand-drawn-diagrams good for any diagram?

No. It is strongest when the result should feel like a sketch or explainer, especially for routes such as teaching, UX, technical explainer, ideation, or page mockup. If you need pixel-perfect brand design or a fully custom illustration, a generic prompt or dedicated design tool may fit better.

Do I need to know Excalidraw to use it?

No. The hand-drawn-diagrams skill is designed to accept natural language and create the structure for you. You only need enough detail to describe the diagram’s purpose, major parts, and desired route.

What is the main limitation?

The skill favors clarity, routing, and validation over artistic freedom. It is not ideal when you want unrestricted creative composition, heavy color styling, or a diagram that ignores the routing rules. The hand-drawn-diagrams guide works best when the task has a clear reading path.

How is this different from a normal prompt?

A normal prompt may generate a description of a diagram. hand-drawn-diagrams is built to produce a usable Excalidraw artifact with workflow steps, route selection, and export-oriented output. That makes it more reliable when you need something you can edit, share, and iterate.

How to Improve hand-drawn-diagrams skill

Give the route, not just the topic

The fastest way to improve results is to say what kind of diagram you want. “Explain my API” is vague; “technical explainer showing request, auth check, handler, database, and response” is actionable. The skill can route better when your prompt names the intended structure of the hand-drawn-diagrams for Diagramming output.

Provide the minimum meaningful structure

Include the audience, the main steps or components, and any must-include labels. If you have a preferred layout, say so: left-to-right flow, top-to-bottom process, clustered notes, or page mockup. This reduces backtracking and keeps the diagram from overfitting to the wrong pattern.

Watch for common failure modes

The usual problems are overlong labels, too many nodes, and ambiguous relationships. If the first output feels crowded, trim the scope and restate the key sequence. If arrows become messy, simplify the flow before asking for a rerender. When improving hand-drawn-diagrams usage, fewer ideas usually beats more detail.

Iterate with targeted feedback

Ask for one kind of revision at a time: simplify labels, change route, reduce density, or increase fidelity for a mockup. If the diagram is close but not quite right, point to the exact section that failed rather than reissuing the whole prompt. That keeps the next version aligned with the original job-to-be-done and makes the hand-drawn-diagrams install decision pay off in practice.