home / skills / derklinke / codex-config / plantuml-graphs

plantuml-graphs skill

safe

This skill creates and renders PlantUML diagrams from .puml files using the CLI, validating syntax and producing PNG outputs.

npx playbooks add skill derklinke/codex-config --skill plantuml-graphs

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.5 KB

---
name: plantuml-graphs
description: Create and edit PlantUML diagrams and render them to PNG files using the PlantUML CLI. Use when users ask for UML or system diagrams in `.puml` format and want CLI-exported PNG outputs.
---

# PlantUML Graphs

Use PlantUML text files as source of truth, then render with the CLI. Prefer the bundled script for deterministic and repeatable `.puml -> .png` conversion.

## Workflow
1. Confirm diagram type and scope (sequence, class, component, activity, state, etc.).
2. Create or update a `.puml` file with `@startuml` and `@enduml`.
3. Run syntax check before rendering.
4. Render to PNG.
5. Confirm output file path(s) and report what was generated.

## Skill path (set once)
```bash
export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export PLANTUML_RENDER="$CODEX_HOME/skills/plantuml-graphs/scripts/render_plantuml.sh"
```

## Quick start
Render one file:
```bash
bash "$PLANTUML_RENDER" path/to/diagram.puml
```

Render all diagrams in a directory to one output folder:
```bash
bash "$PLANTUML_RENDER" path/to/diagrams --out-dir path/to/png
```

Syntax-only check:
```bash
bash "$PLANTUML_RENDER" path/to/diagram.puml --check-only
```

## Direct CLI fallback
```bash
plantuml -checkonly path/to/diagram.puml
plantuml -tpng path/to/diagram.puml
plantuml -tpng -output path/to/png path/to/diagrams/*.puml
```

## Minimal template
```plantuml
@startuml
Alice -> Bob: Hello
@enduml
```

## Dependencies
- `plantuml` CLI
- `dot` from Graphviz

Install on macOS if needed:
```bash
brew install plantuml graphviz
```

Overview

This skill creates and edits PlantUML diagrams and renders them to PNG files using the PlantUML CLI. It treats .puml files as the source of truth and prefers a bundled script for deterministic, repeatable .puml → .png conversion. Use it when you need consistent CLI-driven exports of UML and system diagrams.

How this skill works

I confirm the diagram type and scope (sequence, class, component, activity, state, etc.), then create or update a .puml file using @startuml ... @enduml. The workflow runs a syntax check, then invokes the PlantUML CLI (or the bundled render script) to produce PNG files. Outputs and paths are reported so you know exactly which PNGs were generated.

When to use it

When you need UML or system diagrams in .puml format.
When you want CLI-driven, repeatable rendering to PNG for CI or documentation builds.
When you maintain diagrams as source files and need deterministic outputs.
When you want to batch-render many diagrams into a single output folder.
When you need to validate PlantUML syntax before rendering.

Best practices

Keep a minimal template for quick tests (use @startuml/@enduml).
Run syntax-only checks before full renders to catch errors early (--check-only).
Store .puml files under version control and treat them as the canonical artifact.
Use the bundled render script for consistent environment variables and output paths. Export PLANTUML_RENDER once per environment.
Ensure plantuml and graphviz (dot) are installed on build agents or developer machines.

Example use cases

Create a sequence diagram for a new API interaction and export a PNG for docs.
Batch-render all architecture diagrams in a directory for a release handbook.
Validate diagrams in CI by running syntax-only checks and failing the build on errors.
Convert class and component diagrams to PNG for inclusion in Confluence or Markdown-based docs.
Update an activity diagram .puml and regenerate the PNG for the product README.

FAQ

What dependencies are required?

The plantuml CLI and dot from Graphviz. On macOS you can install them with brew install plantuml graphviz.

How do I run a single file or a directory?

Use the bundled render script: bash "$PLANTUML_RENDER" path/to/diagram.puml or bash "$PLANTUML_RENDER" path/to/diagrams --out-dir path/to/png. You can also use plantuml -tpng and -output directly.