Live · Open source

diagram-polish

A Claude Code skill that turns the Mermaid block in a README, or a rough description of a system, into a clean architecture diagram. It boils the system down to five to seven boxes and draws them in one consistent look.

GitHub

A data pipeline drawn by Mermaid's default theme, and the same pipeline redrawn by diagram-polish

Type: Claude Code skill + Node.js script
Period: Oct 2026
Runs on: Your machine · Node.js 18+

About

diagram-polish is a Claude Code skill that redraws architecture diagrams. Give it the Mermaid block from a README, a rough sketch or description, or just the repository, and it returns a clean SVG and PNG.

It works in four steps. Claude reads the source and checks it against the code, reduces the system to five to seven boxes, and writes the boxes and arrows into a small diagram.json. A script then lays them out, routes the lines and draws the picture. Claude looks at the result and fixes what the checks can't see, such as an arrow pointing the wrong way.

The architecture diagrams on this site were made this way. There are three themes, sage, blue and mono, each in light and dark. The skill is open source: install it as a plugin, or copy the skill folder into ~/.claude/skills.

What it does

Mermaid in, a clean diagram out: Reads a Mermaid block, a README or the code and redraws it in one look: soft boxes, a frame around what runs together, another tone for services you don't run, dashed lines for scheduled work.
Five to seven boxes: Pieces of one codebase are merged, duplicate arrows are joined and labels shrink to a word or two. The code is checked first, so nothing is drawn that doesn't exist.
Checks its own drawing: The script stops on mistakes and warns about cut-off boxes, overlaps, lines through boxes and colliding labels. Claude looks at the picture before handing it over.
Korean and Japanese text: Box widths are measured for Hangul, kana and Han characters, and the PNG picks a system sans font for them.

Architecture

Claude reads the Mermaid and checks it against the project's code, writes the boxes and arrows into diagram.json, and render.mjs lays them out and draws the SVG and PNG. Claude then looks at the picture and fixes what the checks can't see.

How it's built

Skill: Claude Code skill (SKILL.md) · plugin manifest (claude plugin install)
Script: Node.js · dependency-free SVG renderer · text width estimation · right-angle edge routing
Picture: SVG · Geist · light and dark palettes · auto SVG (prefers-color-scheme)
PNG: @resvg/resvg-js · system sans font for Hangul and kana
Checks: Validator for clipping, overlaps, lines through boxes and label collisions · one-command redraw and check of all examples

A Mermaid sequence diagram with twelve messages, next to the same system drawn as seven boxes and arrows

The same pipeline in the sage, blue and mono themes, and the sage theme in dark mode

The skill needs Claude Code; the script alone needs only Node.js. The "before" pictures are Mermaid's default theme.