ai-for-dummies/submitted-skills/Marcos Silva/skills/diagram-plantuml/SKILL.md

name, description

name	description
diagram-plantuml	Embed PlantUML diagrams inside a Confluence page using the {plantuml} macro in the storage body. Use when a page needs a sequence, component, class, state, activity, deployment, or timing diagram and the macro name is not in the caller's muscle memory.

Diagram — PlantUML in Confluence

PlantUML renders server-side on the Confluence PlantUML plugin. The macro is {plantuml}, the body is plain PlantUML between @startuml and @enduml, and the host (BASS) renders it through the bundled plugin — no external URL needed for private spaces.

Hard rules

• Macro name is plantuml, lowercase. {PlantUML} and {plantUml} both fail to render.
• Body goes inside <ac:plain-text-body><![CDATA[ … ]]></ac:plain-text-body>, not inside <ac:rich-text-body>. The rich-text body treats the body as XHTML, which mangles <, >, and & that PlantUML relies on.
• Always include @startuml and @enduml even though PlantUML accepts bodies without them. The Confluence renderer is stricter than the CLI.
• No diagram wider than ~900 px. Confluence content columns are narrow; a wide diagram overflows on smaller screens. Split or simplify.
• No diagram inside an info / note / warning panel. The renderer nests and crops. Put the diagram at body root, then put a {tip} after it with the takeaway.
• No diagram inside a code block. Same nesting failure.
• Never paste a base64 PNG into the body to skip PlantUML. If PlantUML can't render what you drew, simplify the diagram.

Storage template

<ac:structured-macro ac:name="plantuml">
  <ac:plain-text-body><![CDATA[@startuml
!theme plain
skinparam dpi 150

participant Client
participant Service

Client -> Service: request
Service --> Client: response
@enduml]]></ac:plain-text-body>
</ac:structured-macro>

The !theme plain directive keeps diagrams legible on the BASS light background; the skinparam dpi 150 is the right size for the Confluence column width. Drop both when a diagram already has its own skinparam block.

Workflow

1. Decide the diagram type. See references/diagram-types.md for the cheat sheet (sequence, component, class, state, activity, deployment, timing, use case, ER, mindmap).
2. Draft the PlantUML in a .puml scratch file. Run plantuml -tpng -checkonly -failfast2 file.puml if plantuml is on $PATH — fast feedback loop before posting.
3. Wrap in the storage template above.
4. Add a one-line caption directly after the macro using a {tip} block or a bolded sentence; do not rely on the title attribute (some renderers strip it).
5. Hand the body to the page-reviewer skill. The reviewer re-runs the syntax check on every {plantuml} block.

Common patterns

• Sequence with notes: use note left of Alice: … / note right of Bob: …. Inside an alt/opt/loop block, the note attaches to the branch.
• Component / C4: use !include <C4_Container> only if the BASS PlantUML plugin has the C4 stdlib. If unsure, prefer hand-drawn component arrows.
• State: use state "Long label" as S1 to avoid breaking state names that contain spaces.
• Timing: use robust for digital signals and analog for continuous; mixing them on one line is a render error.

Troubleshooting

Symptom	Likely cause
Macro renders as plain text	Macro name wrong, or the body is inside <ac:rich-text-body> instead of <ac:plain-text-body>
Diagram renders empty	@startuml / @enduml missing, or body has unescaped < / > outside CDATA
Diagram crops on the right	Width over the column budget — split or simplify
Theme reverts to dark on dark space	Use !theme plain explicitly; some renderers ignore the page theme
C4 include fails	Plugin doesn't ship the stdlib — switch to hand-drawn arrows

Full troubleshooting table: references/troubleshooting.md.

Related

Skill	Role
confluence-page	Owns the storage body; delegates diagrams here
page-reviewer	Re-runs the syntax check on every {plantuml} block