# Pretty Mermaid Skills: an AI agent skill that renders Mermaid diagrams to SVG, PNG and terminal ASCII

> Pretty Mermaid wraps the beautiful-mermaid renderer into an agent skill with 15 themes, six diagram types and a batch CLI. It runs in Node.js without a browser, and its main constraint is that the agent still has to write valid Mermaid source.

**imxv/Pretty-mermaid-skills** — AI Agent Skill to generate and render beautiful Mermaid diagrams as SVG or terminal ASCII — 15 themes, 6 diagram types, batch CLI, no browser.

- Repository: https://github.com/imxv/Pretty-mermaid-skills
- Website: https://www.skills.sh/imxv/pretty-mermaid-skills/pretty-mermaid
- Stars: 1,501 · Forks: 72
- Language: JavaScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/imxv-pretty-mermaid-skills

## What Pretty Mermaid Skills solves, and who it is for

An agent that answers a question about a system often produces a Mermaid block, and that block is useless in a terminal. Mermaid's own tooling assumes a browser or a headless Chromium to turn source into an image, which is a heavy dependency to carry into a coding agent's environment. Pretty Mermaid Skills exists to close that gap: it takes Mermaid source and produces a themed SVG, a PNG, or ASCII and Unicode art for a terminal, all locally in Node.js. The README states the renderer works "without Chromium, Puppeteer, or a DOM."

The audience is narrow and specific. The README lists Claude Code, Cursor, Gemini CLI, Antigravity, OpenCode, Codex and qoder as supported environments, and the repository topics include agent-skills, claude-code, codex and cursor. If you are building an agent workflow where diagrams are an output rather than an interactive activity, this is aimed at you. If you want to draw diagrams by hand in a browser tab, it is not.

## How rendering works: beautiful-mermaid plus resvg, no browser

The dependency list is short and tells most of the story. package.json declares two runtime dependencies: beautiful-mermaid at ^1.1.3 and @resvg/resvg-js at ^2.6.2. The README acknowledges that the project is "Based on beautiful-mermaid" by lukilabs. So the architecture is a wrapper: beautiful-mermaid handles Mermaid parsing and layout, resvg rasterises vector output into PNG, and the scripts in scripts/ expose both through a CLI.

That split explains the PNG claim. The README says PNG output "is rendered directly in Node.js with no external converter required," which is what resvg-js provides: a native Rust rasteriser bound to Node. It also explains why the diagram type list is exactly six (flowchart, sequence, state, class, ER, XY chart). The wrapper cannot render more than the underlying library supports, so the ceiling is beautiful-mermaid's, not this project's.

The skill packaging is the other half. The repository ships SKILL.md plus references/DIAGRAM_TYPES.md, references/THEMES.md and references/api_reference.md, which is the shape agent skills take: a top-level instruction file the agent reads, with deeper references loaded only when needed. The renderer is the executable part; the markdown is what tells the model how to call it.

## Installing the skill and rendering a first diagram

The README gives one install command, run through the skills CLI. It installs globally, which is the -g flag, and skips the interactive prompt with -y.

```bash
npx skills add imxv/pretty-mermaid-skills@pretty-mermaid -g -y
```

After that, verification is a list command. You should see pretty-mermaid appear in the global skill list, and Node.js 16 or newer is required per the README and the engines field in package.json.

```bash
npx skills list -g
```

To render something, the scripts take an input file, an output path and a theme. The README's single-diagram example writes an SVG:

```bash
node scripts/render.mjs \
  --input diagram.mmd \
  --output output.svg \
  --theme tokyo-night
```

Switching to PNG adds --format png and a --width value, which is where resvg does its work:

```bash
node scripts/render.mjs \
  --input diagram.mmd \
  --output output.png \
  --format png \
  --width 1200 \
  --theme tokyo-night
```

Before any of that, run node scripts/themes.mjs to print the available theme names, and remember the theme identifiers are hyphenated strings like zinc-light, catppuccin-mocha and tokyo-night-storm. If you have a directory of .mmd files, batch.mjs takes --input-dir and --output-dir instead of a single --input, and the README describes batch rendering as parallel.

## Where Pretty Mermaid Skills stops being the right tool

The six diagram types are a hard boundary. Mermaid supports more than flowchart, sequence, state, class, ER and XY chart, and anything outside those six has no path through this wrapper. If your documentation depends on Gantt charts, pie charts, git graphs, mindmaps or quadrant charts, this skill cannot render them, and no theme or flag will change that.

There is a second, quieter limitation. The renderer is only as good as the Mermaid source it receives, and the skill does not appear to validate semantics beyond what beautiful-mermaid accepts. An agent that writes a malformed flowchart gets a failure, not a corrected diagram. The README documents a smoke test (npm test runs scripts/smoke-test.mjs) and a documentation validator (npm run validate), but neither is described as repairing input. Treat the skill as a renderer, not as a diagram author.

The third constraint is environmental. Node.js 16 or newer is the stated floor, and the install path goes through npx skills add, so you need network access to the skills registry at install time and a Node runtime at render time. Environments that forbid third-party CLI installers, or that pin an older Node, are out.

## How it differs from the Mermaid live editor and from calling beautiful-mermaid directly

The Mermaid live editor is the obvious comparison, and the difference is not cosmetic. The live editor is an interactive browser application: you type source, you see the diagram update, you export. Pretty Mermaid Skills inverts that. There is no editing surface, no preview loop, and no browser at all. The input arrives as a file on disk and the output is written to a path you name. For a human sketching a diagram, the live editor wins on feedback. For an agent that already produced the source as part of a larger task, the file-in, file-out model is the one that composes.

Against beautiful-mermaid itself, the difference is packaging rather than rendering. The README credits beautiful-mermaid as the basis, and package.json depends on it directly, so the drawing engine is the same. What Pretty Mermaid adds is the skill layer (SKILL.md and the references/ directory), the CLI entry points exposed through the bin field as render-mermaid, batch-mermaid and list-mermaid-themes, and a curated theme set of 15 names. If you are writing a Node script and do not need an agent to discover the tool, calling beautiful-mermaid directly removes a layer. If you want an agent to find and use it without instructions, the skill wrapper is the point.

## Maintenance, upgrade cost and the MIT licence

The repository is not archived, and the last push was on 2026-08-22, roughly a month before this writing. There are no retrieved releases, so versioning appears to live in CHANGELOG.md and RELEASING.md rather than in tagged releases. package.json is marked private and carries version 1.0.0, which means npm publishing is not the distribution channel; npx skills add against the GitHub repository is.

Upgrade cost is bounded by two things. First, the beautiful-mermaid dependency is declared as ^1.1.3, so minor and patch updates arrive without a change to this repository, and a breaking change upstream would surface here. Second, @resvg/resvg-js is a native module, so platform support depends on prebuilt binaries being available for your architecture. Neither is unusual, but both mean an upgrade can fail for reasons outside this project's code.

The licence is MIT, stated in the README and present as a LICENSE file at the repository root. MIT is permissive and imposes no copyleft obligation on your own code, but this is a description of the licence text, not legal advice, and the dependency licences (beautiful-mermaid, resvg-js) are separate from it. Check those independently if your organisation audits transitive licences.

## Conclusion

Adopt Pretty Mermaid Skills if your agent already emits Mermaid and you want themed SVG or terminal ASCII without installing Chromium. Skip it if you need diagram types beyond flowchart, sequence, state, class, ER and XY, or if you want a live editor rather than a renderer. Before committing, run the smoke test with npm test and confirm that node scripts/themes.mjs lists the themes you plan to use, because the theme list is the part of the surface most likely to drift from what your documentation promises.

## FAQ

### What does Pretty Mermaid Skills do?

It is an AI agent skill that turns Mermaid source into themed SVG, PNG or terminal ASCII output. Rendering happens locally in Node.js, and the README states it works without Chromium, Puppeteer or a DOM.

### How do I install Pretty Mermaid Skills?

The README gives a single command: npx skills add imxv/pretty-mermaid-skills@pretty-mermaid -g -y. You can confirm it landed by running npx skills list -g and checking that pretty-mermaid appears. Node.js 16 or newer is required.

### Which diagram types and themes does Pretty Mermaid Skills support?

Six diagram types are listed: flowchart, sequence, state, class, ER and XY chart. The theme set is 15 built-in themes split across light, dark and other categories, including zinc-light, tokyo-night, catppuccin-mocha, dracula, nord and solarized-dark.

### Can Pretty Mermaid Skills render PNG without installing a browser?

Yes. The README states PNG output is rendered directly in Node.js with no external converter required, which is consistent with the @resvg/resvg-js dependency in package.json. You request it with --format png and a --width value.

## Sources

- [imxv/Pretty-mermaid-skills on GitHub](https://github.com/imxv/Pretty-mermaid-skills)
- [Issues](https://github.com/imxv/Pretty-mermaid-skills/issues)
- [License: MIT](https://github.com/imxv/Pretty-mermaid-skills/blob/main/LICENSE)
- [Project website](https://www.skills.sh/imxv/pretty-mermaid-skills/pretty-mermaid)
- [README](https://github.com/imxv/Pretty-mermaid-skills/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/imxv-pretty-mermaid-skills