Plantuml Skill

PlantUML Diagram Skill

Overview

Generate .puml PlantUML diagram files and export to PNG/SVG using Kroki — a cloud rendering API that requires no local installation beyond curl.

Format: .puml (PlantUML text) Renderer: Kroki API (https://kroki.io) — just curl, no Java needed Output: PNG, SVG Diagram types: sequence, component, class, ER, activity, use case, state, C4, and more

When to Use

Explicit triggers:

• "plantuml diagram", "sequence diagram", "class diagram", "component diagram"
• "UML", "activity diagram", "use case diagram", "state machine"
• "visualize", "draw", "diagram", "flowchart", "architecture chart"

Proactive triggers:

• Explaining a system with 3+ interacting components
• Describing API flows, authentication sequences, message passing
• Showing class hierarchies, database schemas, or ER models
• Illustrating state machines or lifecycle flows

When NOT to use it — route elsewhere:

• General, non-UML quick diagrams embedded in Markdown → mermaid.
• Freeform, heavily-styled, or branded diagrams needing pixel control → drawio.
• A hand-drawn / sketchy look → excalidraw or tldraw.

Modes

Once triggered, route by what the user actually wants — then run the shared render loop (Steps 4–8):

Prerequisites

Option A: Kroki API (recommended — no install)

# Just needs curl (pre-installed on macOS/Linux/Windows Git Bash)
curl --version

Option B: Local Kroki via Docker (for offline use)

docker run -d -p 8000:8000 yuzutech/kroki
# Then replace https://kroki.io with http://localhost:8000 in commands

Option C: Local PlantUML jar (traditional)

# Requires Java + Graphviz
brew install graphviz   # macOS
sudo apt install graphviz  # Ubuntu
# Download plantuml.jar from https://plantuml.com/download
java -jar plantuml.jar diagram.puml

Workflow

Step 1: Check Dependencies

curl --version

curl is available on all modern systems. If missing, install via package manager.

Step 2: Pick Diagram Type

Choose the most appropriate PlantUML diagram type (see reference below).

Step 3: Generate .puml File

Write the PlantUML source file with @startuml / @enduml markers.

Step 4: Export via Kroki (capture the HTTP status)

Pick the backend first. The default below (public Kroki) uploads the `.puml` source to kroki.io — for sensitive diagrams use a local backend instead, and never silently fall back. See `references/rendering-backends.md`. For local Kroki, swap https://kroki.io → http://localhost:8000.

# PNG (recommended) — keep the status code so Step 5 can verify it
http=$(curl -s -w "%{http_code}" -o diagram.png \
  -X POST https://kroki.io/plantuml/png \
  -H "Content-Type: text/plain" \
  --data-binary "@diagram.puml")
echo "HTTP $http"

# SVG
http=$(curl -s -w "%{http_code}" -o diagram.svg \
  -X POST https://kroki.io/plantuml/svg \
  -H "Content-Type: text/plain" \
  --data-binary "@diagram.puml")
echo "HTTP $http"

Step 5: Validate & self-correct (loop — do NOT skip)

Never report success on a blind curl. Verify the output first; treat the export as failed if any of these hold:

• $http is not 200. Kroki returns 400 on a syntax error and writes the error text into the output file, so a .png can exist yet be broken.
• The file is empty: [ -s diagram.png ] fails.
• The bytes aren't a real image: file diagram.png should report PNG image data; for SVG the file should start with <svg or <?xml.

if [ "$http" != "200" ] || [ ! -s diagram.png ]; then
  echo "Render failed — Kroki said:"
  cat diagram.png    # the 400 body holds the offending line + reason
fi

On failure: cat the output file to read Kroki's error, fix the flagged .puml line (see Common Mistakes), then re-run Step 4. Repeat up to 3 times. If a targeted line fix doesn't clear it, degrade in this order, re-rendering after each step — stop as soon as it renders:

1. remove exotic shapes → plain rectangle/component/node
2. strip skinparam / !theme (render plain first)
3. remove note lines
4. simplify labels, wrap in "…"
5. reduce edges
6. switch to a simpler diagram type rather than forcing the current one

For a per-diagram-type error catalog and the Kroki safe subset, read `references/kroki-troubleshooting.md`. If it still fails after 3 tries, stop and show the user the raw Kroki error — do not claim the diagram was produced.

Step 6: Self-check (vision)

The Step 5 loop only proves Kroki returned a valid image — not that the diagram is readable. After it renders, use the agent's vision capability to read the PNG and catch what auto-layout (Graphviz) can't prevent. PlantUML positions everything itself, so the failures here are about readability, not your coordinates:

• Max 2 self-check rounds — if issues remain after 2 fixes, show the user anyway.
• Re-render (Step 4) and re-validate (Step 5) after every fix.
• If vision is unavailable, skip self-check and show the PNG directly.

Step 7: Review loop

After self-check, show the exported image and collect feedback. Apply the minimal `.puml` edit for each request, then re-render and re-validate:

• Overwrite the same diagram.puml / output file each round — don't create v1, v2, …
• Safety valve: after 5 rounds, suggest the user fine-tune the .puml directly or at plantuml.com.

Step 8: Report to User

Only after Steps 5–7 pass. Tell the user:

• Path to the .puml source file
• Path to the exported PNG/SVG
• Brief description of what was generated
• Which backend rendered it, and whether the source left the machine — e.g. "via public Kroki (uploaded to kroki.io)" vs "via local Kroki (stayed local)"

Import Workflows

Two non-default modes — load the linked playbook when triggered, then run the same Step 4–8 loop: