Markdown Validation Skill

Markdown Validation

Validate markdown files after writing or editing them.

Iron Law

Always run markdownlint after writing markdown. Fix ALL errors before proceeding.

This is not optional. This is not negotiable. Markdown files that fail linting create inconsistency and maintenance burden.

Workflow

Write/Edit markdown file
        │
        ▼
Run markdownlint on file
        │
        ▼
    ┌───────────┐
    │  Errors?  │
    └───────────┘
        │
   ┌────┴────┐
   │         │
   ▼         ▼
  Yes        No
   │         │
   ▼         ▼
Fix errors  Done
   │
   ▼
Re-run markdownlint
   │
   ▼
(repeat until no errors)

Process

1. Run Validation

After writing or editing a markdown file, run:

markdownlint <file-path>

2. Interpret Results

No output: File passes validation. Proceed.

Error output: Fix each error before proceeding.

Common errors:

| Code | Issue | Fix | | ----- | --------------------------- | -------------------------------- | | MD001 | Heading level increment | Use sequential heading levels | | MD009 | Trailing spaces | Remove trailing whitespace | | MD012 | Multiple blank lines | Use single blank lines | | MD022 | Headings need blank lines | Add blank line before/after | | MD031 | Fenced code needs blanks | Add blank line before/after | | MD032 | Lists need blank lines | Add blank line before/after list | | MD034 | Bare URL | Use proper link syntax | | MD047 | No newline at end of file | Add final newline |

3. Fix Errors

For each error:

Read the error message and line number
Navigate to the specific location
Apply the fix
Re-run validation

Do not proceed until all errors are fixed.

4. Confirm Success

Only after markdownlint returns no errors:

Markdown validation passed for <file-path>.

Red Flags

These thoughts mean STOP - you are rationalizing:

| Thought | Reality | | ------------------------------------ | ----------------------------------- | | "It's just a small formatting issue" | Small issues compound into chaos | | "I'll fix it later" | Later never comes. Fix it now. | | "The content is correct" | Correct content with bad format | | | is still broken | | "markdownlint is too strict" | Consistency requires strictness | | "This file is temporary" | All files deserve quality | | "I don't have time" | Fixing later takes more time | | "It's only one warning" | One warning becomes ten |

Integration Points

This skill is invoked by:

rpikit:writing-plans - After writing plan documents
rpikit:researching-codebase - After writing research documents
rpikit:brainstorming - After writing design documents
PostToolUse hooks - Automatically after Write/Edit on .md files

Requirements

markdownlint must be installed. Install via:

npm install -g markdownlint-cli

If markdownlint is not available, warn and proceed:

Warning: markdownlint not installed. Skipping validation.
Consider installing: npm install -g markdownlint-cli

Anti-Patterns

Skipping Validation

Wrong: Writing markdown and moving on without checking Right: Always run markdownlint after every markdown write/edit

Partial Fixes

Wrong: Fixing some errors and ignoring others Right: Fix ALL errors. Zero tolerance.

Disabling Rules

Wrong: Adding disable comments to bypass errors Right: Fix the underlying issue

Batch Validation

Wrong: Writing many files then validating all at once Right: Validate immediately after each file write/edit

Agent Skills: Markdown Validation

Install this agent skill to your local

Skill Files