Use md-to-confluence

Turn a Markdown runbook, design note or guide into a Confluence page

Turn a Markdown runbook, design note or guide into a Confluence page: storage-format XHTML with real code blocks, tables, tasks, info and warning panels, images as attachments and an optional contents macro, a warning for everything dropped, and an optional publish that first shows which page it will create or overwrite and at what version, refuses stale or wrong-space overwrites, and takes credentials only from the environment.

Reach for it when the user says "put this in Confluence", "publish this markdown to the wiki", "update the Confluence page with this", "convert to Confluence storage format", or names a Confluence space for a Markdown file.

Install it

npx skilldrop-cli install md-to-confluence                 # Claude Code, your user folder
npx skilldrop-cli install md-to-confluence --project       # Claude Code, this repo
npx skilldrop-cli install md-to-confluence --ide cursor    # or kiro, codex, antigravity, copilot

It is part of the Converters pack: --pack converters installs it with its neighbours.

It ships scripts, so it needs Python 3 (standard library only, nothing to install). What they may touch is declared in its manifest.

Ask for it

Say it the way you would to a colleague. Requests like these route to it:

• "put this runbook in Confluence under the SRE space"
• "Convert README.md to Confluence storage format so I can paste it into the source editor"
• "Publish design-notes.md as a wiki page under Architecture on our atlassian site"
• "update Confluence page 48213 with the new deploy-checklist.md"
• "our team docs live in Confluence, can you get this markdown onto a page with the code blocks looking right"

Requests like these belong to a different skill, so it shouldn't answer them:

• "Convert this markdown to a Word document legal can track changes in"
• "Turn the markdown report into a single HTML file I can email"
• "Create Jira epics and issues from this PRD"

If another skill answers instead, ask for this one by name: "use md-to-confluence".

Check what you get

A good result:

• The right page, said out loud. Every publish is preceded by the page id, title, space, current version and last editor from a live check, and a yes.
• No silent overwrite. Updates carry --expected-version; a newer version stops the run.
• Nothing lost silently. Each WARN is fixed in the source or named in the reply; rollback steps in HTML are rewritten, not dropped.
• Images are listed by attachment name, with any missing file or name clash called out before publishing.
• Code survives byte for byte, including a ]]> inside it; the script checks the page is well-formed.
• Tokens never appear in a command, a file or the reply.
• Facts untouched. Restructuring Markdown never changes a command, threshold, name or date.

See a worked example

• queue runbook

Use something else when

• A Word file to edit with tracked changes; use md-to-docx
• Jira epics and issues from a PRD; use tracker-brief-sync
• Writing the runbook itself; use runbook-generator, then convert

Next

• SKILL.md, the instructions the agent reads
• Its page on the site
• Related: md-to-docx, runbook-generator, tracker-brief-sync

Edit this page on GitHub · View source