agentleFS
TechNickAITechNickAI/hermes-skills/skills/engineering/diagram-rendering/SKILL.md

diagram-rendering

Skill0 starsChanged 3 months agoMITView on GitHub

Draw a diagram or chart from text and deliver it inline in chat. One script, scripts/render.py, covers three diagram languages and data charts, and always ends in a PNG (or an inline image URL) — because chat platforms render images, not .d2/.mmd/.dot/.svg source. Two jobs, one tool: - Diagrams (flowcharts, architecture, sequence, ER) — you write terse text in D2, Mermaid, or Graphviz; the hosted renderer (Kroki) returns an SVG and the script rasterizes it locally to a crisp 2×…

  • Installs packages

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use for fast, auto-laid-out diagrams or charts when hosted rendering is acceptable (the content is not sensitive, or you point *_BASE at a …

    line 65
  2. Very specific:

    Write a Chart.js config (~/pnl.json):

    line 143
  3. Very specific:

    Prefer the local PNG + MEDIA: default — it renders on every platform and you can verify the image before sending.

    line 179
  4. Distinctive:

    Always eyeball anything that matters for legibility, clipping, and correctness.

    line 212
  5. Very specific:

    Don't paste a 1000-char raw QuickChart GET URL into chat: Use the local-PNG default or --short-url.

    line 220

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Diagram Rendering 📈

Draw a diagram or chart from text and deliver it inline in chat. One script, scripts/render.py, covers three diagram languages and data charts, and always ends in a PNG (or an inline image URL) — because chat platforms render images, not .d2/.mmd/.dot/.svg source.

Overview

Two jobs, one tool:

  • Diagrams (flowcharts, architecture, sequence, ER) — you write terse text in D2, Mermaid, or Graphviz; the hosted renderer (Kroki) returns an SVG and the script rasterizes it locally to a crisp 2× PNG.
  • Data charts (line, bar, pie, etc.) — you write a Chart.js JSON config; QuickChart renders it, either as a local PNG (default) or a short inline URL.

Pick the language by the tradeoff you want:

LanguageLayoutTradeoff
D2modern, rounded, auto-laid-outbest-looking default; layout can wander on very dense graphs
Graphvizstrict orthogonal, deterministicmost robust auto-layout for dense/dependency graphs; visually stiffer
Mermaidsimple flow/sequencefastest to write; plainest default styling

Charts (QuickChart) cover the data side — P&L curves, win-rate bars, category breakdowns. Same tool, so one skill draws both a flow and a plot.

When to Use

Use for fast, auto-laid-out diagrams or charts when hosted rendering is acceptable (the content is not sensitive, or you point *_BASE at a self-hosted instance).

  • "draw / show / diagram this", "make a flowchart / architecture / sequence / ER diagram"
  • "chart / plot / graph our P&L / win rate / breakdown"

Route elsewhere:

  • Hand-drawn / whiteboard aesthetic → excalidraw.
  • Offline, pixel-controlled dark-SVG "card" where you hand-place every box → architecture-diagram.
  • Photographic / illustrative images → an image-generation skill.

Requirements

  • Headless Chromium for the diagram paths (rasterizes SVG). The script probes chromium-browser, chromium, google-chrome, google-chrome-stable, or honors CHROMIUM_BIN. On macOS set CHROMIUM_BIN="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome". Not needed for chart --short-url (pure API call).
  • Network to kroki.io (diagrams) and quickchart.io (charts) — free, no key. Point at self-hosted instances with KROKI_BASE / QUICKCHART_BASE (http(s) only; these are trusted operator config, never derive them from an untrusted prompt).
  • Pillow (pip install pillow) — recommended; enables real blank-render detection. Without it the script only checks PNG magic + a weak size heuristic and cannot reliably catch a blank canvas — so eyeball the image regardless.

Workflow

The script lives next to this SKILL.md. Resolve its directory as SKILL_DIR and call it by absolute path — do not assume the caller's working directory:

SKILL_DIR="$(dirname "$(realpath path/to/this/SKILL.md)")"   # or the skill dir you loaded

1. Write the diagram text

Save to a file. Example D2 (~/flow.d2):

direction: down
firehose: "Trades firehose" {shape: oval; style: {fill: "#083344"; stroke: "#22d3ee"; font-color: "#e2e8f0"}}
elig: "Eligible?" {shape: diamond; style: {fill: "#1e293b"; stroke: "#94a3b8"; font-color: "#e2e8f0"}}
ladder: "Price ladder" {style: {fill: "#2e1065"; stroke: "#a78bfa"; font-color: "#e2e8f0"; border-radius: 8}}
firehose -> elig
elig -> ladder: yes

Mermaid (.mmd) and Graphviz (.dot) work the same way — the script passes the text straight through to Kroki.

2. Render to PNG

python3 "$SKILL_DIR/scripts/render.py" diagram --lang d2       --in ~/flow.d2  --out ~/flow.png
python3 "$SKILL_DIR/scripts/render.py" diagram --lang mermaid  --in ~/flow.mmd --out ~/flow.png
python3 "$SKILL_DIR/scripts/render.py" diagram --lang graphviz --in ~/flow.dot --out ~/flow.png

The script prints the absolute PNG path on success and exits non-zero on a failed or blank render (it retries transient host errors first). --out must be under $HOME (see pitfall #1). Optional --width / --height (default 900×700, scaled 2×).

3. Deliver inline

The printed path is what the platform renders. Put it in your reply as a standalone, unfenced line (a code-fenced MEDIA: will NOT attach the image):

MEDIA:/home/you/flow.png

Inspect the image first — the blank-check catches empty renders, not wrong content.

Charts

Write a Chart.js config (~/pnl.json):

{
  "type": "line",
  "data": {
    "labels": ["Mon", "Tue", "Wed"],
    "datasets": [
      {
        "label": "P&L $",
        "data": [0, 42, 124],
        "borderColor": "#34d399",
        "backgroundColor": "rgba(52,211,153,0.15)",
        "fill": true,
        "tension": 0.3
      }
    ]
  }
}

Default: local PNG (POSTs the config, so large configs are fine), deliver via MEDIA::

python3 "$SKILL_DIR/scripts/render.py" chart --config ~/pnl.json --out ~/pnl.png

Only if the target channel is known to auto-embed remote image URLs, a short URL is lighter (the platform fetches it; no local file):

python3 "$SKILL_DIR/scripts/render.py" chart --config ~/pnl.json --short-url
#   -> https://quickchart.io/chart/render/zf-...   (a public bearer link)

Prefer the local PNG + MEDIA: default — it renders on every platform and you can verify the image before sending. Use --short-url only for channels that reliably inline remote images.

Tiered strategy (what to reach for)

  1. Default diagram → D2. Best-looking, one command.
  2. Dense / dependency graph, layout getting messy → Graphviz. Deterministic layout.
  3. Just need a quick flow, styling irrelevant → Mermaid.
  4. Data, not boxes → chart (QuickChart). Local PNG default; short-URL only where it inlines.
  5. Fully offline / pixel-exact brand card → architecture-diagram (hand SVG).

Common Pitfalls

  1. Snap Chromium can only WRITE under $HOME, and NOT to hidden (dot-prefixed) files. AppArmor silently blocks writes to /tmp and to ~/.foo.png (the screenshot just never appears). The script enforces --out under $HOME (symlink-resolved) and uses a visible temp filename for the render. Reading a hidden source file is fine; writing a hidden output is not.
  2. Kroki renders D2 to SVG only — its PNG endpoint 400s for D2. The script always fetches SVG and rasterizes locally (for every language, so 2× scale + --width/height apply uniformly). Don't "optimize" it back to requesting D2 PNG.
  3. Kroki's Mermaid renderer is intermittently flaky — it occasionally 400s with "Failed to launch the browser process" (a failure inside Kroki's own headless browser, under load). The script retries transient 5xx/that-400 a couple times. If it still fails, it's the host — retry later or switch language.
  4. Untrusted render output is rasterized with JavaScript DISABLED. Kroki/QuickChart responses are outside your trust boundary; SVG can carry scripts. The script renders with --disable-javascript (Kroki SVG is static and needs none). The svg subcommand is for trusted SVG only.
  5. Blank-render detection catches empty canvases, not wrong content, and is only authoritative with Pillow installed. Valid-but-wrong text renders fine and passes. Always eyeball anything that matters for legibility, clipping, and correctness.
  6. Default Python-urllib User-Agent gets 403'd by Kroki. The script sends a real UA. If you write your own fetch, set User-Agent or you'll get 403.
  7. Both diagram source AND chart data leave the machine (to Kroki / QuickChart respectively). A "private thread" does not protect the data from those providers, and a --short-url is a public bearer link. For sensitive content, use approved self-hosted KROKI_BASE / QUICKCHART_BASE endpoints or an offline sibling skill (architecture-diagram, excalidraw).
  8. Don't paste a 1000-char raw QuickChart GET URL into chat. Use the local-PNG default or --short-url.

Verification Checklist

  • --out path is under $HOME and not dot-prefixed
  • Chromium present for diagram paths (CHROMIUM_BIN or one of the four probed names)
  • Script exited 0 and printed a PNG path (non-zero = blank/failed/host-down after retries)
  • Eyeballed the image for correctness, clipping, legibility (guard only catches blank)
  • Delivered as an unfenced MEDIA:<path> line (PNG) or a --short-url link on a channel that inlines it
  • Sensitive content? Used a self-hosted *_BASE or an offline skill instead

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

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.