markdown-formatting

---
name: markdown-formatting
description: "Use when writing PR descriptions, issue bodies, documentation, or notes - applies consistent Markdown conventions (heading levels, list markers, code-block languages, link text) and provides PR and issue templates"
---

# 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

```markdown
## Summary

[One-line description of the change]

## Changes

- [Change 1]
- [Change 2]

## Test Plan

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

### Issue Body

```markdown
## Problem

[What is wrong or missing]

## Steps to Reproduce

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

## Expected

[What should happen]

## Actual

[What actually happens]
```

## Example: Filled-in PR Description

```markdown
## Summary

Add retry with exponential backoff to the `fetchUser` API client.

## Changes

- Wrap `fetchUser` in a retry helper (3 attempts, 200ms base delay)
- Surface a `RetryExhaustedError` after the final attempt
- Add unit tests covering success-after-retry and exhaustion paths

## Test Plan

- [x] `npm test` passes, including new `retry.test.ts` cases
- [x] Manual check: killed the mock server mid-request, saw retries in logs (#87)
```

Note the applied rules: `##` headings, `-` list markers, backticks for code identifiers, `#87` issue reference, and a one-line summary leading the document.

## Anti-patterns

- Walls of text without structure
- Inconsistent list markers (`*`, `-`, `+` mixed)
- Code blocks without language identifiers
- Headings used as emphasis
- Trailing whitespace or excessive blank lines