Markdown Review Gate

Markdown Review Gate

The quality gate that runs before Markdown becomes HTML. A converter will happily render a document with three H1s, four dead links, an image with no alt text, and a 67-word sentence — the HTML validates and the page is still bad. This skill catches those defects while they are still cheap to fix, and fails the build when they are blocking.

Zero network calls, by design. Relative links and anchors resolve on disk; external URLs are inventoried and reported but never fetched. A gate that fails because someone else's server was slow is a gate engineers learn to ignore.

When to use this skill

• Before publishing a doc, guide, or article that will be converted to HTML
• Wiring a docs CI gate that must block a merge on real defects without blocking on style
• Auditing an inherited Markdown corpus to size the accessibility and link-rot backlog
• Enforcing house terminology across a docs set (front-end vs frontend, GitHub vs Github)
• Checking accessibility of source content against the WCAG criteria that survive conversion
• Calibrating prose to an audience — a runbook read at 3am needs a different band than an API reference

Inputs the skill expects

• One or more Markdown files (with or without YAML frontmatter)
• A review config JSON: required frontmatter fields, structure and accessibility thresholds, term map, gate settings
• The target audience for the prose (drives the readability band — the single most consequential input)
• The project root, when the corpus uses root-relative (/docs/...) links
• The blocking policy: which severity fails the build, and the warning budget

Clarify First

Before generating, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• Target audience for the prose — why it changes the output: selects the Flesch band and grade ceiling; a general-public band (60-80) and a specialist band (40-60) flag opposite sets of sentences
• Required frontmatter fields — why it changes the output: every missing field is an error, so guessing the schema produces either false blockers or a silent gap
• Blocking severity and warning budget — why it changes the output: decides whether the run reports or blocks, which determines whether this is an audit or a gate
• Whether the corpus is new or inherited — why it changes the output: an inherited corpus needs report-only phase 1, not a gate that fails on day one

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Workflows