netcracker/ai-for-dummies
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: review Gustavo and Marcos submitted skills

Browse Source
This commit is contained in:
Marcos Silva
2026-09-04 09:07:54 -03:00
parent 6694897ae9
commit 5756dceb5a
38 changed files with 2749 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
submitted-skills/Marcos Silva/skills/diagram-plantuml/SKILL.md
+97
View File
@@ -0,0 +1,97 @@
---
name: diagram-plantuml
description: 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
```xml
<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](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](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 |
submitted-skills/Marcos Silva/skills/diagram-plantuml/references/diagram-types.md
+153
View File
@@ -0,0 +1,153 @@
# PlantUML Diagram Types
The eight diagrams the Confluence page author reaches for, with the
PlantUML skeleton for each. Pick the type by what the reader needs to
*do* with the diagram, not by what the data looks like.
| Reader needs | Pick |
|--------------|------|
| Trace a request across actors | sequence |
| Show who owns which service | component |
| Show static structure / inheritance | class |
| Show valid states of one object | state |
| Show branching workflow | activity |
| Show deployment topology | deployment |
| Show signal timing / concurrency | timing |
| Show domain entities | ER |
## Sequence
```
@startuml
participant Client
participant Service
participant DB
Client -> Service: request
Service -> DB: query
DB --> Service: rows
Service --> Client: response
@enduml
```
## Component
```
@startuml
[Web] --> [API]
[API] --> [DB]
[API] --> [Cache]
@enduml
```
For C4, prefer hand-drawn boxes if the BASS PlantUML plugin doesn't ship the
`C4_Container` stdlib. Test with one diagram before committing to the
notation.
## Class
```
@startuml
class Order {
+id: UUID
+status: Status
+total(): Money
}
class LineItem {
+sku: string
+qty: int
}
Order "1" *-- "*" LineItem
@enduml
```
## State
```
@startuml
[*] --> Draft
Draft --> Submitted: submit
Submitted --> Approved: approve
Submitted --> Rejected: reject
Approved --> [*]
Rejected --> [*]
@enduml
```
## Activity
```
@startuml
start
:parse input;
if (valid?) then (yes)
:process;
else (no)
:reject;
stop
endif
:persist;
stop
@enduml
```
## Deployment
```
@startuml
node "k8s prod" {
[service-a] --> [service-b]
}
node "external" {
[IdP]
}
[service-a] --> [IdP]
@enduml
```
## Timing
```
@startuml
robust "Client" as C
robust "Service" as S
C is Idle
S is Idle
@0
C is Requesting
@5
S is Processing
@10
S is Idle
C is Idle
@enduml
```
## ER
```
@startuml
entity "Order" {
*id : UUID
--
total : Money
}
entity "LineItem" {
*id : UUID
--
sku : string
qty : int
}
Order ||--o{ LineItem : contains
@enduml
```
## What is NOT a use case
If the diagram needs prose between boxes, it is not a use case. Use a
sequence or activity diagram instead.
## When to use multiple diagrams
A page that needs two diagrams is fine. A page that needs five is a wall
— split the page.
submitted-skills/Marcos Silva/skills/diagram-plantuml/references/troubleshooting.md
+66
View File
@@ -0,0 +1,66 @@
# PlantUML Troubleshooting
Symptoms and fixes for the four classes of rendering failure on BASS
Confluence.
## Macro renders as plain text
| Cause | Fix |
|-------|-----|
| Macro name wrong (`PlantUML`, `Plantuml`) | Use `plantuml`, lowercase |
| Body inside `<ac:rich-text-body>` | Move to `<ac:plain-text-body>` |
| Macro opened but not closed | Add the matching `</ac:structured-macro>` |
| Page is in wiki renderer mode | Re-save in storage format (page properties → editor) |
## Diagram renders empty
| Cause | Fix |
|-------|-----|
| `@startuml` / `@enduml` missing | Add both, even if PlantUML accepts bodies without |
| Body has unescaped `<` / `>` outside CDATA | Wrap entire body in `<![CDATA[ … ]]>` |
| `!include` points to a stdlib the plugin doesn't ship | Replace with hand-drawn equivalent |
| File-size limit exceeded (very large diagrams) | Split into multiple diagrams |
## Diagram crops on the right
| Cause | Fix |
|-------|-----|
| Width > ~900 px | Split the diagram horizontally into two, or simplify |
| Long labels on long arrows | Shorten labels; move detail to body text |
| Padding parameters set too high | Drop `skinparam Padding`, `skinparam Margin` overrides |
## Theme reverts to dark on dark space
| Cause | Fix |
|-------|-----|
| Page theme overrides the diagram theme | Use `!theme plain` explicitly at the top of the body |
| BASS theme override | Hard-code colors with `skinparam` per element |
## C4 / standard library includes fail
| Cause | Fix |
|-------|-----|
| Plugin doesn't ship the stdlib | Switch to `component` diagram or hand-drawn boxes |
| Include URL is blocked by network policy | Mirror the stdlib locally, use `!include /path/to/C4_Container.puml` (only if the plugin supports it) |
## Debugging loop
1. Save the `.puml` body to a file.
2. Run `plantuml -tpng -checkonly -failfast2 file.puml`.
3. If local parse fails, the body is wrong — fix the syntax.
4. If local parse succeeds but Confluence fails, the wrapper is wrong — fix
the storage macro form.
## When to give up on PlantUML
- The diagram needs interactivity (hover, click). Confluence PlantUML does
not support this.
- The diagram needs real images (logos, photos). Drop them in via attachment
instead.
- The diagram needs to be edited by non-technical authors. PlantUML is not
the right tool.
## When to escalate
- The BASS plugin version changes and breaks a working diagram. Capture the
diff, fix the diagram, and update this troubleshooting page.