---
name: slack-mrkdwn-format
source: https://app.decimal.ai/s/slack-mrkdwn-format@1/SKILL.md
source_sha256: 5e6bd6392b65
---

# Slack mrkdwn format

## Contract

Slack does NOT parse standard (CommonMark / GitHub) Markdown. It parses its own dialect,
**mrkdwn**, whose inline tokens differ. Apply this whenever the output is a message that will be
posted to a Slack channel, thread, or DM. The default Markdown a model reaches for renders in Slack
as broken literal text (you see `**bold**`, `## Heading`, and unclickable `[label](url)`).

## Rules (the exact token forms)

1. **Bold** = a SINGLE pair of asterisks: `*text*`. Never `**text**` (that prints two literal
   asterisks, no bold).
2. **Italic** = a pair of underscores: `_text_`. Never a single pair of asterisks (`*text*` is BOLD
   in Slack, not italic).
3. **Bold + italic** = nest them: `*_text_*`.
4. **Strikethrough** = a SINGLE pair of tildes: `~text~`. Never `~~text~~` (prints literal tildes).
5. **Inline code** = backticks: `` `text` `` (this one matches Markdown).
6. **Links** = `<url|visible label>`: the URL, a pipe, then the label, all inside angle brackets,
   e.g. `<https://example.com/dash|View dashboard>`. A bare URL needing no label is just `<url>`.
   Never the Markdown `[label](url)` form -- Slack prints it literally and the link is not clickable.
7. **Headings** = there are NONE. Slack has no `#`, `##`, or `###`. A section title is just a bold
   line: `*Section title*`, usually followed by a blank line. ALL-CAPS or a leading emoji can add
   weight, but never a markdown header mark.
8. **Bulleted list** = lines starting with `•` (preferred) or `-`. **Numbered list** = `1.`, `2.`.
9. **Block quote** = `> text` (matches Markdown). **Code block** = triple backticks (matches Markdown).
10. **Emoji** = colon shortcodes such as `:white_check_mark:`, `:warning:`, `:rocket:` (Unicode also
    renders). Shortcodes are the portable form.

Everything not listed (paragraphs, blank-line spacing) is plain text.

## Worked examples (Markdown default -> Slack mrkdwn)

- Bold: `**Deploy complete**`  ->  `*Deploy complete*`
- Italic: `*draft, do not ship*`  ->  `_draft, do not ship_`
- Link: `[Open the build](https://example.com/build/42)`  ->  `<https://example.com/build/42|Open the build>`
- Bare link: `https://example.com/status`  ->  `<https://example.com/status>`
- Heading: `## Release 9.4 notes`  ->  `*Release 9.4 notes*`
- Strikethrough: `~~9:00~~ moved to 10:30`  ->  `~9:00~ moved to 10:30`
- List label in bold: `- **Owner:** Dana`  ->  `• *Owner:* Dana`
- Numbered step: `1. **Build** then deploy`  ->  `1. *Build* then deploy`
- Quote: `> shipping is blocked` stays `> shipping is blocked` (matches Markdown)

A full message side by side -- LEFT is the wrong default, RIGHT renders correctly in Slack:

BEFORE (standard Markdown):
```
## **Build summary**

- **Status:** green
- *Owner:* Lee
- See the [run](https://example.com/run/9) -- ~~retry~~ passed on first try.
```
AFTER (Slack mrkdwn):
```
*Build summary*

• *Status:* green
• _Owner:_ Lee
• See the <https://example.com/run/9|run> -- ~retry~ passed on first try.
```

## Edge cases & exceptions

- **A title the user calls "a big header":** still no `#`. Use a bold line, optionally ALL CAPS:
  `*RELEASE STATUS*`.
- **Bold a single word mid-sentence:** wrap only that word, `*urgent*`, with no surrounding spaces
  inside the asterisks (`* urgent *` does not render).
- **A literal asterisk or underscore** (e.g. `2 * 3`, a filename `my_file`): Slack only formats
  matched pairs that hug non-space characters, so a lone `*` or an underscore inside a word is
  usually safe as-is; if it renders, wrap the run in inline code.
- **URL with no friendly label:** drop the pipe -- `<https://example.com>` -- do not invent a label.
- **Combining strike + replacement:** keep both on one line, `~old value~ new value`, so the change
  reads at a glance.
- **Nested emphasis:** to bold AND italicize, the underscores go inside the asterisks: `*_text_*`.
  The reverse (`_*text*_`) also renders, but pick one form and keep it consistent.
- **An email address or a word with an underscore** (e.g. `user_name`) can trigger accidental
  italics; if Slack swallows the underscores, wrap the token in inline code: `` `user_name` ``.

## Do / Don't

- DON'T `**bold**`  /  DO `*bold*`
- DON'T `*italic*`  /  DO `_italic_`
- DON'T `~~strike~~`  /  DO `~strike~`
- DON'T `[label](https://example.com)`  /  DO `<https://example.com|label>`
- DON'T `<https://example.com>` then `(label)`  /  DO put the label after a pipe: `<https://example.com|label>`
- DON'T `## Heading` or `### Subhead`  /  DO a bold line `*Heading*`
- DON'T paste GitHub-style `- [ ]` task boxes  /  DO `• :white_check_mark:` style bullets
- DON'T use `*` for italics and `_` for bold  /  DO the opposite: `*` bold, `_` italic

## Common mistakes (the base model's wrong defaults)

- Reflexively writing standard/GitHub Markdown because the task says "message" or "post" -- Slack is
  the one place that markup does not work.
- Using `**` for bold: the single most common failure; it renders as visible asterisks.
- Using `[text](url)`: renders literally; the link is dead.
- Using `##`/`###` for section titles: renders the hash marks literally.
- Using `~~` for strikethrough: renders literal tildes.
- Using `*word*` intending italics: in Slack that is BOLD; italics need underscores.

## Quick checklist

- [ ] Bold is `*single*`; no `**` anywhere.
- [ ] Italic is `_underscore_`; not single asterisks.
- [ ] Strikethrough is `~single~`; no `~~`.
- [ ] Links are `<url|label>` (or bare `<url>`); no `[label](url)`.
- [ ] No `#`/`##`/`###`; section titles are bold lines.