YAML to HTML Explainer

yaml-to-html explainer

A Claude Code plugin with two skills that turn an understanding target — a document, repository summary, pull request / diff, README, design note, or specification — into an offline HTML explainer bundle tailored to how a particular reader understands things.

The two skills split the work cleanly:

skill	role	output
generate-explainer-yaml	Gen YAML	core.yaml (meaning) + view.yaml (presentation strategy) + quiz.yaml (comprehension quiz, default)
generate-explainer-html	Gen HTML	a bundle: a light/dark shell + switchable iframe views (incl. a quiz tab)

Input (doc / repo / PR / README / design note / spec)
  ↓ generate-explainer-yaml
core.yaml  (what it MEANS — concepts, relations, importance, difficulty, sources)
view.yaml  (how to SHOW it to this reader — audience, forms, emphasis)
quiz.yaml  (how to CHECK understanding — questions, answers, explanations)
  ↓ generate-explainer-html
HTML bundle: index.html (light/dark shell + view switcher + add-a-view prompts)
             + views/NN-<id>.html  (one switchable iframe view each, incl. a quiz tab)

Quizzes are generated by default. Both the quiz.yaml and the interactive quiz tab (answer → instant grading → explanation, adapted to the reader and per-item difficulty) are produced unless you explicitly say you don't want a quiz in your prompt. The score lives only in the page — reloading resets it (the bundle stores nothing by design).

Quick start

1. Install the plugin (run these inside Claude Code):

/plugin marketplace add hirokita117/yaml-to-html-skill
/plugin install yaml-to-html@yaml-to-html-skill

2. Ask for an explainer. A single prompt runs both skills in the right order — generate-explainer-yaml first (writes core.yaml + view.yaml), then generate-explainer-html (reads that YAML by absolute path and builds the HTML bundle). Paste a document / repo summary / PR diff / README / design note, or point at a path.

English

Build me an offline HTML explainer bundle for this PR, aimed at an engineer reviewing it.
First use generate-explainer-yaml to produce core.yaml + view.yaml, then use
generate-explainer-html to turn that YAML (by absolute path) into a light/dark switchable
view bundle in ./explainer-bundle.

--- target ---
<paste the PR / document / repo summary / README / design note here, or give a path>

Japanese

この PR を、レビューするエンジニア向けに分かりやすく説明する HTML バンドルを作ってください。
まず generate-explainer-yaml で core.yaml と view.yaml を生成し、
続けて generate-explainer-html でその YAML（絶対パス）から
ライト/ダーク切り替え付きのビュー HTML バンドルを ./explainer-bundle に組み立ててください。

--- 対象 ---
<ここに PR / ドキュメント / リポジトリ概要 / README / 設計メモを貼る、またはパスを指定>

3. Open it. Open ./explainer-bundle/index.html in Firefox over file://, or serve the folder for Chrome/Edge (cd explainer-bundle && python3 -m http.server). See Opening the bundle for why.

Prefer to drive it step by step? Generate just the YAML first ("generate-explainer-yaml で core.yaml と view.yaml を作って"), review the two files, then hand their absolute paths to generate-explainer-html.

What the output looks like

The HTML output is a bundle (a directory), not a single file:

• A light/dark shell (index.html) with a theme toggle (light by default).
• A right pane that switches between iframe views. Each view is a separate self-contained HTML document under views/. Views are additive — ask for a "table" view next to your "beginner" view and you get a second tab, not a replacement.
• A left pane of copyable prompt templates. Each asks another local-file-reading AI (Claude Code / Cursor / an agentic IDE) to read the YAML by absolute path and return one new view to add to the bundle. The prompts never embed the YAML content.

This is not a web app

• No server, no API route, no build pipeline, no chat UI.
• No external CDN, CSS, or JS; no network calls; no storage or cookies.
• Each view runs in a sandboxed iframe (sandbox="allow-scripts", no allow-same-origin) and cannot reach the parent page.

The shell loads each view via a local relative src (e.g. views/01-engineer.html) — a local file read, not a network read. (A remote src stays forbidden.)

core.yaml vs. view.yaml

Two intermediate representations sit between the input and the HTML, produced by generate-explainer-yaml: