spillwavesolutions/mastering-confluence-agent-skill
Overview
This skill provides comprehensive Confluence documentation management for uploading, downloading, converting, and syncing content. It handles Markdown↔Wiki conversion, diagram rendering (Mermaid/PlantUML), image attachments, large document uploads without MCP size limits, and Git-to-Confluence sync via mark CLI. Use it to automate reliable Confluence workflows and avoid common upload pitfalls.
How this skill works
The skill wraps a set of scripts and utilities to interact with Confluence REST APIs instead of MCP for uploads, ensuring no practical size limits and proper attachment handling. It converts Markdown to Confluence Wiki or storage formats, renders diagrams to PNG/SVG, embeds images using markdown syntax, and supports CQL searches and downloads (including child pages and attachments). Authentication and upload logic are centralized so uploads include attachments and metadata correctly.
When to use it
- Upload Markdown documents with images or diagrams to Confluence (large files supported)
- Create or update Confluence pages programmatically and preserve attachments
- Download pages and page trees to Markdown with attachments and frontmatter
- Convert Markdown to Confluence Wiki Markup or storage format for manual editing
- Search Confluence with CQL queries to locate pages or content
- Synchronize a Git documentation repo to Confluence using mark CLI
Best practices
- Always run the upload script with --dry-run first to validate output
- Convert Mermaid/PlantUML diagrams to PNG/SVG before upload and reference with markdown image syntax
- Do not use MCP tools for uploading large content; use the v2 upload script that uses REST API
- Ensure .env credentials and Page IDs are correct; include parent-id for new pages to preserve hierarchy
- Verify attachments exist locally and are referenced with relative paths in the markdown
Example use cases
- Mass-migrate a documentation directory from GitHub to Confluence with images and diagrams preserved
- Automate nightly sync of a docs branch to Confluence via mark CLI and generated metadata
- Export a Confluence space subtree to a local Markdown archive with attachments for offline editing
- Convert developer README files to Confluence Wiki Markup for internal publishing
- Run targeted CQL searches to find pages that mention APIs and bulk-update them
FAQ
MCP upload tools impose strict size limits and can HTML-escape Confluence XML. The upload_v2 script uses REST APIs and handles large content and attachments reliably.
How do diagrams get handled?
Convert Mermaid and PlantUML to PNG/SVG using provided render scripts or CLI tools, reference them with standard markdown image syntax, and the upload script will attach them to the page.
