PlantUML

SKILL.md

---
name: plantuml
description: Generate UML diagrams (use case, class, sequence, activity, state, component, deployment, object, timing, and more) using PlantUML. Use when the user asks to draw, create, or generate any UML diagram, or mentions PlantUML, UML, use case diagram, class diagram, sequence diagram, activity diagram, state diagram, or any structural/behavioral diagram.
---

# PlantUML Diagram Generation

## One-Liner

```bash
java -jar ~/tools/plantuml.jar -tpng -charset UTF-8 file.puml
```

## Prerequisites

- **PlantUML jar:** `~/tools/plantuml.jar`
- **Graphviz:** Required for most diagram types. Verify with `dot -V`.
- **Java:** Required runtime. Verify with `java -version`.

If Graphviz is missing, sequence diagrams still render (they use the built-in lambda renderer), but other diagram types will fail.

## Quick Start

1. Write `.puml` source file
2. Generate image: `java -jar ~/tools/plantuml.jar -tpng -charset UTF-8 <file>.puml`
3. PlantUML uses the word after `@startuml` as the output filename (e.g., `@startuml MyDiagram` → `MyDiagram.png`)
4. Copy to outbound media dir and send via `message` tool — OpenClaw will handle path resolution automatically

## Diagram Types & Syntax

See [references/syntax-guide.md](references/syntax-guide.md) for detailed syntax per diagram type.

### Use Case Diagram

```plantuml
@startuml DiagramName
left to right direction
skinparam packageStyle rectangle
skinparam actorStyle awesome

actor User
actor Admin

rectangle "System Name" {
  usecase "Login" as UC1
  usecase "Do Something" as UC2
}

User --> UC1
User --> UC2
UC2 .> UC1 : <<include>>
@enduml
```

### Class Diagram

```plantuml
@startuml DiagramName
skinparam classAttributeIconSize 0

abstract class Shape {
  + draw(): void
}
class Circle {
  - radius: double
}
Shape <|-- Circle

Circle "1" --> "0..*" Point : contains >
@enduml
```

### Sequence Diagram

```plantuml
@startuml DiagramName
actor User
participant ":System" as SYS

User -> SYS : request()
activate SYS
SYS --> User : response()
deactivate SYS

alt success
  SYS --> User : ok
else failure
  SYS --> User : error
end
@enduml
```

### Activity Diagram

```plantuml
@startuml DiagramName
start
:Step 1;
if (Condition?) then (yes)
  :Step 2a;
else (no)
  :Step 2b;
endif
stop
@enduml
```

### State Diagram

```plantuml
@startuml DiagramName
[*] --> Idle
Idle --> Processing : start
Processing --> Done : complete
Processing --> Error : fail
Done --> [*]
Error --> [*]
@enduml
```

### Component Diagram

```plantuml
@startuml DiagramName
component [Web App] as WA
component [API Server] as API
interface "REST API" as REST

WA -right- REST
REST -right- API
@enduml
```

### Deployment Diagram

```plantuml
@startuml DiagramName
node "Web Server" as WS {
  component [Web App] as WA
}
node "DB Server" as DB {
  database [Database] as D
}
WA ..> D : JDBC
@enduml
```

## Key Conventions

- **File naming:** Use kebab-case for `.puml` filenames (e.g., `order-system-class.puml`).
- **Diagram label:** Always name `@startuml <PascalCaseName>` — this becomes the output filename.
- **Charset:** Always pass `-charset UTF-8` for CJK content.
- **Format:** Default to `-tpng`. Use `-tsvg` for vector output when needed.
- **Batch:** Pass multiple `.puml` files in one command for efficiency.
- **Output directory:** Default is same directory as source. Use `-o <dir>` to specify a different output directory.

## Rendering & Delivery Workflow

1. Write `.puml` to workspace
2. Run: `java -jar ~/tools/plantuml.jar -tpng -charset UTF-8 <file>.puml`
3. Verify output exists and has nonzero size
4. Copy PNG to `~/.openclaw/media/outbound/` (create if needed)
5. Send via `message` tool with `media` parameter — OpenClaw handles path resolution automatically

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `Cannot run program "dot"` | Graphviz not installed. Sequence diagrams still work; others need `apt install graphviz`. |
| Empty output file (0 bytes) | Likely a syntax error. Run with `-v` flag to see detailed error output. |
| Smetana `UnsupportedOperationException` | Avoid `-Playout=smetana`; use Graphviz instead. |
| CJK garbled text | Ensure `-charset UTF-8` flag is set and source file is UTF-8. |
| Image too large/small | Add `-DPLANTUML_LIMIT_SIZE=16384` before the jar, or resize in the puml with `skinparam dpi`. |

## Advanced: Output Size Control

```bash
# Increase max image size (default 4096)
java -DPLANTUML_LIMIT_SIZE=16384 -jar ~/tools/plantuml.jar -tpng -charset UTF-8 file.puml
```

Within the diagram:
```plantuml
skinparam dpi 150
```