jira-formatting

name	jira-formatting
description	Format Jira comments and descriptions using Atlassian’s Text Formatting Notation. Use this skill to generate headings, lists, links, code blocks and other structures in Jira tickets.

Jira formatting skill

When asked to format text for a Jira ticket, follow these rules. They are based on Atlassian’s Text Formatting Notation help page and ensure your comments render correctly in the wiki renderer.

Headings

• Use prefixed notation h1., h2., …, h6. followed by a space and the heading text to create headings of decreasing size. Example:

h1. Release notes
h2. New features
h3. Bug fixes

Text effects

• Bold: wrap text in *asterisks*.
• Italic: wrap text in _underscores_.
• Citation: wrap text in ??double question marks??.
• Strikethrough: wrap text in -hyphens-.
• Underline/Inserted: wrap text in +pluses+.
• Superscript: wrap text in ^carets^.
• Subscript: wrap text in ~tildes~.
• Monospaced/code: wrap text in {{double curly braces}}.
• Block quote: start a line with bq. to quote a single paragraph.
• Multi‑paragraph quote: wrap paragraphs in {quote}…{quote}.
• Colour: wrap text in {color:name}…{color}. Replace name with a colour name or hex code, e.g. {color:red}important{color}.

Paragraphs and breaks

• An empty line starts a new paragraph.
• Use \\ at the end of a line to force a line break.
• Use ---- on its own line to insert a horizontal rule.
• Use --- to insert an em dash and -- for an en dash.

Links

• Internal anchors/attachments: [ #anchor ] or [ ^attachment.ext ] (without spaces) create links to anchors or attachments.
• External link: [http://example.com] creates a plain URL.
• External link with alias: [Text|http://example.com] displays Text as the link.
• Email: [mailto:[e-mail]] links to an email address.
• File: [file:///c:/path/to/file.txt] links to a local file.
• Anchor macro: {anchor:anchorName} defines a bookmark that you can link to with [#anchorName].
• User profile: [~username] links to a user’s profile page.

Lists

• Bulleted lists: start each line with *. Increase indentation by repeating the asterisk. Example:

* item one
* item two
** subitem
** another subitem
* item three

• Numbered lists: start each line with #. Increase indentation with additional # characters. Example:

# first item
# second item
## nested item
## nested item
# third item

• You can mix nested bullet and numbered lists. Keep the list markers (*, - or #) in the first column; leading spaces are ignored.

Images and attachments

• Embed images with !URL! or !attached-image.gif!. If the URL is fully qualified, the image is loaded remotely; otherwise it references an attached file.
• Create thumbnails with !image.jpg|thumbnail! (works with attached images only).
• Add attributes using a | followed by comma‑separated name=value pairs, e.g. !image.gif|align=right, vspace=4!.
• Embed media or other attachments with !filename.ext|width=300,height=400! and set properties such as width, height, and id. Supported formats include SWF, MOV, WMV, MP3 and others.

Tables

Use double pipes to define the header row and single pipes for subsequent rows. Example:

||Name||Priority||Status||
|Task A|High|In Progress|
|Task B|Medium|Done|

Advanced macros

• Preformatted text: wrap text in {noformat}…{noformat} to disable further formatting.

• Panels: use {panel}…{panel} to enclose text in a panel. Optional parameters include:

  • title: a panel title.
  • borderStyle: e.g. solid or dashed.
  • borderColor: e.g. #ccc.
  • borderWidth: e.g. 2px.
  • bgColor: background colour of the panel body.
  • titleBGColor: background colour of the title bar.

  Example:

  {panel:title=My Title|borderStyle=dashed|borderColor=#ccc|titleBGColor=#F7D6C1|bgColor=#FFFFCE}
  Important notes here.
  {panel}
  

• Code blocks: wrap code in {code}…{code}. You can specify a language (e.g. {code:python}) and any of the panel parameters above. Example:

  {code:java|title=Example.java|borderStyle=solid}
  // Java example
  public String getFoo() {
      return foo;
  }
  {code}
  

Miscellaneous

• Escape special characters by prefixing them with a backslash, e.g. \{ to produce { in the output.
• Jira supports a number of emoticons and status lozenges. Typing :), :P, (y), (n), (on), (off), (flag) and other variations inserts the corresponding graphical icon.

Usage

When formatting Jira content, apply these rules directly in your text. Claude will follow this guide when generating or editing Jira comments and descriptions. To invoke this skill manually, type /jira-formatting followed by the text you want formatted.