Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
type
skill
lifecycle
stable
name
lint-clean-markdown
description
Write markdown that passes markdownlint on first attempt — encode the most common rules as muscle memory
tier
standard
inheritance
inheritable
applyTo
**/*.md
currency
2026-05-01T00:00:00.000Z
lastReviewed
2026-05-01T00:00:00.000Z
Lint-Clean Markdown
Eliminate the edit-lint-fix cycle by writing markdown correctly the first time.
When to Use
Authoring any markdown file in this brain or in heir documentation
Reviewing a PR that touches .md files
The file just hit MD031, MD032, MD022, or MD060 errors
The Golden Rule
When in doubt: add a blank line.
Roughly 90% of markdown lint errors are missing blank lines. Lists, code blocks, and headings all need breathing room.
Core Rules Quick Reference
Rule
Code
Pattern
Mnemonic
Blank lines around lists
MD032
\n- item\n- item\n
"Lists breathe"
Blank lines around fences
MD031
\n\``code```\n`
"Code breathes"
Blank line before headings
MD022
text\n\n## Head
"Headers breathe"
Use dash for lists
MD004
- not * or +
"Dash dash dash"
No trailing whitespace
MD009
No spaces at line end
"Clean endings"
Hard line break in prose
(no MD code)
End line with \ then newline
"Backslash breaks"
Single final newline
MD047
One \n at EOF
"One newline"
Language on fences
MD040
```js not ```
"Name your code"
Consistent fence style
MD046
Use ``` not indent
"Fences only"
No bold as heading
MD036
Use ## not **text**
"Headers are headers"
Table separator spacing
MD060
Space around pipes
"Tables breathe too"
Rule Details
MD032: Blank Lines Around Lists
❌ Wrong: text immediately before/after list
✅ Correct: blank line before first - AND after last -
**Why**:
- Reason one
- Reason two
**Result**: Something
MD031: Blank Lines Around Code Blocks
❌ Wrong: text touching the fence markers
✅ Correct: blank line before opening ``` AND after closing ```
MD022: Blank Lines Before Headings
❌ Wrong: Some text.\n## Heading
✅ Correct: Some text.\n\n## Heading
Hard Line Breaks in Prose (the metadata-block trap)
The problem: Markdown collapses consecutive lines into one wrapped paragraph. A block of metadata like **Date**:, **Author**:, **Status**: on consecutive lines renders as one run-on sentence unless you force breaks.
The wrong fixes:
Two trailing spaces (text ) — works in most renderers, but lints as MD009 (no trailing whitespace) and is invisible in source review.
Empty lines between every item — turns the metadata block into a wall of paragraphs with massive vertical spacing.
<br/> tag — works but mixes HTML into prose markdown; flagged as MD033 in many configs.
The right fix: end each line with a backslash (\) followed by a newline. This is the CommonMark hard-line-break form. Renders identically to two spaces, but is visible in source review and lints clean.
Note the spacing: one space before the backslash, then the newline. The last line in the block does not need the backslash (no break needed after the final line).
When this rule fires:
Document metadata blocks (Date / Author / Status / Audience / Trigger) at the top of decision docs, ADRs, READMEs
Address blocks, contact-info blocks
Any list of consecutive **Label**: value lines that should visually be separate but should not have full paragraph spacing between them
Poetry, lyrics, or any prose where line breaks are semantic
When this rule does NOT fire:
Inside a real Markdown list (use - or 1. instead)
Inside a table (use <br/> for in-cell line breaks)
Inside a code fence (literal newlines work; no special handling needed)
MD004: Use Dash for Unordered Lists
❌ Wrong: * item or + item
✅ Correct: - item
MD040: Specify Language on Fenced Code
❌ Wrong: ``` (no language)
✅ Correct: ```javascript or ```text or ```markdown
Mermaid-Specific Rules
Template Blocks Use text
When showing a template/pattern (not a renderable diagram), use ```text instead of ```mermaid. The Mermaid parser will fail on placeholder text like [DIAGRAM_TYPE].
Diagram Type Required
Every ```mermaid block must declare its diagram type on the first line (flowchart TB, sequenceDiagram, etc.) — otherwise it renders blank.
Nested Code Block Problem
You cannot nest fenced code blocks in markdown. When documenting code-block rules:
Use inline code for short examples: `js`
Use descriptions instead of showing wrong examples literally
Use single examples showing only the correct form
This skill itself demonstrates the solution.
Pre-Write Mental Checklist
Before writing markdown, plan for:
☐ Will I have lists? → blank lines around them
☐ Will I have code blocks? → blank lines around them
☐ Will I show "wrong" examples? → can't nest fences, describe instead
☐ Will I have tables? → need | ---- | separator row
