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
| 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-runMCP 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 123456789See Downloading Guide for details.
Upload Pages with Images
- Convert diagrams to images first using
design-doc-mermaidorplantumlskills - Reference images with standard markdown:
 - Upload via REST API:
python3 ~/.claude/skills/confluence/scripts/upload_confluence_v2.py \
document.md --id PAGE_IDSee 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 firstSee 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