PUML-PlantUML Expert Skill

Deep PlantUML knowledge (all 27 chapters from official reference) + cross-platform local rendering + image→PUML reverse engineering. Offline rendering. Any OS. No assumed paths. Full Python + Java + PlantUML auto-detection and installation.

Quick Decision Tree

User request
├── "Create/draw a diagram from description"   → § Generate PUML
├── "Convert image/screenshot to PUML"         → § Image → PUML
├── "Render/preview/generate image from code"  → § Render Locally
├── "Fix/debug my PUML"                        → § Diagnose & Fix
└── "Explain syntax / how do I..."             → references/syntax-quick-ref.md

§ First Run — Bootstrap from Zero

The bootstrap scripts require no pre-installed tools — they install Python → Java → PlantUML in the correct order. Run once per machine.

macOS / Linux

bash

bash scripts/bootstrap.sh           # install everything
bash scripts/bootstrap.sh --verify  # install + test render

Windows (PowerShell — built into Windows 10/11)

powershell

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\bootstrap.ps1
.\scripts\bootstrap.ps1 -Verify

If Python is already available

bash

python3 scripts/render.py --detect      # show what's detected
python3 scripts/setup.py               # install Java + PlantUML
python3 scripts/setup.py --java        # ensure Java only
python3 scripts/setup.py --jar         # force JAR download
python3 scripts/setup.py --verify      # install + test render
python3 scripts/render.py --install-hint  # show manual steps

What gets installed:

Component	macOS	Linux	Windows
Python 3.9+	brew	apt/dnf/pacman/snap	winget/choco/scoop
Java JRE 11+	brew cask temurin	apt/dnf/pacman	winget Temurin/Zulu
PlantUML	brew	apt/dnf/pacman/snap	winget/choco/scoop
Fallback	—	`~/.plantuml/plantuml.jar`	`~/.plantuml/plantuml.jar`

Java detected from:

$JAVA_HOME

, PATH, macOS

/usr/libexec/java_home

, Azul/Zulu (

zulu*

), Temurin, Homebrew OpenJDK, SDKMAN,

/usr/lib/jvm/*

§ Generate PUML from Description

Step 1 — Identify diagram type:

Keywords in request	Type	Tag
sequence of calls, API flow, messages	Sequence	`@startuml`
classes, OOP, inheritance, methods	Class	`@startuml`
process, workflow, flowchart, steps	Activity (new)	`@startuml`
architecture, services, components	Component	`@startuml`
database, schema, tables, entities	ER	`@startuml`
states, lifecycle, status transitions	State	`@startuml`
use cases, actors, user stories	Use Case	`@startuml`
objects, instances, runtime snapshot	Object	`@startuml`
timing, signals, waveforms	Timing	`@startuml`
brainstorm, concept map, topics	MindMap	`@startmindmap`
project timeline, schedule, milestones	Gantt	`@startgantt`
work breakdown, project phases	WBS	`@startwbs`
UI form, wireframe, mockup	Salt	`@startsalt`
JSON data structure	JSON	`@startjson`
YAML data structure	YAML	`@startyaml`
network topology, servers, subnets	nwdiag	`@startuml` + `nwdiag {}`
enterprise architecture, ArchiMate	Archimate	`@startuml` + `archimate` kw
math formula, equation, LaTeX	Maths	`@startmath` / `@startlatex`
ASCII art diagram	Ditaa	`@startditaa`

Step 2 — Generate using the full syntax in

references/syntax-quick-ref.md

. Always include: a

title

line,

skinparam shadowing false

, labels on all arrows.

Step 3 — Write, validate & render:

bash

cat > /tmp/diagram.puml << 'PUML'
@startuml
title My Diagram
... generated code ...
@enduml
PUML

python3 scripts/render.py /tmp/diagram.puml --check   # validate
python3 scripts/render.py /tmp/diagram.puml -f svg -o /tmp/  # render

§ Image → PUML (Reverse Engineering)

View the image — use the
```
view
```
tool or examine the upload
Identify the diagram type —
```
references/image-to-puml.md
```
Extract elements — names, labels, arrows, relationships, cardinality
Generate PUML — reproduce faithfully, correct arrow types
Validate & render — compare against original; refine if needed

Visual analysis guide:
references/image-to-puml.md

§ Render Locally

Use

scripts/render.py

— auto-detects binary vs JAR+Java, any OS.

bash

# macOS / Linux
python3 scripts/render.py diagram.puml                        # PNG
python3 scripts/render.py diagram.puml -f svg -o ./output/   # SVG
python3 scripts/render.py diagram.puml -f pdf -o ./output/   # PDF
cat diagram.puml | python3 scripts/render.py --stdin -f svg -n "name" -o /tmp/

# Windows
py scripts\render.py diagram.puml
py scripts\render.py diagram.puml -f svg -o .\output\

Direct CLI (if

plantuml

is in PATH):

bash

plantuml -tsvg diagram.puml
plantuml -tpng -o ./output/ *.puml
plantuml -checkonly diagram.puml

Present the output file to the user after rendering using

present_files

Full options, env vars, formats, troubleshooting:
references/local-rendering.md

§ Diagnose & Fix PUML

bash

python3 scripts/render.py diagram.puml --check

Error	Cause	Fix
`No @startuml found`	Missing wrapper	Add `@startuml` / `@enduml`
`Unknown command`	Typo or wrong diagram type	Check syntax-quick-ref.md
Arrow `→` (Unicode)	ASCII required	Use `->` not `→`
`Cannot find class`	Forward reference	Declare before use
Graphviz error	`dot` not installed	`brew/apt install graphviz` OR add `!pragma layout smetana`
PlantUML not found	Not installed	`bash scripts/bootstrap.sh`
Java not detected	Non-standard JDK	Set `JAVA_HOME` env var
Python not found	Python missing	`bash scripts/bootstrap.sh`
Unicode broken	Charset issue	`plantuml -charset UTF-8 file.puml`

§ Syntax Cheatsheet (Ultra-Quick)

Full reference (all 27 chapters, 2700+ lines):
references/syntax-quick-ref.md

Sequence arrows:

->   sync          -->  response/dashed
->>  thin           -->> thin dashed
->x  lost           ->o  open arrowhead
<->  bidirectional  ->+  activate   -->-  deactivate
[->  incoming      ->]   outgoing

Class relationships:

<|--  inheritance    <|..  realization
o--   aggregation    *--   composition
-->   dependency     ..>   usage
--    association    --()  lollipop (provided interface)
"1" *-- "0..*"  : label  (with cardinality and label)

ER cardinality (crow's foot):

||   exactly one    o|   zero or one
o{   zero or more   |{   one or more

All @start tags:

@startuml          most diagrams
@startmindmap      mind maps
@startgantt        gantt charts
@startwbs          work breakdown
@startsalt         wireframes
@startjson         JSON display
@startyaml         YAML display
@startmath         AsciiMath
@startlatex        LaTeX formula
@startditaa        Ditaa ASCII art

Universal formatting:

plantuml

title My Title
skinparam shadowing false
skinparam monochrome true
!theme cerulean
left to right direction
!pragma layout smetana    ' no Graphviz needed

Complete Diagram Coverage (All 27 Chapters from PDF)

Ch	Type	Notes
1	Sequence	Full: arrows, groups, activation, notes, autonumber, mainframe, parallel, stereotypes/spots, anchors, encompass, hide footbox
2	Use Case	Full: actors, extends/include, notes, packages, business UC, JSON overlay
3	Class	Full: visibility, stereotypes, spots, generics, lollipop, extends/implements keywords, hide/show/remove, $tags, namespaces
4	Object	Instances, relations, maps, association objects
5	Activity (Legacy)	Old `(*) -->` syntax, branches, synchronization bars, partitions
6	Activity (New)	start/stop, if/else/elseif, switch/case, while, repeat, fork, split, swimlanes, SDL shapes, goto/label, connectors, condition style
7	Component	Components, interfaces, ball-socket, grouping, ports, hide unlinked
8	Deployment	All element types, nesting, ports, round corners, orientation
9	State	Nested, concurrent, fork/join, history, choice, pin, expansion, note on link, inline colour
10	Timing	robust, concise, binary, clock, analog; relative time, anchors, highlights
11	JSON	Display, highlight, styles, minimal examples
12	YAML	Display, highlight, aliases, Creole
13	Network (nwdiag)	Networks, nodes, addresses, grouping, sprites, peer networks
14	Wireframe (Salt)	All widgets: button, input, dropdown, radio, checkbox, grid, tree, tabs, group box, scrollbox
15	Archimate	archimate keyword, junctions, macros, StdLib integration
16	Gantt	Tasks, constraints, milestones, colours, completion %, hyperlinks, closed days, zoom, scale
17	MindMap	OrgMode and Markdown syntax, left branches, multiroot, colours, direction
18	WBS	OrgMode syntax, direction, colours, arrows, word wrap
19	Maths	AsciiMath ( `@startmath` ), LaTeX/JLaTeXMath ( `@startlatex` ), inline `<math>` tags
20	ER (Info Engineering)	Entities, attributes, PK/FK markers, crow's foot relations
21	Common Commands	comments, scale/zoom, title, caption, header, footer, legend, newpage, mainframe, appendix, pragma
22	Creole	Bold, italic, mono, strike, underline, wave; lists, headings, tables, links, emoji, HTML tags, Unicode
23	Sprites	Define hex sprites, inline SVG sprites, import from StdLib, OpenIconic, Font Awesome
24	Skinparam	Full per-element skinparam + modern `<style>` CSS-like alternative + all themes
25	Preprocessing	Variables, conditions, while/loop, procedures, functions, default args, unquoted, keyword args, includes, subparts, themes, define, builtins ( `%string` , `%strlen` , `%date` , `%random` , `%hsl_color` , etc.)
26	Unicode	Native UTF-8, `&#XXXX;` and `<U+XXXX>` references, emoji `<:name:>` , charset flag
27	StdLib	ArchiMate, AWS, Azure, C4, Kubernetes, Elastic, GCP, CloudOgu, Tupadr3/FontAwesome, EDGY
—	Ditaa	`@startditaa` ASCII art to diagram

Reference Files

File	Content
`references/syntax-quick-ref.md`	2700+ lines — complete syntax for all 27 chapters
`references/image-to-puml.md`	Visual analysis guide for image→PUML reverse engineering
`references/local-rendering.md`	Setup, CLI flags, formats, env vars, troubleshooting

Scripts

Script	Purpose
`scripts/bootstrap.sh`	Start here — macOS/Linux — installs Python→Java→PlantUML (no deps)
`scripts/bootstrap.ps1`	Start here — Windows — PowerShell 5+, no deps required
`scripts/setup.py`	Python setup: detect/install Java + PlantUML; also reports Python
`scripts/render.py`	Cross-platform render: auto-detects Python/binary/JAR/Java

puml-plantuml

NPX Install

Tags

SKILL.md Content

PUML-PlantUML Expert Skill

Quick Decision Tree

§ First Run — Bootstrap from Zero

macOS / Linux

Windows (PowerShell — built into Windows 10/11)

If Python is already available

§ Generate PUML from Description

§ Image → PUML (Reverse Engineering)

§ Render Locally

§ Diagnose & Fix PUML

§ Syntax Cheatsheet (Ultra-Quick)

Complete Diagram Coverage (All 27 Chapters from PDF)

Reference Files

Scripts