alirezarezvani--claude-skills/markdown-html/CLAUDE.md

Markdown → HTML — Domain Guide

This file provides domain-specific guidance for skills in markdown-html/.

Purpose

The markdown-html domain converts long markdown files (the actual artifacts produced inside a Claude project — specs, reports, RFCs, PR writeups, slide outlines) into world-class, single-file, lightly-interactive HTML. Inspired by Thariq Shihipar's argument (Medium, 2026): markdown collapses past ~100 lines because it lacks visual machinery for density and lateral navigation; HTML restores both.

It is not an interactive prompt-tuning playground (/playground plugin owns that lane), not a landing-page generator (marketing/landing/), not a session-handoff brief generator (engineering/handoff/ + productivity/handoff/), and not a static-site generator (single-file artifacts, not site indices).

Skills (v2.10.3 — domain complete)

Skill	Purpose	context: fork?	Status
markdown-html-orchestrator	Domain orchestrator — classifies doctype, gates on threshold + onboarding, routes to converter	YES	✓ live
design-system	One-time onboarding wizard + WCAG-AA-validated brand palette (12 CSS custom properties) + shared config	NO	✓ live
md-document	Long-form converter: sticky TOC, collapsibles, search, code-copy, scrollspy	NO	✓ live
md-review	Code-review converter: 2-col diff + severity-tagged margin annotations + jump-nav	NO	✓ live
md-slides	Slide-deck converter: arrow-key nav + presenter mode + print-to-PDF	NO	✓ live

All three converters are shipped. Routing always targets the converter skill's scripts — never hand-render HTML inline.

Hard rules (domain-specific)

1. Refuses input < 100 lines. Markdown still wins below the threshold (Shihipar). Every converter (and the orchestrator) prints the line count and a "keep as markdown" recommendation.
2. Refuses without design-system onboarding. The orchestrator's route_explainer.py checks config_loader.setup_completed(). If false, refuse and surface onboarding (python3 markdown-html/skills/design-system/scripts/onboard.py).
3. WCAG AA enforced. brand_palette_validator.py rejects color combinations whose body-text contrast falls below 4.5:1 on bg. Link contrast is iteratively walked to 4.5:1 by adjusting luminance.
4. Single-file HTML output. All CSS and JS inline. The only permitted external CDN entries are Google Fonts CSS and Prism.js. No bundler, no build step, no JS framework runtimes (vanilla JS + IntersectionObserver only).
5. Never silently chain converters. "Convert this markdown AND make slides from it AND a code review" is three operations. Pick one, finish, ask before chaining.
6. Stdlib-only Python. Deterministic logic, no LLM calls in scripts.
7. Customization in use, not decoration. Every converter MUST render differently when the user changes design_style, brand.primary, code_theme, or toc.behavior. If a token doesn't change behavior, it doesn't belong in the schema.
8. Onboarding-first. The orchestrator surfaces onboarding the moment it detects a missing setup_completed_at. Don't render with placeholder defaults silently.

Build pattern

Path-B contract per skill: SKILL.md + 3 stdlib scripts + 3 references (each citing 5-7 sources) + (optional) 1 asset template. The orchestrator skill ships context: fork in its frontmatter. The design-system skill is the shared brand owner — every converter imports its config_loader.py via sys.path.insert(0, .../design-system/scripts).

Each SKILL.md ships a "Forcing-question library" section (cited-canon grilling, one question at a time) — same discipline as research-ops, commercial, and business-operations.

Agent + command pattern

• cs-markdown-html-orchestrator — density-first markdown-to-HTML converter. Voice: "What decision does this HTML drive — is the reader skimming, deciding, or presenting?"
• /cs:markdown-html <path>.md — top-level router (classifier + route + recommend)
• /cs:grill-markdown-html <path>.md — Matt-Pocock-style 5-question grill before conversion
• /cs:design-system — surface the onboarding wizard

Per-sub-skill commands (all live):

• /cs:md-document, /cs:md-review, /cs:md-slides

Anti-patterns (domain-level)

• ❌ Converting markdown < 100 lines — markdown still wins. Refuse + cite Shihipar.
• ❌ Skipping onboarding because "the user wants it done now." Surface onboarding — it's 60 seconds.
• ❌ Multi-file output (separate CSS / JS / image folders). Single file or nothing.
• ❌ External JS framework runtimes (React, Vue, Svelte, Alpine). Vanilla JS + IntersectionObserver only.
• ❌ Silently overwriting existing output files. output_path_resolver.py suffixes -2, -3, … by default.
• ❌ Setting MARKDOWN_HTML_NO_CONFIG=1 silently for an interactive user.
• ❌ Decorative tokens — every token must change at least one converter's output.
• ❌ Inventing brand colors when the user hasn't onboarded.
• ❌ A skill that overlaps Anthropic's official Playground plugin (sliders/knobs/prompt-copy-back).
• ❌ A skill that overlaps marketing/landing/ (landing-page generation from scratch).

Customization pipeline

1. User runs python3 markdown-html/skills/design-system/scripts/onboard.py.
2. Wizard validates brand colors via brand_palette_validator.py, derives 12-token palette.
3. Result written to ~/.config/markdown-html/design-system.json (or ./.markdown-html/design-system.json with --scope project).
4. Every converter sub-skill imports config_loader.py and calls load_config() to read project > global > defaults.
5. Each converter's renderer emits a single <style> block with :root { --md-bg: ...; } for all 12 tokens, then references those variables throughout the CSS.
6. Result: change a single field via --set brand.primary=#FF6B35 → next conversion re-renders with the new brand.

References

• Spec: Thariq Shihipar — Claude Code HTML output: Why Markdown Lost and How to Switch (Medium, 2026)
• Forking pattern source: research-ops/skills/research-ops-skills/SKILL.md (context: fork, two-signal routing)
• Onboarding pattern source: research-ops/skills/clinical-research/scripts/onboard.py + config_loader.py
• Brand palette math source: marketing/landing/skills/landing/scripts/brand_palette_validator.py
• Matt Pocock grill-with-docs: engineering/grill-with-docs
• Single-file HTML discipline source: marketing/landing/skills/landing/SKILL.md