Atlassian Document Format (ADF) Writer

Jira and Confluence Cloud APIs do not accept Markdown or HTML for rich-text fields. They require ADF — a JSON tree of typed nodes loosely modelled on ProseMirror. Pasting Markdown into a Jira description field via the API will be stored as literal characters, not formatted text. This skill is your reference for producing valid ADF.

When this skill kicks in

Whenever a task touches a rich-text field on Jira or Confluence — issue descriptions, comments, page bodies, custom-field text, work-log comments, etc. — the body must be ADF. The user often won't say "ADF" explicitly; they'll say "write the description" or "add a comment". Treat that as the trigger.

If the user only wants the Markdown source (e.g., to paste into the Jira UI manually, where the editor will convert it), produce Markdown instead — but say so explicitly so they know the difference. The default for anything API-bound is ADF.

Top-level shape

Every ADF document is a doc node with version: 1: