SKILL.md
Confluence Management Skill
Type: Project | Version: 2.2.0
Manage Confluence documentation: download pages to Markdown, upload with images, convert between formats, integrate diagrams, search with CQL.
Contents
- [Critical Constraints](#critical-constraints)
- [Quick Start](#quick-start)
- [Core Capabilities](#core-capabilities)
- [Checklists](#checklists)
- [Reference Documentation](#reference-documentation)
- [Scripts](#scripts)
Critical Constraints
DO NOT USE MCP FOR PAGE UPLOADS - Size limits apply (~10-20KB max)
# Use REST API scripts instead:
python3 scripts/upload_confluence_v2.py document.md --id PAGE_IDMCP tools are fine for reading pages but fail for uploading large content.
Quick Start
Upload Markdown to Confluence
# Update existing page
python3 scripts/upload_confluence_v2.py document.md --id 780369923
# Create new page
python3 scripts/upload_confluence_v2.py document.md --space DEV --parent-id 123456
# Preview first (recommended)
python3 scripts/upload_confluence_v2.py document.md --id 780369923 --dry-runDownload Confluence to Markdown
# Single page
python3 scripts/download_confluence.py 123456789
# With child pages
python3 scripts/download_confluence.py --download-children 123456789
# Multiple pages
python3 scripts/download_confluence.py 123456 456789 789012Convert Markdown to Wiki Markup
python3 scripts/convert_markdown_to_wiki.py input.md output.wikiSearch Confluence (via MCP)
mcp__atlassian__confluence_search({
query: 'space = "DEV" AND text ~ "API" AND created >= startOfYear()'
})Core Capabilities
| Capability | Tool/Script | Reference |
|---|---|---|
| Upload pages with images | uploadconfluencev2.py |
[uploadguide](references/uploadguide.md) |
| Download pages to Markdown | download_confluence.py |
[downloadguide](references/downloadguide.md) |
| Convert Markdown ↔ Wiki | convertmarkdownto_wiki.py |
[conversionguide](references/conversionguide.md) |
| Search pages (CQL) | MCP confluence_search | [cqlreference](references/cqlreference.md) |
| Wiki Markup syntax | - | [wikimarkupguide](references/wikimarkupguide.md) |
| Render Mermaid diagrams | render_mermaid.py |
[imagehandling](references/imagehandlingbestpractices.md) |
| Git-to-Confluence sync | mark CLI | [marktoolguide](references/marktoolguide.md) |
| Troubleshooting | - | [troubleshootingguide](references/troubleshootingguide.md) |
Checklists
Upload Checklist
Copy and track progress:
Upload Progress:
- [ ] Diagrams converted to PNG/SVG (if Mermaid/PlantUML present)
- [ ] All images use markdown syntax: 
- [ ] No raw Confluence XML in markdown
- [ ] All image files verified to exist
- [ ] Dry-run tested: `--dry-run`
- [ ] Upload executed with v2 script (not MCP)
- [ ] Page URL verified accessibleDownload Checklist
Download Progress:
- [ ] Page ID obtained from Confluence URL
- [ ] Credentials configured in .env file
- [ ] Output directory specified
- [ ] --download-children flag set (if hierarchy needed)
- [ ] Download completed successfully
- [ ] Attachments downloaded to {Page}_attachments/
- [ ] Frontmatter contains correct metadataImage Handling
Standard Workflow:
- Convert diagrams (if Mermaid/PlantUML):
```bash # Mermaid mmdc -i diagram.mmd -o diagram.png -b transparent
# PlantUML plantuml diagram.puml -tpng ```
- Reference in markdown (always use markdown syntax):
``markdown  ``
- Upload (script handles attachments):
``bash python3 scripts/uploadconfluencev2.py document.md --id PAGE_ID ``
Common Mistakes:
- Using raw XML:
<ac:image>...- Gets HTML-escaped, appears as text - Using MCP for uploads - Size limits cause failures
- Forgetting to convert diagrams - Code blocks don't render
Reference Documentation
| Document | Purpose |
|---|---|
| [uploadguide.md](references/uploadguide.md) | Complete upload workflow |
| [downloadguide.md](references/downloadguide.md) | Complete download workflow |
| [wikimarkupguide.md](references/wikimarkupguide.md) | Wiki Markup syntax reference |
| [conversionguide.md](references/conversionguide.md) | Markdown ↔ Wiki Markup rules |
| [imagehandlingbestpractices.md](references/imagehandlingbestpractices.md) | Diagrams and images |
| [troubleshootingguide.md](references/troubleshootingguide.md) | Common errors and fixes |
| [marktoolguide.md](references/marktoolguide.md) | Git-to-Confluence sync |
| [confluencestorageformat.md](references/confluencestorageformat.md) | API storage format |
| [cqlreference.md](references/cqlreference.md) | CQL query syntax |
| [atlassianmcptools.md](references/atlassianmcptools.md) | MCP tool reference |
Scripts
| Script | Purpose |
|---|---|
uploadconfluencev2.py |
Upload Markdown with images (no size limits) |
download_confluence.py |
Download pages to Markdown with attachments |
convertmarkdownto_wiki.py |
Convert Markdown to Wiki Markup |
render_mermaid.py |
Render Mermaid diagrams to PNG/SVG |
generatemarkmetadata.py |
Generate mark CLI metadata headers |
confluence_auth.py |
Shared authentication utilities |
Dependencies
pip install atlassian-python-api md2cf python-dotenv PyYAML mistune \
requests markdownify beautifulsoup4Prerequisites
Required
- Atlassian MCP Server (
mcp__atlassian) with Confluence credentials
Optional
- mark CLI: Git-to-Confluence sync
``bash brew install kovetskiy/mark/mark ``
- Mermaid CLI: Diagram rendering
``bash npm install -g @mermaid-js/mermaid-cli ``
When Not to Use
- Simple page reads → Use MCP directly
- No images/diagrams, small content → MCP may work
- Jira issues → Use Jira-specific tools
Version: 2.2.0 | Last Updated: 2025-12-28