Markdown formatting

Skill britt/agent-skills/skills/markdown-formatting

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 templatesFrom its SKILL.md

Install

npx -y skills add britt/agent-skills --skill markdown-formatting

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.1 KB, as published. Nobody here has run it

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

Lead with the point - TL;DR or summary first, details after
Use structure - Headings, lists, and whitespace aid scanning
Be consistent - Same patterns across all outputs
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

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