feat: review Gustavo and Marcos submitted skills

2026-09-04 09:07:54 -03:00
parent 6ccc692759
commit 76d83c9cf9
38 changed files with 2749 additions and 6 deletions
@@ -0,0 +1,112 @@
+# Confluence Storage Macros
+
+Confluence Cloud storage format accepts a fixed set of macros. Anything not in
+this catalog either renders as plain text or fails silently. Before adding a
+new macro to a draft, check the name here.
+
+## Inline
+
+| Macro | When |
+|-------|------|
+| `{code}` | Fenced code with optional language |
+| `{plantuml}` | Diagrams — see `diagram-plantuml` skill |
+| `{info}` | Info panel |
+| `{note}` | Note panel |
+| `{warning}` | Warning panel |
+| `{tip}` | Tip panel |
+| `{excerpt}` | Reusable fragment; also `excerpt-include` |
+| `{anchor}` | Inline anchor for `{pageref}` |
+| `{pageref}` | Cross-page reference by anchor |
+| `{children}` | Lists child pages |
+| `{include}` | Includes another page (full or excerpt) |
+| `{table-of-content}` | Outline from heading hierarchy |
+| `{expand}` | Collapsible section |
+| `{status}` | Coloured status pill |
+| `{cheese}` | Image gallery — prefer `image` element instead |
+| `{noformat}` | Plain monospace, no language hint |
+
+## Panels
+
+Panels take rich-text bodies. PlantUML inside a panel does not render — put
+diagrams at body root.
+
+```xml
+<ac:structured-macro ac:name="info">
+  <ac:rich-text-body>
+    <p>Body goes here.</p>
+  </ac:rich-text-body>
+</ac:structured-macro>
+```
+
+Available panel macros: `info`, `note`, `warning`, `tip`, `success`,
+`error`, `panel` (generic).
+
+## Code block
+
+```xml
+<ac:structured-macro ac:name="code">
+  <ac:parameter ac:name="language">python</ac:parameter>
+  <ac:parameter ac:name="title">example.py</ac:parameter>
+  <ac:parameter ac:name="linenumbers">true</ac:parameter>
+  <ac:plain-text-body><![CDATA[def hello():
+    pass]]></ac:plain-text-body>
+</ac:structured-macro>
+```
+
+`language` accepts the short names from Confluence's language list (`python`,
+`java`, `javascript`, `typescript`, `go`, `bash`, `sql`, `json`, `yaml`,
+`xml`, `markdown`). Anything outside the list falls back to plain monospace.
+
+## Tables
+
+Standard XHTML tables. Confluence does not need the `<ac:structured-macro
+ac:name="table">` wrapper for plain tables.
+
+```xml
+<table>
+  <tbody>
+    <tr>
+      <th>Column A</th>
+      <th>Column B</th>
+    </tr>
+    <tr>
+      <td>cell</td>
+      <td>cell</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+For sortable or filterable tables, use the `table-plus` macro — but only
+when the table is genuinely worth the overhead.
+
+## Links
+
+- External: `<a href="https://…">label</a>`
+- Page by title: `<ac:link><ri:page ri:content-title="Hub"/></ac:link>`
+- Page by id: `<ac:link><ri:page ri:content-id="12345"/></ac:link>`
+- Attachment: `<ac:link><ri:attachment ri:filename="diagram.png"/></ac:link>`
+- User mention: `<ac:link><ri:user ri:username="marcos"/></ac:link>`
+
+## Attachments
+
+Attachments go through `mcp__atlassian.confluence_upload_attachment` /
+`confluence_create_page_from_file` (with the file path) — never as base64 in
+the body. See `attachments.md`.
+
+## What is NOT a macro
+
+| Construct | Status |
+|-----------|--------|
+| Wiki markup (`{code}…{code}`) | Renders only on pages whose renderer is set to wiki; do not assume |
+| Markdown fences | Not interpreted; render as text |
+| HTML5 `<details>` | Rendered as plain HTML; works but no styling |
+| Inline SVG | Works but is not editable through the page editor; prefer PlantUML |
+| `<script>` / `<iframe>` | Stripped by Confluence; do not bother |
+
+## Naming conventions
+
+- Macro names are lowercase.
+- Parameter names are lowercase with words separated by `-`, not `_`
+  (`linenumbers`, not `line_numbers`).
+- Parameter values that include spaces must be quoted.