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]

Example: Filled-in PR Description

## 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: britt
• Source: britt/claude-code-skills
• License: MIT
• Homepage: https://britt.github.io/claude-code-skills/

Install and usage instructions live in the source repository linked above.