Umple Diagram Generator Skill

Overview

Generate an Umple .ump model from user requirements and render it to SVG via Umple + Graphviz.

Supported Diagram Types & Guidance

Diagram Type	Umple Generator	Guidance File	When to Use
State Machine	`GvStateDiagram`	`references/state-machine-guidance.md`	User requests state machine diagram
Class Diagram	`GvClassDiagram`	`references/class-diagram-guidance.md`	User requests class diagram
Unsupported	-	-	Inform user it's not yet supported

Script

Entry point: scripts/main.ts (run with Bun via npx -y bun).

Quick Start

bash

# Folder mode: organized output with all files (.ump, .gv, .svg)
npx -y bun ${SKILL_DIR}/scripts/main.ts --input model.ump --output ./diagrams --name "light-controller"

# Exact path mode: save SVG to specific file path
npx -y bun ${SKILL_DIR}/scripts/main.ts --input model.ump --output ./my-diagram.svg

# Class diagram with custom name
npx -y bun ${SKILL_DIR}/scripts/main.ts --input model.ump --output ./diagrams --name "user-system" --type class-diagram

Replace ${SKILL_DIR} with the absolute path to this skill directory.

Script Options

Option	Description
`-i, --input <path>`	Input `.ump` file (required)
`-o, --output <path>`	Output path: directory for folder mode, or `.svg` file for exact path (required)
`-n, --name <name>`	Diagram name for folder mode (optional, triggers folder mode)
`-t, --type <type>`	Diagram type: `state-machine` (default), `class-diagram`
`-s, --suboption <opt>`	GvStateDiagram suboption (repeatable)
`--json`	JSON output with details
`-h, --help`	Show help

Output Modes

Folder Mode (when --name is specified or --output is a directory):

•Creates organized folder with timestamped name
•Includes all files: .ump (source), .gv (graphviz), .svg (diagram)

Folder naming:

•With --name: <sanitized-name>_<timestamp>/
•Without --name: <diagram-type>_<timestamp>/

Example:

code

diagrams/
└── light-controller_20260121_183045/
    ├── model.ump
    ├── model.gv
    └── model.svg

Exact Path Mode (when --output ends with .svg):

•Saves only the SVG file to the exact specified path
•Useful when user specifies a specific output location

Example:

bash

npx -y bun ${SKILL_DIR}/scripts/main.ts --input model.ump --output /path/to/my-diagram.svg
# Result: /path/to/my-diagram.svg (only SVG, no folder created)

Exit Codes

Code	Meaning
0	Success
1	Missing dependencies (umple or dot)
2	Umple validation/compilation failed
3	SVG generation failed or unsupported diagram type

Pre-flight checks (must do before running Umple)

Dependencies

Dependency	Check Command	Installation	Required
Umple CLI	`command -v umple`	Download	Yes
Graphviz	`command -v dot`	`brew install graphviz`	Yes

If dependencies are missing, stop and inform the user.

Workflow (do this every time)

Step 1 — Clarify only what you must

If ambiguous, propose your plan and ask minimal clarifying questions:

Diagram Type	Key Questions
State Machine	Initial state? Events? Final states? Guards/actions?
Class Diagram	Main entities? Attributes? Relationships? Multiplicities?

Step 2 — Write the Umple model

Critical: Read the appropriate guidance file from the table above before writing code.

Step 3 — Determine output path and generate the diagram

Agent should choose the appropriate mode:

•Folder mode (recommended): Use when generating for user review/documentation
•Exact path mode: Use only when user explicitly specifies a file path

Folder mode example:

bash

tmpdir="$(mktemp -d)"
cat >"$tmpdir/model.ump" <<'EOF'
// (generated Umple goes here)
EOF

npx -y bun ${SKILL_DIR}/scripts/main.ts --input "$tmpdir/model.ump" --output <output-dir> --name "<meaningful-name>" --type [state-machine|class-diagram]

Folder naming guidelines:

•Use --name with a descriptive name derived from user requirements (e.g., "user-authentication", "order-workflow")
•If no clear name from requirements, omit --name to use auto-generated name
•The script automatically adds timestamp to prevent conflicts

Exact path mode example (when user specifies):

bash

npx -y bun ${SKILL_DIR}/scripts/main.ts --input "$tmpdir/model.ump" --output /path/specified/by/user.svg --type [state-machine|class-diagram]

Step 4 — Validate output correctness

Check exit code (see table above). If non-zero, read error output, fix Umple, and retry up to 3 times.

Repair loop (required)

On each failure:

•Identify the root cause from script output (syntax error, unknown state, missing semicolon, etc.).
•Apply a focused fix to the Umple model.
•Re-run: npx -y bun ${SKILL_DIR}/scripts/main.ts --input "$tmpdir/model.ump" --output <output-dir> --name "<name>" --type [state-machine|class-diagram]

Output contract

•Specify which diagram type was generated.
•Show the generated Umple code (single umple code block).
•Confirm the exact command you ran.
•Folder mode: Provide the output folder path and SVG file location. Exact path mode: Provide the SVG file path.

Guardrails (do not skip)

•Never invent Umple syntax: if unsure, prefer a smaller model that is valid.
•Use exact path mode only when the user explicitly provides an .svg path; otherwise use folder mode.
•If umple or dot is missing, stop and ask the user to install them (do not try to install system deps).
•Keep Umple “code” inside Umple actions/guards minimal (no secrets, no real credentials, no I/O).

Notes

•Prefer folder mode unless the user explicitly provides an .svg output path.
•Keep references one level deep (use references/* files directly from this doc).