markdown-drafts

---
name: markdown-drafts
description: Use markdown formatting when drafting content intended for external systems (GitHub issues/PRs, Jira tickets, wiki pages, design docs, etc.) so formatting is preserved when the user copies it. Load this skill before producing any draft the user will paste elsewhere.
---

## Markdown Drafts

When the user asks you to draft, write, or compose content that will be copied into an external
system — GitHub issues, pull request descriptions, Jira tickets, wiki pages, design documents,
RFCs, or similar — **always use markdown syntax** so that formatting survives the copy-paste.

### When This Applies

- GitHub issues and pull request descriptions
- Jira ticket descriptions and comments
- Confluence / wiki page drafts
- Design documents and RFCs
- Slack messages (Slack renders a subset of markdown)
- Any content the user explicitly says will be copied elsewhere

### Formatting Rules

- Use `#`, `##`, `###` headers to create structure
- Use `-` or `*` for unordered lists, `1.` for ordered lists
- Use triple-backtick fenced code blocks with language tags (e.g., ` ```cpp `) for code
- Use `inline code` backticks for identifiers, file paths, commands, and config values
- Use `**bold**` for emphasis on key points and `_italic_` for secondary emphasis
- Use markdown tables when presenting structured comparisons or data
- Use `> blockquotes` for callouts, quoted text, or important notes
- Use `[link text](url)` for references — never bare URLs in running prose
- Use `---` horizontal rules to separate major sections when appropriate
- Use task lists (`- [ ]` / `- [x]`) when drafting action items or checklists
- Keep line lengths reasonable (e.g., 80-120 characters)

### Structure Guidelines

- Start with a concise summary paragraph before diving into details
- Use headers to break content into scannable sections
- Keep paragraphs short — walls of text are hard to scan in issue trackers
- Put the most important information first (inverted pyramid)
- End with next steps, open questions, or action items when relevant

### Rendering: Always Emit Raw Markdown

The chat interface renders markdown, which strips the raw syntax (`###`, `**`, `` ` ``, etc.) from
the output. Since these drafts are meant to be **copied and pasted** into external systems, the user
needs the raw markup characters preserved.

**Always wrap the entire draft in a fenced code block** so the chat interface displays it as literal
text. Use a plain triple-backtick fence (no language tag):

    ```
    ## My Heading

    - bullet one
    - **bold text** and `code`
    ```

This ensures the user sees and can copy the exact markdown source. Never render the draft as
formatted text outside a code fence — the markup will be silently consumed by the chat UI.

### What NOT To Do

- Do not render the draft as formatted markdown outside a code fence — the user will lose the syntax
- Do not use plain text formatting (e.g., ALL CAPS for headers, `====` underlines, manual indentation)
- Do not use HTML tags unless the target system requires them and markdown is insufficient
- Do not add emoji unless the user's draft style includes them or they explicitly request it
- Do not use common cliche AI-generated phrases, tropes, or filler content like tricolons,
  or generic intros/outros. Be concise and to the point.
- Do not include editorial comments or unsubstantiated claims. Stick to the facts and the user's
  instructions precisely. If you need to ask clarifying questions, do so instead of making assumptions.