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