Agent skill · writing content · alirezarezvani
markdown-html-orchestrator
Use when the user wants a markdown file turned into a single-file interactive HTML page (document, code review or slide deck). Classifies it with doctype_classifier.py and routes to md-document, md-review or md-slides.
Why this skill is useful
Adds a deterministic routing mechanism for converting markdown to HTML based on document type, which the AI wouldn't reliably generate on its own.
What it needs
About 6k tokens when loaded. Last updated 2026-08-05. 23,939 stars on the source repository.
What this skill does
Markdown → HTML — Domain Orchestrator Thariq Shihipar's argument (Claude Code HTML output essay, Medium 2026): markdown collapses past 100 lines for agent-generated artifacts. Long specs, code reviews, and architecture explainers lose density, hierarchy, and lightweight interaction the moment they exceed a screen of text. HTML restores all three — single-file, browser-native, shareable. This orchestrator forks context, classifies the input markdown deterministically, routes to the right converter sub-skill, and returns a digest with the output path. Heavy intake (full markdown bodies, diffs, slide decks) stays in the forked context. Domain status (complete): all five skills are live — orchestrator + design-system (onboarding + shared brand tokens) + the three converter sub-skills (md-document, md-review, md-slides). Always route conversions to the shipped converter's scripts; never hand-render HTML inline. When to invoke Symptom Sub-skill --- --- "Convert this RFC / spec / report / explainer to HTML" — long-form doc md-document "Turn this PR writeup / code review into HTML" — markdown with diff blocks md-review "Make a slide deck from this markdown" — --- boundaries or H1 cadence md-slides Pre-flight gates (hard refusals) 1. Below the 100-line threshold. Markdown wins below 100 lines (Shihipar). The classifier prints belowminlines: true and routeexplainer.py refuses. Tell the user to keep their input as markdown. 2. Design-system not onboarded. If ~/.config/markdown-html/design-system.json doesn't exist (or its setupcompletedat is null), refuse. Point the user at python3 markdown-html/skills/design-system/scripts/onboard.py (or --defaults for a zero-touch run). 3. Unwritable save location. outputpathresolver.py refuses if the configured defaultoutputdir (or --out override) isn't writable. Routing logic (deterministic) Two-signal threshold pattern lifted from research-ops/skills/research-ops-skills/SKILL.md. Filename hint = 2 points; each content signal = 1 point. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills alirezarezvani/markdown-html-orchestrator--c6c111