PlantUML Skill (for Codex)
Goals
- •Generate correct PlantUML.
- •For business workflows, model roles (swimlanes) × steps without breaking the flow.
- •Prefer modern styling:
!theme+<style>first; useskinparamonly when needed.
Workflow (must follow)
- •Confirm intent quickly: diagram type, purpose, roles/lanes, scope, exceptions/branches, parallelism.
- •Search official docs with
python scripts/search_docs.py "<query>".- •If docs cache is missing, fetch it first:
python scripts/fetch_docs.py(cache is local-only; not committed).
- •If docs cache is missing, fetch it first:
- •Output a complete, renderable diagram (
@startuml…@enduml) in apumlcode block. - •Sanity-check readability: avoid crossings, reduce width, consistent naming, add legend/notes if helpful.
Doc search (query examples)
- •
"Swimlanes |Swimlane| alias" - •
"partition group activity diagram beta" - •
"fork split activity diagram beta" - •
"!theme %get_all_theme" - •
"style <style> activityDiagram"
Business workflow conventions (swimlanes)
- •Use Activity Diagram (beta) for swimlanes.
- •Role = lane, step = action, decision =
if/else, retry =repeat, parallel =fork/split. - •Split large flows into phases with
partition/group.
Format / validate / render (PNG)
This skill includes a helper script that uses the official PlantUML CLI via Docker (no public server; no local Java required):
- •Recommended:
python scripts/plantuml_server.py build path/to/diagram.puml(format → validate → png) - •Individual commands:
- •
python scripts/plantuml_server.py format path/to/diagram.puml - •
python scripts/plantuml_server.py validate path/to/diagram.puml --out path/to/diagram.validation.txt - •
python scripts/plantuml_server.py render path/to/diagram.puml --format png --out path/to/diagram.png
- •
Docker image can be overridden via PLANTUML_DOCKER_IMAGE.
If your repo uses mise + uv, you can wrap these with tasks (e.g. mise run plantuml-build ...) for reproducible runs.
Output rules
- •Always output fully renderable PlantUML.
- •Add
titleandlegend/notewhen it reduces reader confusion.