Confluence

Confluence Skill

Critical Rules

• DO NOT use MCP for any Confluence operation — this plugin uses REST API for all operations. No MCP dependency.
• DO NOT use MCP for page uploads — size limit ~10-20KB. Use upload_confluence.py instead.
• DO NOT use MCP for structural modifications — AI tool delays cause 650x slowdown (~13min vs ~1s). Use REST API scripts.
• DO NOT create temporary analysis scripts (/tmp/analyze_*.py). Use existing analyze_page.py.
• DO NOT write inline scripts to manipulate ADF JSON — use the structural scripts which handle ADF marks correctly.
• DO NOT use raw XML/HTML for images. Use markdown syntax: ![alt](path.png).
• DO NOT forget diagram conversion — pre-convert Mermaid/PlantUML to PNG/SVG before upload.
• For Rovo AI search: use Claude Code's built-in mcp__claude_ai_Atlassian_Rovo__searchAtlassian (requires one-time Atlassian authentication via mcp__claude_ai_Atlassian__authenticate).

Architecture

New page:     Markdown → markdown_to_adf.py (pre-processor + mistune) → ADF JSON → REST API v2
Edit page:    read_page.py (ADF) → Method 6 JSON diff/patch → REST API v2 PUT ADF
Download:     REST API v2 GET ADF → adf_to_markdown.py → readable Markdown (display only)
Read page:    read_page.py → REST API v2 → Markdown or ADF JSON (stdout)
Search:       search_cql.py → REST API v1 CQL → formatted results + confidence analysis
Structural:   Direct REST API scripts (add_table_row.py, add_panel.py, etc.) → ~1s each
Attachment:   v1 REST API (no v2 equivalent)
Page width:   v1 REST API property (no v2 equivalent)

Key points:

• Method 6 roundtrip never goes through Markdown — ADF in, ADF out
• adf_to_markdown.py is display-only (for Claude to read), not a data conversion step
• markdown_to_adf.py includes a pre-processor that fixes emoji lines (✅/❌) and [ ] checkboxes
• Upload priority: REST API v2 ADF (primary) → no MCP fallback
• All operations require CONFLUENCE_URL, CONFLUENCE_USER, CONFLUENCE_API_TOKEN

Decision Matrix

All .py scripts run with: uv run --managed-python scripts/SCRIPT_NAME.py

Workflows

Reading Pages

1. Resolve URL → page ID:

   uv run --managed-python scripts/url_resolver.py "URL"
   

2. Read page:

   uv run --managed-python scripts/read_page.py PAGE_ID
   

Method 6: Edit Existing Pages (Recommended)

Edits text while preserving all macros. Operates directly on ADF JSON — Markdown is display-only.

When to use: Fix typos, improve clarity, update docs on pages with macros. Not for: New pages (use upload_confluence.py), massive restructuring.

Usage — natural language:

"Edit Confluence page 123456 to fix typos"
"Update API docs on page 789012"

Workflow:

1. Read page ADF via REST API:

   uv run --managed-python scripts/read_page.py PAGE_ID --format adf
   

2. Safe mode (default): edit outside macros only. Advanced mode: edit inside macros (requires confirmation)

3. Auto-backup to .confluence_backups/{page_id}/ (keeps last 10)

4. Write back via v2 API (auto-restore on failure)

Implementation: scripts/mcp_json_diff_roundtrip.py

Upload Markdown (New Page / Full Replace)

upload_confluence.py converts Markdown → ADF via markdown_to_adf.py → uploads via REST API v2.

# Update existing page
uv run --managed-python scripts/upload_confluence.py doc.md --id PAGE_ID

# Create new page
uv run --managed-python scripts/upload_confluence.py doc.md --space SPACE_KEY --parent-id PARENT_ID

# Auto-detect from frontmatter
uv run --managed-python scripts/upload_confluence.py doc.md

# Options: --dry-run, --title "...", --width narrow, --table-layout default

User intent mapping:

• "Upload X under page Y" → --space + --parent-id
• "Update page 123" → --id 123
• "Upload this downloaded file" → no args (frontmatter)

Frontmatter options:

---
title: "My Page"
confluence:
  id: "123456"
  width: full           # full (default) or narrow
  table:
    layout: full-width  # full-width (default) or default
    colwidths: [12, 10, 40, 38]
---

Download Page (Display Utility)

Downloads via v2 ADF API → converts to readable Markdown. Display only — use Method 6 for roundtrip editing.

uv run --managed-python scripts/download_confluence.py PAGE_ID
uv run --managed-python scripts/download_confluence.py --download-children PAGE_ID
uv run --managed-python scripts/download_confluence.py --output-dir ./docs PAGE_ID

Custom markers in downloaded Markdown:

• <!-- EXPAND: "title" --> ... <!-- /EXPAND -->, <!-- PANEL: type --> ... <!-- /PANEL -->
• :shortname: (emoji), <!-- MENTION: id "name" -->, <!-- CARD: url -->
• <!-- STATUS: "text" color -->, <!-- DATE: timestamp -->

These markers are recognized by upload_confluence.py for page duplication/migration.

Structural Modifications (Direct REST API)

650x faster than MCP (~1s vs ~13min). Example:

uv run --managed-python scripts/add_table_row.py PAGE_ID \
  --table-heading "Access Control Inventory" \
  --after-row-containing "GitHub" \
  --cells "Elasticsearch Cluster" "@Data Team" "Read-Only" \
  --dry-run

Common patterns for structural scripts:

# Most scripts: PAGE_ID + --after-heading or --at-end + content args + --dry-run
uv run --managed-python scripts/add_panel.py PAGE_ID --after-heading "Setup" --panel-type info --content "Note text" --dry-run
uv run --managed-python scripts/add_list_item.py PAGE_ID --after-heading "TODO" --item "New task" --position end
uv run --managed-python scripts/insert_section.py PAGE_ID --new-heading "New Section" --level 2 --after-heading "Existing"
uv run --managed-python scripts/add_media.py PAGE_ID --image-path "./img.png" --at-end --width 500
uv run --managed-python scripts/add_status.py PAGE_ID --search-text "Status:" --status "TODO" --color blue
uv run --managed-python scripts/add_mention.py PAGE_ID --search-text "Owner:" --user-id "557058..." --display-name "John"
uv run --managed-python scripts/analyze_page.py PAGE_ID [--type codeBlock|table|bulletList]

Search

Primary: CQL search via REST API

uv run --managed-python scripts/search_cql.py 'space = "DEV" AND text ~ "API"'
uv run --managed-python scripts/search_cql.py 'title ~ "deployment"' --limit 20

Rovo AI search (when CQL confidence is low):

When search_cql.py reports confidence < 0.6 and asks if you want Rovo AI search:

1. Check if Atlassian integration is authenticated — try calling mcp__claude_ai_Atlassian_Rovo__searchAtlassian
2. If not authenticated, call mcp__claude_ai_Atlassian__authenticate to start OAuth flow
3. After authentication: mcp__claude_ai_Atlassian_Rovo__searchAtlassian({query: "search terms"})
4. If user declines authentication: use existing CQL results as-is

Convert Markdown ↔ Wiki Markup

uv run --managed-python scripts/convert_markdown_to_wiki.py input.md output.wiki

Editing Existing Pages: Decision Order

1. Structural scripts (add_table_row, insert_section, add_panel...) → precise, fast, ~1s
2. Method 6 (read_page.py --format adf + mcp_json_diff_roundtrip) → free-form text editing, fix typos, AI-driven
3. upload_confluence.py → full page replacement (last resort)

Always start with analyze_page.py PAGE_ID to understand the page structure first.

Common Mistakes

Image Handling

1. Convert diagrams if needed: mmdc -i diagram.mmd -o diagram.png or plantuml diagram.puml -tpng
2. Use markdown syntax: ![alt](./path/to/image.png)
3. Upload: uv run --managed-python scripts/upload_confluence.py doc.md --id PAGE_ID

Checklists

Upload: Convert diagrams → Use markdown image syntax → --dry-run test → Upload with script → Verify page

Download: Get page ID (use url_resolver.py for short URLs) → Set output dir → Run download → Verify attachments

Script Reference

All scripts: uv run --managed-python scripts/SCRIPT_NAME.py

All structural scripts support --dry-run for preview.

Scripts that accept text input (add_list_item, add_panel, add_blockquote, insert_section, add_nested_expand) support markdown inline syntax which is auto-converted to ADF marks:

• `code` → code mark, **bold** → strong mark, *italic* → em mark, ~~strike~~ → strike mark

Example: --item '"compat"- **REQUIRED** for all models' correctly renders as code + bold in Confluence.

When NOT to Use Scripts

• Jira issues → Use Jira-specific tools
• Rovo AI search → Use built-in mcp__claude_ai_Atlassian_Rovo__searchAtlassian (when CQL quality is low)

Prerequisites

• uv — all scripts use PEP 723 inline metadata
• Env vars (REQUIRED): CONFLUENCE_URL, CONFLUENCE_USER, CONFLUENCE_API_TOKEN
  • Generate token: https://id.atlassian.com/manage-profile/security/api-tokens
• Optional: mark CLI (Git-to-Confluence sync), Mermaid CLI (diagram rendering)
• Optional: Claude Code built-in Atlassian integration (for Rovo AI search — authenticate via mcp__claude_ai_Atlassian__authenticate)

References

• Wiki Markup Guide - Syntax reference
• CQL Reference - Query language
• Mention Account ID Lookup - Find user IDs
• Troubleshooting - Common errors and fixes

Converted and distributed by TomeVault — claim your Tome and manage your conversions.