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

| Mode | The user wants… | Entry point | |---|---|---| | Generate (default) | a diagram from a text description | Steps 1–8 below | | From code | a diagram of existing source code | [references/from-source-code.md](references/from-source-code.md) → Steps 4–8 | | Embed | the PlantUML inside a Markdown doc rendered to images | [references/markdown-embed.md](references/markdown-embed.md) | | Refine | to change an existing diagram | load its .puml, apply the minimal edit (Step 7), re-render (Steps 4–6) | | Review | to know whether an existing diagram is readable / correct | run the Step 6 vision self-check on the image |

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](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 ` 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

```plantuml
@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 >
  --
  name : varchar
  email : varchar
  created_at : datetime
}

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

entity "PRODUCT" as prod {
  * id : int >
  --
  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 , 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 

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: ` (Container, ContainerDb), (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 ` 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](references/kroki-troubleshooting.md).

| Mistake | Fix | |---------|-----| | curl POST returns HTML error page | Check network; try curl -v to see error details | | Kroki returns 400 Bad Request | cat the output file — Kroki wrote the offending line + reason there; fix it and re-render via the Step 5 loop. Validate syntax at https://www.plantuml.com/plantuml/uml/ | | Arrow direction unexpected | Use --> for downward/right; explicitly use -up->, -down->, -left->, -right-> | | Diagram too large/crowded | Split into multiple diagrams or use package/rectangle grouping | | Missing @startuml / @enduml | Always wrap diagram in these markers | | Special chars in labels | Wrap in quotes: "Label: value" | | C4 includes not found | Use the bundled !include (resolved on the standard plantuml endpoint and c4plantuml); never a remote !includeurl https://… — Kroki cannot fetch external URLs | | Component overlap | Use together { } or explicit layout hints (top to bottom direction) | | Sequence participants out of order | Declare participant explicitly at top in desired left-to-right order |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Agents365-ai
• Source: Agents365-ai/plantuml-skill
• License: MIT
• Homepage: https://agents365-ai.github.io/plantuml-skill/

Install and usage instructions live in the source repository linked above.