md_skill

Overview

This skill produces clean, linter-friendly Markdown that IDEs and markdown linters can parse without warnings. It automates common fixes and enforces patterns for code fences, tables, links, lists, and HTML so documentation and README files remain stable and machine-parseable. Use it to catch and correct the small syntax issues that break previews, CI checks, or documentation pipelines.

How this skill works

The skill inspects Markdown for common syntax pitfalls: unclosed or mismatched fences, nested code blocks, table pipe mismatches, malformed links, inconsistent list indentation, unclosed HTML tags, and missing blank lines around blocks. It suggests precise fixes and a validation checklist, and can output a corrected snippet or a safe template to replace the broken section. The output follows a predictable fence-level strategy and escaping rules so editors and linters stop reporting errors.

When to use it

• Writing or editing README files for repositories
• Creating documentation pages or developer guides
• Composing skill or code example files that include nested code blocks
• Before committing markdown to CI where markdown linting runs
• When IDE preview or markdownlint reports parse errors

Best practices

• Always close code fences with the same fence characters you opened
• Use longer outer fences (increasing backticks) when nesting code blocks
• Escape pipe characters in table cells with a backslash
• Keep consistent indentation for nested lists (2 or 4 spaces)
• Add blank lines before and after code blocks and block-level HTML
• Validate links and use reference-style links for repeated targets

Example use cases

• Fixing a README that fails markdownlint with "Unclosed code block"
• Converting nested examples that contain inline backticks into properly fenced blocks
• Escaping table cells that contain pipes so the table column count stays consistent
• Adding missing closing tags for details/summary blocks that break previews
• Running a quick pre-commit check to ensure headings have a space after # and lists are consistent