Workflow & Core Tools · daymade/claude-code-skills
mermaid-tools
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.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
Relies on two bundled scripts in sequence: extract_diagrams.py uses regex to extract ```mermaid code blocks from markdown and numbers/names them, then extract-and-generate.sh invokes mermaid-cli (mmdc) file-by-file to render PNGs.
daymade-docs/mermaid-tools/scripts/extract_diagrams.py
mermaid_pattern = r'```mermaid\n(.*?)\n```'
extract_diagrams.py looks back at context to find the nearest section header to name diagrams (e.g., 01-diagram-name.mmd); SKILL.md specifies that scripts are bundled in the scripts/ directory to ensure portability.
The rendering engine is mermaid-cli + local Chrome: the script sets PUPPETEER_EXECUTABLE_PATH to /usr/bin/google-chrome-stable and passes puppeteer-config.json alongside -w/-H/-s dimensions and scale parameters.
daymade-docs/mermaid-tools/scripts/extract-and-generate.sh
PUPPETEER_EXECUTABLE_PATH="$CHROME_PATH" mmdc \ -i "$mmd_file" \ -o "$diagram.png" \ --puppeteerConfigFile "$CONFIG_FILE" \ -w "$width" \ -H "$height" \ -s "$SCALE_FACTOR"
This means rendering is completely local with zero dependency on online Mermaid services; puppeteer-config.json includes common container flags like --no-sandbox/--disable-gpu (tailored for WSL2).
High-resolution output is controlled via environment variable overrides: MERMAID_WIDTH/HEIGHT/SCALE default to 1200×800×2, and can be increased to 2400×1800×4 or SCALE=5 for presentations or print.
daymade-docs/mermaid-tools/SKILL.md
MERMAID_WIDTH=2400 MERMAID_HEIGHT=1800 MERMAID_SCALE=4 ./extract-and-generate.sh "<markdown_file>" "<output_directory>"
Explicitly shown as an example in the 'High-Resolution Output for Presentations' section of SKILL.md.
Smart sizing infers dimensions based on diagram name keywords: timeline/gantt are widened and flattened, architecture/system/caching are enlarged, workflow/sequence/api are widened, and default is 1200×800.
daymade-docs/mermaid-tools/SKILL.md
- **Timeline/Gantt**: 2400×400 (wide and short) - **Architecture/System/Caching**: 2400×1600 (large and detailed)
The script uses bash regex [[ "$diagram" =~ timeline|gantt ]] to implement this logic; naming originates from contextual naming by extract_diagrams.py, working in tandem.
Pre-flight dependency checks are built into the flow: if mmdc, google-chrome-stable, or python3 is missing, it prompts to check references/setup_and_troubleshooting.md (including Chrome installation and dependency lists for WSL2).
daymade-docs/mermaid-tools/SKILL.md
1. **mermaid-cli**: `mmdc --version` 2. **Google Chrome**: `google-chrome-stable --version` 3. **Python 3**: `python3 --version`
The reference document also explains how to add the Google apt repository (dl.google.com) to install Chrome—an installation-time network action, see security.
Execution convention is 'run from the scripts/ directory': the script locates files via ${CLAUDE_SKILL_DIR} and depends on relative paths to extract_diagrams.py and puppeteer-config.json in the same directory.
daymade-docs/mermaid-tools/SKILL.md
cd "${CLAUDE_SKILL_DIR}/scripts" ./extract-and-generate.sh "<markdown_file>" "<output_directory>"
SKILL.md repeatedly emphasizes ('CRITICAL: Use the bundled extract-and-generate.sh'); failing to cd will cause failures due to missing dependencies.
2Core Capabilities
01Extract all Mermaid code blocks from markdown and number them sequentially (01, 02, …)
02Generate .mmd source files and high-resolution .png images (configurable width, height, and scale)
03Smart sizing: automatically select canvas dimensions based on diagram type (timeline, architecture, workflow, etc.)
04Validate output PNGs (non-empty, file type check, and dimensions via identify)
05Override canvas size via environment variables (MERMAID_WIDTH/HEIGHT/SCALE) for presentations or print
06Privacy-friendly local rendering: diagram content is never sent to online services
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | mermaid-cli (mmdc) |
| cli | Google Chrome（/usr/bin/google-chrome-stable，headless 渲染） |
| cli | python3（extract_diagrams.py） |
| network | dl.google.com（setup 参考文档：加 Chrome apt 源并 sudo apt install，一次性安装） |
| cli | file / sort -V / stat / identify(可选)（bash 工具链） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Executes local scripts or commands: bash scripts/extract-and-generate.sh (set -e, local)
- 网络端点: Declares external network access: None at runtime; setup reference doc includes one-off installation actions: wget dl.google.com public key + sudo apt install google-chrome-stable
- 本地工作目录: File I/O and artifact output: Writes .mmd/.png to the output directory (default: <markdown_file_dir>/diagrams); mkdir -p output directory
Audit Notes: Includes local bash/python scripts + mmdc local rendering, with zero outbound network traffic, zero credential reading, and zero file deletion at runtime; writes only .mmd/.png to the user-specified directory. Notes: ① Chrome rendering uses --no-sandbox (standard practice for container/WSL environments, but still a security downgrade); ② sudo/apt steps for Chrome installation reside in reference documentation as environment prerequisites rather than the execution path.
5Second-Pass Verification
- [ok] 脚本三件套自包含 — extract-and-generate.sh / extract_diagrams.py / puppeteer-config.json 均在 scripts/ 且被 SKILL 逐一引用。
- [ok] mmdc 本地渲染 + PUPPETEER_EXECUTABLE_PATH — 脚本内逐字存在 'PUPPETEER_EXECUTABLE_PATH="$CHROME_PATH" mmdc -i ... --puppeteerConfigFile' 调用。
- [ok] smart sizing 逻辑一致 — SKILL.md 尺寸表与脚本 [[ "$diagram" =~ timeline|gantt ]] 等分支对应。
- [ok] PNG 校验存在 — 脚本 'test -s ... && file ... | grep -q "PNG image"' + identify 尺寸回退分支属实。
- [ok] 运行期无网络 — 三个脚本全文无 curl/wget/requests/http 调用；唯一网络在 setup 参考文档的 dl.google.com apt 安装（sudo，用户主动执行）。
- [ok] 无凭证读取 — 仅读 MERMAID_WIDTH/HEIGHT/SCALE/CLAUDE_SKILL_DIR 等路径/尺寸变量，无 token/secret/key 环境读取。
- [ok] --no-sandbox 浏览器参数 — puppeteer-config.json args 含 --no-sandbox/--disable-setuid-sandbox 等；渲染目标为本地生成的图表 HTML，输入为工作区 markdown。
- [ok] 元数据 — GitHub API：MIT / 1385 stars / pushed 2026-09-09T12:33:29Z；本地 HEAD==pin d5c4678。
6Verdict & Scenarios
Best for: Suitable for WSL2/Linux users needing to batch-export PNGs from markdown containing Mermaid diagrams (for docs, slides, blog posts), requiring mmdc + Chrome pre-installed; also ideal for workflows demanding local rendering for confidentiality.
Not for: Not suitable for environments lacking Chrome or sudo installation privileges; not suitable for users needing pixel-perfect customization of diagram naming/layout (limited dimension knobs); non-Mermaid diagram formats (PlantUML, etc.) are unsupported.
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload mermaid-tools.tar.gz
sha256:
Option B · Copy Guide for Agent3b3522624bae3e65…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.