Use when user requests diagrams, flowcharts, sequence diagrams, class diagrams, component diagrams, ER diagrams, architecture charts, or visualizations — including generating a diagram from existing source code, or rendering/extracting PlantUML embedded in a Markdown file to images (e.g. preparing docs for Confluence/Notion). Also use proactively when explaining systems with 3+ components, APIs, data flows, or class hierarchies. Generates .puml files and exports to PNG/SVG via Kroki API (no local install required).
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use when user requests diagrams, flowcharts, sequence diagrams, class diagrams, component diagrams, ER diagrams, architecture charts, or visualizations — including generating a diagram from existing source code, or rendering/extracting PlantUML embedded in a Markdown file to images (e.g. preparing docs for Confluence/Notion). Also use proactively when explaining systems with 3+ components, APIs, data flows, or class hierarchies. Generates .puml files and exports to PNG/SVG via Kroki API (no local install required).
license
MIT
homepage
https://github.com/Agents365-ai/plantuml-skill
compatibility
Requires curl on PATH (pre-installed on macOS/Linux/Windows Git Bash). Default renderer is the public Kroki API at https://kroki.io; can also point to a local Kroki Docker instance, or fall back to a local PlantUML jar + Java + Graphviz.
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
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 ]; thenecho"Render failed — Kroki said:"cat diagram.png # the 400 body holds the offending line + reasonfi
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:
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:
Check
What to look for
Fix
Label truncation / overrun
Text clipped or spilling past a box
Shorten the label, wrap in "…", or break with \n
Component overlap / cramped
Boxes touching or crowded; unreadable
Add together { }, layout hints, or split the diagram
Wrong orientation / aspect
Diagram far too wide or too tall to read
Switch left to right direction ↔ top to bottom direction
Edge spaghetti
Many relations crossing, hard to follow
Reorder declarations, group with package/together, or add hidden edges for layout
Wrong diagram type
Type doesn't suit the content
Switch type (sequence, state, C4, …)
Low contrast
Text blends into the fill / theme
Adjust skinparam / !theme so text contrasts the fill
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:
User request
Edit action
Change a label
Edit the element / message text in the .puml
Add / remove an element or relation
Add or delete the matching line
Change a color
skinparam, !theme, or an inline #color on the element
Change layout direction
Swap left to right direction ↔ top to bottom direction
Restructure / group
Wrap related elements in a package / together { }, or regenerate
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
Type
Keyword
Use for
Sequence
@startuml + sequence syntax
API calls, protocol flows, message passing
Component
@startuml + components
service architecture, module dependencies
Class
@startuml + class syntax
OOP models, data structures
ER / Entity
@startuml + entity syntax
database schemas
Activity
@startuml + activity syntax
workflows, business processes
Use Case
@startuml + actor/usecase
system requirements, user stories
State
@startuml + state syntax
state machines, lifecycle
C4 Context
@startuml + C4 includes
high-level system context maps
Mind Map
@startmindmap
topic breakdowns, concept maps
Gantt
@startgantt
project timelines, schedules
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)
@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
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 standardplantuml 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
Quick table below; for a per-diagram-type error catalog, the Kroki safe subset, and the failure-degradation ladder, see 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 <C4/C4_Context> (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
