plantuml-skill

Generating PlantUML diagrams and exporting them to PNG or SVG through the Kroki rendering API, which needs no local installation beyond curl. Supported diagram types include sequence, component, class, ER, activity, use case, state, and C4. Five modes route the work: Generate from a text description as the default, From code to diagram existing source, Embed to render PlantUML inside a Markdown document to images, Refine to change an existing diagram, and Review to assess whether an existing image is readable.

The workflow writes a .puml file with the start and end markers, then exports via a Kroki POST while capturing the HTTP status. A validate-and-self-correct loop is emphasized: a blind curl is never trusted, because Kroki returns a 400 on syntax errors and writes the error text into the output file, so the process checks the status code, that the file is non-empty, and that the bytes are a real image. On failure it reads Kroki's error and retries up to three times, degrading through a defined order that simplifies shapes, strips skinparam and themes, removes notes, simplifies labels, reduces edges, and finally switches diagram type.

A vision-based self-check then reads the rendered PNG for readability problems that auto-layout cannot prevent, such as label truncation, overlap, wrong orientation, edge spaghetti, and low contrast, limited to two rounds, followed by a review loop for user feedback. Three rendering backends are offered: the public Kroki API, a local Kroki Docker instance, or a local PlantUML jar with Java and Graphviz. A privacy note warns that public Kroki uploads the diagram source, and the document routes non-UML or heavily styled needs to mermaid, drawio, or excalidraw.