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

Core Workflows

📖 Reading Confluence Pages from URLs

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

Workflow

1. 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

2. Resolve to page ID:

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

3. 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

1. Read page via MCP
2. Auto-detect macros
3. Choose mode: Safe (edit outside macros) or Advanced (edit inside macros)
4. Auto-backup to .confluence_backups/{page_id}/
5. Claude edits based on instruction
6. 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

1. Convert diagrams (if Mermaid/PlantUML):

   # Mermaid
   mmdc -i diagram.mmd -o diagram.png -b transparent
   # PlantUML
   plantuml diagram.puml -tpng
   

2. Reference in markdown (always use markdown syntax):

   ![Architecture Diagram](./diagrams/architecture.png)
   

3. Upload (script handles attachments):

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

Common Mistakes

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)

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