markdown-formatting

Markdown Formatting Skill

Apply consistent Markdown formatting to all outputs. Structure content for readability and professionalism.

When to Use

Activate when producing:

• PR descriptions and issue bodies
• Documentation and guides
• Notes and summaries
• Structured artifacts that will be saved or published (reports, READMEs, changelogs)

Not for conversational chat replies — normal responses don't need templates or strict formatting rules.

Core Principles

1. Lead with the point - TL;DR or summary first, details after
2. Use structure - Headings, lists, and whitespace aid scanning
3. Be consistent - Same patterns across all outputs
4. Respect context - PRs need checklists, docs need examples

Formatting Rules

Document Structure

# Title (standalone documents only)

Brief summary or TL;DR (1-2 sentences)

## Section Heading

Content organized by topic...

Headings

• Use ## for main sections (reserve # for document title)
• Use ### sparingly for subsections
• Never skip levels (no ## to ####)

Lists

• Use - for unordered lists (not *)
• Use 1. for ordered/sequential steps
• Nest with 2-space indent
• Keep list items parallel in structure

Code

• Inline: backticks for commands, filenames, variables
• Blocks: triple backticks with language identifier
• Always specify language: typescript, bash, ```json

Emphasis

• Bold for key terms, warnings, important points
• Italics sparingly for emphasis or introducing terms
• Never combine bold and italics

Links

• Descriptive text: [installation guide](url) not [click here](url)
• Reference issues/PRs with #123 format

Templates

PR Description

## Summary

[One-line description of the change]

## Changes

- [Change 1]
- [Change 2]

## Test Plan

- [ ] [Test case 1]
- [ ] [Test case 2]

Issue Body

## Problem

[What is wrong or missing]

## Steps to Reproduce

1. [Step 1]
2. [Step 2]

## Expected

[What should happen]

## Actual

[What actually happens]