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:

• Generate a diagram from existing source code — class diagram of a module, sequence from a request handler, component map of a repo, ER from ORM models. Read the code, extract the real entities/relationships, draw only what's there. → `references/from-source-code.md`
• Render PlantUML embedded in Markdown — extract `plantuml / `puml blocks (and linked .puml), render each to an image, and rewrite the Markdown with image links (e.g. to publish to Confluence / Notion, which don't render fenced PlantUML). → `references/markdown-embed.md`

---

Diagram Types

---

Syntax Reference

Component / Architecture Diagram

@startuml
!theme plain

title Microservices Architecture

actor "Client" as client
rectangle "API Gateway" as gateway #LightBlue

rectangle "Services" {
  component "User Service" as user
  component "Order Service" as order
}

database "User DB" as userdb
database "Order DB" as orderdb
queue "Kafka" as kafka

client --> gateway
gateway --> user
gateway --> order
user --> userdb
order --> orderdb
order --> kafka : events

@enduml

Shape types:

• actor "Name" as id — stick figure (user, external actor)
• component "Name" as id — component box with [brackets]
• rectangle "Name" as id — plain rectangle (for groups/layers)
• database "Name" as id — cylinder (database)
• queue "Name" as id — queue symbol
• cloud "Name" as id — cloud shape (external services)
• node "Name" as id — server/node box
• frame "Name" as id — frame grouping
• package "Name" { } — package grouping

Arrows:

• A --> B — solid arrow
• A -> B — thin arrow
• A ..> B — dashed arrow
• A --> B : label — labeled arrow
• A <--> B — bidirectional

Colors:

• #LightBlue, #LightGreen, #LightYellow, #Pink, #Violet
• #AED6F1 (blue), #A9DFBF (green), #FAD7A0 (orange), #F1948A (red)
• #D7BDE2 (purple), #F9E79F (yellow), #D3D3D3 (grey)

---

Sequence Diagram

@startuml
!theme plain
title Login Flow

participant "Client" as C
participant "API Gateway" as G
participant "Auth Service" as A
database "User DB" as D

C -> G : POST /login
G -> A : validateCredentials(user, pass)
A -> D : SELECT * FROM users WHERE email = ?
D --> A : user record
A --> G : 200 OK + JWT token
G --> C : { token: "..." }

@enduml

Arrow types:

• A -> B — synchronous call
• A --> B — return / dashed
• A ->> B — async message
• A -[#red]-> B — colored arrow
• activate A / deactivate A — show activation box

---

Class Diagram

@startuml
!theme plain

class User {
  +int id
  +String name
  +String email
  +login() : bool
  +logout()
}

class Order {
  +int id
  +Date createdAt
  +float total
  +place()
  +cancel()
}

class Product {
  +int id
  +String name
  +float price
}

User "1" --> "*" Order : places
Order "*" --> "*" Product : contains

@enduml

Relationships:

• A --> B — association
• A --|> B — inheritance
• A ..|> B — implements interface
• A *-- B — composition
• A o-- B — aggregation
• A "1" --> "*" B : label — with multiplicities

---

ER Diagram

@startuml
!theme plain

entity "USER" as user {
  * id : int <<PK>>
  --
  name : varchar
  email : varchar
  created_at : datetime
}

entity "ORDER" as ord {
  * id : int <<PK>>
  --
  * user_id : int <<FK>>
  total : decimal
  status : varchar
}

entity "PRODUCT" as prod {
  * id : int <<PK>>
  --
  name : varchar
  price : decimal
}

user ||--o{ ord : places
ord }o--|{ prod : contains

@enduml

---

Activity / Flowchart

@startuml
!theme plain

start

:Receive Order;

if (Payment valid?) then (yes)
  :Process Payment;
  :Send Confirmation Email;
  :Update Inventory;
  :Ship Order;
  :Mark as Delivered;
else (no)
  :Send Payment Failed Email;
  :Cancel Order;
endif

stop

@enduml

---

State Diagram

@startuml
!theme plain

[*] --> Pending

Pending --> Processing : payment_received
Processing --> Shipped : packed
Shipped --> Delivered : confirmed
Processing --> Cancelled : cancel
Pending --> Cancelled : cancel

Delivered --> [*]
Cancelled --> [*]

@enduml

---

C4 Context Diagram

C4 uses the bundled C4-PlantUML standard library via !include <C4/...>, which Kroki and recent local jars resolve with no network fetch. Export with the standard plantuml endpoint (the c4plantuml Kroki type also works).

@startuml
!include <C4/C4_Context>

title System Context — Internet Banking

Person(customer, "Banking Customer", "A customer of the bank")
System(banking, "Internet Banking System", "Lets customers view their accounts")
System_Ext(mail, "E-mail System", "The internal Microsoft Exchange system")

Rel(customer, banking, "Uses", "HTTPS")
Rel(banking, mail, "Sends e-mail via", "SMTP")
@enduml

Other levels: <C4/C4_Container> (Container, ContainerDb), <C4/C4_Component> (Component). Common macros: Person, System, System_Ext, Container, Rel, Boundary. Do not use a remote !includeurl https://… — Kroki cannot fetch external URLs; always use the bundled <C4/…> form.

---

Export Commands

Quick reference for the renderer variants. The Kroki ones drop the status capture for brevity — when actually exporting, use the Step 4 form and run the Step 5 validation loop.

# PNG via Kroki API (recommended)
curl -s -X POST https://kroki.io/plantuml/png \
  -H "Content-Type: text/plain" \
  --data-binary "@diagram.puml" \
  -o diagram.png

# SVG via Kroki API
curl -s -X POST https://kroki.io/plantuml/svg \
  -H "Content-Type: text/plain" \
  --data-binary "@diagram.puml" \
  -o diagram.svg

# Via local Kroki Docker (offline)
curl -s -X POST http://localhost:8000/plantuml/png \
  -H "Content-Type: text/plain" \
  --data-binary "@diagram.puml" \
  -o diagram.png

# Via local PlantUML jar (if installed)
java -jar plantuml.jar diagram.puml
# Output: diagram.png in same directory

---

Themes

!theme plain       ← clean, minimal (recommended)
!theme cerulean    ← blue-tinted
!theme blueprint   ← dark blue background
!theme aws-orange  ← AWS style
!theme vibrant     ← vivid colors

Or use skinparam for custom styling:

skinparam backgroundColor #FAFAFA
skinparam componentBorderColor #555555
skinparam ArrowColor #333333
skinparam FontName Arial

---

Common Mistakes

Quick table below; for a per-diagram-type error catalog, the Kroki safe subset, and the failure-degradation ladder, see `references/kroki-troubleshooting.md`.

Generating Diagrams from Existing Source Code

Use when the user points at real code and asks for a diagram of it — "class diagram of this module", "sequence diagram for this request handler", "component map of the repo", "ER diagram from these models".

Core rule: read the code, don't guess. Open the files, extract the real entities and relationships, and draw only what is actually there — mark anything inferred. Then render + validate via the normal Workflow Step 4–5 loop.

Pick the diagram type from the code shape

Steps

1. Read the relevant files with the file/search tools — never infer structure from file names alone. 2. Extract entities + relationships into a short list and sanity-check it against the code before drawing. 3. Emit .puml from that list, preserving the real identifiers. Keep member signatures concise (drop method bodies). 4. Scope large inputs — one module/package per diagram. Split rather than cram (see large-diagram-patterns thinking); a 40-class god-diagram helps no one. 5. Render + validate — Workflow Step 4–5.

Example — Python classes → class diagram

class Animal:
    def speak(self): ...

class Dog(Animal):
    def fetch(self): ...

class Owner:
    def __init__(self):
        self.pets: list[Animal] = []

→

@startuml
!theme plain
abstract class Animal {
  +speak()
}
class Dog {
  +fetch()
}
class Owner {
  +pets : List<Animal>
}
Animal <|-- Dog
Owner "1" o-- "*" Animal : owns
@enduml

Kroki Troubleshooting & Safe Subset

Deep reference for the Step 5 self-check loop. Read this when a render returns 400 (or a broken file) and fixing the single flagged line did not resolve it.

Kroki renders PlantUML server-side with a recent PlantUML + Graphviz, so you do not need anything installed locally beyond curl. Two hard limits to remember:

• No network fetches. Kroki will not resolve a remote !includeurl https://….

Use the bundled !include <C4/…> standard-library form instead.

• The output file is the error channel. On a syntax error Kroki returns

HTTP 400 and writes the reason into the file you asked it to -o. Always cat that file — it names the offending line.

What renders reliably on Kroki (safe subset)

These diagram types and features are dependable through the public Kroki API:

• Sequence — including alt / opt / loop / par fragments and activate / deactivate
• Component / package, with modest skinparam styling
• Class, object, deployment, use case
• Activity (the modern start … stop syntax)
• State machines
• ER / entity
• C4 via the bundled !include <C4/C4_Context|C4_Container|C4_Component>
• Mind map, Gantt

Treat exotic shapes, heavy skinparam blocks, embedded sprites/icons, and custom fonts as optional — they are the first things to fail and the first things to drop when degrading (below).

Failure-degradation ladder

If re-rendering after a targeted line fix still returns 400 (or the layout is unusable), simplify in this order, re-running Step 4 after each step. Stop as soon as it renders:

1. Remove exotic shapes — fall back to rectangle / component / node. 2. Strip styling — delete skinparam blocks and !theme; render plain first. 3. Remove notes — note left/right/over lines are a common parse trap. 4. Simplify labels — drop special characters; wrap any remaining label in "…". 5. Reduce edges — cut redundant relationships; a smaller graph parses and lays out more reliably. 6. Switch engine — if a feature simply isn't supported, render the core idea in a simpler diagram type rather than forcing the current one.

Re-add the dropped styling only once the structure renders cleanly.

Common syntax errors by diagram type

General (any diagram)

• Missing @startuml / @enduml (or @startmindmap / @startgantt) wrapper.
• Smart quotes / non-breaking spaces / tabs pasted from a doc or chat — retype the line.
• Unbalanced { } in package / rectangle / class bodies.

Sequence

• alt / opt / loop / par / group each need a matching end.
• Reversed arrow: B <- A sends to B's left; use A -> B for left-to-right intent.
• Participants render in first-mention order — declare participant at the top to fix left-to-right order.

Class

• Relationship glyphs: <|-- inheritance, *-- composition, o-- aggregation, ..|> realization. Mixing the dashes/heads silently changes meaning.
• Multiplicities must be quoted: User "1" --> "*" Order.

Activity

• Do not mix the legacy (*) syntax with the modern start / :action; / stop syntax in one diagram.
• Every if (…) then needs endif; every repeat needs repeat while.

State

• Use [*] for the initial/final pseudo-state; [ ] or () will fail.
• Composite states need state Name { … } braces, not indentation.

ER / entity

• Crow's-foot cardinality goes between the entities: user ||--o{ order.
• Attribute block separator is -- on its own line inside the entity { } body.

Component

• Overlap/crowding is a layout symptom, not an error — add together { } or a direction hint (left to right direction) before assuming the source is wrong.

C4

• 400 with "cannot include" → you used a remote !includeurl; switch to the bundled !include <C4/C4_Context>.
• Macro arity matters: System(alias, "Label", "Description") — a missing argument throws.

Rendering PlantUML Embedded in Markdown (Extract → Render → Rewrite)

Use when a Markdown file already contains PlantUML and the user wants images instead of raw source — "render the diagrams in this README", or "prepare this doc for Confluence / Notion" (those platforms don't render fenced PlantUML).

What to find

1. Fenced blocks: `plantuml or `puml … ` 2. Linked sources: ![alt](path/to/diagram.puml)

Steps (per diagram)

1. Extract the source — the fenced body, or read the linked .puml. 2. Name it stably — slug from the nearest heading or the alt text, e.g. images/<doc>-<slug>.png. Stable names keep re-runs idempotent (no duplicate files piling up each time the doc is reprocessed). 3. Render + validate via Workflow Step 4–5, writing into the images dir. 4. Rewrite the Markdown:

• fenced block → replace with ![alt](images/<doc>-<slug>.png)
• linked .puml → repoint the link to the rendered image

5. Keep the source. Either leave the original .puml on disk, or tuck the source under a collapsed block so the diagram stays editable:

````markdown !Login flow

<details><summary>PlantUML source</summary>

   ...original source...

</details> ````

Notes

• SVG vs PNG — SVG keeps text crisp and is smaller for line diagrams; PNG

is the safest for pasting into Confluence / Notion. Pick per target.

• Report, don't silently skip — process every match and report a count

("rendered 4 of 4 diagrams"); surface any that failed Step 5 validation instead of dropping them.

Rendering Backends — Selection, Precedence & Transparency

The skill can render through three backends. They produce the same output; they differ in install cost and, crucially, where your source goes.

Selection / precedence

Decide the backend before Step 4:

1. Honor an explicit choice — if the user named a backend, or KROKI_URL is set in the environment, use it. (Swap https://kroki.io → that base URL in the Step 4 commands.) 2. Sensitive content — internal systems, secrets, proprietary names, unreleased architecture → prefer a local backend. If none is available, say so and ask before sending the source to public Kroki. 3. Otherwise → default to public Kroki (zero-install).

Use one base URL throughout a session; don't mix.

No silent downgrade

This is the rule that makes the choice trustworthy:

• Don't quietly fall back. If the chosen backend is unavailable (local Kroki

not running, no java/jar), do not silently switch to another. Tell the user which backend failed and what the alternatives are, then proceed only with a sensible default or their go-ahead.

• Report the path in Step 8. State which backend rendered and whether the

source left the machine — e.g. "rendered via public Kroki (source uploaded to kroki.io)" vs "rendered via local Kroki (stayed on your machine)." The user should never have to guess whether their diagram crossed the network.