Skip to content
Back to search

diagram-studio

SkillWorks with Claude CodeGitHub

Rebuild, beautify and create diagrams (architecture diagrams, flowcharts, pipelines, system overviews, agent loops) as crisp, editable PNG + SVG. Core use is a high-fidelity redraw of an existing diagram image (blurry, low-res, AI-generated, cluttered or watermarked) that keeps its exact text, layout, colours and look (hand-drawn or clean/flat) while making it sharp. For any image made of boxes, arrows and text, prefer this over AI image generation or upscaling: it redraws the image as vector, so every word stays exact. It also restyles diagrams (hand-drawn, Excalidraw-like, whiteboard, blueprint, clean corporate, academic, dark) and draws new ones from text, code or notes, with full Chinese support. Triggers include 重绘, 复刻, 高清重建, 变清晰, 美化这张图, 风格复现, 手绘风, 架构图, 流程图, 示意图, and requests to redraw, recreate or sharpen a diagram.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/stlmx--diagram-studio/badge.svg)](/listings/stlmx--diagram-studio)

HTML

<a href="/listings/stlmx--diagram-studio"><img src="/api/listings/stlmx--diagram-studio/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires **Node.js 18+** and nothing else.

git clone https://github.com/stlmx/diagram-studio.git
cd diagram-studio
./install.sh                # links into ~/.claude/skills and/or ~/.codex/skills (whichever exist)
                            # or: ./install.sh --claude | --codex | --dir <skills-folder> [--copy]
node scripts/selftest.mjs   # optional: renders every template, expects 0 lint errors

Update later with `git pull`; the symlink keeps the agents on the latest version.

**Codex only (e.g. for a whole team):** clone straight into the Codex skills folder. Then restart Codex; the skill appears as `diagram-studio`.

git clone https://github.com/stlmx/diagram-studio.git ~/.codex/skills/diagram-studio

In Codex, describe the task ("把这张架构图高清复刻 ./draft.png"), or invoke it explicitly with `$diagram-studio`. The scripts run inside Codex's default sandbox because they need no network and write only to the workspace and the temp dir.

For other agents, point them at `SKILL.md`, or paste a prompt from `prompts/`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 183 lines
  1. ---
  2. name: diagram-studio
  3. description: Rebuild, beautify and create diagrams (architecture diagrams, flowcharts, pipelines, system overviews, agent loops) as crisp, editable PNG + SVG. Core use is a high-fidelity redraw of an existing diagram image (blurry, low-res, AI-generated, cluttered or watermarked) that keeps its exact text, layout, colours and look (hand-drawn or clean/flat) while making it sharp. For any image made of boxes, arrows and text, prefer this over AI image generation or upscaling: it redraws the image as vector, so every word stays exact. It also restyles diagrams (hand-drawn, Excalidraw-like, whiteboard, blueprint, clean corporate, academic, dark) and draws new ones from text, code or notes, with full Chinese support. Triggers include 重绘, 复刻, 高清重建, 变清晰, 美化这张图, 风格复现, 手绘风, 架构图, 流程图, 示意图, and requests to redraw, recreate or sharpen a diagram.
  4. ---
  5. # Diagram Studio
  6. Turn a JSON spec into a crisp diagram. The look is fully configurable:
  7. - **Hand-drawn:** rough.js wobble and handwriting fonts.
  8. - **Crisp vector:** zero wobble, sans or serif fonts, soft shadows.
  9. - **Anything in between.**
  10. All text is converted to outlines, so the SVG and PNG look identical everywhere. A linter catches overlaps, overflowing text, labels on borders and arrows that pass through boxes.
  11. Everything is bundled: **Node 18+ is the only requirement**, with no `npm install` and no network.
  12. `SKILL_DIR` below means the absolute path of this skill folder (the folder that contains this file).
  13. ```bash
  14. node SKILL_DIR/scripts/render.mjs diagram.json --out out/ # → out/diagram.png (2x), .svg, .report.json, .tiles/
  15. ```
  16. ## 0. Running in Codex, Claude Code or another agent
  17. - **SKILL_DIR:**
  18. - In Codex, expand the skill's short path with the skill-roots table (e.g. `r0/diagram-studio/SKILL.md` → `~/.codex/skills/diagram-studio`).
  19. - In Claude Code it is usually `~/.claude/skills/diagram-studio`.
  20. - Always call the scripts with that absolute path.
  21. - **Looking at images is mandatory**: the original, the grid, the tiles and the comparison.
  22. - Codex: use the **`view_image`** tool with the PNG path. `render.mjs` writes `name.preview.png` (≤ 1400 px) for this, so there is no need to resize the image yourself; use `name.tiles/*.png` for detail.
  23. - Claude Code: use the Read tool.
  24. - Never judge a render from the lint output alone.
  25. - **Sandbox-friendly:**
  26. - Only `node` is needed. There are no network calls and no installs.
  27. - Outputs go to `--out`; keep it inside the workspace, e.g. `./diagram-out`.
  28. - WebP/HEIC conversion writes to the system temp dir.
  29. - **The user pasted an image instead of giving a path:** if you can see an attachment path, use it. Otherwise ask for the file path, because the tools need a real file.
  30. - **Finishing:** list the absolute paths of the PNG, SVG and JSON so the user can open them.
  31. ## 1. Pick the job
  32. | User wants | Job | Read next |
  33. |---|---|---|
  34. | "Make this image clearer / higher-res / cleaner", "redraw / rebuild / 复刻 / 高清重建 this" | **A. Rebuild from image.** Fidelity first: keep the original's style unless told otherwise | `references/rebuild-from-image.md` (**required**) |
  35. | "Beautify / tidy / 美化 this diagram" | **A + polish.** Same as A, then improve hierarchy, spacing and alignment | `references/rebuild-from-image.md` |
  36. | A new diagram from a description, code or notes | **B. New diagram** | `references/spec.md` |
  37. | A different look ("make it hand-drawn", "flat corporate", "blueprint", "for a paper") | **C. Restyle** | `references/style-guide.md` |
  38. For a given image, **match its style by default**: hand-drawn stays hand-drawn, flat stays flat, and its colours and font category stay as they are. Only change the look when the user asks. Presets are starting points, not limits; `styleOverrides`, custom palettes and custom font files (`"fonts"`) can reproduce almost any look. Ask about the fidelity level only when the request is genuinely ambiguous, for example "beautify" with no reference style. Otherwise default to **faithful + clearer**.
  39. Start from the closest template in `templates/`: copy it into the working folder and edit the copy. Previews are in `assets/gallery/`. A template is a pattern, not content: replace **all** of its text and keep line breaks and arrows exactly as in your source. `--expect` catches leftovers and changed wording.
  40. | Template | Shows |
  41. |---|---|
  42. | `dense-rebuild.json` | Rebuild of a dense architecture image: explicit coordinates, cards, panels, merged connectors, inline labels |
  43. | `pipeline-rag.json` | Left-to-right pipeline: rows with `connect`, `rightOf`, auto-fitting panels |
  44. | `layered-architecture-zh.json` | Chinese layered architecture: stacked `below` rows, fan-in arrows, cylinders |
  45. | `flowchart-decision.json` | Flowchart: pill, diamond, yes/no branches, loop-back arrows |
  46. | `agent-loop.json` | Cycle: curved arrows, badges, ellipse hub |
  47. | `auto-layout.json` | No coordinates: ELK auto-layout with groups |
  48. ## 2. The loop (every job)
  49. 1. **Inventory first.** List every text string verbatim (save it as `texts.txt`, one per line), every node, every arrow (from → to, label) and every group. Nothing gets invented or dropped.
  50. 2. **Write** `name.json`, starting from a template.
  51. 3. **Render**: `node SKILL_DIR/scripts/render.mjs name.json --out OUT --expect texts.txt`
  52. 4. **Fix every ERROR**; each one comes with a concrete `→` fix. Fix WARNs unless intended, and silence intended ones with `"ignore": ["code"]` on that element or arrow.
  53. 5. **Look** at `OUT/name.png` and `OUT/name.tiles/*.png`, and compare with the original (`scripts/compare.mjs`). Run the checklist in `prompts/visual-review.md`; the linter cannot judge meaning, balance or fidelity.
  54. 6. Repeat steps 3–5 until there are 0 errors and it reads well (usually 2–4 rounds).
  55. 7. **Deliver**:
  56. - `name.png`: 2x; use `--scale 3` for print.
  57. - `name.svg`: vector.
  58. - `name.json`: kept for later edits.
  59. Add one line on what you kept and what you improved.
  60. ## 3. Spec in 60 seconds
  61. ```json
  62. {
  63. "canvas": { "width": 1600 },
  64. "style": "marker",
  65. "title": "Checkout Service",
  66. "subtitle": "{blue:clients} · {purple:services} · {green:data}",
  67. "elements": [
  68. { "id": "web", "title": "Web app", "icon": "app-window", "x": 120, "y": 220 },
  69. { "id": "api", "title": "API", "color": "purple", "emphasis": true, "rightOf": "web", "gap": 160,
  70. "lines": ["`POST /checkout`", { "text": "validates cart", "muted": true }] },
  71. { "id": "db", "type": "cylinder", "title": "Orders DB", "color": "green", "below": "api", "gap": 120 },
  72. { "id": "core", "type": "panel", "title": "Backend", "color": "purple", "contains": ["api", "db"] },
  73. { "id": "n1", "type": "note", "text": "Idempotent by **order id**", "rightOf": "core", "gap": 40 }
  74. ],
  75. "arrows": [
  76. { "from": "web", "to": "api", "label": "HTTPS" },
  77. { "from": "api", "to": "db", "label": "INSERT", "color": "green" }
  78. ]
  79. }
  80. ```
  81. - **Element types:** `box` (default), `pill`, `ellipse`, `circle`, `diamond`, `cylinder`, `note`, `card`, `panel`, `text`, `icon`, `badge`, `image`, `path` (custom SVG shape), plus the layout helpers `row`, `column` and `group`.
  82. - **Position** each element with one of these:
  83. - `x`/`y` for the top-left corner, or `cx`/`cy` for the centre.
  84. - `below` / `above` / `rightOf` / `leftOf` plus `gap`.
  85. - `contains`, which auto-fits a panel around its children.
  86. Size is automatic. Set `w`/`h` to match an original exactly.
  87. - **Text:** `title` is bold, and `\n` breaks the line. `lines` are body lines. Markup inside text:
  88. - `**bold**`
  89. - `` `code` `` (uses the code font)
  90. - `{green:span}` and `{muted:span}`
  91. - `->` (drawn as an arrow glyph)
  92. Chinese and English mix freely. Per element you can set `size`, `textSize`, `font`, `textColor` and `align`.
  93. - **Colour** with a family (`blue purple green orange red teal yellow pink gray navy`), a shade (`blue.tint`), `#hex` or a plain CSS name such as `white`, set through `color`, `fill`, `stroke` and `textColor`.
  94. - **Arrows** connect `from` to `to`:
  95. - Pin a side and slide along it with `"id.right"` or `"id.right+20"`.
  96. - Labels: `label`, placed with `labelPos` (`above`, `below`, `left`, `right` or `inline`) and nudged with `labelAt`.
  97. - Look: `dash`, `color`, `width`, and `head` (`end`, `start`, `both` or `none`).
  98. - Path: `via` points, `points` (an exact polyline), or `"route": "curve"`.
  99. Every key is in `references/spec.md`.
  100. ## 4. Look: style, palette, font, effects
  101. - **Style presets:**
  102. - Hand-drawn: `marker` (default), `neat`, `excalidraw`, `sketchy`, `whiteboard`, `pencil`, `blueprint`, `chalk`.
  103. - Crisp: `clean`, `paper`.
  104. Any preset field can be overridden through `styleOverrides`:
  105. - `roughness` (0 = perfectly straight lines) and `bowing`
  106. - `fillStyle` (`solid`, `hachure`, `cross-hatch`, `dots` or `none`)
  107. - `strokeScale`, `cornerRadius`
  108. - `shadow` (`none`, `soft` or `hard`)
  109. - `font`, `cjkFont`, `codeFont`, `background`
  110. - **Palettes:** `marker`, `pastel`, `excalidraw`, `mono`, `academic`, `colorblind`, `modern`, `blueprint`, `chalkboard`, `midnight`. To reproduce an original's colours exactly, run `node SKILL_DIR/scripts/palette.mjs original.png` and paste the result.
  111. - **Fonts:**
  112. - Handwriting: `shantell`, `kalam`, `caveat`, `patrick`, `architects`.
  113. - Sans: `inter`. Serif: `serif`. Mono: `mono`.
  114. - CJK: `kai` (handwritten), `kuaile` (playful), `sans-sc` (clean).
  115. - Your own `.ttf`/`.otf`/`.woff`: `"fonts": {"brand": {"regular": "Brand.ttf", "bold": "Brand-Bold.ttf"}}`, then `"font": "brand"`.
  116. - **Catalogs:** `assets/gallery/styles.png`, `palettes.png` and `fonts.png`. Regenerate them with `scripts/catalog.mjs`.
  117. - **Icons:** 1,500+ Lucide icons. Search with `node SKILL_DIR/scripts/icons.mjs search 数据库 robot queue`, and preview with `icons.mjs sheet a,b,c`.
  118. - **Original-image tools:**
  119. - `grid.mjs`: overlay coordinates on the original. Read the red axis labels, never pixel positions.
  120. - `fontmatch.mjs`: show sample text in every font next to a zoomed crop of the original.
  121. - `palette.mjs`: extract the original's colours.
  122. - `crop.mjs`: cut out logos, photos or screenshots to embed as `image` elements.
  123. - `compare.mjs`: side-by-side review; add `--crop x,y,w,h` to zoom both images to the same region.
  124. - **Dark or alternate versions:** keep the same spec and change only `palette` (`midnight`, `blueprint` or `chalkboard`) or `style`, then render under another `--name`.
  125. - **For slides (PPT, Keynote):** `"canvas": {"aspect": "16:9"}` pads the image to the slide ratio. `"background": "transparent"` gives a PNG with alpha. The SVG can also be pasted directly.
  126. ## 5. Clarity rules (always apply)
  127. 1. **Keep the words exactly** as given: labels, code identifiers and Chinese terms. Never invent, translate or drop text unless asked.
  128. 2. **Make the hierarchy visible:**
  129. - Bold title per box.
  130. - Identifiers as body or `code` text.
  131. - Explanations as `muted` text.
  132. - Section titles in their section's colour.
  133. 3. **Colour means something:** one family per region or role, used consistently. Arrow labels inherit their arrow's colour.
  134. 4. **Room to breathe:**
  135. - ≥ 60 px between shapes joined by a labelled arrow, ≥ 24 px otherwise.
  136. - Panels fitted with `contains`.
  137. - No label on a border.
  138. 5. **Readable when shrunk:**
  139. - Text ≥ 18 px (defaults: node 30, body 25, label 24).
  140. - Canvas 1400–2200 px wide, with an aspect ratio between 1:2 and 3:1. The linter warns otherwise.
  141. - Long chains of 6+ nodes: snake them into 2–3 rows, or use ELK `"direction": "DOWN"`, rather than one very long row.
  142. 6. **Few crossings and no detours.** Align and reorder before adding `via`.
  143. 7. **Polish, don't redesign,** in rebuild jobs: improve alignment, spacing and hierarchy, but keep topology, reading order and style identity.
  144. ## 6. Definition of done
  145. - [ ] `render.mjs` reports **0 errors**. Any remaining warning is intended and silenced with `ignore`.
  146. - [ ] Every inventory string is present and spelled exactly (`--expect texts.txt` passes).
  147. - [ ] You viewed the PNG and the tiles, and for rebuilds compared them side by side with the original: same structure, same style identity, clearer.
  148. - [ ] You delivered the PNG, SVG and JSON, with a short "kept / improved" note.
  149. ## 7. Troubleshooting
  150. - `node: command not found`: install Node 18+. Nothing else is needed.
  151. - WebP, HEIC, BMP or TIFF input is converted automatically when `sips`, `magick`, `dwebp`, `ffmpeg` or Python PIL is available. Otherwise ask the user for a PNG or JPEG.
  152. - A character renders as `?`: the bundled fonts cover Latin, GB2312 Chinese and common symbols. Rephrase it, or register a font that has it.
  153. - For every lint code and its fix, see `references/troubleshooting.md`.
README.md · README · 123 lines
  1. # Diagram Studio
  2. **Rebuild, beautify and create diagrams: crisp PNG + SVG from a small JSON spec.**
  3. **高清重建、美化和绘制各类示意图:用一份 JSON 描述,生成清晰的 PNG 和 SVG。**
  4. Diagram Studio is an agent skill. It works in OpenAI Codex and Claude Code, and in any agent that can read a `SKILL.md` and run `node`. Give it a blurry or messy diagram and it rebuilds the diagram at high fidelity, keeping the original look (hand-drawn or flat) and fixing the clarity. It can also draw new diagrams or restyle existing ones.
  5. **Blurry original → rebuilt (same layout, same hand-drawn look, every word kept)**
  6. | Before (low-res, blurry) | After (diagram-studio) |
  7. |---|---|
  8. | ![before](assets/gallery/demo-before.jpg) | ![after](assets/gallery/demo-after.png) |
  9. **The same spec, restyled with one line each: `"style": "clean"` and `"palette": "midnight"`**
  10. | Clean | Dark |
  11. |---|---|
  12. | ![clean](assets/gallery/demo-clean.png) | ![dark](assets/gallery/demo-dark.png) |
  13. More: [all styles](assets/gallery/styles.png) · [all palettes](assets/gallery/palettes.png) · [fonts](assets/gallery/fonts.png) · [template previews](assets/gallery/)
  14. ## Why
  15. - **Fidelity first.** A coordinate grid, colour extraction, a text inventory check (`--expect`) and a side-by-side compare help a rebuild match the original.
  16. - **Any look.**
  17. - Ten style presets: 8 hand-drawn and 2 crisp vector.
  18. - Ten palettes.
  19. - Eleven fonts, Chinese included.
  20. - Bring your own font, or fine-tune wobble, stroke, corners, shadows and fills.
  21. - **Readable by construction.**
  22. - Auto-sized boxes and orthogonal arrow routing that avoids shapes.
  23. - Ports spread automatically, and labels are placed away from lines and borders.
  24. - A linter explains every problem with a concrete fix.
  25. - **Works for weaker models too.** The spec is declarative: relative positioning, rows and auto-fitting panels mean no pixel maths, and ELK auto-layout needs no coordinates at all. Error messages say exactly what to change.
  26. - **Zero setup.** Everything is vendored (rough.js, opentype.js, resvg-wasm, ELK, Lucide, OFL fonts). You need only Node 18+: no npm install, no network, no browser.
  27. ## Install
  28. Requires **Node.js 18+** and nothing else.
  29. ```bash
  30. git clone https://github.com/stlmx/diagram-studio.git
  31. cd diagram-studio
  32. ./install.sh # links into ~/.claude/skills and/or ~/.codex/skills (whichever exist)
  33. # or: ./install.sh --claude | --codex | --dir <skills-folder> [--copy]
  34. node scripts/selftest.mjs # optional: renders every template, expects 0 lint errors
  35. ```
  36. Update later with `git pull`; the symlink keeps the agents on the latest version.
  37. **Codex only (e.g. for a whole team):** clone straight into the Codex skills folder. Then restart Codex; the skill appears as `diagram-studio`.
  38. ```bash
  39. git clone https://github.com/stlmx/diagram-studio.git ~/.codex/skills/diagram-studio
  40. ```
  41. In Codex, describe the task ("把这张架构图高清复刻 ./draft.png"), or invoke it explicitly with `$diagram-studio`. The scripts run inside Codex's default sandbox because they need no network and write only to the workspace and the temp dir.
  42. For other agents, point them at `SKILL.md`, or paste a prompt from `prompts/`.
  43. ## Use (just ask)
  44. - "这张图太糊了,帮我高清重建,保持原来的风格。" / "Rebuild this diagram sharper, same style."
  45. - "把这张架构图美化一下,对齐、配色统一。" / "Beautify this figure: align things, unify colours."
  46. - "画一张 RAG 流水线图,手绘风,放 PPT。" / "Draw our release pipeline, clean corporate style, plus a dark version."
  47. - "把这张图改成 Excalidraw 风 / blueprint / 论文风。" / "Restyle this as Excalidraw, blueprint or paper style."
  48. The prompts in `prompts/` are copy-paste ready: rebuild, new diagram, restyle, and the visual-review checklist.
  49. ## Manual use
  50. ```bash
  51. node scripts/render.mjs my.json --out out/ [--scale 2] [--expect texts.txt] # PNG + SVG + report + zoom tiles
  52. node scripts/grid.mjs original.png [--crop x,y,w,h] # coordinate grid over a reference image
  53. node scripts/palette.mjs original.png # extract its colour scheme as a palette block
  54. node scripts/compare.mjs original.png out/my.png [--crop x,y,w,h] # side by side (or zoomed region)
  55. node scripts/fontmatch.mjs "标题" "Title" --image original.png --crop x,y,w,h # pick the closest fonts
  56. node scripts/crop.mjs original.png x,y,w,h # keep a logo or photo region as an image
  57. node scripts/icons.mjs search database 机器人 # 1,500+ Lucide icons, Chinese aliases
  58. node scripts/catalog.mjs all --out-dir gallery/ # style, palette and font sheets
  59. ```
  60. A spec looks like this (full reference in `references/spec.md`):
  61. ```json
  62. {
  63. "style": "marker",
  64. "title": "Checkout",
  65. "elements": [
  66. { "id": "web", "title": "Web app", "icon": "app-window", "x": 100, "y": 200 },
  67. { "id": "api", "title": "API", "color": "purple", "rightOf": "web", "gap": 150, "lines": ["`POST /checkout`"] },
  68. { "id": "db", "type": "cylinder", "title": "Orders", "color": "green", "below": "api", "gap": 110 }
  69. ],
  70. "arrows": [ { "from": "web", "to": "api", "label": "HTTPS" }, { "from": "api", "to": "db" } ]
  71. }
  72. ```
  73. ## Layout of this folder
  74. ```
  75. SKILL.md agent entry point (workflows, rules, definition of done)
  76. references/ spec.md · rebuild-from-image.md · style-guide.md · troubleshooting.md
  77. prompts/ copy-paste prompts + visual-review checklist
  78. templates/ 6 worked examples (dense rebuild, pipeline, Chinese layers, flowchart, loop, auto-layout)
  79. scripts/ render · grid · palette · fontmatch · compare · crop · icons · catalog · selftest
  80. scripts/lib/ engine, text, routing, lint, ELK bridge, vendored libraries
  81. assets/ palettes.json · styles.json · fonts/ · icons/ · gallery/
  82. ```
  83. ## Extend
  84. - **Palette:** add an entry to `assets/palettes.json`, using the same family names.
  85. - **Style:** add an entry to `assets/styles.json`. Any field from the existing presets is allowed.
  86. - **Font:** drop a `.ttf`, `.otf` or `.woff` file into `assets/fonts/` and register it in `fonts.json`. For a single spec, use `"fonts": {...}` instead.
  87. - **Template:** add a JSON file to `templates/` and run `node scripts/selftest.mjs --gallery`.
  88. ## License
  89. MIT for the skill's code, docs and templates. Bundled components keep their licenses (MIT, ISC, MPL-2.0, EPL-2.0, OFL-1.1); see `THIRD_PARTY_NOTICES.md`.
  90. ## Tested with
  91. It was developed against Claude (Opus, Sonnet, Haiku) acting as normal users, on blurry and watermarked rebuilds, new Chinese and English diagrams, and restyles, with the friction they reported fixed. Issues and PRs are welcome; please include the spec JSON and the `render.mjs` output.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.