---

name: markdown-validation description: >- Validates markdown files using markdownlint after writing or editing. Invoke this skill after creating or modifying any markdown file to ensure consistent formatting and zero linting violations.

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

CopyWrite/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:

Copymarkdownlint <file-path>

2. Interpret Results

No output: File passes validation. Proceed.

Error output: Fix each error before proceeding.

Common errors:

3. Fix Errors

For each error:

1. Read the error message and line number
2. Navigate to the specific location
3. Apply the fix
4. Re-run validation

Do not proceed until all errors are fixed.

4. Confirm Success

Only after markdownlint returns no errors:

CopyMarkdown validation passed for <file-path>.

Red Flags

These thoughts mean STOP - you are rationalizing:

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:

Copynpm install -g markdownlint-cli

If markdownlint is not available, warn and proceed:

CopyWarning: 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