baoyu-diagram

baoyu-diagram

Diagram Generator

Write real SVG code directly, following a consistent design system, the output is self-contained .svg files (embedded styles, auto dark-mode), editable by humans, scales to any size without quality loss, and embeds cleanly into articles, WeChat posts, slide decks, Notion, and markdown.

When given source material (topic descriptions, documents, technical specs, pasted content), the skill analyzes what diagrams would best convey the material, recommends diagram type(s) and whether the content should be split into multiple focused diagrams, confirms the plan once, then generates all diagrams.

This is not an image-generation skill — it does not call any LLM image model. Claude writes the SVG node-by-node, doing the layout math by hand so every diagram honors the rules in references/.

Usage

# Topic string — skill analyzes and proposes a plan
/baoyu-diagram "how JWT authentication works"

# File path — skill reads, analyzes, and proposes a plan
/baoyu-diagram path/to/content.md

# Pasted content — prompts for input if no argument given
/baoyu-diagram

# Force a specific diagram type (skips type recommendation)
/baoyu-diagram "transformer attention"    --type illustrative
/baoyu-diagram "Kubernetes architecture"  --type structural
/baoyu-diagram "CI/CD pipeline"           --type flowchart
/baoyu-diagram "OAuth 2.0 flow"           --type sequence
/baoyu-diagram "Shape hierarchy"          --type class

# Language and output path
/baoyu-diagram "微服务架构"              --lang zh
/baoyu-diagram "build pipeline" --out docs/build-pipeline.svg

Options

Option Values

--type flowchart, sequence, structural, illustrative, class, auto (default — route on verb). When specified, forces this type for all diagrams — skips type recommendation.

--lang en, zh, ja, ko, ... (default: match the user's language)

--out Output file path. When set, the skill generates exactly one diagram at this path — analysis produces a single-diagram plan focused on the most important aspect of the material.

Diagram types

Pick the type by what the reader needs, not by the noun in the prompt.

The primary test: is the reader trying to document this, or understand it? Documentation wants precision — flowchart, sequence, or structural. Understanding wants the right mental model — illustrative.

Type Reader need Route on verbs like Reference

Flowchart Walk me through the steps, in order "walk through", "steps", "process", "lifecycle", "workflow", "state machine", "gate", "router", "parallelization", "orchestrator", "evaluator" references/flowchart.md

Flowchart (phase band) Walk me through each phase; show the tools at each stage "phase 1/2/3", "multi-phase operation", "each phase has tools", "attack phases", "phased workflow", "security operation phases", "penetration test stages", "phase N feeds phase N+1" references/flowchart-phase-bands.md

Sequence Who talks to whom, in what order "protocol", "handshake", "auth flow", "OAuth", "TCP", "TLS", "gRPC", "request/response", "who calls what", "exchange between", "round trip", "webhook" references/sequence.md

Structural Show me what's inside what, how it's organized "architecture", "organised", "components", "layout", "what's inside", "topology", "subsystem", "two systems", "side by side", "foreground + background" references/structural.md

Illustrative Give me the intuition — draw the mechanism "how does X work", "explain X", "I don't get X", "intuition for", "why does X do Y", "LLM with tools", "agent and environment", "central + attachments" references/illustrative.md

Class What are the types and how are they related "class diagram", "UML", "inheritance", "interface", "schema", "types and subtypes", "data model" references/class.md

Routing heuristic: "how does X work" is the default ambiguous case. Prefer illustrative unless the user specifically asks for steps or components. A diagram that makes the reader feel "oh, that's what it's doing" is illustrative — even if the subject is software.

Multi-actor test for sequence: if the prompt names ≥2 distinct actors/participants/services (User + Server, Client + Auth + Resource, Browser + CDN + Origin), prefer sequence even when the verb is "flow" or "process". Single-actor "X flow" (build pipeline, request lifecycle, GC) stays flowchart. When you pick sequence for a multi-actor reason, announce it: "Picked sequence because the prompt names N actors (…). Rerun with --type flowchart to force the step-list version."

Worked examples of verb-based routing: same subject, different diagram depending on what was asked. Use these as a sanity check after picking a type.

User says Type What to draw

"how do LLMs work" Illustrative Token row, stacked layer slabs, attention threads across layers.

"transformer architecture / components" Structural Labeled boxes: embedding, attention heads, FFN, layer norm.

"how does attention work" Illustrative One query token, fan of lines to every key, line thickness = weight.

"how does gradient descent work" Illustrative Contour surface, a ball rolling down, a trail of discrete steps.

"what are the training steps" Flowchart Forward → loss → backward → update.

"how does TCP work" Illustrative Two endpoints, numbered packets in flight, an ACK returning.

"TCP handshake sequence" Sequence SYN → SYN-ACK → ACK between client and server lifelines.

"how does a hash map work" Illustrative Key falling through a hash function into one of N buckets.

"LLM with retrieval, tools, memory" Illustrative Central LLM subject with dashed radial spokes to three labeled attachments.

"gate pattern with pass/fail exit" Flowchart Pill In → LLM → Gate → LLM → LLM → pill Out, with a dashed Fail branch to Exit.

"LLM router / parallelization" Flowchart Simple fan-out: pill In → hub → 3 branches → aggregator → pill Out.

"Pi session + background analyzer" Structural (subsystem) Two dashed sibling containers side by side, each with a short internal flow, labeled cross-system arrows.

"prompt engineering vs. context engineering" Structural (subsystem) Two sibling containers, each showing its internal mechanism with cross-links.

"agent + environment loop" Illustrative Human pill ↔ LLM rect ↔ Environment pill, Action/Feedback labels on the edges.

"Claude Code workflow with sub-loops" Sequence 4 actors with 1–2 dashed message frames labeled "Until tests pass" / "Until tasks clear".

"generator-verifier loop" Flowchart Outer loop container; two boxes with green ✓ / coral ✗ status circles on the return edge. See flowchart.md → "Loop container" + "Status-circle junctions".

"from TODOs to tasks" Structural (subsystem) Two siblings: left = checklist (checkbox glyphs); right = DAG of task nodes with one dashed future-state node. See structural.md → "Rich interior" + "Dashed future-state node".

"finding the sweet spot" Illustrative Horizontal spectrum axis between two opposing labels; option boxes under tick points with the middle one highlighted. See illustrative.md → "Spectrum / continuum".

"agent teams with task queue" Flowchart Queue glyph inside the lead box, then vertical fan-out to workers. See flowchart.md → "Queue glyph inside box" + "Vertical fan-out".

"message bus architecture" Structural Central horizontal bar + agents above/below, each linked by a publish/subscribe arrow pair. See structural.md → "Bus topology".

"shared state store" Structural Central hub with a doc icon + 4 corner satellites, bidirectional arrow pairs. See structural.md → "Radial star topology".

"orchestrator vs. agent teams" Structural (subsystem) Two siblings; left = hub + fan-out; right = queue + vertical fan-out. See structural.md → "Rich interior for subsystem containers".

"orchestrator vs. message bus" Structural (subsystem) Two siblings; left = hub + fan-out; right = mini bus topology. See structural.md → "Rich interior".

"advisor strategy" Structural Single container, multi-line box bodies (title/role/meta), mixed solid+dashed+bidirectional arrows with a legend strip. See structural.md → "Mixed arrow semantics" + "Multi-line box body".

"tool calling vs. programmatic" Sequence Parallel independent rounds — left = stacked rounds; right = stacked rounds wrapped in a tall script box. See sequence.md → "Parallel independent rounds".

"Claude + environment + skill" Illustrative Two subject boxes with a bidirectional arrow; annotation circle at the midpoint labels the skill. See illustrative.md → "Annotation circle on connector".

"code execution vs. dedicated tool" Structural (subsystem) Two siblings; left = Computer box with nested Terminal; right = Claude with an attached gadget box for Tools. See structural.md → "Rich interior" + "Attached gadget box".

"Shape inheritance / class hierarchy" Class 3-compartment rects (name / attrs / methods) with hollow-triangle inheritance arrows. See class.md.

"order lifecycle / status transitions" Flowchart (state machine) State rects + initial/final markers + event [guard] / action transition labels. See flowchart.md → "State machine".

"network topology (3-tier)" Structural (network) Dashed zone containers (Internet / DMZ / Internal) + labeled device rects. See structural.md → "Network topology".

"database comparison matrix" Structural (matrix) Header row + zebra-striped body rows with ✓/✗ glyphs in cells. See structural.md → "Comparison matrix".

"multi-phase attack / each phase has tools" Flowchart (phase band) Stacked dashed phase bands; compact tool cards with icons in each band; colored cross-band arrows (normal / exploit / findings); operator icons on left. See flowchart-phase-bands.md.

"phased workflow / phase 1 recon phase 2 exploit" Flowchart (phase band) Phase labels as eyebrow text; tool card rows centered in each band; side annotations; legend strip. See flowchart-phase-bands.md.

Most common routing failure: picking a flowchart because it feels safer when an illustrative diagram would give the reader more insight. Illustrative is the more ambitious choice, and almost always the right one when the reader needs understanding rather than documentation.

Cycles, ERDs, and gantt charts are out of scope for v1. For cycles, draw the stages linearly with a small ↻ returns to start return glyph (see flowchart.md). For ERDs, suggest a dedicated tool (mermaid, plantuml) — do not attempt to fake them in pure SVG.

Workflow

Step 1: Capture input

Read the user's prompt, content file, or pasted content. Note any flags (--type, --lang, --out).

Input Action

File path to .md / .txt Read the file as source material

Pasted content or topic string Capture as source material

No input at all Ask with AskUserQuestion

If --out is given, the skill will generate exactly one diagram at that path — the analysis in Step 2 produces a single-diagram plan focused on the most important aspect of the material.

Step 2: Analyze material and produce plan

Analyze the source material and make three decisions:

Decision A: Type routing

For the input material, determine which diagram type(s) are appropriate using the routing table in "Diagram types."

Situation Action

Only one type makes sense (clear verb signal, or --type given) That type is the recommendation. No choice needed.

Multiple types could each produce a useful diagram from the same material List the candidates with a one-sentence rationale for each. The user picks in Step 3.

Decision B: Content splitting

Assess whether the material should produce one diagram or multiple sub-diagrams.

Single diagram when:

• Material is focused on one concept, one mechanism, one process

• Named elements count is manageable (under ~6 for flowchart, under ~4 actors for sequence, under ~3 containers for structural — but architecture diagrams may have 10–20 elements in a single diagram; see Step 5a item 6, "Architecture enrichment")

• One "After seeing this diagram, the reader understands ___" sentence covers the whole material

Multiple sub-diagrams when:

• Material covers 2+ independent mechanisms or processes

• Named element count exceeds comfortable limits for one diagram type

• Material has natural subsections that each deserve visual treatment

• Different parts of the material map to different diagram types

For each sub-diagram, determine: focus area, recommended type, named elements, and the "reader understands ___" sentence.

What to diagram:

• Core mechanisms the reader needs to understand (→ illustrative)

• Multi-step processes described in prose (→ flowchart)

• Multi-actor interactions (→ sequence)

• Architectural descriptions with containment or hierarchy (→ structural)

• Type hierarchies or data models (→ class)

• Comparisons between two approaches or systems (→ structural subsystem)

What NOT to diagram:

• Simple lists — a bullet list is already visual enough

• Concepts already shown in an existing image or figure

• Purely emotional or narrative passages with no underlying mechanism

• Content that is a single sentence or trivially simple

• Decorative filler — every diagram must earn its place with a concrete reader need

Decision C: Overview diagram

When the plan includes multiple sub-diagrams, assess whether an additional overview diagram that shows the big picture is worthwhile.

Situation Decision

Sub-diagrams are parts of a coherent system, seeing how they relate adds value Include an overview diagram (typically structural or illustrative)

Sub-diagrams cover independent topics that don't form a coherent whole Skip the overview

Material is simple enough that sub-diagrams already cover everything Skip the overview

Plan output

Save the plan as outline.md (for multiple diagrams) or hold in memory (for single diagram).

Single-diagram plan format:

## Diagram Plan
**Material**: [source description]
**Diagrams**: 1
**Type**: [type] (rationale)
**Named elements**: [list]
**Reader need**: "After seeing this diagram, the reader understands ___"
**Slug**: [slug]

Multi-diagram plan format:

---
material: [source description]
slug: [material-slug]
diagram_count: N
language: en
---

Per-diagram entry:

## Diagram 1: [focus area]
**Type**: [type] (rationale)
**Named elements**: [list]
**Reader need**: "After seeing this diagram, the reader understands ___"
**Slug**: [2-4 kebab-case words]
**Filename**: 01-{type}-{slug}/diagram.svg

## Diagram 2: [focus area]
...

## Overview diagram (if applicable)
**Type**: [structural/illustrative]
**Purpose**: Shows how diagrams 1-N relate as parts of a larger system
**Named elements**: [high-level elements]
**Slug**: overview-[slug]
**Filename**: overview-{type}-{slug}/diagram.svg

Requirements:

• Each diagram justified by a concrete reader need (the "After seeing this..." sentence)

• Type chosen per the routing table, not arbit

...