Hand-Drawn Diagrams Skill
Turn one natural-language prompt into hand-drawn Excalidraw architecture, workflow, and UX wireframe diagrams, with a hosted edit link, stroke-by-stroke animation, and PNG export.
Evidence shows least-privilege tendencies: defaults to /tmp over user workspace, forbids rendering unvalidated files, clear file-location rules, complete MIT license with upstream attribution to Excalidraw and excalidraw-animate. Deducted for: the core delivery chain sends full diagram content as URL hashes to the excalidraw.com hosted service with non-prominent data-flow disclosure; open_diagram.py auto-opens a browser without explicit user confirmation; publisher identity is unverified.
Repo contains a real pytest suite (hosted_scene_urls, open_diagram) and the workflow enforces a validate-before-URL failure-feedback path; INSTALL.md has a troubleshooting table. Deducted for: static review cannot execute reproduction; no CI workflow running tests (only a skill-review workflow) is shown; slow-marked Playwright/browser-path tests suggest thin coverage.
Scenarios, routing table (teach/UX/funnel/medical etc.), output modes and trigger keywords are clearly described; non-fit boundary (not an Excalidraw replacement) is stated. Deducted for: core function depends on excalidraw.com hosted URLs and browser rendering, whose reachability from mainland China is uncertain; no Chinese-language support mentioned.
Well-layered docs (SKILL.md→workflow→steps→references), install/uninstall scripts, clear MIT license and third-party attribution, complete test instructions. Deducted for: registry license metadata is NOASSERTION; no version number or changelog; README credits deemwar while LICENSE copyright is Muthukumaran Navaneethakrishnan, making maintenance responsibility inconsistent.
The claimed capability (natural language → editable .excalidraw → animation/PNG) is consistent with the scripts, routing and templates; the comparison table vs. using Excalidraw directly is clear; example output images are referenced. Deducted for: static review cannot verify outputs are directly usable; the hosted-URL delivery via open.html redirect is unverified in actual execution.
Auditable primary material exists: committed tests, deterministic encoding tests, referenced sample files, upstream library attribution. Deducted for: no independent reproduction in this static review; README demo images/animations unverifiable here; no third-party execution evidence (no test-running CI).
- Delivery chain encodes full diagram content into URLs sent to excalidraw.com; avoid hosted links for sensitive diagrams
- open_diagram.py auto-opens a browser — an external effect; confirm before use
- Core rendering depends on excalidraw.com and the GitHub/npm ecosystem; mainland-China reachability is unverified
- Inconsistent maintainer attribution (deemwar vs LICENSE copyright holder) and no version/changelog make long-term maintenance uncertain
- Static review executed nothing; output quality and script behavior were not independently reproduced
What does this skill do, and when should you use it?
hand-drawn-diagrams is an Agent Skill for Claude Code, Codex CLI, and compatible agents that converts natural-language descriptions into hand-drawn-style Excalidraw diagrams. It auto-selects a diagram type from user intent (teaching, brainstorming, UX flow, funnel, technical explainer, medical, creative, or page mockup), draws using a shared shape grammar, and validates output via bundled scripts. Deliverables include a standard .excalidraw source file, a hosted edit URL, an animated SVG that draws itself stroke by stroke, and PNG on request. Source files default to /tmp/hand-drawn-diagrams/, keeping the user's workspace clean.
The skill runs a three-step workflow: 1) Route — reads its step files and picks a diagram type from the routing table in references/activation-routing.xml based on user intent; 2) Draw — designs the diagram with the shape grammar in references/fundamental-shapes.md and writes a non-empty .excalidraw JSON file to /tmp/hand-drawn-diagrams/<slug>/; 3) Validate & Deliver — runs scripts/validate_excalidraw.py, then scripts/open_diagram.py to generate a hosted edit URL and open it in the browser. Labels follow rules of 1–5 words per shape and max 3 short bullets per container. Default style is monochrome hand-drawn; rendering prefers Chrome DevTools MCP with a Playwright fallback. Animation and PNG are offered as follow-ups.
- A student turning course notes into hand-drawn revision maps before exams
- A system architect generating system and API flow diagrams from one sentence, with an editable Excalidraw link
- A designer or product manager sketching UX flows or page mockups as monochrome wireframes
- A teacher preparing concept explainers and lesson breakdowns for class
- A sales team producing funnel and conversion-path visuals
- A developer adding an animated SVG architecture explainer to documentation
What are this skill's strengths and limitations?
- Zero starting point: natural language in, diagram out, with automatic diagram-type selection and non-overlapping layout
- Output is standard .excalidraw files — open, edit, and own them in Excalidraw with no lock-in
- One prompt can yield a hosted edit URL, animated SVG (powered by excalidraw-animate), and PNG
- Source files default to /tmp/, keeping the workspace clean
- Built-in validation script enforces checking before URL generation, preventing empty diagram delivery
- The repo's License field shows NOASSERTION while the README states MIT — licensing needs independent verification
- Full rendering (fast PNG/animation) depends on Chrome DevTools MCP or Playwright; capabilities shrink if neither is present
- No test suite or cross-platform verification evidence is provided in the source
- Label and text constraints (1–5 words per shape, max 3 bullets per container) limit information-dense diagrams
- Validation covers script checks plus style rules (font, monochrome), not semantic correctness of the diagram
How do you install this skill?
Run npx skills add muthuishere/hand-drawn-diagrams. The installer supports Claude Code, Codex, OpenCode, Windsurf, GitHub Copilot, Cursor, Gemini CLI, and 40+ more agents, detecting installed agents automatically. Global vs project scope and uninstall options are documented in the repo's INSTALL.md (details not covered in the source material). For faster PNG and animated SVG rendering, optionally install chrome-devtools-mcp per INSTALL.md; otherwise rendering falls back to Playwright.
How do you use this skill?
After installing, prompt a supported agent in natural language, e.g. "draw an architecture diagram for an order system" or "sketch this flow as a hand-drawn wireframe". By default a hosted Excalidraw editor opens in your browser for editing and download; say "open the animation" for the stroke-by-stroke view, "save image" to export a PNG, or "save as excalidraw" to keep the source file. Sources go to /tmp/hand-drawn-diagrams/ unless you explicitly ask for project files.
How does this skill compare with similar options?
The README compares it against using Excalidraw directly: Excalidraw starts from a blank canvas where you draw everything yourself, while this skill starts from a natural-language prompt, auto-picks the route, auto-assigns layout, generates animation, and delivers a hosted URL. It is a layer on top of Excalidraw, not a replacement. Animation is powered by dai-shi's open-source excalidraw-animate.