render-mermaid
Skill0 starsChanged 5 months agoMITView on GitHub
Use ONLY when the user explicitly asks to visualize, render, view, open, preview, see, or display a mermaid diagram (a `.mmd` file or a fenced ```mermaid block) as an image or PDF. Trigger phrases include "show me this as a diagram", "render the mermaid", "open the diagram", "can I see that visually", "graph it", "visualize this". Do NOT trigger when the user is merely writing, editing, pasting, or reviewing mermaid syntax in source files -- that work does not need rendering and the skill would burn tokens and time for no reason.
In this repository34 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- architectureSkill
- code-reviewSkill
- debugSkill
- dep-auditSkill
- deploy-checklistSkill
- documentationSkill
- end-agent-sessionSkill
- incident-responseSkill
- likec4-dslSkill
- load-agentSkill
- manual-testSkill
- market-scanSkill
- new-agentSkill
- new-goal-loopSkill
- nexus-microSkill
- nexusSkill
- nexus-sprintSkill
- orchestration-cost-policySkill
- persona-forgeSkill
- project-onboardSkill
- prompt-refinerSkill
- public-readinessSkill
- release-prepSkill
- secrets-syncSkill
- standupSkill
- system-designSkill
- tech-debtSkill
- testing-strategySkill
- tmux-session-captureSkill
- tsdocSkill
- web-ui-automation-componentsSkill
- web-ui-automation-surveySkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 41
If the source is a fenced block, write it to a temp .mmd (or pipe to from-stdin --name <stem>).
- Distinctive: line 42
Run the script. Default format is PDF.
- Distinctive: line 53
Triggering on plain mermaid authoring: If the user just pasted a mermaid block to discuss its content, do not render.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Render Mermaid
Render a mermaid diagram and open it in the user's default viewer. Defaults to PDF (vector, baked fonts, dark-mode-proof, snap/flatpak-safe).
When to fire
Trigger ONLY if the user clearly asks to see the diagram. "Write a mermaid diagram of X" alone is NOT a render request. "Write it AND show me" IS.
Quick reference
| Source | Command |
Existing .mmd file | uv run ${CLAUDE_PLUGIN_ROOT}/skills/render-mermaid/render_mermaid.py from-file <path> |
| Fenced ```mermaid block in conversation | Pipe via heredoc to from-stdin --name <stem> |
| Want SVG/PNG instead of PDF | Add --format svg or --format png |
| Don't auto-open | Add --no-open |
The renderer writes to ~/Downloads/<stem>.<ext> (snap-Firefox-readable) and runs xdg-open detached so the tool call returns immediately.
Workflow
- Locate the mermaid source: a file path the user named, OR the most recent fenced ```mermaid block in the conversation.
- If the source is a fenced block, write it to a temp
.mmd(or pipe tofrom-stdin --name <stem>). Choose<stem>from context (e.g. the topic of the diagram). - Run the script. Default format is PDF. Switch to SVG only if the user explicitly asked for SVG; switch to PNG only for embedding/sharing.
- The script prints the output path on stdout and detaches the viewer. Tell the user where it landed and what format.
Format choice
- PDF (default) -- viewer-portable, vector, baked fonts. Survives system dark-mode and Linux image viewers that don't parse mermaid's embedded
<style>block. - SVG -- only when the user wants to drop it in a web page or edit in Inkscape. On Linux, snap Firefox cannot read
/tmp; the script writes to~/Downloads/to avoid that pitfall. - PNG -- only for chat embeds or social posts. Renders at default DPI -- bump width on the CLI if the user wants it big.
Common mistakes
- Triggering on plain mermaid authoring. If the user just pasted a mermaid block to discuss its content, do not render. Wait for an explicit ask.
- Choosing SVG by default. SVG looks broken in eog/Loupe because mermaid relies on CSS variables that those viewers do not resolve. Use PDF unless the user names SVG.
- Putting output in /tmp. Snap/flatpak browsers cannot read
/tmp. The script already handles this; don't override-o. - Forgetting
--no-sandbox. On Ubuntu 23.10+ Puppeteer fails withFATAL: No usable sandbox. The script already supplies a Puppeteer config; don't bypass it.
Dependencies
npx (Node/npm). The script invokes npx -y -p @mermaid-js/mermaid-cli mmdc, which fetches mmdc on first run and caches it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.