# Markdown Formatting

> Format AI outputs into consistent, readable Markdown for PRs, issues, docs, and notes Use when this capability is needed.

- Skill: `tomevault-io/markdown-formatting` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/markdown-formatting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/markdown-formatting/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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
- Any structured text output

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

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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/britt) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->