About md-lint
md-lint is a skill for formatting and checking Markdown documents. It runs markdownlint-cli2 and Prettier after edits, while distinguishing automatic fixes from issues that need manual changes.
Key features
- 01Runs Markdown formatting after edits
- 02Fixes common Markdown lint issues
- 03Identifies rules requiring manual edits
- 04Documents conforming Markdown conventions
Use cases
- 01Normalize Markdown after editing
- 02Check headings, whitespace, and links
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/md-lintin Claude Code to confirm it loaded.
Details
From the project READMESTARTER_CHARACTER = 🔏
Markdown Formatter Contract
A PostToolUse hook runs markdownlint-cli2 --fix and then prettier --write on every markdown file written or edited, excluding .llmtmp/, .llmdocs/, SKILL.md, and plan files. Writing to this contract avoids a rewrite, and a rewrite invalidates the in-context copy of the file.
What prettier rewrites
| Input | Output |
|---|---|
* item, + item | - item |
1) ordered marker | 1. |
*emphasis* | _emphasis_ |
__strong__ | **strong** |
*** thematic break | --- |
| Two or more blank lines | One blank line |
| Runs of spaces inside a line | Single space |
| Unpadded table cells | Cells padded to column width |
| No trailing newline | Trailing newline added |
Prose is not rewrapped. Long lines stay as written.
What markdownlint fixes
Missing space after #, missing blank lines around headings and fenced blocks, trailing whitespace, and bare URLs.
Four rules are off: MD013 (line length), MD024 (duplicate headings), MD029 (ordered list prefix), MD033 (inline HTML).
What neither can fix
These reach the model as hook feedback and need a manual edit:
- MD003, heading style. Setext headings underlined with
===or---are errors. Use ATX (#,##). - MD025, one H1 per document.
- MD045, images need alt text.
- MD042, links need a destination.
- MD040, fenced code blocks need a language.
Writing conforming markdown
Start with a single # Title. Use ATX headings, - bullets, _emphasis_, **strong**, one blank line between blocks, a language on every fence, alt text on every image, and a trailing newline.