Generate production-quality SVG+PNG technical diagrams — architecture, data flow, flowchart, sequence, agent/memory, or concept maps — across 7 visual styles. Use when user wants "generate diagram", "draw diagram", "visualize", "architecture diagram", "flowchart", or any system/flow they want illustrated. Pairs with /ak:preview --diagram for visual self-review and /ak:mermaidjs-v11 for inline-doc diagrams; this skill is the publish-grade output mode.
Generate production-quality SVG+PNG technical diagrams — architecture, data flow, flowchart, sequence, agent/memory, or concept maps — across 7 visual styles. Use when user wants "generate diagram", "draw diagram", "visualize", "architecture diagram", "flowchart", or any system/flow they want illustrated. Pairs with /ak:preview --diagram for visual self-review and /ak:mermaidjs-v11 for inline-doc diagrams; this skill is the publish-grade output mode.
user-invocable
true
when_to_use
Invoke for publish-grade architecture or flow diagrams.
{"author":"agentkit","version":"1.0.0","attribution":"Vendored from fireworks-tech-graph by yizhiyanhua-ai (MIT)","license":"MIT","upstream":"github.com/yizhiyanhua-ai/fireworks-tech-graph","upstream_sha":"7b22cdd","imported_at":"2026-04-28"}
Tech Graph
Generate production-quality SVG technical diagrams exported as PNG via rsvg-convert.
Vendored from upstream fireworks-tech-graph (yizhiyanhua-ai, MIT). System dep librsvg (provides rsvg-convert) is installed via claude/skills/install.sh. Do NOT use upstream's npx skills add instructions — this skill is part of the AgentKit Engineer stack.
Vendoring Notes
This skill is vendored — installation is handled by claude/skills/install.sh (no manual npx skills add step). The required system dependency librsvg (rsvg-convert binary) is installed automatically alongside FFmpeg/ImageMagick when ck install runs. Drift from upstream is tracked in ~/claudekit/.maintainer/external-sources.json (Mode A entry) — see CLAUDE.md "External Source Drift Watcher" in the monorepo for the update procedure.
Helper Scripts (Recommended)
Four helper scripts in scripts/ directory provide stable SVG generation and validation:
Renders nodes, arrows, and legend entries from JSON input
Escapes text content to keep output XML-valid
3. validate-svg.sh - Validate SVG syntax
./scripts/validate-svg.sh <svg-file>
Checks XML syntax
Verifies tag balance
Validates marker references
Checks attribute completeness
Validates path data
4. test-all-styles.sh - Batch test all styles
./scripts/test-all-styles.sh
Tests multiple diagram sizes
Validates all generated SVGs
Generates test report
When to use scripts:
Use scripts when generating complex SVGs to avoid syntax errors
Scripts provide automatic validation and error reporting
Recommended for production diagrams
When to generate SVG directly:
Simple diagrams with few elements
Quick prototypes
When you need full control over SVG structure
Workflow (Always Follow This Order)
Classify the diagram type (see Diagram Types below)
Extract structure — identify layers, nodes, edges, flows, and semantic groups from user description
Plan layout — apply the layout rules for the diagram type
Load style reference — always load references/style-1-flat-icon.md unless user specifies another; load the matching numbered style reference for exact color tokens and SVG patterns
Map nodes to shapes — use Shape Vocabulary below
Check icon needs — load references/icons.md for known products
Write SVG with adaptive strategy (see SVG Generation Strategy below)
Validate: Run rsvg-convert file.svg -o /dev/null 2>&1 to check syntax
(Optional) Visual self-review — if your runtime can read images, load the exported PNG back and inspect it. Syntactic validity does not guarantee visual correctness: arrows may cross through component interiors, labels may collide with lifelines or other labels, boxes may overlap, alt-frame text may sit on top of a message, or a legend may cover content. If you see any of these, revise the SVG and re-export; repeat until the rendered image is clean. Common fixes:
Route arrows through gaps between boxes, not through box interiors
Full mapping of UML 14 diagram types to supported diagram types:
UML Diagram
Supported As
Notes
Class
Class Diagram
Full UML notation
Component
Architecture Diagram
Use colored fills per component type
Deployment
Architecture Diagram
Add node/instance labels
Package
Architecture Diagram
Use dashed grouping containers
Composite Structure
Architecture Diagram
Nested rects within components
Object
Class Diagram
Instance boxes with underlined name
Use Case
Use Case Diagram
Full actor/ellipse/relationship
Activity
Flowchart / Process Flow
Add fork/join bars
State Machine
State Machine Diagram
Full UML notation
Sequence
Sequence Diagram
Add alt/opt/loop frames
Communication
—
Approximate with Sequence (swap axes)
Timing
Timeline
Adapt time axis
Interaction Overview
Flowchart
Combine activity + sequence fragments
ER Diagram
ER Diagram
Chen/Crow's foot notation
Shape Vocabulary
Map semantic concepts to consistent shapes across all diagram types:
Concept
Shape
Notes
User / Human
Circle + body path
Stick figure or avatar
LLM / Model
Rounded rect with brain/spark icon or gradient fill
Use accent color
Agent / Orchestrator
Hexagon or rounded rect with double border
Signals "active controller"
Memory (short-term)
Rounded rect, dashed border
Ephemeral = dashed
Memory (long-term)
Cylinder (database shape)
Persistent = solid cylinder
Vector Store
Cylinder with grid lines inside
Add 3 horizontal lines
Graph DB
Circle cluster (3 overlapping circles)
Tool / Function
Gear-like rect or rect with wrench icon
API / Gateway
Hexagon (single border)
Queue / Stream
Horizontal tube (pipe shape)
File / Document
Folded-corner rect
Browser / UI
Rect with 3-dot titlebar
Decision
Diamond
Flowcharts only
Process / Step
Rounded rect
Standard box
External Service
Rect with cloud icon or dashed border
Data / Artifact
Parallelogram
I/O in flowcharts
Arrow Semantics
Always assign arrow meaning, not just color:
Flow Type
Color
Stroke
Dash
Meaning
Primary data flow
blue #2563eb
2px solid
none
Main request/response path
Control / trigger
orange #ea580c
1.5px solid
none
One system triggering another
Memory read
green #059669
1.5px solid
none
Retrieval from store
Memory write
green #059669
1.5px
5,3
Write/store operation
Async / event
gray #6b7280
1.5px
4,2
Non-blocking, event-driven
Embedding / transform
purple #7c3aed
1px solid
none
Data transformation
Feedback / loop
purple #7c3aed
1.5px curved
none
Iterative reasoning loop
Always include a legend when 2+ arrow types are used.
Layout Rules & Validation
Spacing:
Same-layer nodes: 80px horizontal, 120px vertical between layers
Canvas margins: 40px minimum, 60px between node edges
Snap to 8px grid: horizontal 120px intervals, vertical 120px intervals
Arrow Labels (CRITICAL):
MUST have background rect: <rect fill="canvas_bg" opacity="0.95"/> with 4px horizontal, 2px vertical padding
Place mid-arrow, ≤3 words, stagger by 15-20px when multiple arrows converge
Maintain 10px safety distance from nodes
Arrow Routing:
Prefer orthogonal (L-shaped) paths to minimize crossings
Anchor arrows on component edges, not geometric centers
Route around dense node clusters, use different y-offsets for parallel arrows
Jump-over arcs (5px radius) for unavoidable crossings
Line Overlap Prevention (CRITICAL - most common bug on Codex):
When two arrows must cross each other, ALWAYS use jump-over arcs to prevent visual overlap:
Crossing horizontal arrows: add a small semicircle arc (radius 5px, stroke same color as arrow, fill none) that "jumps over" the other line
SVG pattern for jump-over: use a white/matching-background arc on the lower layer, then draw the upper arc on top
Multiple crossings: stagger arc radii (5px, 7px, 9px) so arcs don't overlap each other
Never let two arrows' straight-line segments cross without a jump-over arc
Validation Checklist (run before finalizing):
Arrow-Component Collision: Arrows MUST NOT pass through component interiors (route around with orthogonal paths)
Text Overflow: All text MUST fit with 8px padding (estimate: text.length × 7px ≤ shape_width - 16px)
Arrow-Text Alignment: Arrow endpoints MUST connect to shape edges (not floating); all arrow labels MUST have background rects
Container Discipline: Prefer arrows entering and leaving section containers through open gaps between components, not through inner component bodies
