skills.rest
arnonmoscona
arnonmosconaCOMMUNITY
Explore all skills by this author →
GitHub

diagramming

Select notation and layout engines to produce readable architecture and dependency diagrams.

Updated May 3, 2017
Search Tags:#layout#mermaid#diagramming#visualization#dependency graph#graphviz#architecture diagram
One-click install
npx skills add https://github.com/arnonmoscona/dot_files --skill diagramming-arnonmoscona
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: diagramming
Source: https://github.com/arnonmoscona/dot_files/tree/main/wsl/.claude/skills/diagramming
Command: npx skills add https://github.com/arnonmoscona/dot_files --skill diagramming-arnonmoscona

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Diagrams often fail because the wrong notation or layout engine is chosen, producing cluttered, unreadable pictures that are worse than prose. This Skill guides notation choice, engine selection, and layout tuning so diagrams actually communicate structure. ## Core Features & Use Cases - Engine Selection Guidance: Defaults to Mermaid for most diagrams and identifies when dense layered graphs (25+ nodes) require Graphviz dot instead. - Render-and-Inspect Loop: Instructs checking installed renderers (dot, neato, mmdc, rsvg-convert), rendering to PNG, and visually judging output against seven concrete layout quality criteria. - Tuning Levers: Covers grouping, rank direction, splines, transitive reduction, and structural color so layouts improve through structure rather than cosmetics. - Use Case: When asked to draw a dependency graph of a large codebase, detect that Mermaid will sprawl, switch to Graphviz dot with grouping and rankdir=TB, render to PNG, and iterate until crossings and overlaps are minimized. ## Quick Start Use the diagramming skill to draw a clear dependency diagram of this project's modules and show me the rendered result.

Frequently Asked Questions about diagramming

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I choose between Mermaid and Graphviz for a diagram?▼

Use Mermaid by default since it renders inline in Markdown almost everywhere. Switch to Graphviz dot only for dense layered graphs with roughly 25 or more nodes where Mermaid's dagre or elk layouts sprawl with empty regions and full-height edges.

What makes a diagram layout readable?▼

Readable layouts keep related entities close together, use short arrows with few bends, minimize crossings, avoid lines crossing boxes, prevent box overlap, and stay compact. These criteria conflict, so compare candidates by naming which criteria each wins or loses.

When should I use Graphviz neato instead of dot?▼

Use neato when the insight you want is hub and component structure on a flat graph with no sub-packages, since force-directed layouts reveal disconnected subsystems and hub modules that layered dot drawings hide. Dot remains stronger for layered DAGs.

Why does my Mermaid diagram look cluttered and wide?▼

Mermaid's dagre engine spreads dense layered graphs very wide with large empty regions, and elk makes them very tall. This is an engine limitation, not a tuning failure; switch to Graphviz dot for compact layered drawings.

How do I simplify a graph with too many edges before drawing?▼

Apply a transitive reduction, which drops every edge implied by a longer path and often halves the edge count. Check for cycles first since reduction is only meaningful on a DAG, and state that the drawing is reduced since reachability is unchanged.

Related Skills

Explore More Software Engineering Skills→
JasonWarrenUKJasonWarrenUK
5

domain-modeller

Map domain entities, relationships, and boundaries into Mermaid diagrams or Cypher structures.

Community
Intermediate
zhiluopzhiluop
16

siyuan-markdown

Edit Siyuan notes with SFMarkdown to render wiki links, block references, and embedded blocks.

Community
Basic
TalonT-OrgTalonT-Org
5

verify-diag

Validate architecture diagrams against source code for component and connection accuracy.

Official
Advanced
reason-machinesreason-machines
4

system-design-visualizer-tool

Converts static system design diagrams into interactive React Flow visualizations using GPT-4o and Mermaid.

Official
Intermediate