---

name: confluence description: Manage Confluence documentation with downloads, uploads, conversions, and diagrams. Use when asked to "download Confluence pages", "upload to Confluence", "convert Wiki Markup", "sync markdown to Confluence", "create Confluence page", or "handle Confluence images".

Confluence Management Skill

Manage Confluence documentation through Claude Code: download pages to Markdown, upload large documents with images, convert between formats, and integrate Mermaid/PlantUML diagrams.

Table of Contents

• Quick Decision Matrix
• MCP Size Limits
• Prerequisites
• Core Workflows
• Reference Documentation

Quick Decision Matrix

| Task | Tool | Notes | |------|------|-------| | Read pages | MCP tools | confluence_get_page, confluence_search | | Small text-only uploads (<10KB) | MCP tools | confluence_create_page, confluence_update_page | | Large documents (>10KB) | upload_confluence_v2.py | REST API, no size limits | | Documents with images | upload_confluence_v2.py | Handles attachments automatically | | Git-to-Confluence sync | mark CLI | Best for CI/CD workflows | | Download pages to Markdown | download_confluence.py | Converts macros, downloads attachments |

MCP Size Limits

MCP tools have size limits (10-20KB) for uploads. For large documents or pages with images, use the REST API via upload_confluence_v2.py:

# Upload large document
python3 ~/.claude/skills/confluence/scripts/upload_confluence_v2.py \
    document.md --id 780369923

# Dry-run preview
python3 ~/.claude/skills/confluence/scripts/upload_confluence_v2.py \
    document.md --id 780369923 --dry-run

MCP works for reading pages but not for uploading large content.

Prerequisites

Required

• Atlassian MCP Server (mcp__atlassian-evinova) with Confluence credentials

Optional

• mark CLI: Git-to-Confluence sync (brew install kovetskiy/mark/mark)
• Mermaid CLI: Diagram rendering (npm install -g @mermaid-js/mermaid-cli)

Core Workflows

Download Pages to Markdown

# Single page
python3 ~/.claude/skills/confluence/scripts/download_confluence.py 123456789

# With child pages
python3 ~/.claude/skills/confluence/scripts/download_confluence.py --download-children 123456789

# Custom output directory
python3 ~/.claude/skills/confluence/scripts/download_confluence.py --output-dir ./docs 123456789

See Downloading Guide for details.

Upload Pages with Images

1. Convert diagrams to images first using design-doc-mermaid or plantuml skills
2. Reference images with standard markdown: ![Description](./images/diagram.png)
3. Upload via REST API:

python3 ~/.claude/skills/confluence/scripts/upload_confluence_v2.py \
    document.md --id PAGE_ID

See Image Handling Best Practices for details.

Search Confluence

mcp__atlassian-evinova__confluence_search({
  query: 'space = "DEV" AND text ~ "API"',
  limit: 10
})

Create/Update Pages (Small Documents)

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

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

Sync from Git (mark CLI)

Add metadata to Markdown files:

<!-- Space: DEV -->
<!-- Parent: Documentation -->
<!-- Title: API Guide -->

# API Guide
Content...

Sync to Confluence:

mark -f documentation.md
mark --dry-run -f documentation.md  # Preview first

See mark Tool Guide for details.

Convert Between Formats

See Conversion Guide for the complete conversion matrix.

Quick reference:

| Markdown | Wiki Markup | |----------|-------------| | # Heading | h1. Heading | | **bold** | *bold* | | *italic* | _italic_ | | `code` | {{code}} | | [text](url) | [text\|url] |

Reference Documentation

Detailed guides in the references/ directory:

| Guide | Purpose | |-------|---------| | Wiki Markup Reference | Complete syntax for Confluence Wiki Markup | | Conversion Guide | Markdown to Wiki Markup conversion rules | | Storage Format | Confluence XML storage format details | | Image Handling | Workflows for images, Mermaid, PlantUML | | mark Tool Guide | Git-to-Confluence sync with mark CLI | | Troubleshooting | Common errors and solutions |

Available MCP Tools

| Tool | Description | |------|-------------| | confluence_search | Search using CQL or text | | confluence_get_page | Retrieve page by ID or title | | confluence_create_page | Create new page | | confluence_update_page | Update existing page | | confluence_delete_page | Delete page | | confluence_get_page_children | Get child pages | | confluence_add_label | Add label to page | | confluence_get_labels | Get page labels | | confluence_add_comment | Add comment to page | | confluence_get_comments | Get page comments |

Utility Scripts

| Script | Purpose | |--------|---------| | scripts/upload_confluence_v2.py | Upload large documents with images | | scripts/download_confluence.py | Download pages to Markdown | | scripts/convert_markdown_to_wiki.py | Convert Markdown to Wiki Markup | | scripts/convert_wiki_to_markdown.py | Convert Wiki Markup to Markdown | | scripts/render_mermaid.py | Render Mermaid diagrams |

---

Version: 2.1.0 | Last Updated: 2025-01-21