Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Mermaid Tools · nicepkg | DecimalAI

nicepkg/mermaid-tools

SkillScore82Maintained

Extracts Mermaid diagrams from markdown files and generates high-quality PNG images using bundled scripts. Activates when working with Mermaid diagrams, converting diagrams to PNG, extracting diagrams from markdown, or processing markdown files with embedded Mermaid code.

Documentationby nicepkg

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Doc Ops pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/nicepkg-mermaid-tools/SKILL.md

decimalai skills pull nicepkg-mermaid-tools --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/nicepkg-mermaid-tools/SKILL.md https://app.decimal.ai/s/nicepkg-mermaid-tools/SKILL.md

Raw file: /s/nicepkg-mermaid-tools/SKILL.md ↗ · machine-readable summary at /s/nicepkg-mermaid-tools.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

22 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 5d ago

—+3% tokens0% turns82% of whole cases pass with skill (18/22)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-04	✗→✓	▲ Improved	-25%	0%
case-05	✗→✓	▲ Improved	66%	0%
case-06	✗→✓	▲ Improved	-36%	0%
case-07	✗→✓	▲ Improved	66%	0%
case-09	✗→✓	▲ Improved	-26%	0%

Showing 5 of 22 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/3/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

nicepkg / ai-workflow

workflows/talk-to-slidev-workflow/.claude/skills/mermaid-tools/SKILL.md

View on GitHub ↗

License MITImported 8/3/2026Version v1Bundled 4 files · scripts

Skill contents

scripts/

references/

SKILL.md

Mermaid Tools

Overview

This skill enables extraction of Mermaid diagrams from markdown files and generation of high-quality PNG images. The skill bundles all necessary scripts (extract-and-generate.sh, extract_diagrams.py, and puppeteer-config.json) in the scripts/ directory for portability and reliability.

Core Workflow

Standard Diagram Extraction and Generation

Extract Mermaid diagrams from a markdown file and generate PNG images using the bundled extract-and-generate.sh script:

bash
cd ~/.claude/skills/mermaid-tools/scripts
./extract-and-generate.sh "<markdown_file>" "<output_directory>"

Parameters:

<markdown_file>: Path to the markdown file containing Mermaid diagrams
<output_directory>: (Optional) Directory for output files. Defaults to <markdown_file_directory>/diagrams

Example:

bash
cd ~/.claude/skills/mermaid-tools/scripts
./extract-and-generate.sh "/path/to/document.md" "/path/to/output"

What the Script Does

Extracts all Mermaid code blocks from the markdown file
Numbers them sequentially (01, 02, 03, etc.) in order of appearance
Generates .mmd files for each diagram
Creates high-resolution PNG images with smart sizing
Validates all generated PNG files

Output Files

For each diagram, the script generates:

01-diagram-name.mmd - Extracted Mermaid code
01-diagram-name.png - High-resolution PNG image

The numbering ensures diagrams maintain their order from the source document.

Advanced Usage

Custom Dimensions and Scaling

Override default dimensions using environment variables:

bash
cd ~/.claude/skills/mermaid-tools/scripts
MERMAID_WIDTH=1600 MERMAID_HEIGHT=1200 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"

Available variables:

MERMAID_WIDTH (default: 1200) - Base width in pixels
MERMAID_HEIGHT (default: 800) - Base height in pixels
MERMAID_SCALE (default: 2) - Scale factor for high-resolution output

High-Resolution Output for Presentations

bash
cd ~/.claude/skills/mermaid-tools/scripts
MERMAID_WIDTH=2400 MERMAID_HEIGHT=1800 MERMAID_SCALE=4 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"

Print-Quality Output

bash
cd ~/.claude/skills/mermaid-tools/scripts
MERMAID_SCALE=5 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"

Smart Sizing Feature

The script automatically adjusts dimensions based on diagram type (detected from filename):

Timeline/Gantt: 2400×400 (wide and short)
Architecture/System/Caching: 2400×1600 (large and detailed)
Monitoring/Workflow/Sequence/API: 2400×800 (wide for process flows)
Default: 1200×800 (standard size)

Context-aware naming in the extraction process helps trigger appropriate smart sizing.

Important Principles

Use Bundled Scripts

CRITICAL: Use the bundled extract-and-generate.sh script from this skill's scripts/ directory. All necessary dependencies are bundled together.

Change to Script Directory

Run the script from its own directory to properly locate dependencies (extract_diagrams.py and puppeteer-config.json):

bash
cd ~/.claude/skills/mermaid-tools/scripts
./extract-and-generate.sh "<markdown_file>" "<output_directory>"

Running the script without changing to the scripts directory first may fail due to missing dependencies.

Prerequisites Verification

Before running the script, verify dependencies are installed:

mermaid-cli: mmdc --version
Google Chrome: google-chrome-stable --version
Python 3: python3 --version

If any are missing, consult references/setup_and_troubleshooting.md for installation instructions.

Troubleshooting

For detailed troubleshooting guidance, refer to references/setup_and_troubleshooting.md, which covers:

Browser launch failures
Permission issues
No diagrams found
Python extraction failures
Output quality issues
Diagram-specific sizing problems

Quick fixes for common issues:

Permission denied:

bash
chmod +x ~/.claude/skills/mermaid-tools/scripts/extract-and-generate.sh

Low quality output:

bash
MERMAID_SCALE=3 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"

Chrome/Puppeteer errors: Verify all WSL2 dependencies are installed (see references for full list).

Bundled Resources

scripts/

This skill bundles all necessary scripts for Mermaid diagram generation:

extract-and-generate.sh - Main script that orchestrates extraction and PNG generation
extract_diagrams.py - Python script for extracting Mermaid code blocks from markdown
puppeteer-config.json - Chrome/Puppeteer configuration for WSL2 environment

All scripts must be run from the scripts/ directory to properly locate dependencies.

references/setup_and_troubleshooting.md

Comprehensive reference documentation including:

Complete prerequisite installation instructions
Detailed environment variable reference
Extensive troubleshooting guide
WSL2-specific Chrome dependency setup
Validation procedures

Load this reference when dealing with setup issues, installation problems, or advanced customization needs.

Want to see if nicepkg/mermaid-tools would activate on your phrasing? Try it before you install — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/24/2026, 18:38 UTC · 22 cases

Measured on 20 comparable cases — below the 22 needed to publish a lift, so this result is shown here but not on the registry card or leaderboard.

Lift

+64%

82% vs 18%

Agent turns

1.0 vs 1.0

Tokens

+3%

1,817.55 vs 1,763.65

fail → pass · 14pass → pass · 4fail → fail · 4

Per-case results (22)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-04 I am preparing our system documentation at `/docs/api.md` for print publication. What shell command options and environment settings generate high-dpi print-quality diagram assets into `/docs/print_build`?	fail→pass	15,833	4,442	-72%	1	1	0%	2,780	2,076	-25%	0	0	—
case-05 If the extraction process is run on `/projects/backend/README.md` without specifying an output directory argument, in which directory path will the generated diagrams be saved?	fail→pass	6,554	1,880	-71%	1	1	0%	968	1,607	+66%	0	0	—
case-01 I just updated `/docs/architecture.md` which contains several embedded Mermaid charts. Could you extract each chart from the markdown file and generate high-resolution PNG image files for them in the `/docs/diagrams_output` directory?	fail→fail	4,017	10,821	+169%	1	1	0%	526	1,681	+220%	0	0	—
case-02 I need to prepare images of the flowcharts from `/projects/spec.md` for a slide deck. Please extract the Mermaid diagrams from that document and render them as ultra high-resolution PNGs so they don't look blurry on large screens. Save the results in `/projects/deck_images`.	fail→fail	4,345	7,202	+66%	1	1	0%	239	1,745	+630%	0	0	—
case-03 Our roadmap markdown file located at `/team/roadmap.md` has a couple of timeline and sequence diagrams. Can you run the diagram extraction process on it so that both the raw `.mmd` files and rendered image files are saved to `/team/exports`?	fail→fail	18,115	5,569	-69%	1	1	0%	3,293	1,661	-50%	0	0	—
case-06 When processing `/specs/network.md` into `/specs/out`, I need to override the default canvas width to 1600 pixels and default height to 1200 pixels. Which environment variables should be set?	fail→pass	19,271	2,167	-89%	1	1	0%	2,743	1,759	-36%	0	0	—
case-07 Why does invoking `extract-and-generate.sh` fail when executed directly from the user's root workspace directory `/home/user/app` without changing directories first?	fail→pass	8,987	6,168	-31%	1	1	0%	1,404	2,325	+66%	0	0	—
case-08 When extracting multiple Mermaid diagrams from `/docs/guide.md`, what sequential prefix pattern is prepended to the generated diagram filenames?	pass→pass	15,653	2,565	-84%	1	1	0%	2,589	1,749	-32%	0	0	—
case-09 In the smart sizing feature, what automatic pixel dimensions are assigned when rendering a diagram with a filename containing timeline or gantt?	fail→pass	30,977	2,286	-93%	1	1	0%	2,211	1,630	-26%	0	0	—
case-18 What is the exact filename of the JSON config file passed to Chrome or Puppeteer during headless rendering in WSL2?	fail→pass	8,839	1,428	-84%	1	1	0%	1,508	1,550	+3%	0	0	—
case-10 What automatic pixel dimensions are assigned by smart sizing when rendering a diagram named with architecture, system, or caching?	fail→pass	11,737	1,557	-87%	1	1	0%	1,816	1,563	-14%	0	0	—
case-11 What width and height pixel dimensions does smart sizing apply to diagrams named monitoring, workflow, sequence, or api?	fail→pass	14,576	2,093	-86%	1	1	0%	2,020	1,647	-18%	0	0	—
case-12 What canvas dimensions in pixels are assigned by smart sizing when a diagram's filename does not match any recognized category keyword?	pass→pass	9,635	1,747	-82%	1	1	0%	1,685	1,613	-4%	0	0	—
case-13 Before running the extraction workflow, what three terminal commands should be run to verify that all binary dependencies required by the script are installed?	fail→pass	8,430	1,678	-80%	1	1	0%	1,374	1,647	+20%	0	0	—
case-19 The generated PNG diagrams from `/docs/report.md` look blurry. Which single environment variable can be increased to boost rendering resolution without altering canvas dimensions?	fail→pass	18,630	2,510	-87%	1	1	0%	3,353	1,752	-48%	0	0	—
case-14 Executing `extract-and-generate.sh` produces `permission denied`. What bash command grants execution permissions to this script?	fail→pass	2,187	1,805	-17%	1	1	0%	348	1,594	+358%	0	0	—
case-15 Where is the reference markdown file containing setup instructions and WSL2 Chrome troubleshooting details located within the skill repository?	fail→pass	9,489	1,696	-82%	1	1	0%	1,408	1,526	+8%	0	0	—
case-16 What specific environment variable combination of width, height, and scale is recommended for extracting high-resolution diagrams from `/slides/design.md` for a presentation deck?	fail→pass	9,703	3,295	-66%	1	1	0%	1,719	1,875	+9%	0	0	—
case-17 What is the exact name of the Python script responsible for parsing markdown files and extracting raw Mermaid code blocks?	fail→pass	9,932	1,541	-84%	1	1	0%	1,578	1,552	-2%	0	0	—
case-20 In my markdown document `/docs/spec.md`, my Mermaid flowchart line `nodeA -> nodeB` is failing to parse. What is the correct syntax for a basic directed arrow in Mermaid flowcharts?	pass→pass	4,959	3,246	-35%	1	1	0%	890	1,845	+107%	0	0	—
case-21 I have a PlantUML architecture file at `/docs/architecture.puml`. How do I generate a PNG image from this PlantUML file using the standard PlantUML command-line tool?	pass→pass	6,076	4,017	-34%	1	1	0%	1,074	2,021	+88%	0	0	—
case-22 How do I define custom fill colors and stroke styles for specific nodes in a Mermaid sequence diagram using inline CSS directives?	fail→fail	21,208	18,936	-11%	1	1	0%	3,279	3,339	+2%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted, and 20 counted toward the lift figure. The other 2 produced results that are not comparable between the two arms, so they are excluded from the headline rather than averaged into it. The headline lift of +64 percentage points is the difference between those two pass rates over the 20 comparable cases.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 18.2%
Pass rate with the skill: 81.8%
Cases attempted: 22
Cases counted toward lift: 20
Cases that regressed: 0
Skill version measured: v1
Run completed: 8/24/2026, 18:38 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-04

Prompt

I am preparing our system documentation at `/docs/api.md` for print publication. What shell command options and environment settings generate high-dpi print-quality diagram assets into `/docs/print_build`?

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run82

Live evalNeeds ≥20 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+16% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 4 days ago

Other measured skills in the registry, with their headline benchmark lift.

Ready to supercharge your AI agents?

nicepkg/mermaid-tools

SkillSafety

Source

Mermaid Tools

Overview

Core Workflow

Standard Diagram Extraction and Generation

What the Script Does

Output Files

Advanced Usage

Custom Dimensions and Scaling

High-Resolution Output for Presentations

Print-Quality Output

Smart Sizing Feature

Important Principles

Use Bundled Scripts

Change to Script Directory

Prerequisites Verification

Troubleshooting

Bundled Resources

scripts/

references/setup_and_troubleshooting.md

How this skill was measured

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-04

Related skills