markdown-style
markdown-style
The Markdown authoring and review skill. Owns two layers of rules and the procedure for applying them:
- Syntax canon - what valid, portable Markdown looks like. Full canon:
references/syntax-canon.md. - Style overlay - opinionated rules a reviewer enforces on top of valid syntax. Full overlay:
references/style-overlay.md.
The question this skill answers is 'is this doc well-formed?' - not 'does this doc belong here?' Style review never decides whether a doc should exist; it assumes the doc earned its place and asks whether the prose structure and Markdown are clean.
How to run a review
Two passes, syntax before style. The reviewer reads a syntax violation differently from a style violation, so do not interleave them.
Pass 1 - syntax (must-fix)
Run markdownlint first when it is available - the mechanical checks (heading style, list markers, blank lines around blocks, fence style) are its job, and each hit maps onto a canon rule; then walk the file top to bottom for what a linter cannot see. Syntax violations are bugs (invalid or non-portable Markdown: setext where ATX is expected, unfenced code block, missing blank line around a block element, ) instead of . in an ordered list, missing space after #), not judgment calls - fix them directly in one Edit pass. No approval gate; the diff is self-explaining and each fix cites its rule by short name (e.g. syntax/headings/atx-space-after).