agentleFS
LengrosLengros/bennu/.claude/skills/diagram/SKILL.md

diagram

Skill2 starsChanged 4 months agoMITView on GitHub

Draw polished diagrams, schemas, architecture maps, data-flow / lifecycle diagrams, workflows, and infographics by rendering them from code (HTML/CSS + SVG → headless Chrome → PNG) — not by AI image generation. Use when the user wants a clear, editable visual of how a system, process, or set of relationships works, or likes an example diagram and wants something in that style. Produces accurate text, exact colors, and a versionable source you can re-edit. Russian triggers — "нарисуй схему", "сделай диаграмму", "визуализируй архитектуру", "схема воркфлоу", "инфографика", "нарисуй как это работает". Distilled from a real diagramming session, 2026-06-15.

  • Installs packages

53 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use ios-sync, benchmark-models and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • Saqlain-811Skill

    ios-sync

    Regenerate the iOS debug bridge against the latest upstream gstack templates. (gstack)

    Also in 4 projects that use this

  • ShreyRaviSkill

    benchmark-models

    Cross-model benchmark for gstack skills. Runs the same prompt through Claude, GPT (via Codex CLI), and Gemini side-by-side — compares latency, tokens, cost, and optionally quality via LLM judge. Answers "which model is actually best for this skill?" with data instead of vibes. Separate from /benchmark, which measures web page performance. Use when: "benchmark models", "compare models", "which model is best for X", "cross-model comparison", "model shootout". (gstack) Voice triggers (speech-to-text aliases): "compare models", "model shootout", "which model is best".

    Also in 5 projects that use this

  • ShreyRaviSkill

    landing-report

    Read-only queue dashboard for workspace-aware ship. Shows which VERSION slots are currently claimed by open PRs, which sibling Conductor workspaces have WIP work likely to ship soon, and what slot /ship would pick next. No mutations — just a snapshot. Use when asked to "landing report", "what's in the queue", "show me open PRs", or "which version do I claim next". (gstack)

    Also in 5 projects that use this

  • timurgaleevSkill

    document-generate

    Generate missing docs for a feature, module or project as tutorials, how-tos, reference and explanation.

    Also in 4 projects that use this

  • Saqlain-811Skill

    ios-clean

    Remove the DebugBridge SPM package and all #if DEBUG wiring from an iOS app. (gstack)

    Also in 3 projects that use this

  • seek888Skill

    open-gstack-browser

    Launch GStack Browser — AI-controlled Chromium with the sidebar extension baked in. Opens a visible browser window where you can watch every action in real time. The sidebar shows a live activity feed and chat. Anti-bot stealth built in. Use when asked to "open gstack browser", "launch browser", "connect chrome", "open chrome", "real browser", "launch chrome", "side panel", or "control my browser". Voice triggers (speech-to-text aliases): "show me the browser".

    Also in 4 projects that use this

  • +2 more from ShreyRavi
  • +1 more from Saqlain-811

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 2 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 44 edited versions we read keep these.

  • 2

    Distinctive

    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. Distinctive:

    If you catch yourself reusing the example's layout for a different kind of system, stop — that's the mistake.

    line 61
  2. Very specific:

    Don't draw a system from imagination.

    line 65
  3. Very specific:

    If the thing you're drawing has a UI, grep its CSS for color tokens and use them verbatim (grep -nE '\-\-color|#[0-9a-f]{6}' <stylesheet>).

    line 73
  4. Very specific:

    No hand-rolled CSS-triangle arrows: Use a Lucide arrow in a circle (flex mode) or SVG <marker> arrowheads (coordinate mode).

    line 123
  5. Very specific:

    Mermaid via an MCP server: instead of writing a generator.

    line 149
  6. Distinctive:

    When a new diagramming surprise appears, fold the fix back into the templates / this file — don't let the skill calcify.

    line 174

“Common” is measured: kept by at least 6 in 10 of the 44 edited versions of this file we could read. “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 — render diagrams from code, not from a paint model

For anything with labels, structure, or precise relationships — architecture, data flow, lifecycle, workflow, org/topology — render it from HTML/CSS (+ SVG for connectors) screenshotted by headless Chrome. You get correct text, exact colors, and a source you can re-edit and recolor in seconds. This stays the right call whenever you need exact design tokens, fully custom composition, or pixel control with no external dependency.

Raster image-gen used to be disqualified by garbled text; that changed in 2025-26 (Nano Banana Pro / Gemini 3 Pro Image now renders legible in-image text and is marketed for infographics; GPT-image is strong too — Flux is still unreliable for fine text). Use it only for soft illustrative infographics, not structured technical diagrams (still no element-level editing, no exact palette). And in THIS environment raster is UI-only, not agent-drivable: Nano Banana Pro is available via the work Gemini subscription UI, GPT-image via the ChatGPT/Codex ($20) UI — no API key here. So for raster you produce a prompt and hand it off to the user to run in the UI — that path is /illustration-prompt. See "Reach past this skill when" below.

The whole advantage is a tight visual loop: write generator → render → Read the PNG (you can see it) → fix → re-render. Lean on it.


The pipeline

  1. Write a Node generator (.mjs) that inlines icons + emits self-contained HTML. Copy template.mjs from this skill as the skeleton.
  2. Render with render.sh out.html out.png <W> <H> <bgHex>.
  3. Read the PNG, adjust, re-render. Crop by tuning window height (see Gotchas).
  4. Work in a scratch/ dir (gitignored). Keep only the final .png + its .mjs; node_modules (lucide-static ≈ 59 MB) is build-only junk — don't leave it lying around.
cd scratch && npm init -y && npm i lucide-static
node build.mjs                                   # -> build.html (icons inlined)
.claude/skills/diagram/render.sh build.html build.png 1220 900 f1f3efff

Get these right BEFORE styling — they're what makes a diagram good or useless

1. Pick the topology from the SUBJECT, not from a reference image. The single biggest failure mode (learned the hard way this session): the user shows an example they like the look of, and you clone its composition. But composition encodes a specific system shape. Reproduce the example's aesthetic (cards, icons, palette) and choose the structure from what you're actually drawing:

Subject shapeRight composition
One controller managing N identical units (e.g. an orchestrator → many deployments)A control-plane header → grid of repeated unit cards → shared foundation bar
A layered system / serviceStacked tiers + a cross-cutting concerns rail down the side
Data / product lifecycleHorizontal sources → ingest → store → aggregate → channels, with fast-paths and feedback edges drawn explicitly
A process / workflowStages left→right with branch and decision edges

If you catch yourself reusing the example's layout for a different kind of system, stop — that's the mistake.

2. Ground every component in reality (the Bennu evidence rule). Don't draw a system from imagination. Read the real source first; tag each claim [Observed: path:lines] or [ASSUMPTION]. Delegate a fresh Explore agent to map a codebase if the surface is large. Mark status honestly on nodes — implemented / planned / external / stub — instead of presenting aspiration as fact. This session's first early draft invented a component that did not exist; reading the repo replaced it with the real path.

3. Steal the palette from the subject's own design system. If the thing you're drawing has a UI, grep its CSS for color tokens and use them verbatim (grep -nE '\-\-color|#[0-9a-f]{6}' <stylesheet>). Pull the palette straight from the app's own global stylesheet — far better than a guessed palette, and instantly on-brand.


Layout: three modes

  • Simple (flex). Linear or tiered flows: cards in flex rows/columns, an arrow between them. Fast. For the connector use a Lucide arrow icon in a small circle — never a hand-rolled CSS triangle (it renders as an ugly grey nub against rounded card corners).
  • Coordinate-driven (SVG edges). Define every node once as {x,y,w,h}, place the HTML divs absolutely, and draw an SVG .edges layer of bezier <path>s with <marker> arrowheads — all computed from the same coordinates. template.mjs is exactly this. A back-edge (e.g. "a settings screen writes a value back to the store") or a stage-skipping fast-path (e.g. "a live event bypasses the batch pipeline") can ONLY be shown honestly with real arrows — flex can't draw them. Use this when you want total control of the composition (a lifecycle diagram was hand-placed for exactly that reason).
  • Auto-layout (ELK). The fix for hand-placing coordinates. Describe the graph declaratively (nodes with box sizes, edges with source/target); elkjs computes positions AND routes the edges — its layered algorithm is built for directed node-link graphs and, unlike Dagre, auto-routes edges (incl. back-edges). You still render with your own HTML/CSS/SVG reading ELK's output, so design tokens and editability are kept — only the x/y math is delegated. elk-template.mjs is a working example (npm i elkjs). Reach for this for larger or evolving graphs where manual placement doesn't scale; reach for coordinate-driven when the composition itself is the message.

Icons: inline Lucide, don't reach for emoji

  • npm i lucide-static → 1964 monochrome SVGs in node_modules/lucide-static/icons/. Verify a name exists before using it: ls node_modules/lucide-static/icons | grep -i key.
  • Inline the SVG and tint via the parent's color (lucide uses stroke="currentColor"). An <img src=icon.svg> will not take your color — it renders default black.
  • Strip the license comment and the fixed width="24"/height="24" so CSS controls size (template.mjs's ico() does this).
  • Emoji are quick and colorful but read childish and render inconsistently. Default to Lucide for anything technical; offer emoji only if the user wants a playful look.

Gotchas (each one cost an iteration this session)

  • Scope SVG CSS selectors. A rule like .canvas svg { position:absolute; inset:0; width:100% } also matches every inline icon SVG (they're descendants of .canvas), flinging icons into the top-left corner and leaving the tiles empty. Give the edge layer a class and target .canvas > svg.edges — never a bare svg selector inside a container that also holds inline icons.
  • No hand-rolled CSS-triangle arrows. Use a Lucide arrow in a circle (flex mode) or SVG <marker> arrowheads (coordinate mode).
  • Cropping. --screenshot captures the --window-size viewport; there is no full-page CLI flag. Window too short cuts the footer; too tall leaves dead space. Iterate the height, and set --default-background-color to the page bg so any excess is seamless.
  • Retina. --force-device-scale-factor=2 — without it text looks soft.
  • Read the PNG every iteration. The Read tool shows you the image; that visual check is the point. Don't ship a diagram you haven't looked at.

Aesthetic defaults that read "polished"

Rounded cards (radius 13–18) · soft layered shadow (0 1px 2px …, 0 4px 14px …) · hairline borders · icons in tinted rounded tiles · a faint dotted background · restrained palette: one accent + at most one secondary (resist the rainbow) · status badges · a small legend when there's more than one kind of edge/node · optional serif headings for an "institutional" feel. Less candy, more structure.


Reach past this skill when

This skill owns bespoke, brand-exact diagrams. For two other jobs, hand off:

  • Fast / throwaway / generic structural diagram (you don't need custom styling): drive Mermaid via an MCP server instead of writing a generator. mcp-mermaid (open-source, hustcc) generates Mermaid and returns svg/png/base64 with syntax validation for multi-round correction; the official Mermaid Chart MCP has a validate_and_render tool returning PNG/SVG — a built-in verify loop. Lower visual ceiling, but one call and the text is always correct. UML-MCP covers 30+ types (Mermaid, D2, Graphviz, C4, …) if you need a multi-engine gateway. (Eraser.io has the cleanest agent integration — MCP + Agent Skill — but non-watermarked output is pay-gated.)
  • Soft illustrative infographic (the "designed poster" look, text accuracy now OK): hand off a raster prompt via /illustration-prompt. Best text rendering in 2025-26 is Nano Banana Pro (Gemini 3 Pro Image); GPT-image is also strong. In this environment both are UI-only (Nano Banana = work Gemini sub; GPT-image = ChatGPT/Codex $20) — no API key — so you write the prompt and the user runs it in the UI. Not for structured technical diagrams (no element editing, no exact palette).

Rule of thumb: structure + brand → this skill; structure + speed → Mermaid-MCP; illustration → raster hand-off.

Files in this skill

FileWhat it is
render.shheadless-Chrome screenshot wrapper — render.sh in.html out.png [W] [H] [bg]
template.mjscoordinate-driven generator — you place {x,y,w,h} (Lucide inline + SVG .edges)
elk-template.mjsauto-layout variant — ELK places nodes & routes edges, you keep the styling (npm i elkjs)

When a new diagramming surprise appears, fold the fix back into the templates / this file — don't let the skill calcify. (Research provenance: deep-research run 2026-06-15 — ELK+SVG pairing, Mermaid/UML MCP servers, Nano Banana Pro text rendering, all from primary sources.)

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.