Pretty Mermaid
Use this skill whenever Mermaid is the chosen format, including explicit
Mermaid or .mmd, terminal ASCII, and compact static diagrams. Save Mermaid
source before rendering. Keep an existing .mmd file unchanged unless the
user asks to edit it, and place new source beside its export.
Exports retain editable .mmd source and use self-contained SVG, genuine PNG,
or rendered ASCII as requested.
Workflow
Run pretty-mermaid doctor --json. If the launcher is unavailable, resolve this skill directory and run node scripts/pretty-mermaid.mjs doctor --json.
If the runtime is missing or incompatible, use native inline Mermaid with the unchanged source, briefly disclose the fallback, and report the setup command from the doctor result. Do not install packages during an ordinary render.
Create or validate the .mmd source. Use quoted node labels when labels contain punctuation or parentheses. If the user gave no destination, create a task-scoped temporary directory with mktemp -d and keep the source and export there; do not add automatic artifacts to the active repository.
On a graphical surface, default to SVG and the renderer's default theme (github-light when available). In a terminal, render ASCII and include the editable .mmd. Honor an explicit destination, format, theme, color, scale, or transparency setting.
Render the artifact, for example:
pretty-mermaid render \
--input /absolute/path/diagram.mmd \
--output /absolute/path/diagram.svg \
--format svg \
--theme github-light
For PNG, default to --scale 2 unless the user requests another scale. For terminal output, use --format ascii; add --use-ascii only when Unicode box drawing is unsuitable.
Verify the output exists. Display SVG or PNG using its absolute path in the final response and link the .mmd source. For ASCII, include the rendered text and the .mmd path.
Selection Rules
Explicit application choice takes precedence, followed by the existing artifact format. Use $omnigraffle-workflow for OmniGraffle or .graffle.
Use this skill by default whenever Mermaid is selected, including quick explanations,
compact static relationships, and architecture or workflow content that the
user explicitly wants in Mermaid.
Use $archify as the graphical default for architecture and workflow maps,
and for polished interactive sequence, data-flow, or lifecycle artifacts.
Use native inline Mermaid only when the user explicitly requests it or when the runtime is unavailable or rejects the syntax. Briefly disclose automatic fallback, reuse the exact source, and do not silently change semantics.
Use $drawio for explicit draw.io or diagrams.net requests, editable .drawio source, multi-page files, specialized shapes, browser editing, or draw.io Desktop exports.
Use $paper-figure-workflow for reproducible publication figure pipelines; it delegates native execution to the selected application owner.
Use bundled Visualize for adjustable, inspectable, in-conversation spatial
views rather than a standalone static export.
Beautiful Mermaid implements a Mermaid subset. Run capabilities when syntax support is uncertain. If rendering rejects a diagram family, preserve the .mmd, fall back to native inline Mermaid, and report the limitation.
Commands
pretty-mermaid render --input FILE --format svg|png|ascii [--output FILE]
pretty-mermaid batch --input-dir DIR --output-dir DIR --format svg|png|ascii
pretty-mermaid themes [--json]
pretty-mermaid capabilities [--json]
pretty-mermaid doctor [--json]
pretty-mermaid update [--strict]
pretty-mermaid rollback
The toolbox setup installs pretty-mermaid into CODEX_LOCAL_BIN_DIR (default ~/.local/bin). When that directory is not on PATH, run the equivalent node scripts/pretty-mermaid.mjs ... command from this skill directory. Read references/cli.md for complete flags, exit behavior, and runtime recovery.
1---2name: pretty-mermaid3description: Render explicit Mermaid/.mmd, terminal ASCII, or compact static diagrams with editable source. Use Archify for graphical architecture and workflow maps.4---56# Pretty Mermaid78Use this skill whenever Mermaid is the chosen format, including explicit9Mermaid or `.mmd`, terminal ASCII, and compact static diagrams. Save Mermaid10source before rendering. Keep an existing `.mmd` file unchanged unless the11user asks to edit it, and place new source beside its export.12Exports retain editable `.mmd` source and use self-contained SVG, genuine PNG,13or rendered ASCII as requested.1415## Workflow16171. Run `pretty-mermaid doctor --json`. If the launcher is unavailable, resolve this skill directory and run `node scripts/pretty-mermaid.mjs doctor --json`.182. If the runtime is missing or incompatible, use native inline Mermaid with the unchanged source, briefly disclose the fallback, and report the setup command from the doctor result. Do not install packages during an ordinary render.193. Create or validate the `.mmd` source. Use quoted node labels when labels contain punctuation or parentheses. If the user gave no destination, create a task-scoped temporary directory with `mktemp -d` and keep the source and export there; do not add automatic artifacts to the active repository.204. On a graphical surface, default to SVG and the renderer's default theme (`github-light` when available). In a terminal, render ASCII and include the editable `.mmd`. Honor an explicit destination, format, theme, color, scale, or transparency setting.215. Render the artifact, for example:2223 ```bash24 pretty-mermaid render \25 --input /absolute/path/diagram.mmd \26 --output /absolute/path/diagram.svg \27 --format svg \28 --theme github-light29 ```30316. For PNG, default to `--scale 2` unless the user requests another scale. For terminal output, use `--format ascii`; add `--use-ascii` only when Unicode box drawing is unsuitable.327. Verify the output exists. Display SVG or PNG using its absolute path in the final response and link the `.mmd` source. For ASCII, include the rendered text and the `.mmd` path.3334## Selection Rules3536- Explicit application choice takes precedence, followed by the existing artifact format. Use `$omnigraffle-workflow` for OmniGraffle or `.graffle`.3738- Use this skill by default whenever Mermaid is selected, including quick explanations,39 compact static relationships, and architecture or workflow content that the40 user explicitly wants in Mermaid.41- Use `$archify` as the graphical default for architecture and workflow maps,42 and for polished interactive sequence, data-flow, or lifecycle artifacts.43- Use native inline Mermaid only when the user explicitly requests it or when the runtime is unavailable or rejects the syntax. Briefly disclose automatic fallback, reuse the exact source, and do not silently change semantics.44- Use `$drawio` for explicit draw.io or diagrams.net requests, editable `.drawio` source, multi-page files, specialized shapes, browser editing, or draw.io Desktop exports.45- Use `$paper-figure-workflow` for reproducible publication figure pipelines; it delegates native execution to the selected application owner.46- Use bundled Visualize for adjustable, inspectable, in-conversation spatial47 views rather than a standalone static export.48- Beautiful Mermaid implements a Mermaid subset. Run `capabilities` when syntax support is uncertain. If rendering rejects a diagram family, preserve the `.mmd`, fall back to native inline Mermaid, and report the limitation.4950## Commands5152```text53pretty-mermaid render --input FILE --format svg|png|ascii [--output FILE]54pretty-mermaid batch --input-dir DIR --output-dir DIR --format svg|png|ascii55pretty-mermaid themes [--json]56pretty-mermaid capabilities [--json]57pretty-mermaid doctor [--json]58pretty-mermaid update [--strict]59pretty-mermaid rollback60```6162The toolbox setup installs `pretty-mermaid` into `CODEX_LOCAL_BIN_DIR` (default `~/.local/bin`). When that directory is not on `PATH`, run the equivalent `node scripts/pretty-mermaid.mjs ...` command from this skill directory. Read `references/cli.md` for complete flags, exit behavior, and runtime recovery.
jialuohu