home / skills / beshkenadze / claude-skills-marketplace / markdown-formatter

markdown-formatter skill

safe

This skill formats and structures content into clean Markdown with headings, lists, and code blocks to produce ready documentation.

npx playbooks add skill beshkenadze/claude-skills-marketplace --skill markdown-formatter

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.2 KB

---
name: markdown-formatter
description: Format and structure content as clean, well-organized Markdown. Use when asked to create documentation, format text, or generate Markdown output.
version: 1.0.0
---

# Markdown Formatter

## Overview

Transforms unstructured content into clean, well-organized Markdown with proper headings, lists, code blocks, and formatting.

## Instructions

When formatting content to Markdown:

1. **Analyze the content** to identify structure (headings, lists, code, etc.)
2. **Apply hierarchy** using appropriate heading levels (H1 for title, H2 for sections)
3. **Format code** with proper language-specific syntax highlighting
4. **Create lists** for related items (bullet for unordered, numbers for sequential)
5. **Add tables** for structured data comparisons

## Formatting Rules

### Headings
- H1 (`#`) - Document title only
- H2 (`##`) - Major sections
- H3 (`###`) - Subsections
- H4+ - Avoid unless necessary

### Code Blocks
- Inline code: Single backticks for short references
- Fenced blocks: Triple backticks with language identifier

### Lists
- Bullet lists: Related but unordered items
- Numbered lists: Sequential steps or ranked items
- Nested lists: Maximum 2 levels deep

## Examples

### Example: Format API Documentation

**Input:**
"Document the getUser function that takes userId string and returns User object with name email and createdAt fields"

**Output:**
```markdown
## `getUser(userId)`

Retrieves a user by their unique identifier.

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `userId` | `string` | The unique user identifier |

### Returns

`User` object with the following properties:

- `name` - User's display name
- `email` - User's email address
- `createdAt` - Account creation timestamp
```

## Guidelines

### Do
- Keep line length under 100 characters
- Use blank lines to separate sections
- Prefer ATX-style headings (`#`) over Setext
- Use reference-style links for repeated URLs
- Include language identifier in fenced code blocks

### Don't
- Use more than 3 heading levels unless necessary
- Mix heading styles in same document
- Create deeply nested lists (max 2 levels)
- Use HTML tags when Markdown suffices

Overview

This skill formats and structures content into clean, well-organized Markdown for documentation, READMEs, API references, and notes. It enforces consistent heading hierarchy, code block syntax, lists, and tables to produce readable, reusable Markdown output.

How this skill works

The formatter analyzes raw text to detect titles, section breaks, lists, code samples, and tabular data. It maps structure to ATX headings, converts code to fenced blocks with language identifiers, transforms sequences into numbered lists and related items into bullets, and generates Markdown tables for structured data. It also applies style rules like line-length limits, blank lines between sections, and limits on heading depth and nesting.

When to use it

Creating or polishing documentation and READMEs
Converting notes, transcripts, or unstructured text into Markdown
Formatting API docs, function signatures, and parameter tables
Preparing example code blocks with correct language tagging
Generating Markdown for static sites, wikis, or knowledge bases

Best practices

Use H1 only for the document title and H2 for major sections
Include a language identifier on all fenced code blocks
Keep lines under 100 characters for readability
Limit heading levels to three and nested lists to two levels
Separate logical blocks with a blank line and prefer ATX-style headings

Example use cases

Document a function: produce signature, parameters table, and return value section
Turn meeting notes into a structured README with headings and action-item lists
Convert tutorial content into step-by-step numbered procedures with code samples
Create a comparison table for features or configuration options
Format a changelog entry with version heading and bullet highlights

FAQ

Will the formatter change prose tone or content?

No. It restructures and formats the existing content into Markdown without rewriting intent or meaning, unless asked to edit wording.

How are code snippets handled?

Code is placed into fenced blocks with an appropriate language tag when detected; short inline code uses single backticks.