feat: review Gustavo and Marcos submitted skills

2026-09-04 09:07:54 -03:00
parent 6694897ae9
commit 5756dceb5a
38 changed files with 2749 additions and 6 deletions
@@ -0,0 +1,68 @@
+# Attachments
+
+Attachments live on a page and are referenced by filename. They survive page
+moves and template changes, but they do not survive page deletion.
+
+## Upload via mcp-atlassian
+
+```python
+mcp__atlassian.confluence_upload_attachment(
+    pageId=…,
+    filePath="path/to/file.png",
+    comment="optional version note",
+)
+```
+
+Returns a metadata object including the download URL. Use that URL inside the
+page body, not a local file path.
+
+## Reference in the body
+
+By attachment filename:
+
+```xml
+<ac:link>
+  <ri:attachment ri:filename="diagram.png" />
+  <ac:plain-text-link-body><![CDATA[diagram]]></ac:plain-text-link-body>
+</ac:link>
+```
+
+As an inline image:
+
+```xml
+<ac:image ac:width="600">
+  <ri:attachment ri:filename="diagram.png" />
+</ac:image>
+```
+
+Always set `ac:alt` for accessibility:
+
+```xml
+<ac:image ac:width="600">
+  <ri:attachment ri:filename="diagram.png" />
+  <ac:alt>Sequence diagram of the order → inventory → shipment flow.</ac:alt>
+</ac:image>
+```
+
+## What NOT to do
+
+- Don't paste base64 PNG into the body. The page editor can't replace it
+  without re-rendering the whole page; it bloats the storage body; the page
+  cannot be reviewed by lint.
+- Don't link to a public CDN. BASS pages are private; CDN URLs leak and break
+  on access-controlled spaces.
+- Don't re-upload the same file under a new name. Confluence deduplicates by
+  hash within a page, but the editor doesn't surface duplicates well.
+
+## Versioning
+
+Attach with a version suffix (`diagram-v2.png`) when updating. Confluence
+keeps the old version in the attachments list and the page body continues to
+reference the filename; change the filename in the body to point at the new
+version.
+
+## Cleanup
+
+Pages with stale attachments show up in the space's attachment report. When
+removing a diagram, also remove the attachment (do not leave orphaned files
+on the page).