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 scripts/bootstrap.sh           # install everything
bash scripts/bootstrap.sh --verify  # install + test render

Windows (PowerShell — built into Windows 10/11)

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

If Python is already available

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:

Java detected from: $JAVAHOME, PATH, macOS /usr/libexec/javahome, Azul/Zulu (zulu), Temurin, Homebrew OpenJDK, SDKMAN, /usr/lib/jvm/.

§ Generate PUML from Description

Step 1 — Identify diagram type:

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:

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)

1. View the image — use the view tool or examine the upload
2. Identify the diagram type — references/image-to-puml.md
3. Extract elements — names, labels, arrows, relationships, cardinality
4. Generate PUML — reproduce faithfully, correct arrow types
5. 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.

# 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):

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

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

§ 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:

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)

Reference Files

Scripts