Stats
Actions
Tags
turn core.yaml + view.yaml (the explainer's meaning + presentation strategy) into a self-contained html bundle that helps users understand documents, repositories, pull requests, design notes, or specifications. the bundle has a light/dark shell whose right pane switches between multiple iframe view documents, and copyable prompt templates that ask a local-file-reading ai to add another switchable view. use when the user has (or wants) a core.yaml/view.yaml pair and wants a visual html explainer, or wants to add a new representation (table, worktree, cards, faq, beginner, engineer, pdm view, …) to an existing bundle. produce the yaml first with the generate-explainer-yaml skill.
How this skill is triggered — by the user, by Claude, or both
Slash command
/yaml-to-html:generate-explainer-htmlThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Turn a `core.yaml` (meaning) + `view.yaml` (presentation strategy) pair into a
Turn a core.yaml (meaning) + view.yaml (presentation strategy) pair into a
self-contained HTML bundle that:
This is the second half of the pipeline. The core.yaml / view.yaml come from the
generate-explainer-yaml skill (or the user). This skill reads them by absolute
path, authors iframe view documents, and assembles the bundle.
core.yaml + view.yaml (from generate-explainer-yaml)
↓ design + generate (this skill)
HTML bundle: index.html (light/dark shell + view switcher + prompt cards)
+ views/NN-<id>.html (one switchable iframe view each)
The output is a directory, not a single file:
<bundle>/
index.html shell: header (theme toggle) + left prompt pane + right view switcher + ONE <iframe>
views.json ordered manifest of views {id, label, file}
core.yaml copied in (its absolute path is cited by the prompts)
view.yaml copied in
views/
01-<id>.html an iframe view document (full <!DOCTYPE html>, light default)
02-<id>.html
The right-pane iframe loads one view at a time via src="views/<file>"; the tab switcher
swaps it. Views are additive — each new one becomes another tab; existing views and the
shell/prompts are never rewritten.
Do not hand-edit index.html or the prompts — scripts/build_html.py is their only
author. You author iframe view documents only. Do not build a web app, server, API,
or chat UI, and do not depend on any external CDN/CSS/JS.
Get the YAML pair. Take the absolute paths to core.yaml and view.yaml (from the
generate-explainer-yaml skill, or the user). Read them. If they don't exist yet,
produce them with generate-explainer-yaml first.
Author one iframe view document — a full <!DOCTYPE html> document tailored to the
target and reader. Choose the form(s) from view.yaml (table, worktree, cards, faq,
comparison, sequence, reading path, risk/dependency/impact map, glossary, tutorial,
review checklist, …). It must include source references, important concepts, relations,
what to read next, and next questions, and have real visual structure. It must be light
by default and read #theme from its own URL hash (load + hashchange). Inline
CSS/JS only; no network. Follow references/html-generation-rules.md. Example:
references/sample-iframe.html.
Author the prompt templates as a prompts.json array — the "add a view" cards
(table, worktree, beginner, engineer, PdM/Biz, free-form). Each cites the YAML via
{{core_yaml_path}} / {{view_yaml_path}} and must not embed YAML content. Patterns:
references/prompt-template-patterns.md. Starter set: references/sample-prompts.json.
Build the bundle with scripts/build_html.py (see below). Pass --core / --view
(copied in; their absolute paths feed the prompt placeholders) and one or more
--view-html "ラベル=その.html".
Validate the bundle with scripts/validate_html.py on index.html and every
views/*.html. Fix any error and re-validate until it exits 0.
Hand the user the bundle folder with open instructions (below). Summarize which views exist and which "add a view" templates are available.
To add a representation next to the existing ones — do not overwrite:
python scripts/build_html.py --bundle <dir> --prompts <prompts.json> \
--view-html "テーブル=table.html"
views.json and regenerates index.html with a new tab. The
existing views, the shell, and the prompts are preserved. (Re-running with an existing
label updates that view in place instead of duplicating it.)Note: invoke with
python3ifpythonis not on PATH.
Build / grow the bundle:
python scripts/build_html.py \
--bundle ./explainer-bundle \
--core /abs/path/core.yaml \
--view /abs/path/view.yaml \
--prompts prompts.json \
--view-html "エンジニア=engineer.html" \
--view-html "テーブル=table.html"
--bundle and --prompts are required; --core / --view are optional (recommended — the
prompts cite their absolute path) and are left in place on a re-run if omitted; --view-html
is repeatable and appends/updates views.
Validate (safety / self-containment check), including every view file:
python scripts/validate_html.py ./explainer-bundle/index.html ./explainer-bundle/views/*.html
build_html.py is an assembler, not a renderer: it never turns core.yaml into a fixed
diagram. The understanding UI is the iframe view document(s) you authored in step 2.
file:// iframe loads. Open index.html in Firefox over
file://, or serve the folder with a trivial local static server (e.g.
python3 -m http.server run inside the bundle dir — it reads only local files; the
no-network rule constrains the content, not how you serve the folder).#theme hash.validate_html.py fails on an http:// / https:// string — a URL leaked into a
source_ref or a prompt body. URLs are labels here, not live links: drop the scheme
(write example.com/path) or remove the URL, then re-validate.validate_html.py fails on fetch( / XMLHttpRequest / localStorage / etc. — the
forbidden token appears literally inside a prompt body or a view. Reword it generically;
see references/prompt-template-patterns.md → "Safety wording inside prompt bodies".file:// — expected; use Firefox or serve the folder.build_html.py: --view-html must be "LABEL=PATH" — pass each view as ラベル=パス.build_html.py: no views to build — pass at least one --view-html, or build into a
bundle that already has a views.json.views/NN-*.html was removed; rebuild it with --view-html.python scripts/build_html.py \
--bundle ./sample-bundle \
--core ../generate-explainer-yaml/references/sample-core.yaml \
--view ../generate-explainer-yaml/references/sample-view.yaml \
--prompts references/sample-prompts.json \
--view-html "エンジニア=references/sample-iframe.html"
python scripts/validate_html.py ./sample-bundle/index.html ./sample-bundle/views/*.html
Open sample-bundle/index.html (Firefox / served). The right pane shows an
engineer-oriented PR explanation (worktree + reading order + review checklist); the left
pane has the copyable "add a view" templates and the YAML viewers.
references/html-generation-rules.md — safety + UI rules for view documents (src-loaded
iframe, light default, #theme hash)references/output-bundle-structure.md — the bundle's structure and shellreferences/prompt-template-patterns.md — "add a view" prompt templates + path placeholdersreferences/sample-iframe.html — sample iframe view (engineer)references/sample-prompts.json — sample "add a view" templatesreferences/examples.md — three worked reader viewsagents/openai.yaml — portable description of this skill for non-Claude agents../generate-explainer-yaml/references/
(core-yaml-schema.md, view-yaml-schema.md)Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Applies a firm's KYC/AML rules grid to parsed onboarding records: assigns risk rating, checks required documents, outputs rule outcomes with citations, and routes for escalation.
Generates daily or weekly digests of activity from connected sources (chat, email, docs, tasks, CRM), highlighting action items, decisions, mentions, and project updates.
npx claudepluginhub hirokita117/yaml-to-html-skill --plugin yaml-to-html