Agent Skills
› NeverSight/learn-skills.dev
› plantuml-converter
plantuml-converter
GitHub将PlantUML (.puml)文件转换为PNG、SVG或PDF图片。支持通过配置文件或环境变量配置Java和Jar路径，自动下载兼容版本的PlantUML.jar，并提供环境检查与跨平台转换脚本。
Trigger Scenarios
convert puml
render PlantUML
puml to png
export diagram
Install
npx skills add NeverSight/learn-skills.dev --skill plantuml-converter -g -y
SKILL.md
Frontmatter
{
"name": "plantuml-converter",
"description": "Convert PlantUML (.puml) files to images (PNG\/SVG\/PDF). Supports configurable PlantUML jar and Java paths via config file (plantuml-config.json in skill directory) or environment variables (PLANTUML_LIB). No external dependencies beyond Java and PlantUML.jar. Trigger: convert puml, render PlantUML, puml to png, export diagram."
}
PlantUML Converter
Convert PlantUML (.puml) files to image formats (PNG, SVG, PDF).
When to Use
Use this skill when user requests:
- "convert puml", "render PlantUML", "generate image"
- "puml to png", "puml to svg"
- "export diagram", "render diagram"
- Any request involving converting .puml files to images
Prerequisites
- Java: JRE 8+ (JDK 11+ recommended)
- PlantUML.jar: Rendering engine (auto-download available)
Auto-Download
If plantuml.jar is not found, the init-config script will offer to download it automatically:
- Source: GitHub Releases
- Location:
<skill_dir>/lib/plantuml.jar - Size: ~8MB
Version selection based on Java:
| Java Version | PlantUML Downloaded |
|---|---|
| Java 11+ | Latest (1.2026.x) |
| Java 8 | 1.2023.12 (last Java 8 compatible) |
| Unknown | Latest |
The download uses:
- Linux/Mac:
curlorwget - Windows: PowerShell or
curl
Compatibility
Java Version Requirements
| PlantUML Version | Recommended Java |
|---|---|
| 1.2026.x (latest) | Java 11+ |
| 1.2024.x - 1.2025.x | Java 11+ |
| 1.2020.x - 1.2023.x | Java 8+ |
| 1.2019.x and earlier | Java 8+ |
Known Compatibility Issues
| Issue | Cause | Solution |
|---|---|---|
UnsupportedClassVersionError |
Java version too old for PlantUML | Upgrade Java to 8+ |
NoClassDefFoundError |
Corrupt jar or wrong Java | Re-download plantuml.jar |
| PDF generation fails | Missing Graphviz (for some diagrams) | Install Graphviz or use PNG/SVG |
| Emoji/special chars fail | Font missing in Java | Install required fonts or use -charset UTF-8 |
Version Check
The check-env script verifies:
- Java installation and version (must be 8+)
- PlantUML.jar existence
- PlantUML version (optional)
- Compatibility between Java and PlantUML
Configuration
Option 1: Config File (Recommended)
Edit plantuml-config.json in the skill directory (<skill_dir>/plantuml-config.json):
{
"plantumlJar": "C:/tools/plantuml/plantuml.jar",
"javaPath": "C:/Program Files/Java/jdk-17/bin/java.exe"
}
Option 2: Environment Variables
PLANTUML_LIB: Full path to plantuml.jarJAVA_HOME: Java installation directory
Priority
CLI arguments > Config file > Environment variables > System default java
Usage
Windows
Step 1: Initialize Config
%SKILL_DIR%\scripts\init-config.bat
Step 2: Check Environment
%SKILL_DIR%\scripts\check-env.bat
Step 3: Convert Files
REM Single file
%SKILL_DIR%\scripts\convert.bat input.puml
REM Specify format
%SKILL_DIR%\scripts\convert.bat input.puml -f svg
%SKILL_DIR%\scripts\convert.bat input.puml -f png
%SKILL_DIR%\scripts\convert.bat input.puml -f pdf
REM Specify output
%SKILL_DIR%\scripts\convert.bat input.puml -o output.png
REM Batch convert
%SKILL_DIR%\scripts\convert.bat ./diagrams/ -r
Linux/Mac
Step 1: Initialize Config
bash <skill_dir>/scripts/init-config.sh
Step 2: Check Environment
bash <skill_dir>/scripts/check-env.sh
Step 3: Convert Files
# Single file
bash <skill_dir>/scripts/convert.sh input.puml
# Specify format
bash <skill_dir>/scripts/convert.sh input.puml -f svg
bash <skill_dir>/scripts/convert.sh input.puml -f png
bash <skill_dir>/scripts/convert.sh input.puml -f pdf
# Specify output
bash <skill_dir>/scripts/convert.sh input.puml -o output.png
# Batch convert
bash <skill_dir>/scripts/convert.sh ./diagrams/ -r
Direct Command (No Script)
When paths are known, call directly:
REM Windows
java -jar C:\path\to\plantuml.jar -tpng diagram.puml
REM Linux/Mac
java -jar /path/to/plantuml.jar -tpng diagram.puml
Command Arguments
| Argument | Description | Default |
|---|---|---|
input |
.puml file or directory | Required |
-f FORMAT |
Output format: png/svg/pdf | png |
-o OUTPUT |
Output file path | Same directory, same name as input |
-t THEME |
PlantUML theme | None |
-D KEY=VALUE |
PlantUML variable | None |
-r |
Recursive directory processing | false |
--config PATH |
Config file path | <skill_dir>/plantuml-config.json |
--plantuml PATH |
plantuml.jar path | Auto-detect |
--java PATH |
java path | Auto-detect |
Default output behavior: Without -o, the output file is generated in the same directory as the input file with the same base name.
diagram.puml → diagram.png
/path/to/arch.puml → /path/to/arch.png
Character Encoding
All conversions use -charset UTF-8 automatically to handle:
- CJK characters (Chinese, Japanese, Korean)
- Emoji and special symbols
- Unicode text in diagrams
If you still see garbled text, ensure your .puml file is saved with UTF-8 encoding.
PlantUML Examples
Sequence Diagram
@startuml
title User Login Flow
actor User
participant "Frontend" as FE
participant "Backend" as BE
database "Database" as DB
User -> FE: Enter credentials
FE -> BE: POST /api/login
BE -> DB: Query user info
DB --> BE: Return user data
BE --> FE: Return JWT Token
FE --> User: Login success, redirect
@enduml
Class Diagram
@startuml
title Class Diagram Example
class User {
- id: Long
- username: String
- password: String
- email: String
+ login(): Boolean
+ register(): Boolean
+ changePassword(): void
}
class Order {
- orderNo: String
- amount: Double
- status: Enum
+ create(): void
+ cancel(): void
}
class Product {
- productId: Long
- name: String
- price: Double
- stock: Integer
}
User "1" -- "*" Order : has >
Order "*" -- "*" Product : contains >
@enduml
Activity Diagram
@startuml
title Order Processing Flow
start
:User submits order;
if (Stock available?) then (yes)
:Deduct stock;
:Create order;
if (Payment success?) then (yes)
:Ship goods;
:Complete order;
else (no)
:Cancel order;
:Restore stock;
:Notify payment failure;
endif
else (no)
:Notify out of stock;
endif
stop
@enduml
Use Case Diagram
@startuml
title E-Commerce System Use Cases
left to right direction
actor User
actor Admin
rectangle "E-Commerce System" {
usecase "Browse Products" as UC1
usecase "Search Products" as UC2
usecase "Add to Cart" as UC3
usecase "Place Order" as UC4
usecase "Payment" as UC5
usecase "View Orders" as UC6
usecase "Manage Products" as UC7
usecase "Manage Orders" as UC8
usecase "Manage Users" as UC9
}
User --> UC1
User --> UC2
User --> UC3
User --> UC4
User --> UC5
User --> UC6
Admin --> UC7
Admin --> UC8
Admin --> UC9
@enduml
Component Diagram
@startuml
title System Architecture
package "Frontend" {
[Web App] as Web
[Mobile App] as Mobile
}
package "Backend Services" {
[API Gateway] as Gateway
[User Service] as UserService
[Order Service] as OrderService
[Product Service] as ProductService
[Payment Service] as PaymentService
}
database "Database" {
[MySQL] as DB
[Redis] as Cache
}
Web --> Gateway
Mobile --> Gateway
Gateway --> UserService
Gateway --> OrderService
Gateway --> ProductService
Gateway --> PaymentService
UserService --> DB
OrderService --> DB
ProductService --> DB
PaymentService --> DB
UserService --> Cache
@enduml
State Diagram
@startuml
title Order State Transitions
[*] --> Pending: Create order
Pending --> Paid: Payment success
Pending --> Cancelled: Timeout/user cancel
Paid --> Shipping: Merchant ships
Shipping --> Delivered: User confirms receipt
Delivered --> Completed: Auto complete
Delivered --> Refunding: Request refund
Refunding --> Refunded: Refund success
Refunding --> Delivered: Cancel refund
Cancelled --> [*]
Completed --> [*]
Refunded --> [*]
@enduml
Conversion Examples
REM Windows - Basic conversion
convert.bat architecture.puml
REM Windows - SVG format
convert.bat architecture.puml -f svg
REM Windows - Custom theme
convert.bat diagram.puml -t blueprint
REM Windows - Batch convert
convert.bat ./docs/ -r -f svg
# Linux/Mac - Basic conversion
bash convert.sh architecture.puml
# Linux/Mac - SVG format
bash convert.sh architecture.puml -f svg
# Linux/Mac - Custom theme
bash convert.sh diagram.puml -t blueprint
# Linux/Mac - Batch convert
bash convert.sh ./docs/ -r -f svg
Troubleshooting
| Error | Solution |
|---|---|
java: command not found |
Install Java or configure javaPath |
plantuml.jar not found |
Configure plantumlJar or set PLANTUML_LIB |
Syntax error |
Check .puml file syntax |
Permission denied |
Check file permissions |
Script List
| Script | Windows | Linux/Mac | Description |
|---|---|---|---|
| Init config | init-config.bat |
init-config.sh |
Auto-generate config file |
| Check env | check-env.bat |
check-env.sh |
Check Java and PlantUML |
| Convert | convert.bat |
convert.sh |
Main conversion function |
Version History
- e0220ca Current 2026-07-05 21:21
