PlantUML diagrams

Core contract

• Produce an editable .puml source file. Render PNG or SVG when an approved
  backend is available.
• Prefer local execution: host plantuml, then a user-provided or configured
  local plantuml.jar.
• Do not install Java, Graphviz, PlantUML, or other packages unless the user asks.
• Do not use public Kroki or remote !includeurl directives without explicit
  approval for the current task. Explain that the diagram source will leave the
  machine before requesting or acting on that approval.
• Ground diagrams of code and systems in inspected evidence. Mark inferences;
  do not present guessed components, calls, cardinalities, or states as facts.
• Do not claim success until syntax, output bytes, and visual readability have
  been checked.
• Apply a restrained, consistent visual system to new diagrams. Preserve an
  established repository or document style when one exists.
• When serving slidev-ppt (slides/lesson-0X.md): Always use the Slidev Dark Blueprint Profile defined in `references/style-guide.md` (backgroundColor transparent, surface #1E293B, border #38BDF8/#334155, text #E2E8F0, Noto Sans CJK SC), save both .puml and rendered .svg under slides/public/diagrams/, and include only classes/interfaces/relationships grounded in the course outline's 重点内容 and 呈现方式 (never invent std:: on user classes or leak 演讲要点 oral stories onto diagram nodes).

Route the request

Read only the playbooks needed for the request:

Request	Required playbook
Create or refine a diagram	This workflow; read `references/authoring-guide.md` and `references/style-guide.md`
Derive a diagram from a repository or source files	Read `references/from-source-code.md`
Extract or render PlantUML in Markdown	Read `references/markdown-embed.md`
Select a renderer or use approved Kroki	Read `references/rendering-backends.md`
Diagnose a render or layout failure	Read `references/plantuml-troubleshooting.md`
Review an existing rendered diagram	Start at visual QA below; inspect its .puml when available

If the user explicitly requests Mermaid, draw.io, Excalidraw, or another format,
honor that format instead of converting the task to PlantUML.

Workflow

1. Establish the deliverable

• Inspect any existing source, image, Markdown document, and surrounding repo
  conventions before editing.
• Preserve the requested filename and format. Otherwise choose a stable,
  descriptive kebab-case basename and default to .puml plus PNG.
• Prefer SVG for web documentation or scalable line art when the target supports
  it; prefer PNG for chat preview and broad document compatibility.
• Keep one diagram per .puml file so rendering, review, and later edits stay
  unambiguous.

2. Choose the diagram model

Evidence or intent	Diagram type
Time-ordered calls, protocol, request lifecycle	Sequence
Services, modules, dependencies, deployment boundaries	Component or deployment
Types, interfaces, inheritance, ownership	Class
Tables, keys, cardinalities	ER
Decisions and procedural flow	Activity
Lifecycle and allowed transitions	State
Actors and user-visible capabilities	Use case
System boundary and audience-level architecture	C4 context/container/component
Topic hierarchy	Mind map
Dated work and dependencies	Gantt

Choose the smallest diagram that answers the question. Split by concern or
abstraction level when a single view becomes crowded; do not mix C4 context,
container, and component detail in one view.

3. Author the source

• Match the user's language. Keep labels concise and use explicit aliases.
• Apply the palette, typography, spacing, and diagram-specific profile from
  `references/style-guide.md`. Use semantic color
  sparingly; do not create a rainbow of unrelated node colors.
• Encode semantic relationships accurately; do not use arrow direction only for
  visual convenience when it changes meaning.
• Declare sequence participants in desired order. Group related architecture
  elements with package, rectangle, or C4 boundaries.
• Start with plain, portable syntax. Avoid custom fonts, sprites, remote includes,
  and heavy styling until the structure renders correctly.
• Use !include <C4/...> only when the selected local renderer provides that
  standard library. If it does not, use plain components rather than a remote
  include.
• Apply layout hints only after the semantic graph is correct.

Read `references/authoring-guide.md` for compact
templates, relation syntax, styling defaults, and layout heuristics.

4. Render locally

Resolve scripts/render_plantuml.py relative to this SKILL.md. The helper:

• selects only local backends;
• forces PlantUML's SANDBOX security profile and rejects remote-resource
  syntax, blocking URL and local-file resource loading during rendering;
• runs a syntax check before rendering;
• renders into a temporary directory and atomically installs validated output;
• disables embedded PlantUML source metadata in the exported image;
• never installs dependencies or contacts the network.

python3 /path/to/plantuml-skill/scripts/render_plantuml.py diagram.puml \
  --format png --output diagram.png

Use an explicit local jar when requested:

python3 /path/to/plantuml-skill/scripts/render_plantuml.py diagram.puml \
  --backend jar --jar /path/to/plantuml.jar --format svg

With --backend auto, choose the host CLI first and then --jar or
PLANTUML_JAR. Once a backend is selected, do not silently switch after a render
failure. If no local backend exists, keep the .puml and report that rendering
was skipped. Public Kroki is a separate, approval-gated path described in
`references/rendering-backends.md`.

5. Repair syntax failures

Read the complete renderer diagnostic and fix the cited line first. Re-run the
syntax check and render after every edit. Make at most three targeted repair
rounds, simplifying in this order when needed:

1. remove unsupported shapes, sprites, or includes;
2. remove themes and custom skinparam blocks;
3. simplify notes and labels;
4. reduce nonessential relationships;
5. use a simpler diagram type that preserves the core meaning.

Use `references/plantuml-troubleshooting.md`
for error-specific fixes. If the third repair still fails, stop and report the
raw diagnostic and the valid .puml work completed so far.

6. Perform visual QA

Inspect the rendered artifact with the available image-viewing capability. A
successful renderer command is insufficient; PlantUML can produce a valid image
that is unreadable or even an error image on some versions.

Check:

• all requested elements and only supported/in-scope elements are present;
• labels are legible, unclipped, correctly encoded, and free of mojibake;
• relationship direction, cardinality, ordering, and boundary placement match
  the source evidence;
• contrast works and the aspect ratio is suitable for the destination;
• palette, font treatment, border weight, corner treatment, and whitespace are
  consistent with the selected visual system;
• crossings, long arrows, and dense clusters do not hide the main reading path;
• title, legend, notes, and abstraction level are useful rather than decorative.

Make at most two layout/readability repair rounds. Re-render and re-check after
each change. Prefer reordering declarations, changing direction, grouping, or
splitting the view before adding brittle layout tricks. If image inspection is
unavailable, validate the file and disclose that visual QA was skipped.

7. Refine safely

• Modify the existing .puml rather than reconstructing it from the image.
• Apply the smallest semantic edit that satisfies feedback.
• Re-run syntax validation, rendering, and visual QA after every change.
• Overwrite the intended output; do not accumulate v2-final-final files unless
  the user asks to preserve versions.
• Preserve unrelated user changes in a dirty worktree.

8. Hand off

Report:

• clickable paths to the .puml source and each requested PNG/SVG artifact;
• the diagram type and scope in one sentence;
• the exact backend used;
• whether the source stayed local or was uploaded after approval;
• any skipped render, visual-QA limitation, inference, or unresolved issue.

Do not include dependency-install instructions unless they are relevant to a
blocked render or the user asks for setup help.