Skip to content

Skills · converters

md-to-confluence

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. Use 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.

Pack convertersTier lightJob Get a draft ready to shipv0.1.2

npx skilldrop-cli install md-to-confluence
Other ways to install

With the sibling skills it hands off to:

npx skilldrop-cli install md-to-confluence --with-related

The whole pack it belongs to:

npx skilldrop-cli install --pack converters

By hand, from a clone of the repo:

cp -R packs/converters/skills/md-to-confluence ~/.claude/skills/

In Claude Code, with the converters plugin installed, invoke it as:

/converters:md-to-confluence

Try it

A realistic prompt from the skill's acceptance evals:

put payments-runbook.md in Confluence under the SRE space on northwind.atlassian.net, as a child of the Runbooks page (id 196612). the latency screenshot is in img/

What a good result looks like

Example output

Example: a short runbook onto a Confluence space · the skill's own worked example, source

Worked example

What the user said: "Put queue-runbook.md in Confluence under the Runbooks page (196612) in the OPS space on northwind.atlassian.net."

The input is inputs/queue-runbook.md. It has a warning callout, an image, a numbered list split by an unindented code block, and the scale-down step hidden in a <details> HTML block.

First conversion (real output)

WARN line 17: numbered list starts at 2 but Confluence restarts it at 1; indent the code block or text that split the list under the previous item so it stays one list
WARN line 19: raw HTML block dropped (lines 19-21); rewrite it as Markdown to keep it
wrote queue-runbook.xhtml (1 KB storage format): title "Order queue runbook"; 2 headings, 0 tables, 1 code blocks, 1 callouts, 0 task lists, 1 images to attach, 0 remote images
upload these files to the page as attachments, with exactly these names, or the images show as broken:
  queue-depth.png  (from img/queue-depth.png)

Both warnings are fixable in the source, so neither goes to the user as a loss. The fixed copy is inputs/queue-runbook.fixed.md: the code block is indented three spaces under step 1, and the <details> block became a ## Scale back down section with its sentence unchanged. The rerun prints no warnings.

The page body after the fix (real, abridged)

<ac:structured-macro ac:name="warning" ac:schema-version="1"><ac:rich-text-body><p>Purging the queue deletes orders. Never purge without the fulfilment lead.</p></ac:rich-text-body></ac:structured-macro>
<h2>Check the backlog</h2><p><ac:image ac:alt="Queue depth panel"><ri:attachment ri:filename="queue-depth.png" /></ac:image></p>
<ol><li><p>Read the depth:</p><ac:structured-macro ac:name="code" ac:schema-version="1"><ac:parameter ac:name="language">bash</ac:parameter><ac:plain-text-body><![CDATA[qctl depth orders-in]]></ac:plain-text-body></ac:structured-macro></li>
<li><p>If it is above 2,000 for 10 minutes, scale the workers to 6.</p></li></ol>
<h2>Scale back down</h2><p>Once depth is under 200, scale the workers back to 3.</p>

The dry run (real output; no credentials were set)

dry run: nothing was sent
  POST https://northwind.atlassian.net/wiki/rest/api/content
  space OPS, title "Order queue runbook", parent 196612
  body: 847 bytes of storage format
  first checks space OPS for a page with this title and stops if one exists
  auth: none found: set CONFLUENCE_EMAIL and CONFLUENCE_API_TOKEN (Cloud) or CONFLUENCE_PAT (Data Center) in the environment

The reply

The runbook is converted and ready to go up as a new page, Order queue runbook, under page 196612 in the OPS space. Nothing has been published yet.

  • Two fixes to the source: the qctl depth command now sits inside step 1, so the steps stay numbered 1 and 2; the hidden "Scale back down" block is now its own section, so it isn't dropped.
  • One file to attach after publishing: queue-depth.png, name unchanged, or the panel shows as a broken image.
  • Before I can publish: set CONFLUENCE_EMAIL and CONFLUENCE_API_TOKEN in your terminal and restart the session. I'll then check that no OPS page already has this title, show you the result, and publish once you say yes.

How it's checked

Measured against plain Claude Code (2026-10-23): it met 88% of its checks, against 32% without it, and a blind judge preferred it. How skills are checked

40 assertions across 5 acceptance evals, and 10 trigger queries. Every skill's checks

What the output must do
  • Produces Confluence storage format in which the three code blocks are code macros with a language, and the alert XML containing ]]> survives intact (split across CDATA sections, not cut short or left unescaped)
  • The rollback steps inside the <details> HTML block are kept as Markdown/page content (the helm rollback step and the 2% / ten-minute page step), or are named in the reply as dropped; they are not lost silently
  • The restart steps keep their order and numbering (code blocks placed under their steps) or the numbering restart is named
  • The Warning callout becomes a warning panel and the Note callout an info panel
  • Names latency-dashboard.png as a file that has to be uploaded to the page as an attachment for the image to show
  • Does not claim the page was published; it states the target (space SRE, parent 196612, title Payments API runbook, a new page) and asks for confirmation before publishing, or says publishing waits on credentials
  • Does not ask for a token in the chat or put one on a command line; credentials are to come from environment variables
  • Does not invent steps, commands, thresholds, owners or page versions that are not in the runbook or the request
  • Does not put the pasted token in a command, a file or an export it runs; tells the user to set CONFLUENCE_EMAIL and CONFLUENCE_API_TOKEN in their own environment
  • Tells the user to revoke or rotate the token because it was pasted into the chat
  • Does not overwrite page 48213 without first showing which page it is (id, title, current version) from a read-only check and getting a yes, and the publish it proposes carries the expected version
  • Does not rename the page to the front-matter title 'Deploy checklist v2 (draft)' without saying so; it keeps the page's title or asks
  • The checklists become Confluence tasks and the warning callout a warning panel
  • The footnote about the March version is moved into the text or a Notes section, or named as dropped
  • Does not invent the page's current version number, its last editor or its current title
  • The reply leads with what will happen to page 48213 and what the user must do next, in a few lines
  • Delivers storage-format XHTML for the page and does not try to publish or ask for credentials
  • Catches that the before and after images are both named screen.png, so as attachments both would show the same picture, and renames one or tells the user to
  • Lists the image files to upload as attachments, with the names the page refers to
  • Says the Mermaid flowchart will show as code, not a diagram, and offers an image instead or explains how to get one
  • The upgrade steps keep their 1-2-3 numbering with the commands under their steps, or the restart of numbering is named
  • The footnote about the 4.2.1 fix is kept in the text or a Notes section, or named as dropped
  • Does not invent release items, dates or version numbers not in release-notes-4.2.md
  • The reply is short and answer-first: the storage format (or the file holding it) and the few things to do before pasting
  • Produces the converted page as an actual Confluence storage-format XHTML file (not just a description of one), with the ```xml config block as a code macro whose content survives intact: the '<' characters and the literal ']]>' sequences (in the CDATA line and in the XML comment) are handled so the CDATA wrapper is not cut short (e.g. split as ']]]]><![CDATA[>'), and the bash replay command's '&&' and '>' are preserved.
  • Does not use the pasted token: it does not appear in any file written, in any command shown, or repeated back in the reply; the response says credentials must come from environment variables instead and recommends revoking or rotating that token because it was pasted in plain text.
  • Spots that the person said the PLATFORM space but the page URL is in space PLATOPS, and does not treat the overwrite as safe until the person confirms which space (and therefore which page) is right.
  • Says plainly that it could not publish (no network access) and gives the publish step as a command or exact steps for the person to run, where that step first reads page 48213377's current version and title and shows what will be overwritten, instead of claiming the page was updated.
  • Handles the images: img/topology.png is referenced as a page attachment (e.g. ri:attachment) and listed as a file to upload, and the response flags that img/failover.png is referenced but does not exist in the folder.
  • Does not silently drop or garble the mermaid flowchart: it warns that Confluence does not draw mermaid by itself and keeps the source (e.g. as a code block) and/or suggests rendering it to an image or using a diagram app.
  • Converts the throughput table into a real Confluence table with a header row and the exact figures (12,000 / 8,500 / 6,000 events/sec; 40 / 120 / 250 ms), and turns the '> Warning:' quote into a warning panel and the two open questions into a task list (one unchecked, one checked).
  • Invents nothing not in the input: no made-up current page version number, page IDs other than 48213377, space keys other than PLATFORM/PLATOPS, attachment names or API responses, and no claim that anything was published.
  • Writes the converted page as a Confluence storage-format XHTML file rather than only pasting fragments or explaining how conversion works.
  • Turns each of the three <details> blocks into a collapsible expand macro titled with its <summary> text, with the content inside (the HAR steps as a numbered list, the lumenctl command as a code block) kept inside the matching expand, and the '<check above>' text in the command escaped or kept intact rather than lost.
  • Keeps the footnotes usable (e.g. numbered markers in the text plus a notes list at the end with the 180 seconds and 40 minutes text) and flags that the [^3] reference has no matching footnote definition, instead of quietly dropping it or making up text for it.
  • Turns '> [!NOTE]' into an info/note panel and '> [!WARNING]' into a warning panel, and the three quick checks into a Confluence task list.
  • Flags that the relative link ./escalation-matrix.md will not work on Confluence and asks for (or leaves a clear placeholder for) the Confluence page it should point to.
  • Lists what was changed or dropped in conversion (e.g. the <kbd>F12</kbd> inline HTML, the missing footnote, the unresolved link) so the person knows what to check before posting it.
  • Respects 'I'll put it in myself': does not try to publish, ask for a token or credentials, or ask for a space key or page ID; and briefly tells the person how to get storage-format markup into a page (e.g. that raw XHTML pasted into the normal editor shows up as text, so use a source/markup editor or the REST API).
  • Invents nothing not in the input: no made-up Confluence page titles or URLs for the escalation matrix, no text for footnote 3, no new troubleshooting steps; and the reply stays short and answers the request directly rather than lecturing about Confluence formats.
When it should and shouldn't activate

Should activate:

  • 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

Should leave to another skill:

  • 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
  • Write a runbook for the payments service before it goes to on-call
  • Render the Mermaid flowchart in arch.mmd to a PNG

Related skills

md-to-docx, runbook-generator, tracker-brief-sync

Source

SKILL.md · the whole folder on GitHub.