diagramby Garry Tan

Diagram Skill.

A Claude Code and Codex skill for diagrams and charts: turns a description or Mermaid source into an editable Excalidraw file plus rendered SVG and PNG.

Diagrams & Data Visualization
Diagram

Download OpenDesign View usage guide

garrytan/gstack · diagram/SKILL.mdSKILL.md

--- name: diagram description: Turn an English description (or mermaid source) into a diagram triplet: the source, an editable .excalidraw file you can open on excalidraw.com, and rendered SVG + PNG. (gstack) --- ## When to invoke this skill ## Step 1 — Author the diagram ## Step 2 — Stage the render bundle (once per session) ## Step 3 — Render the triplet ## Step 4 — Show and deliver ## Rules

Front matter and section headings read from the upstream file on 2026-09-14 · 16,276 characters in full

01 What it does

What the diagram Skill Does in Claude Code and Codex

Summary, workflow and outputs, all read from the skill's SKILL.md.

From the SKILL.mdRead 2026-09-14 · not a recorded run

In the Skill's Own Terms

Converts an English description or Mermaid source into a diagram triplet: the Mermaid source (.mmd), an editable Excalidraw file (.excalidraw) that opens at excalidraw.com, and rendered SVG + PNG outputs. Rendering is fully offline via a local loopback server — uses the Aside browser when running, otherwise gstack's own headless browser.

Flowcharts (graph LR/TD) and sequence diagrams produce fully editable Excalidraw scenes with real boxes, arrows, and text. Other Mermaid diagram types (state, class, gantt) render to SVG/PNG and export as a single image element in the Excalidraw file — movable and annotatable but not element-editable. The Mermaid source remains the single source of truth for iterating.

What it produces

A Mermaid source file (.mmd) that serves as the LLM-friendly interchange format and single source of truth.

See the example prompt ↗

How It Works

01
Author Mermaid Source
Write Mermaid matching the user's request. Prefer graph LR for pipelines/flows and graph TD for hierarchies.
02
Stage the Render Bundle Once per Session
Stage diagram-render.html in gstack's render staging directory under ${TMPDIR:-/tmp}/gstack-render, content-addressed by bundle SHA.
03
Render the Triplet with One Command
Write the .mmd file, then run gstack-render with the staged bundle.
04
Show and Deliver
Read the PNG inline so the user sees the diagram. List the triplet paths and note that the .excalidraw file opens at excalidraw.com for editing.

02 Find your fit

When to Use the diagram Skill

Use the diagram skill in Claude Code or Codex when the job is diagrams and charts of this kind. Fit and limits below are taken from the skill's own file.

Good Fit

User requests to make a diagram, draw the architecture, create a flowchart, diagram this, or visualize a flow.
Producing crisp vector diagrams for documentation alongside raster outputs for chat, issues, or READMEs.
Generating an editable Excalidraw file the user can open at excalidraw.com, move boxes, and continue working on.

Know the Boundaries

Diagrams with more than 15 nodes in a single scene — split into multiple diagrams for readability.
State, class, gantt, and other non-flowchart/non-sequence Mermaid types produce an Excalidraw file that is movable but not element-editable.

What to Provide

English description or Mermaid sourceThe user provides a description of the diagram to create, or supplies existing Mermaid source to render.

03 Inside the skill

Rules the diagram Skill Gives Claude Code and Codex

8 concrete instructions, defaults and limits the SKILL.md sets for the agent — the part of the file that changes the result.

Never Ship Without Rendering
A .mmd file alone is not a diagram. If rendering is impossible (bundle missing or no browser available), surface the blocker and stop.
Flowcharts and Sequence Diagrams Are Fully Editable
Flowcharts (graph LR/TD) and sequence diagrams convert to fully editable Excalidraw scenes with real boxes, arrows, and text. Other Mermaid types export as one image element.
Base64-encode Source for Browser Transport
Ship Mermaid source to the render page via base64 to avoid interpreting backticks, ${ }, and backslashes in the source. Never splice file contents into a JS template literal.
Output Directory Follows Git Context
Write to ./diagrams/ when cwd is a git repo (artifacts the user can commit), otherwise to /tmp/gstack-diagrams/. Derive slug from subject in kebab-case, max 40 chars.
PNG Width Is Fixed at 1950px
The rasterized PNG is always 1950 pixels wide, equivalent to 300dpi of a 6.5-inch placement.
Rendering Is Fully Offline
The diagram-render bundle is self-contained and served from loopback. No CDN, no network.
Re-render Edited Excalidraw Without Touching Mermaid
When the user edits an .excalidraw file and wants to re-render, load the scene file and export SVG/PNG directly — do not regenerate from Mermaid source.
Prefer Embedding .mmd for PDF Targets
For diagrams going into a PDF, remind the user that make-pdf renders Mermaid fences natively — embedding the .mmd in markdown is better than embedding the PNG.

04 Put it to work

Install diagram in Claude Code or Codex

One npx skills add command, then a first task in your agent and a checklist for the result.

Add diagram to Claude Code, Codex or Your Agent

Run in your project; the installer asks which agent to add it to.

Terminal

npx skills add https://github.com/garrytan/gstack --skill diagram

Generic skills CLI form for diagram/SKILL.md; the repository may document its own path.

Give the Skill a First Diagrams and Charts Task

Written in the skill's own terms; replace the bracketed parts with your material.

Starter prompt

Create a flowchart showing the build pipeline for [my TypeScript project]. Include lint, test, build, and deploy stages with their dependencies. Use graph LR layout and output to ./diagrams/.

Source: written from the SKILL.md in the skill's own terms.

Check the First Result

What the SKILL.md itself says a correct result looks like:

Read the PNG output inline to verify the diagram rendered correctly and matches the user's request.
Check gstack-render output for ERROR: lines indicating Mermaid parse errors — fix the .mmd and retry if present.
Inspect PAGE_ERRORS output for 'Error processing Mermaid diagram' to confirm when the Excalidraw converter fell back to a single image element.
Verify all three OK <path> lines appear in gstack-render output, confirming SVG, PNG, and Excalidraw files were written.
For edited Excalidraw re-renders, ignore the benign WorkerInTheMainChunkError in PAGE_ERRORS — the SVG/PNG are correct.

In OpenDesign import diagram from its SKILL.md link: Plugins → Add → Skill → Import from link, then pick it in the top bar.

Download OpenDesign Read the quickstart

05 Open source, traceable

Source, License and Verification

Where this page's facts come from, and when they were last checked.

Author: Garry Tan
Repository: github.com/garrytan/gstack Branch main
Skill file: diagram/SKILL.md Content checksum recorded at verification; commit 71f6048
License: MIT From LICENSE.
Repository stars: 132,921 GitHub snapshot taken 2026-09-14 for the whole garrytan/gstack repository, which contains 7 skills in this catalog. Not a rating or usage count for diagram.
Verified by OpenDesign: 2026-09-14 Source file, path, license text and star count were checked. Not bundled in OpenDesign main (checked 2026-08-28); a live run has not been recorded on this page.

Inside the SKILL.md

When to invoke this skillUse for diagram, architecture, flowchart, or visualization requests; SVG/PNG use Mermaid style, Excalidraw has hand-drawn aesthetic.
Step 1 — Author the diagramWrite Mermaid source; flowcharts and sequence diagrams become fully editable Excalidraw; other types export as single image.
Step 2 — Stage the render bundle (once per session)Copy diagram-render.html to gstack's render staging directory, content-addressed by SHA, never clobbering concurrent sessions.
Step 3 — Render the tripletWrite .mmd, run gstack-render with base64-encoded source, output SVG/PNG/Excalidraw; check for parse errors and PAGE_ERRORS.
Step 4 — Show and deliverRead PNG inline, list triplet paths, note Excalidraw editability; for changes edit .mmd and re-render.
RulesNever ship without rendering; for PDF targets remind user make-pdf renders Mermaid fences natively.
Completion statusDONE when triplet delivered; BLOCKED if bundle missing or no browser available.

The Skill's Own Description

“Turn an English description (or mermaid source) into a diagram triplet: the source, an editable .excalidraw file you can open on excalidraw.com, and rendered SVG + PNG. (gstack)”

Front-matter description from SKILL.md. The full file is about 16,276 characters. Read the full file on GitHub.

06 Before you install

Questions About the diagram Skill

Answers come from the SKILL.md as read on 2026-09-14, not from a recorded run.

What happens if the render bundle is missing or no browser is available?

The skill stops and tells you to build the bundle by running bun run build:diagram-render in the gstack repo, or to open Aside (macOS 15+) if gstack's browser is not built. The skill never installs Aside for you or substitutes a CDN or another renderer.

Diagram

Run diagram on a Real Diagrams and Charts Task.

Download OpenDesign, import diagram from its SKILL.md link, paste the prompt above, and read the plan before the result.

Download OpenDesign Browse all skills

Terminal

npx skills add https://github.com/garrytan/gstack --skill diagram

What the diagram Skill Does in Claude Code and Codex

In the Skill's Own Terms

How It Works

When to Use the diagram Skill

Good Fit

Know the Boundaries

What to Provide

Rules the diagram Skill Gives Claude Code and Codex

Never Ship Without Rendering

Flowcharts and Sequence Diagrams Are Fully Editable

Base64-encode Source for Browser Transport

Output Directory Follows Git Context

PNG Width Is Fixed at 1950px

Rendering Is Fully Offline

Re-render Edited Excalidraw Without Touching Mermaid

Prefer Embedding .mmd for PDF Targets