name: plantuml description: Generate PlantUML diagrams from text descriptions and convert them to PNG/SVG images. Use when asked to "create a diagram", "generate PlantUML", "convert puml to image", "extract diagrams from markdown", or "prepare markdown for Confluence". Supports all PlantUML diagram types including UML (sequence, class, activity, state, component, deployment, use case, object, timing) and non-UML (ER diagrams, Gantt charts, JSON/YAML visualization, mindmaps, WBS, network diagrams, wireframes, and more).

PlantUML Diagram Generation and Conversion

Purpose
When to Use This Skill
Prerequisites
Creating Diagrams
- Diagram Type Identification
- Resilient Workflow
Converting Source Code to Diagrams
Converting Diagrams to Images
Best Practices
Troubleshooting
References

Purpose

This skill enables comprehensive PlantUML diagram creation and conversion workflows. PlantUML is a text-based diagramming tool that generates professional diagrams from simple, intuitive syntax.

Core capabilities:

Create diagrams from natural language descriptions
Convert source code to architecture diagrams (Spring Boot, FastAPI, Python ETL, Node.js, React)
Convert standalone .puml files to PNG or SVG images
Extract puml code blocks from markdown and convert to images
Process linked .puml files in markdown (![diagram](path/to/diagram.puml))
Validate PlantUML syntax without conversion
Replace markdown diagrams with image links for publication (Confluence, Notion)

When to Use This Skill

Activate for:

Diagram creation requests (e.g., "Create a sequence diagram showing authentication flow")
Code architecture visualization (e.g., "Create deployment diagram for my Spring Boot app")
.puml file to image conversion
Markdown files containing ```puml code blocks or linked .puml files
Confluence or Notion markdown preparation (documents with PlantUML diagrams require conversion first)
Specific diagram types: UML (sequence, class, activity, state, component, deployment, use case, object, timing) or non-UML (ER, Gantt, mindmap, WBS, JSON/YAML, network, Archimate, wireframes)
PlantUML syntax validation

Confluence/Notion uploads: If markdown contains PlantUML diagrams, run conversion FIRST before upload.

Prerequisites

Before creating diagrams, verify the PlantUML setup:

python scripts/check_setup.py

Required components:

Component	Purpose	Installation
Java JRE/JDK 8+	Runtime	https://www.oracle.com/java/technologies/downloads/
plantuml.jar	Diagram generator	https://plantuml.com/download (place in `~/plantuml.jar` or set `PLANTUML_JAR`)
Graphviz (optional)	Complex layouts	https://graphviz.org/download/

Creating Diagrams

Diagram Type Identification

Identify the appropriate diagram type based on user intent:

User Intent	Diagram Type	Reference
Interactions over time	Sequence	`references/sequence_diagrams.md`
System structure with classes	Class	`references/class_diagrams.md`
Workflows, decision flows	Activity	`references/activity_diagrams.md`
Object states and transitions	State	`references/state_diagrams.md`
Database schemas	ER (Entity Relationship)	`references/er_diagrams.md`
Project timelines	Gantt	`references/gantt_diagrams.md`
Idea organization	MindMap	`references/mindmap_diagrams.md`
System architecture	Component	`references/component_diagrams.md`
Actors and features	Use Case	`references/use_case_diagrams.md`
All 19 types	See navigation hub	`references/toc.md`

Syntax resources:

references/toc.md: Navigation hub linking to all diagram types
references/common_format.md: Universal elements (delimiters, metadata, comments, notes)
references/styling_guide.md: Modern <style> syntax for visual customization

Resilient Workflow (Primary - Recommended)

For reliable diagram generation with error recovery, follow the 4-step resilient workflow:

Step 1: Identify Diagram Type & Load Reference

Identify diagram type from user intent
Load references/[diagram_type]_diagrams.md for syntax guide
Consult references/toc.md if ambiguous

Step 2: Create File with Structured Naming

./diagrams/<markdown_name>_<num>_<type>_<title>.puml

Example: ./diagrams/architecture_001_sequence_user_auth.puml

Step 3: Convert with Error Handling (max 3 retries)

If conversion fails:

Check references/troubleshooting/toc.md for error classification
Load specific guide from references/troubleshooting/[category]_guide.md
Check references/common_syntax_errors.md for diagram type

Step 4: Validate & Integrate

Verify image file exists
Add image link: ![title](diagrams/filename.png)
Keep .puml source file for future edits

Full documentation: references/workflows/resilient-execution-guide.md

Quick Syntax Reference

Common elements:

Delimiters: @startuml / @enduml (required)
Comments: ' Single line or /' Multi-line '/
Relationships: -> (solid), --> (dashed), ..> (dotted)
Labels: A -> B : Label text

Minimal examples (see references/[type]_diagrams.md for comprehensive syntax):

' Sequence: references/sequence_diagrams.md
@startuml
Alice -> Bob: Request
Bob --> Alice: Response
@enduml

' Class: references/class_diagrams.md
@startuml
class Animal { +move() }
class Dog extends Animal { +bark() }
@enduml

' ER: references/er_diagrams.md
@startuml
entity User { *id: int }
entity Post { *id: int }
User ||--o{ Post
@enduml

Converting Source Code to Diagrams

The examples/ directory contains language-specific templates for converting common application architectures:

Application Type	Directory	Key Diagrams
Spring Boot	`examples/spring-boot/`	Deployment, Component, Sequence
FastAPI	`examples/fastapi/`	Deployment, Component (async routers)
Python ETL	`examples/python-etl/`	Architecture with Airflow
Node.js	`examples/nodejs-web/`	Express/Nest.js components
React	`examples/react-frontend/`	SPA deployment, component architecture

Workflow:

Identify application type
Review example in examples/[app-type]/
Map code structure to diagram patterns
Copy and adapt the example .puml file
Use Unicode symbols from references/unicode_symbols.md for semantic clarity

Converting Diagrams to Images

Convert Standalone .puml Files

# Convert to PNG (default)
python scripts/convert_puml.py diagram.puml

# Convert to SVG
python scripts/convert_puml.py diagram.puml --format svg

# Specify output directory
python scripts/convert_puml.py diagram.puml --format svg --output-dir images/

Extract and Convert from Markdown

CRITICAL for Confluence/Notion: Run this FIRST before upload if markdown contains PlantUML diagrams.

# Process embedded ```puml blocks AND linked ![](diagram.puml) files
python scripts/process_markdown_puml.py article.md

# Convert to SVG format
python scripts/process_markdown_puml.py article.md --format svg

# Validate syntax only (for CI/CD)
python scripts/process_markdown_puml.py article.md --validate

Outputs:

article_with_images.md: Markdown with image links
images/: Directory with generated images

IDE-Friendly Workflow: Keep diagrams as .puml files during development for IDE preview, then convert for publication.

Direct Command-Line Usage

# Basic conversion
java -jar ~/plantuml.jar diagram.puml

# SVG with custom output
java -jar ~/plantuml.jar --svg --output-dir out/ diagram.puml

# Batch conversion
java -jar ~/plantuml.jar "**/*.puml" --svg

See references/plantuml_reference.md for comprehensive command-line options.

Best Practices

Diagram Quality:

Use descriptive filenames from diagram content
Add comments with ' for clarity
Follow standard UML notation
Test incrementally before adding complexity

Format Selection:

PNG: Web publishing, smaller files, fixed resolution
SVG: Documentation, scalable, supports hyperlinks

Styling: Apply modern <style> syntax from references/styling_guide.md:

@startuml
<style>
classDiagram {
  class { BackgroundColor LightBlue }
}
</style>
' diagram content
@enduml

Themes: !theme cerulean (also: bluegray, plain, sketchy, amiga)

Unicode symbols: Add semantic meaning with symbols from references/unicode_symbols.md:

node "☁️ AWS Cloud" as aws
database "💾 PostgreSQL" as db

Troubleshooting

Quick diagnosis:

Check syntax: java -jar plantuml.jar --check-syntax file.puml
Identify error type
Load troubleshooting guide: references/troubleshooting/toc.md

Common issues:

Issue	Solution
"plantuml.jar not found"	Download from https://plantuml.com/download, set `PLANTUML_JAR`
"Graphviz not found"	Install from https://graphviz.org/download/
"Syntax Error"	Check delimiters match, consult `references/common_format.md`
"Java not found"	Install Java JRE/JDK 8+, verify with `java -version`

Comprehensive guides (215+ errors documented):

references/troubleshooting/toc.md - Navigation hub with error decision tree
references/troubleshooting/[category]_guide.md - 12 focused guides by error type

References

Core Syntax References

Resource	Purpose
`references/toc.md`	Navigation hub for all 19 diagram types
`references/common_format.md`	Universal elements (delimiters, metadata, comments)
`references/styling_guide.md`	Modern `<style>` syntax with CSS-like rules
`references/plantuml_reference.md`	Installation, CLI, and troubleshooting

Troubleshooting Guides

Resource	Coverage
`references/troubleshooting/toc.md`	Navigation hub with error decision tree
`references/troubleshooting/installation_setup_guide.md`	Setup problems
`references/troubleshooting/general_syntax_guide.md`	Syntax errors
`references/troubleshooting/[diagram_type]_guide.md`	Diagram-specific errors

Enrichment Resources

Resource	Purpose
`references/unicode_symbols.md`	Unicode symbols for semantic enrichment
`examples/[framework]/`	Code-to-diagram patterns

Summary

Verify setup: python scripts/check_setup.py
Navigate types: Start with references/toc.md
Learn syntax: Open references/[diagram_type]_diagrams.md
Apply styling: Use references/styling_guide.md
Add symbols: Use references/unicode_symbols.md
Convert files: scripts/convert_puml.py
Process markdown: scripts/process_markdown_puml.py
Troubleshoot: references/troubleshooting/toc.md

Supported diagrams:

UML: sequence, class, activity, state, component, deployment, use case, object, timing
Non-UML: ER, Gantt, mindmap, WBS, JSON/YAML, network, Archimate, wireframes

plantuml

SKILL.md