Mermaid Tools
Turn Mermaid blocks in repos or docs into validated PNG/SVG diagrams using mermaid-cli and bundled extract-and-generate scripts.
Overview
Mermaid-tools is an agent skill for the Build phase (docs subphase, also validate and ship) that documents setup and runs bundled scripts to extract Mermaid from projects and render diagrams with mermaid-cli.
Install
npx skills add https://github.com/daymade/claude-code-skills --skill mermaid-toolsWhat is this skill?
- Documents prerequisites for Node.js, global @mermaid-js/mermaid-cli, and Python 3 for the bundled extractor.
- WSL2-focused Google Chrome install steps plus dependency packages for headless mmdc rendering.
- Script paths under the skill’s scripts/ directory (extract-and-generate.sh and Python extractor).
- Environment variable and troubleshooting sections for failed renders and CLI setup.
- Validation workflow to confirm mmdc and Chrome before generating diagrams.
- Bundled main script: extract-and-generate.sh plus a Python 3 extractor under scripts/.
Adoption & trust: 578 installs on skills.sh; 1.2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have Mermaid in markdown or source files but mmdc fails on WSL2, Chrome is missing, or you lack a repeatable extract-and-render path.
Who is it for?
Indie developers on WSL2/Linux who want agent-guided Mermaid rendering with mermaid-cli and local scripts instead of manual copy-paste to a web editor.
Skip if: Teams that only need inline Mermaid in GitHub previews with no export step, or environments where installing Chrome and global npm CLI tools is blocked.
When should I use this skill?
You need to set up or fix Mermaid diagram generation with mermaid-cli, Chrome on WSL2, or the skill’s extraction scripts.
What do I get? / Deliverables
After following the skill, mmdc and Chrome are verified and the bundled extract-and-generate flow can produce validated diagram assets from your tree.
- Rendered Mermaid PNG/SVG assets
- Validated mmdc and browser toolchain
- Extracted diagram sources from project files
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build → docs because the skill’s purpose is diagram output for architecture and documentation, even though diagrams also support validate and ship conversations. Docs is the primary facet: extraction, rendering, and troubleshooting serve technical writing and visual specs rather than runtime API or frontend code.
Where it fits
Render a proposed user-flow Mermaid chart into PNG for a stakeholder spec before coding.
Batch-regenerate README architecture diagrams after refactoring service names in Mermaid sources.
Refresh deployment topology diagrams in release notes using the bundled extract script.
How it compares
Local skill + scripts for mermaid-cli rendering, not a cloud diagram SaaS or a pure markdown linter.
Common Questions / FAQ
Who is mermaid-tools for?
Solo and indie builders using Claude Code (or similar agents) who document systems with Mermaid and need working mmdc, Chrome-on-WSL2, and extraction automation.
When should I use mermaid-tools?
During Build when writing architecture docs; during Validate when sketching flows in specs; during Ship when updating runbooks—whenever exports must be reproducible from repo content.
Is mermaid-tools safe to install?
It implies global npm installs, apt packages, and shell scripts; review the Security Audits panel on this Prism page and inspect scripts/ before running on sensitive repos.
SKILL.md
READMESKILL.md - Mermaid Tools
# Mermaid Diagram Generation - Setup and Troubleshooting ## Table of Contents - [Prerequisites](#prerequisites) - [Script Locations](#script-locations) - [Features](#features) - [Environment Variables](#environment-variables) - [Troubleshooting](#troubleshooting) - [Validation](#validation) ## Prerequisites ### 1. Node.js and mermaid-cli Install mermaid-cli globally: ```bash npm install -g @mermaid-js/mermaid-cli ``` Verify installation: ```bash mmdc --version ``` ### 2. Google Chrome for WSL2 Install Chrome and dependencies: ```bash # Add Chrome repository wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add - echo "deb [arch=amd64] https://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list # Update and install Chrome sudo apt update sudo apt install -y google-chrome-stable # Install required dependencies for WSL2 sudo apt install -y libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2 libxtst6 xauth xvfb fonts-liberation libxml2-utils ``` Verify Chrome installation: ```bash google-chrome-stable --version ``` ### 3. Python 3 The extraction script requires Python 3 (usually pre-installed on Ubuntu): ```bash python3 --version ``` ## Script Locations The mermaid diagram tools are bundled with this skill in the `scripts/` directory: - Main script: `${CLAUDE_SKILL_DIR}/scripts/extract-and-generate.sh` - Python extractor: `${CLAUDE_SKILL_DIR}/scripts/extract_diagrams.py` - Puppeteer config: `${CLAUDE_SKILL_DIR}/scripts/puppeteer-config.json` All scripts should be run from the `scripts/` directory to properly locate dependencies. ## Features ### Smart Sizing The script automatically adjusts diagram dimensions based on filename patterns: - **Timeline/Gantt charts**: 2400x400 (wide and short) - **Architecture/System/Caching diagrams**: 2400x1600 (large and detailed) - **Monitoring/Workflow/Sequence/API diagrams**: 2400x800 (wide for process flows) - **Default**: 1200x800 (standard size) ### Sequential Numbering Diagrams are automatically numbered sequentially (01, 02, 03, etc.) in the order they appear in the markdown file. ### High-Resolution Output Default scale factor is 2x for high-quality output. Can be customized with environment variables. ## Environment Variables Override default dimensions and scaling: | Variable | Default | Description | |----------|---------|-------------| | `MERMAID_WIDTH` | 1200 | Base width for generated PNGs | | `MERMAID_HEIGHT` | 800 | Base height for generated PNGs | | `MERMAID_SCALE` | 2 | Scale factor for high-resolution output | ### Examples ```bash # Custom dimensions MERMAID_WIDTH=1600 MERMAID_HEIGHT=1200 ./extract-and-generate.sh "file.md" "output_dir" # High-resolution mode for presentations MERMAID_WIDTH=2400 MERMAID_HEIGHT=1800 MERMAID_SCALE=4 ./extract-and-generate.sh "file.md" "output_dir" # Ultra-high resolution for print materials MERMAID_SCALE=5 ./extract-and-generate.sh "file.md" "output_dir" ``` ## Troubleshooting ### Browser Launch Failures **Symptom**: Errors about Chrome not launching or Puppeteer failures **Solution**: 1. Verify Chrome is installed: `google-chrome-stable --version` 2. Check Chrome path in script matches: `/usr/bin/google-chrome-stable` 3. Ensure all dependencies are installed (see Prerequisites section 2) 4. Verify puppeteer-config.json exists at the expected location ### Permission Issues **Symptom**: "Permission denied" when running the script **Solution**: ```bash chmod +x "${CLAUDE_SKILL_DIR}/scripts/extract-and-generate.sh" ``` ### No Diagrams Found **Symptom**: Script reports "No .mmd files found" or "No diagrams extracted" **Solution**: 1. Verify the markdown file contains Mermaid code blocks (` ```mermaid`) 2. Check the markdown file path is correct 3. Ensure Mermaid code blocks are properly formatted ### Python Extraction Failures **Symptom**: Errors during the extraction phase **Solution**: 1. Verify Py