| name | plantuml-diagrams |
| description | Model, create, update, and embed PlantUML diagrams (.wsd files). Use for: component diagram, sequence diagram, class diagram, state diagram, activity diagram, deployment diagram, mindmap, ER diagram. Covers diagram type selection, PlantUML syntax, .wsd file conventions, and embedding via PlantUML proxy in Markdown docs. |
| argument-hint | Describe the system, flow, or relationship you want to diagram |
PlantUML Diagram Modeling
When to Use
Load this skill when asked to:
- Create or update a PlantUML diagram (component, sequence, class, state, activity, deployment, mindmap)
- Add a new
.wsd file under doc/*/uml/
- Embed a diagram image in a Markdown file via the PlantUML proxy URL
- Convert a Mermaid or other diagram to PlantUML
- Explain a system architecture, data flow, or state machine visually
Project Conventions
This project stores PlantUML source in .wsd files and renders them in .svg format via plantuml2svg.bat. The .wsd files are located in doc/architecture/uml/ for architecture diagrams and doc/config/uml/ for configuration diagrams. Each file should start with @startuml <diagram-name> and end with @enduml.:
- Architecture diagrams:
doc/architecture/uml/
- Config diagrams:
doc/config/uml/
- Start every file with
@startuml <diagram-name> and end with @enduml
Procedure
1. Understand the Subject
- Ask (or infer from context) what system, flow, or relationship needs to be visualized.
- Identify the grain: high-level context, internal component structure, inter-object sequence, or state machine?
2. Select the Diagram Type
Use diagram-types.md for syntax details. Quick selection guide:
| Goal | Diagram Type |
|---|
| Show hardware/software component structure | component |
| Show interactions over time between objects | sequence |
| Show class relationships and inheritance | class |
| Show system states and transitions | state |
| Show a process, algorithm, or decision flow | activity |
| Show deployment on hardware / tasks | deployment |
| Show topic/concept hierarchy | mindmap |
| Show database table relationships | entity (ER) |
3. Create or Update the .wsd File
New diagram — create doc/<area>/uml/<diagram-name>.wsd:
@startuml <diagram-name>
title <Human Readable Title>
' ---------------------------------------------------------------------------
' Put diagram contents here
' ---------------------------------------------------------------------------
@enduml
Existing diagram — read the current file first, then apply the minimum necessary changes.
Style rules:
- Use
' for single-line comments, /' ... '/ for block comments.
- Keep element labels short; use
as aliases for long names: component "My Long Name" as myComp.
- Group related elements in
package or namespace blocks.
- Limit a single diagram to ~25 elements; split into sub-diagrams when larger.
- Apply
skinparam at the top of the file to match project style when touching existing diagrams.
4. Embed the Diagram in Markdown
Add the proxy image reference in the relevant .md file:
Use the master branch URL for diagrams intended for the default branch; use Development for work-in-progress.
5. Validate Locally (Optional)
If the PlantUML VSCode extension is available, open the .wsd file and use Preview Current Diagram (Alt+D) to verify the output before committing.
Alternatively, paste the source into the PlantUML online server for a quick render check.
6. Finalize
- Confirm the
.wsd filename uses snake_case consistent with neighboring files.
- Verify the proxy URL in the Markdown points to the correct branch and file path.
- Add or update any surrounding prose in the Markdown to reference the new diagram.
Quality Checklist
References
