PlantUML Diagrams
Produce structurally valid PlantUML with explicit semantics and readable layout.
Routing
- Choose PlantUML for UML, C4, enterprise architecture, or
.pumloutput. - Choose
../mermaid/SKILL.mdfor lightweight diagrams embedded directly in Markdown. - Choose
../processon-diagram-generator/SKILL.mdwhen hosted editing or ProcessOn output is explicitly required. - Do not ask the user to choose a renderer when the requested notation or target format already determines it.
Workflow
- Extract actors, components, types, states, messages, or deployment nodes from the request and source.
- Select the diagram family and intended abstraction level.
- Generate a complete source block with matching start/end directives.
- Use aliases for long names and packages/boundaries for meaningful grouping.
- Validate with a local PlantUML renderer when available; otherwise perform structural checks.
- Save a
.pumlfile only when requested or when integrating into an existing documentation tree.
Diagram selection
| Need | Primary syntax |
|---|---|
| Runtime interaction | sequence, participant, actor |
| Static type model | class, interface, relationships |
| Logical architecture | component, package, interface |
| Runtime topology | node, cloud, database, artifact |
| Lifecycle | state, [*] |
| Workflow | start, if, while, fork, stop |
| User goals | actor, usecase |
| C4 model | C4 include plus Person, System, Container, Component |
Load only the matching file under examples/ when syntax details are needed.
Authoring rules
- Wrap standard UML diagrams in
@startumland@enduml. - Define aliases once and reuse them consistently.
- Label relationships with purpose or protocol when it improves understanding.
- Separate logical architecture from deployment topology when one diagram becomes crowded.
- Keep C4 levels distinct; do not mix context, container, and component detail without an explicit reason.
- Avoid remote
!includedependencies unless the user accepts network-dependent rendering. - Do not invent components, protocols, multiplicities, or calls that are unsupported by evidence.
Output
Inline delivery:
```plantuml
@startuml
actor User
participant API
database DB
User -> API: Submit request
API -> DB: Persist data
DB --> API: Result
API --> User: Response
@enduml
```
File delivery: prefer docs/diagrams/<descriptive-name>.puml unless the repository defines another convention. Never overwrite silently.
Validation checklist
- Start/end directives match.
- Aliases and referenced elements are defined.
- Relationship direction and multiplicity are intentional.
- C4 includes are available in the target rendering environment.
- No secrets or machine-specific paths appear in source.
- Local rendering succeeds when a renderer is available.
