Confluence Management Skill

Version: 0.1.0 (Testing Phase)

🚨 Critical Constraints

DO NOT USE MCP FOR PAGE UPLOADS - Size limits apply (~10-20KB max)

DO NOT USE MCP FOR STRUCTURAL MODIFICATIONS - AI tool delays cause 650x slowdown

Use REST API scripts instead:

For uploading documents:

uv run --managed-python scripts/upload_confluence.py document.md --id PAGE_ID

For structural modifications (adding table rows, etc.):

uv run --managed-python scripts/add_table_row.py PAGE_ID --table-heading "..." --after-row-containing "..." --cells "..." "..." "..."

DO NOT CREATE TEMPORARY ANALYSIS SCRIPTS - Use existing analyze_page.py tool

DON'T create one-off scripts like:

/tmp/analyze_gemini_page.py /tmp/show_all_blocks.py

DO use the existing tool:

uv run --managed-python scripts/analyze_page.py PAGE_ID uv run --managed-python scripts/analyze_page.py PAGE_ID --type codeBlock

Performance Reality:

• MCP roundtrip for structural changes: ~13 minutes (91% is AI processing delays)

• Python REST API direct: ~1.2 seconds (650x faster)

• Bottleneck: AI tool invocation intervals, NOT MCP network I/O

MCP tools are fine for reading pages and simple text edits but fail for structural modifications due to AI processing overhead.

Quick Decision Matrix

NOTE: All .py scripts below must be run with uv run --managed-python scripts/SCRIPT_NAME.py

When to Use What Tool

Task Category Specific Task Tool Speed Notes

Analysis Understand page structure analyze_page.py

<1s 🔍 Shows all components

Text Editing Fix typos, improve clarity MCP Method 6 Interactive ✅ Preserves macros

Block Elements Add table row add_table_row.py

~1s ⚡ 650x faster than MCP

Add list item add_list_item.py

~1s Bullet or numbered lists

Add info/warning panel add_panel.py

~1s 4 panel types available

Insert new section insert_section.py

~1s Heading + content

Add line to code block add_to_codeblock.py

~1s Insert commands/code lines

Add blockquote (citation) add_blockquote.py

~1s For quotes and citations

Add horizontal rule add_rule.py

~1s Section divider

Add image add_media.py

~2-5s Uploads and embeds image

Add image group add_media_group.py

~3-8s Multiple images in row/grid

Add nested expand add_nested_expand.py

~1s Expand inside expand

Inline Elements Add status label add_status.py

~1s TODO/DONE/IN PROGRESS

Add @mention add_mention.py

~1s Notify users

Add date add_date.py

~1s Deadlines and timestamps

Add emoji add_emoji.py

~1s Visual expressions

Add inline card add_inline_card.py

~1s Rich URL preview card

Document Ops Upload large files (>10KB) upload_confluence.py

~5-10s No size limits

Upload with images upload_confluence.py

~5-10s Handles attachments

Download to Markdown download_confluence.py

~5-10s Converts macros

Reading Search/read pages MCP tools Fast ✅ OK for reading

Small Changes Text-only (<10KB) MCP create/update Slow ⚠️ Size limited

CI/CD Git-to-Confluence sync mark CLI Fast Best for automation

Conversion Markdown ↔ Wiki convert_markdown_to_wiki.py

Fast Format conversion

Core Workflows

📖 Reading Confluence Pages from URLs

When user provides a Confluence URL, automatically resolve and read the page:

Workflow

Detect URL format:

• Short URL: https://site.atlassian.net/wiki/x/2oEBfw

• Full URL: https://site.atlassian.net/wiki/spaces/SPACE/pages/123456789/Title

• Direct page ID: 123456789

Resolve to page ID:

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

Read page content (via MCP):

mcp__plugin_confluence_atlassian__getConfluencePage({ cloudId: "...", pageId: "resolved_page_id", contentFormat: "markdown" })

Examples

User: "https://site.atlassian.net/wiki/x/2oEBfw" → Resolve: page ID 2130805210 → Read page and display content

User: "Read https://site.atlassian.net/wiki/spaces/DEV/pages/123456/API-Docs" → Extract page ID: 123456 → Read page and display content

🆕 Method 6: Intelligent Roundtrip Editing (Recommended for Editing Existing Pages)

Revolutionary Feature: Edit existing Confluence pages while preserving all macros (expand panels, status badges, page properties, etc.) and allow Claude to intelligently edit text content.

When to Use Method 6?

✅ Good Use Cases:

• Fix typos and grammar errors on pages

• Improve clarity and readability of existing content

• Update documentation while preserving page structure

• Edit pages containing important macros (without losing them)

❌ Not Suitable For:

• Creating brand new pages → Use upload_confluence.py

• Massive restructuring of entire page → Use upload_confluence.py

• Batch updating multiple pages → Use Method 1 (download + edit + upload)

Usage

Simply use natural language commands, system handles automatically:

"Edit Confluence page 123456 to fix typos and improve clarity" "Update the API documentation on page 789012 to reflect the new endpoints" "Fix grammar issues in page 456789"

Workflow

• Read page via MCP

• Auto-detect macros

• Choose mode: Safe (edit outside macros) or Advanced (edit inside macros)

• Auto-backup to .confluence_backups/{page_id}/

• Claude edits based on instruction

• Write back to Confluence (auto-restore on failure)

Two Modes

Safe Mode (default, recommended):

• Skips macro content, only edits outside text

• Zero risk, macro structure completely unaffected

• Suitable for most use cases

Advanced Mode (advanced, requires confirmation):

• Can edit text inside macros (e.g., content in expand panels)

• Requires explicit user confirmation

• Automatic backup + auto-restore on failure

• Suitable when need to edit info boxes, warning panels content

Backup/Restore

• Auto-backup before each edit (keeps last 10 in .confluence_backups/{page_id}/ )

• Manual restore: "Rollback Confluence page 123456 to previous backup"

• Auto-restore on write failure

• Uses ADF JSON diff/patch, macro-preserving, OAuth auth

• Implementation: scripts/mcp_json_diff_roundtrip.py

Upload Markdown to Confluence

CRITICAL: Use absolute path to script WITHOUT cd command.

User Intent Detection (Decision Tree)

The script automatically detects user intent based on CLI arguments:

1. Update existing page (explicit):

uv run --managed-python scripts/upload_confluence.py document.md --id PAGE_ID

Always updates PAGE_ID, ignores frontmatter

2. Create new page (explicit):

uv run --managed-python scripts/upload_confluence.py document.md --space SPACE_KEY --parent-id PARENT_ID

Always creates new page, even if frontmatter has id

Use this when cloning docs to another space or creating duplicate pages

3. Auto-detect from frontmatter (no CLI args):

uv run --managed-python scripts/upload_confluence.py document.md

Uses frontmatter id (update) or space (create)

Best for downloaded files with frontmatter metadata

When User Says

• "Upload X to Confluence under page Y" → Use --space

• --parent-id (create new)

• "Create a new page based on this downloaded doc" → Use --space

• --parent-id (ignores frontmatter id)

• "Update Confluence page 123" → Use --id 123 (update existing)

• "Upload this downloaded file" → No args (use frontmatter)

Additional Options

Preview before uploading (recommended)

uv run --managed-python scripts/upload_confluence.py document.md --id 780369923 --dry-run

Override title

uv run --managed-python scripts/upload_confluence.py document.md --id 780369923 --title "New Title"

Structural Modifications (Fast Method) 🚀

Performance: Direct REST API (~1.2s) vs MCP (~13min) = 650x speedup

Example - Add Table Row:

Preview first (recommended)

uv run --managed-python scripts/add_table_row.py PAGE_ID
--table-heading "Access Control Inventory"
--after-row-containing "GitHub"
--cells "Service" "Owner" "Access"
--dry-run

Actual update

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

Key Parameters:

• PAGE_ID : Confluence page ID (from URL or url_resolver.py)

• --table-heading : Heading text before the target table

• --after-row-containing : Text in first cell of row to insert after

• --cells : New row's cell contents (space-separated, use quotes if contains spaces)

• --dry-run : Preview mode, doesn't actually update

Prerequisites: Set environment variables CONFLUENCE_URL , CONFLUENCE_USER , CONFLUENCE_API_TOKEN

All other tools (list, panel, section, etc.) follow similar pattern. See Quick Decision Matrix table for full list.

Download Confluence to Markdown

Single page

uv run --managed-python scripts/download_confluence.py 123456789

With child pages

uv run --managed-python scripts/download_confluence.py --download-children 123456789

Custom output directory

uv run --managed-python scripts/download_confluence.py --output-dir ./docs 123456789

Convert Markdown to Wiki Markup

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

Search Confluence (via MCP)

mcp__atlassian__confluence_search({ query: 'space = "DEV" AND text ~ "API" AND created >= startOfYear()', limit: 10 })

Create/Update Pages (Small Documents Only)

// Create page mcp__atlassian__confluence_create_page({ space_key: "DEV", title: "API Documentation", content: "h1. Overview\n\nContent here...", content_format: "wiki" })

// Update page mcp__atlassian__confluence_update_page({ page_id: "123456789", title: "Updated Title", content: "h1. New Content", version_comment: "Updated via Claude Code" })

Image Handling

Standard Workflow

Convert diagrams (if Mermaid/PlantUML):

Mermaid

mmdc -i diagram.mmd -o diagram.png -b transparent

PlantUML

plantuml diagram.puml -tpng

Reference in markdown (always use markdown syntax):

Upload (script handles attachments):

uv run --managed-python scripts/upload_confluence.py document.md --id PAGE_ID

Common Mistakes

❌ Wrong ✅ Correct

Creating temp scripts Use existing: analyze_page.py

Using raw XML Use markdown:

MCP for uploads Use upload_confluence.py

Forgetting diagram conversion Pre-convert Mermaid/PlantUML to PNG/SVG

Ignoring 401 Unauthorized Run /mcp to re-authenticate

Checklists

Upload: Convert diagrams (Mermaid/PlantUML) → Use markdown image syntax → Dry-run test → Upload with script → Verify page accessible

Download: Get page ID (use url_resolver.py for short URLs) → Configure credentials (.env) → Set output directory → Run download script → Verify attachments in {Page}_attachments/

Available MCP Tools

Search, read pages, create/update (⚠️ size limited), delete, labels, comments. See mcp__plugin_confluence_atlassian__*

for full list.

Utility Scripts

IMPORTANT: All Python scripts must be run with uv run --managed-python to ensure correct dependency management.

ADF Coverage: 15 structural modification tools covering 16/19 ADF node types (84% coverage, ~98% practical coverage)

• ✅ All common block elements (table, list, code, panel, heading, quote, rule, images)

• ✅ All common inline elements (status, mention, date, emoji, card)

• ❌ Only missing: multiBodiedExtension (tabs macro), mediaInline (rare)

Script Purpose Usage

scripts/confluence_adf_utils.py

Shared Utils Library - ADF operation core functions (auth, read, write, find nodes) Import by other scripts

scripts/analyze_page.py

🔍 Analyze Page Structure - Show all components (tables, lists, code blocks, panels, headings) and suggest which tool to use uv run --managed-python scripts/analyze_page.py PAGE_ID [--type codeBlock|table|bulletList|...]

scripts/add_table_row.py

⚡ Fast Add Table Row (~1.2s vs MCP 13min) uv run --managed-python scripts/add_table_row.py PAGE_ID --table-heading "..." --after-row-containing "..." --cells "..." "..."

scripts/add_list_item.py

📋 Add bullet/numbered list items uv run --managed-python scripts/add_list_item.py PAGE_ID --after-heading "..." --item "..." [--position start|end]

scripts/add_panel.py

💡 Add info/warning/note/success panels uv run --managed-python scripts/add_panel.py PAGE_ID --after-heading "..." --panel-type info --content "..."

scripts/insert_section.py

📑 Insert new section (heading + content) uv run --managed-python scripts/insert_section.py PAGE_ID --new-heading "..." --level 2 [--after-heading "..."]

scripts/add_to_codeblock.py

💻 Add line to code block uv run --managed-python scripts/add_to_codeblock.py PAGE_ID --search-text "..." --add-line "..." [--position after]

scripts/add_blockquote.py

💬 Add blockquote (citation) uv run --managed-python scripts/add_blockquote.py PAGE_ID --quote "..." [--after-heading "..."|--at-end]

scripts/add_rule.py

➖ Add horizontal rule (divider) uv run --managed-python scripts/add_rule.py PAGE_ID [--after-heading "..."|--at-end]

scripts/add_media.py

🖼️ Add image (uploads and embeds) uv run --managed-python scripts/add_media.py PAGE_ID --image-path "./img.png" [--after-heading "..."|--at-end] [--width 500]

scripts/add_status.py

🏷️ Add status label (TODO/DONE/etc.) uv run --managed-python scripts/add_status.py PAGE_ID --search-text "..." --status "TODO" [--color blue]

scripts/add_mention.py

👤 Add @mention (notify user) uv run --managed-python scripts/add_mention.py PAGE_ID --search-text "..." --user-id "557058..." [--display-name "John"]

scripts/add_date.py

📅 Add date (inline timestamp) uv run --managed-python scripts/add_date.py PAGE_ID --search-text "..." --date "2026-03-15"

scripts/add_emoji.py

😀 Add emoji uv run --managed-python scripts/add_emoji.py PAGE_ID --search-text "..." --emoji ":smile:"

scripts/add_media_group.py

🖼️🖼️ Add image group (multiple images) uv run --managed-python scripts/add_media_group.py PAGE_ID --images "./img1.png" "./img2.png" [--after-heading "..."|--at-end]

scripts/add_nested_expand.py

📂 Add nested expand panel uv run --managed-python scripts/add_nested_expand.py PAGE_ID --parent-expand "Details" --title "More" --content "..."

scripts/add_inline_card.py

🔗 Add inline card (URL preview) uv run --managed-python scripts/add_inline_card.py PAGE_ID --search-text "..." --url "https://..."

scripts/upload_confluence.py

📝 Upload Markdown (supports large files, images) uv run --managed-python scripts/upload_confluence.py doc.md --id PAGE_ID

scripts/download_confluence.py

📥 Download as Markdown (with attachments) uv run --managed-python scripts/download_confluence.py PAGE_ID

scripts/convert_markdown_to_wiki.py

🔄 Markdown ↔ Wiki Markup conversion uv run --managed-python scripts/convert_markdown_to_wiki.py input.md output.wiki

scripts/mcp_json_diff_roundtrip.py

✏️ Intelligent text editing (preserves macros) Used by Method 6, see above

Prerequisites

Required:

• uv package manager - All scripts use PEP 723 inline metadata, must run with uv run --managed-python

• Atlassian MCP Server (mcp__atlassian ) with Confluence credentials (for MCP tools)

• Environment variables: CONFLUENCE_URL , CONFLUENCE_USER , CONFLUENCE_API_TOKEN (for REST API scripts)

Optional:

• mark CLI: Git-to-Confluence sync (brew install kovetskiy/mark/mark )

• Mermaid CLI: Diagram rendering (npm install -g @mermaid-js/mermaid-cli )

References

• Wiki Markup Guide - Complete syntax reference

• CQL Reference - Confluence Query Language syntax

• Mention Account ID Lookup - How to find user account IDs for @mentions

• Troubleshooting - Common errors and fixes

When NOT to Use Scripts

• Simple page reads → Use MCP directly

• No images/diagrams, small content (<10KB) → MCP may work

• Jira issues → Use Jira-specific tools