md-format Skill

A simple tool to fix messy markdown files automatically.

Why Use This?

When AI generates markdown or you write documentation, the output often has issues:

• Tables that don't align properly
• Missing blank lines between sections
• Inconsistent spacing around headings
• Lists that look squished together

This skill fixes all of these problems automatically using Prettier, the same tool used by professional developers worldwide.

Quick Installation

Option 1: Install as a Claude Code Skill (Recommended)

1. Clone this repository to your Claude skills directory:

   git clone https://github.com/ossipoff/md-format.git ~/.claude/skills/md-format

2. The skill is now ready to use! You can invoke it directly in Claude Code with /md-format.

For agents: Always trigger via /md-format or python scripts/format_and_lint.py. Do not run prettier or markdownlint-cli directly — they are internal implementation details.

Option 2: Use the Python Script Directly

If you just want to format markdown files without installing as a skill:

# Format a file (check mode - shows what needs fixing)
python scripts/format_and_lint.py path/to/file.md

# Auto-fix and save changes
python scripts/format_and_lint.py --fix path/to/file.md

What It Does

The skill automatically fixes common markdown problems:

Before:

|Name|Age|City|
|---|---|---|
|John|25|NYC|

After:

| Name | Age | City |
| ---- | --- | ---- |
| John | 25  | NYC  |

It also adds missing blank lines, aligns tables, and ensures consistent spacing throughout your document.

How It Helps You

• Saves time: No more manual formatting of tables and lists
• Improves readability: Clean, professional-looking documentation
• Reduces errors: Consistent formatting prevents mistakes
• Works automatically: Set up once, forget about it

Automatic Formatting Setup

Want markdown files to be formatted automatically every time you write them? Here's how:

The skill repository includes two hook scripts — pick the one for your platform:

Platform	Hook script	Extra requirement
Linux / macOS	hooks/md-format-hook.sh (bash)	jq
Windows	hooks/md-format-hook.ps1 (PowerShell)	none

Add a PostToolUse hook to your ~/.claude/settings.json.

Linux / macOS:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "/home/YOUR_USERNAME/.claude/skills/md-format/hooks/md-format-hook.sh"
          }
        ]
      }
    ]
  }
}

Windows:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "powershell -ExecutionPolicy Bypass -File C:/Users/YOUR_USERNAME/.claude/skills/md-format/hooks/md-format-hook.ps1"
          }
        ]
      }
    ]
  }
}

That's it! The hook will now format any .md file Claude writes or edits using the skill's Python script. Both hooks read the tool payload from stdin, skip anything that isn't an existing .md file, and always exit 0 so a formatting failure never blocks the edit.

Note: Replace YOUR_USERNAME with your actual username. Tilde (~) does NOT expand inside JSON config files — you must use a full absolute path. If you installed the skill elsewhere, adjust the path accordingly.

Troubleshooting: The hooks fail silently by design. If files stop getting formatted, run python scripts/format_and_lint.py --check <file.md> manually to see the error the hook swallowed.

Examples

Fix Broken Tables

Before:

|Product|Price|Stock|
|-------|-----|-----|
|Widget| $5 | 100 |
|Gadget|$10| 50 |

After:

| Product | Price | Stock |
| ------- | ----- | ----- |
| Widget  | $5    | 100   |
| Gadget  | $10   | 50    |

Add Missing Line Breaks

Before:

# Title## Subtitle

- Item 1
- Item 2

After:

# Title

## Subtitle

- Item 1
- Item 2

Requirements

• Node.js and npm (the script will auto-install Prettier and markdownlint-cli globally if needed)
• Python 3.x
• jq — only for the bash hook on Linux/macOS; the Windows PowerShell hook has no extra dependencies

Configuration

Ignore Files

By default, the skill will format all markdown files. If you want to skip certain files (like README.md or SKILL.md), create a .md-format-ignore file in your project:

# .md-format-ignore
README.md
SKILL.md
*.generated.md

One pattern per line. Lines starting with # are comments. The skill checks for this file automatically when formatting.

Linting with markdownlint-cli

The skill also checks your markdown for common issues using markdownlint-cli. This catches problems like:

• Trailing punctuation in headings (MD026)
• Inconsistent list numbering (MD029)
• Line length violations (MD013)
• And many other style issues

To fix linting issues automatically, use the --fix flag:

python scripts/format_and_lint.py --fix path/to/file.md

This runs both Prettier formatting AND markdownlint fixes in one command.

Customize Formatting

The skill uses sensible defaults, but you can customize:

• Create .prettierrc for custom formatting rules
• Use --technical flag for documents with code/equations (120 char lines)
• Use --print-width 100 to set custom line length

Getting Help

Run the skill directly in Claude Code with /md-format or check the SKILL.md file for detailed documentation.