Agent skill

Markdown HTML Orchestrator

by alirezarezvani in alirezarezvani/claude-skills

A skill your agent uses when a user wants to convert any markdown file in their Claude project into a single-file, lightly-interactive HTML — long-form documents (specs, plans, RFCs, reports…

MITAuto-check passedDocuments & Office

Install Markdown HTML Orchestrator

skills CLI
$ npx skills add alirezarezvani/claude-skills --skill markdown-html-orchestrator -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install alirezarezvani/claude-skills markdown-html-orchestrator --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/alirezarezvani/claude-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/markdown-html/skills/markdown-html-orchestrator .claude/skills/markdown-html-orchestrator && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
markdown-html-orchestrator
GitHub stars
28k
Token cost
~2.7k tokens
SKILL.md length
1,069 words
Files
7 (incl. scripts, references)
Skills in repo
342
Repo updated
First seen
Licence
MIT

At a glance

A skill your agent uses when a user wants to convert any markdown file in their Claude project into a single-file, lightly-interactive HTML — long-form documents (specs, plans, RFCs, reports…

  • Works in 5 steps: Confirm onboarding → Classify the input → Route or ask → …
  • A user wants to convert any markdown file in their Claude project into a single-file
  • SKILL.md covers When to invoke, Pre-flight gates (hard refusals), Routing logic (deterministic) and Workflow, plus 7 more sections
  • Runs Python scripts from its folder; calls python3

What it does

Markdown HTML Orchestrator is an agent skill from alirezarezvani/claude-skills. Use when a user wants to convert any markdown file in their Claude project into a single-file, lightly-interactive HTML — long-form documents (specs, plans, RFCs, reports, explainers), code reviews with diffs and severity-tagged annotations, or slide decks. Triggers on "convert this markdown to HTML", "make this an HTML file", "turn this into an interactive document", "render this report as HTML", "PR writeup as HTML", "slides from this markdown". Forks context to route to one of three converter sub-skills…

Its SKILL.md is about 2.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 8 other files, including scripts and reference files (for example `references/information_density_canon.md`, `references/orchestrator_routing_patterns.md` and `references/single_file_html_discipline.md`).

It sits in Documents & Office, covering Slides and decks, Markdown and Design systems. The repository describes itself as: 380 Claude Code skills & agent skills & plugins (30+ Agents, 70+ custom commands, 380+ skills, customizable references, scripts)for Claude Code, Codex, Gemini CLI, Cursor, and 8… The licence is MIT.

When your agent uses it

  • A user wants to convert any markdown file in their Claude project into a single-file
  • Lightly-interactive HTML — long-form documents (specs
  • Code reviews with diffs and severity-tagged annotations
  • Convert this markdown to HTML

Example prompts

  • “convert this markdown to HTML”
  • “make this an HTML file”
  • “turn this into an interactive document”
  • “/markdown-html-orchestrator”

Requirements

  • Python 3

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Confirm onboarding
  2. Classify the input
  3. Route or ask
  4. Resolve the output path
  5. Hand off to the sub-skill

What it can do on your machine

Read from SKILL.md and the folder at commit 19392f7. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 3 files in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python3

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Markdown HTML Orchestrator loads about 2.7k tokens when it runs, and up to ~6.1k if it reads all its reference files. Until then it costs about 251 tokens; SKILL.md has 1,069 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~251
When it runs · the whole SKILL.md, loaded when a task matches
~2.7k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~6.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from alirezarezvani/claude-skills at commit 19392f7, republished under its MIT licence (© alirezarezvani). 1,069 words, ~2,744 tokens.

Download SKILL.mdSave it as .claude/skills/markdown-html-orchestrator/SKILL.md (or your agent's skills folder). This skill also uses 6 other files; get the full folder from GitHub.
name
markdown-html-orchestrator
description
Use when a user wants to convert any markdown file in their Claude project into a single-file, lightly-interactive HTML — long-form documents (specs, plans, RFCs, reports, explainers), code reviews with diffs and severity-tagged annotations, or slide decks. Triggers on "convert this markdown to HTML", "make this an HTML file", "turn this into an interactive document", "render this report as HTML", "PR writeup as HTML", "slides from this markdown". Forks context to route to one of three converter sub-skills (md-document, md-review, md-slides) based on a deterministic doctype classifier, after the user has run the design-system onboarding once. Refuses if input is under 100 lines (per Shihipar — markdown still wins below the threshold) or design-system isn't onboarded. Distinct from Anthropic's official Playground plugin (which is interactive prompt-tuning controls with sliders/knobs/prompt-copy-back) and from marketing/landing/ (which is a landing-page generator).
context
fork
version
2.10.3
author
Alireza Rezvani
license
MIT
tags
markdown, html, converter, orchestrator, documentation, code-review, slides, design-system
compatible_tools
claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli

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

SymptomSub-skill
"Convert this RFC / spec / report / explainer to HTML" — long-form docmd-document
"Turn this PR writeup / code review into HTML" — markdown with diff blocksmd-review
"Make a slide deck from this markdown" — --- boundaries or H1 cadencemd-slides

Pre-flight gates (hard refusals)

  1. Below the 100-line threshold. Markdown wins below 100 lines (Shihipar). The classifier prints below_min_lines: true and route_explainer.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 setup_completed_at 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. output_path_resolver.py refuses if the configured default_output_dir (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. Silent-route allowed when winner ≥ 3 AND (runner-up = 0 OR winner ≥ 2× runner-up). Below threshold → one clarifying question with a recommended answer.

Signal table
Signal classFilename hintsContent signalsSub-skill
DOCUMENTreport.md, *-doc.md, spec.md, rfc-*.md, *-analysis.md, *-explainer.md## Table of Contents (2), ^# , ^## , markdown table rows, > [!NOTE]/[!TIP]/[!IMPORTANT] calloutsmd-document
REVIEWreview.md, *-pr-*.md, *.diff.md, code-review*.md```diff (2), ^[-+]{3} (2), ^@@ (2), > [!BLOCKER]/[!MAJOR]/[!MINOR]/[!NIT] (2), LGTM/nit:/blocker:md-review
SLIDESdeck.md, slides.md, *-talk.md, presentation*.md^---$ ≥ 3 (2 + per-boundary), <!-- notes: (2), H1 count ≥ 5 with median gap ≤ 12 lines (2)md-slides

The pipeline:

bash
python3 markdown-html/skills/markdown-html-orchestrator/scripts/doctype_classifier.py \
    --input <path>.md --output json \
  | python3 markdown-html/skills/markdown-html-orchestrator/scripts/route_explainer.py

route_explainer.py checks the design-system status, applies the < 100-line refusal, and prints one of: ROUTE_SILENTLY -> md-<type>, ASK_USER one question: ..., or REFUSE — fix the issues above.

Workflow

Step 1 — Confirm onboarding

If the user has never run onboarding, surface the one-time setup:

bash
python3 markdown-html/skills/design-system/scripts/onboard.py

Ten questions, 1-2 minutes. Captures brand primary + accent + heading/body Google Fonts + design style (editorial/technical/minimal/playful) + default output dir + syntax theme + TOC behavior + optional logo/company. Stored at ~/.config/markdown-html/design-system.json. Re-runnable with --scope project for per-repo overrides.

Step 2 — Classify the input

Run doctype_classifier.py on the markdown. Inspect the verdict.

Step 3 — Route or ask

Pipe the classification into route_explainer.py. If it says ROUTE_SILENTLY, forward the original markdown + the design-system config into the named sub-skill's renderer in the forked context. If it says ASK_USER, ask ONE question with the recommended answer.

Step 4 — Resolve the output path
bash
python3 markdown-html/skills/markdown-html-orchestrator/scripts/output_path_resolver.py \
    --input <path>.md --doctype <document|review|slides>

Collision handling defaults to -2 / -3 / ... suffix; --on-collision timestamp for stamped names.

Step 5 — Hand off to the sub-skill

The routed converter sub-skill's renderer (md-document/scripts/, md-review/scripts/, or md-slides/scripts/) takes the input markdown, the design-system config, and the resolved output path, and writes a single self-contained HTML file. The orchestrator returns a ≤ 100-word digest: input lines, output path, design style applied, top 3 features used (TOC, search, code-copy, etc.), and one forcing question for the user. Never render HTML by hand — the converter scripts own the rendering.

Show full SKILL.md (516 more words)Show less

Forcing-question library (Matt Pocock grill-with-docs pattern)

Walk these one at a time, with a recommended answer per question, citing the canon. Lift this list into /cs:grill-markdown-html for plan-stage interrogation.

  1. What decision does this HTML drive — is the reader skimming, deciding, or presenting? Recommended: name it first; density follows from purpose. Canon: Shihipar — "match output format to consumption context"; Tufte — Visual Display of Quantitative Information, ch. 1.
  2. Is the input markdown ≥ 100 lines? Recommended: yes — below that, keep it as markdown. Canon: Shihipar — markdown still wins under 100 lines.
  3. Is the design-system onboarded? Recommended: yes, globally (~/.config/markdown-html/design-system.json). Canon: research-ops onboarding pattern (research-ops/CLAUDE.md §8); WCAG 2.2 §1.4.3 (text contrast 4.5:1).
  4. Where does the output save, and will it overwrite anything? Recommended: the configured default_output_dir with --on-collision suffix. Canon: Matt Pocock handoff skill — never silently overwrite a working artifact.
  5. Document type confidence — silent-route or one question? Recommended: silent-route only when the classifier's verdict is one of document/review/slides AND silent_route_allowed: true. Otherwise ask. Canon: research-ops two-signal threshold (research-ops/skills/research-ops-skills/SKILL.md §"Routing logic").

Never run a sub-skill before the lane is locked.

Assumptions

  1. User has a markdown file ≥ 100 lines they want to convert.
  2. User has run onboarding once (~/.config/markdown-html/design-system.json exists with setup_completed_at populated).
  3. Single-file HTML output is acceptable (no multi-file site, no embedded server, no build step).
  4. Externals limited to Google Fonts CSS + Prism.js CDN (jsdelivr / cdnjs).

Non-goals

  • Not a landing-page generator (use marketing/landing/).
  • Not an interactive prompt-tuning playground (use Anthropic's official playground plugin).
  • Not a static-site generator (no multi-file output, no site index).
  • Not a PDF generator (slides use @media print; user prints from browser).
  • Not a watch / live-reload pipeline (conversion is one-shot).

Distinct from

  • Anthropic Playground plugin (/playground) — builds interactive controls (sliders, knobs, drag-drop) for prompt tuning, with a copy-prompt-back loop. This plugin converts existing markdown documents to HTML. Different tools for different jobs.
  • marketing/landing/ — generates landing pages from scratch (Phase-0 intake → 3 sections → branded TSX/HTML). This plugin converts an existing markdown file you already have.
  • engineering/handoff/ + productivity/handoff/ — preserve session continuity between Claude conversations. Different artifact type (handoff brief vs. document conversion).

Output artifacts

Sub-skillArtifactStatus
md-documentdoc-<slug>.html (single file, sticky TOC, collapsibles, search, code-copy, scrollspy)✓ live
md-reviewreview-<slug>.html (2-col diff + severity margin notes + jump-nav)✓ live
md-slidesdeck-<slug>.html (arrow-key nav + presenter mode + print-to-PDF)✓ live

Anti-patterns (do not)

  • ❌ Convert markdown < 100 lines — markdown still wins. Refuse and tell the user.
  • ❌ Run the orchestrator before the design-system is onboarded. The output looks broken without tokens.
  • ❌ Silently chain two sub-skills (e.g., "convert doc AND make slides from it"). Pick one, finish, ask before chaining.
  • ❌ Use external JS frameworks (React/Vue/Svelte). Vanilla JS + IntersectionObserver only. Prism.js CDN is the single exception.
  • ❌ Multi-file output (extracted CSS, asset directories). Single file or nothing — that's the whole point.
  • ❌ Overwrite an existing output file by default. The path resolver suffixes -2, -3, …; --on-collision overwrite is opt-in only.

References

  • Spec: Thariq Shihipar — "Claude Code HTML output" (Medium, 2026)
  • Forking pattern: research-ops/skills/research-ops-skills/SKILL.md (context: fork, two-signal routing)
  • Customization pattern: research-ops/skills/clinical-research/scripts/ (onboard.py, config_loader.py)
  • Brand palette math: marketing/landing/skills/landing/scripts/brand_palette_validator.py (WCAG + HSL derive)
  • Information-density canon: Tufte; Shihipar's thariqs.github.io/html-effectiveness/ gallery; Wattenberger interactive essays; Maggie Appleton digital gardens

© alirezarezvani, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 6 other files (scripts, references) in markdown-html/skills/markdown-html-orchestrator of alirezarezvani/claude-skills.

  • SKILL.md
  • references/information_density_canon.md
  • references/orchestrator_routing_patterns.md
  • references/single_file_html_discipline.md
  • scripts/doctype_classifier.py
  • scripts/output_path_resolver.py
  • scripts/route_explainer.py

Open the folder on GitHubat commit 19392f7

Compare with similar skills

Markdown HTML Orchestrator next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Markdown HTML Orchestrator compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Markdown HTML Orchestrator this skillalirezarezvani/claude-skills28k—~2.7kAutomated safety check: PassMIT
Data Viz Deckthatrebeccarae/claude-marketing162—~1.8kAutomated safety check: PassMIT
Visualizedisplay-dev/visualize132—~7.4kAutomated safety check: PassMIT
Opendesignmanalkaff/opendesign261—~2.3kAutomated safety check: PassMIT
Ky Markdown RebuilderKyrieCheungYep/ky-markdown-rebuilder117—~5.7kAutomated safety check: PassNone
Web Designdrewnekota/cetus146—~2.1kAutomated safety check: PassMIT

Similar skills

  • Data Viz Deck

    thatrebeccarae/claude-marketing

    Transform audit data, performance reports, and structured analyses into polished visual deliverables.

    162 GitHub stars~1.8k tokensUpdated 4 mo ago
    Documents & OfficeAuto-check passed
  • Visualize

    display-dev/visualize

    Generate beautiful, on-brand HTML artifacts — reports, diagrams, diff reviews, slide decks, plans, recaps, dashboards.

    132 GitHub stars~7.4k tokensUpdated 22 days ago
    Frontend & DesignAuto-check passed
  • Opendesign

    manalkaff/opendesign

    A skill your agent uses when starting any design task — HTML pages, slide decks, interactive prototypes, UI kits, brand systems.

    261 GitHub stars~2.3k tokensUpdated 3 mo ago
    Frontend & DesignAuto-check passed
  • Ky Markdown Rebuilder

    KyrieCheungYep/ky-markdown-rebuilder

    Rebuild visual documents into reliable Markdown by combining text extraction with page or screenshot alignment.

    117 GitHub stars~5.7k tokensUpdated 2 mo ago
    Documents & OfficeAuto-check passed
  • Web Design

    drewnekota/cetus

    A skill your agent uses when building any web page, HTML artifact, landing page, dashboard, slide deck, report, email, or UI component the user will look at.

    146 GitHub stars~2.1k tokensUpdated 3 days ago
    Frontend & DesignAuto-check passed
  • Frontend Slides

    zarazhangrui/frontend-slides

    Builds animated HTML slide decks that run in the browser with no dependencies, or converts PowerPoint files to the web, starting from visual style previews.

    30k GitHub starsUsed in 16 repos~7k tokens
    Documents & OfficeAuto-check passed

More from alirezarezvani/claude-skills

All 342 skills in this repo
  • Agile Product Owner

    alirezarezvani/claude-skills

    Writes INVEST-checked user stories with acceptance criteria, splits epics, plans sprints from velocity and ranks the backlog with a weighted score.

    28k GitHub starsUsed in 3 repos~3.2k tokens
    Auto-check passed
  • Product Strategist

    alirezarezvani/claude-skills

    OKR cascade toolkit for product leaders: generates aligned company-to-team OKRs from five strategy types and scores how well they line up.

    28k GitHub starsUsed in 2 repos~1.8k tokens
    Auto-check passed
  • App Store Optimization

    alirezarezvani/claude-skills

    App Store Optimization (ASO) toolkit for researching keywords, analyzing competitor rankings, generating metadata suggestions, and improving app visibility on Apple App Store and Google Play Store.

    28k GitHub starsUsed in 1 repo~4.2k tokens
    Auto-check passed
  • AWS Solution Architect

    alirezarezvani/claude-skills

    Design AWS architectures for startups using serverless patterns and IaC templates.

    28k GitHub starsUsed in 1 repo~2.5k tokens
    Auto-check passed
  • Campaign Analytics

    alirezarezvani/claude-skills

    Calculates attribution, funnel and ROI figures for marketing campaigns with three Python scripts that need only the standard library.

    28k GitHub starsUsed in 1 repo~2.1k tokens
    Auto-check passed
  • Code to PRD

    alirezarezvani/claude-skills

    Reverse-engineers a frontend, backend or fullstack codebase into a product requirements document with per-page docs, an enum dictionary and an API inventory.

    28k GitHub starsUsed in 1 repo~4.9k tokens
    Auto-check passed

Questions about Markdown HTML Orchestrator

What does Markdown HTML Orchestrator do?

A skill your agent uses when a user wants to convert any markdown file in their Claude project into a single-file, lightly-interactive HTML — long-form documents (specs, plans, RFCs, reports…. Markdown HTML Orchestrator is an agent skill from alirezarezvani/claude-skills. Use when a user wants to convert any markdown file in their Claude project into a single-file, lightly-interactive HTML — long-form documents (specs, plans, RFCs, reports, explainers), code reviews with diffs and severity-tagged annotations, or slide decks.

When should I use Markdown HTML Orchestrator?

Markdown HTML Orchestrator fits situations like: A user wants to convert any markdown file in their Claude project into a single-file; lightly-interactive HTML — long-form documents (specs; code reviews with diffs and severity-tagged annotations; convert this markdown to HTML.

How do I install Markdown HTML Orchestrator in Claude Code?

Run `npx skills add alirezarezvani/claude-skills --skill markdown-html-orchestrator -a claude-code`. Or copy the skill folder (markdown-html/skills/markdown-html-orchestrator in alirezarezvani/claude-skills) into .claude/skills/markdown-html-orchestrator in your project. Claude Code loads it when a task matches its description.

How do I install Markdown HTML Orchestrator in Codex?

Run `npx skills add alirezarezvani/claude-skills --skill markdown-html-orchestrator -a codex`. Or copy the skill folder (markdown-html/skills/markdown-html-orchestrator in alirezarezvani/claude-skills) into .agents/skills/markdown-html-orchestrator in your project. Codex loads it when a task matches its description.

Can I use Markdown HTML Orchestrator in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add alirezarezvani/claude-skills --skill markdown-html-orchestrator -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/markdown-html-orchestrator, .gemini/skills/markdown-html-orchestrator, .github/skills/markdown-html-orchestrator and .opencode/skills/markdown-html-orchestrator in your project.

What does Markdown HTML Orchestrator need to run?

Going by SKILL.md and its folder, Markdown HTML Orchestrator needs Python for the scripts in its folder and the command-line tools its instructions call (python3). Our summary lists: Python 3.

Does Markdown HTML Orchestrator access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Markdown HTML Orchestrator safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Markdown HTML Orchestrator use?

Markdown HTML Orchestrator is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Markdown HTML Orchestrator use?

About 2.7k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 3.4k tokens, read only when the agent opens those files.

What are the alternatives to Markdown HTML Orchestrator?

Skills that share tags, products or a category with Markdown HTML Orchestrator: Data Viz Deck (thatrebeccarae/claude-marketing, 162 stars), Visualize (display-dev/visualize, 132 stars), Opendesign (manalkaff/opendesign, 261 stars) and Ky Markdown Rebuilder (KyrieCheungYep/ky-markdown-rebuilder, 117 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Markdown HTML Orchestrator?

alirezarezvani (a GitHub user) maintains it in alirezarezvani/claude-skills, which has 27,829 GitHub stars. The repository holds 342 skills in this directory. The repository was last updated on August 30, 2026.

Source: alirezarezvani/claude-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.