diagram-skill

A tool-agnostic Claude Code skill for creating, editing, and iteratively refining diagrams in any project. Excalidraw is the primary tool — authored as .excalidraw JSON and rendered to PNG fully locally (no browser, network, or Docker). Mermaid is a legacy fallback for existing .mmd files or explicit Mermaid / inline-in-Markdown requests.

Layout

• SKILL.md — entry point + backend routing (Excalidraw default; Mermaid legacy).
• scripts/render.sh — dispatcher; routes a source file to a backend by extension.
• backends/excalidraw/ — primary backend: pure-Node renderer + element-schema reference.
• backends/mermaid/ — legacy backend: mmdc + headless Chrome (ported from mermaid-diagrams).

Workflow

Author docs/diagrams/<name>.excalidraw → bash scripts/render.sh docs/diagrams/<name>.excalidraw → Read the PNG → refine the JSON → re-render. The read-the-PNG-and-refine loop is the point: you adjust an existing diagram instead of regenerating it. Share via serve-image / serve-gallery over Tailscale.

Guarantees

• Writes only inside the current project's docs/diagrams/. Never /tmp or $HOME.
• No public-host uploads; rendering is local.
• Source files (.excalidraw / .mmd) are the source of truth.

Rendering

• Excalidraw: @vraksha/excalidraw-cli (node-canvas), vendored into node_modules on first render. A RENDER_BACKEND hook is reserved for a future headless-Chromium / SVG backend.
• Mermaid: @mermaid-js/mermaid-cli (mmdc) via a global install or npx.

Adding a backend

Create backends/<name>/render.sh <input> [output] (writes an image, nothing outside the project), add one extension → backend line to scripts/render.sh, and a routing note to SKILL.md.

Install

Added to agentic-dev-config as a submodule; install.sh symlinks it into ~/.claude/skills/.