| name | single-html-forge |
| description | Generate a single self-contained HTML file — a horizontal slide deck, a vertical-scroll explainer document, or a fixed-canvas summary image — with zero external runtime dependencies, then verify it mechanically. Use when the user asks for HTMLスライド, 単一HTMLスライド, single-file HTML presentation, ブラウザーで開く説明資料, HTML 説明資料, HTMLサマリ画像, or self-contained HTML, or wants to hand someone a deck or explainer that opens anywhere without PowerPoint. Also use to embed images into such a file or to re-check an existing one. Does not output PPTX. |
| argument-hint | 作りたい内容と、deck / doc / poster のどれか |
| user-invocable | true |
| license | CC BY-NC-SA 4.0 |
| metadata | {"author":"yamapan (https://github.com/aktsmm)"} |
Single HTML Forge
One HTML file. No CDN, no build step, no external fetch at runtime. Opens the same on any machine and survives being emailed.
When to Use
- "HTMLスライドを作って" / "単一HTMLで資料にして" / "ブラウザーで開ける説明資料にして" / "サマリ画像を1枚"
- Handing a deck or explainer to someone who should not need PowerPoint
- Embedding images into a self-contained HTML artifact
- Re-verifying or editing an artifact this skill produced
Not for: PPTX output (this skill does not produce it), editable diagram source files, or anything needing a live server.
Archetype Routing
Ask which one unless the request already says. Load only that archetype's reference.
| Archetype | Shape | Use for | Reference |
|---|
deck | 16:9 slides, keyboard nav, presenter overlay | talks, walkthroughs | archetype-deck.md |
doc | vertical scroll, sidebar nav, numbered citations | explainers, comparisons, handouts | archetype-doc.md |
poster | one fixed canvas, exported as PNG | summary images, social cards | archetype-poster.md |
deck also has an outline layout: a slide list on the left, the stage on the right, collapsed with O when projecting. Start from deck-outline-skeleton.html when the deck will be read or reviewed rather than presented.
Intake
- Archetype (above).
- Topic, audience, what they should be able to do or decide afterwards, and roughly how much content.
- Colour direction — propose two or three, or derive one from the topic. See design-tokens.md.
- Images? If any is a screenshot or of unknown provenance, ask the sanitization question in Hard Constraints before embedding.
- Which export, if any: PDF, PNG, or per-slide PNG. Produce only what was asked for.
Hard Constraints
These gate the output. They are here, not in a reference, because a reference may never be read.
- No artifact-specific JavaScript or CSS. Script is the bundled runtime only; styling is the fixed template plus typed custom properties. Any other
<script> or <style> fails verification.
- Images ride in a
data: URI on an <img>, or in allowlisted inline SVG. Nothing else may carry a resource — not CSS url(), not srcset, not <object>, <embed>, <iframe>, <video>, <link>, and never srcdoc.
- No web fonts. System font stack only. Glyphs will differ across machines; say so rather than claiming pixel fidelity.
- Do not generate brand logos or trademarks.
- Never write a customer name, tenant name, subscription id, or internal hostname into the output.
- Before embedding a screenshot or an image of unknown provenance, ask: "is this sanitized for publication?" On "no" or "not sure", stop and mask it first (mask_image.py). A text scan cannot see a name rendered inside an image, so this judgement stays with the user. Re-ask if the image changes.
- Prefer the active workspace's instructions for colour and formatting when they exist; otherwise use this skill's defaults.
- Never call an artifact finished on Tier 1 alone. Without the browser pass, report it as
UNVERIFIED.
Build Flow
-
Storyboard first and stop there. Open with one sentence for the whole artifact — where it starts, what it passes through, where it lands — then one row per slide or section: the id it will keep, the assertion it makes, and the block that carries it. Wait for the user's answer before opening a skeleton.
| id | assertion | block |
|---|
| s2 | 鍵は保管するのをやめる | shf-cards × 2 |
Assertions, not topic names (anti-slop.md). One wrong line is free to fix here and costs a rebuild plus a re-verify once twelve slides exist. Skip only for a poster, or when the user arrives with the structure already settled. If the user hands the rest back, fill it provisionally and mark which rows they never saw.
-
Copy the skeleton for the chosen archetype from assets/skeletons/.
-
Replace the content, using the storyboard ids as data-slide-id and section id. Keep them stable — they are the handles for later edits.
-
Adjust colours by editing <style id="shf-theme"> only; that block is the whole design system, so carrying it into the next artifact is how a series stays consistent. Never touch <style id="shf-css"> or <script id="shf-runtime">; both are hash-pinned.
-
For each image: embed_assets.py, then paste the dataUri into an <img> with alt and data-asset-ref, and add the asset entry to <script id="shf-model">.
-
Verify, then export only the requested format.
Changing anything under assets/runtime/ or assets/css/ means re-running build_skeletons.py, which regenerates the skeletons and re-pins the registry.
Verification Gate
python scripts/verify_html.py <artifact.html> --tier2
- Tier 1 is standard library only and always runs: canonical grammar, element and attribute allowlist, pinned-region hashes, theme tokens, model and asset closure, data URI decode, image metadata, link schemes, size budget.
- Tier 2 needs Playwright: blocks all network egress, walks every slide, waits for images to finish decoding, then checks for zero-size images, missing viewBox, overflow, and console errors.
Exit codes: 0 PASS, 1 FAIL, 2 UNVERIFIED. Anything but 0 means do not ship it.
Fast path is the default: one viewport, only the requested export. Do the exhaustive pass at publish time. Even the fast path never skips single-file-ness, image decode, overflow at the target viewport, deck navigation, or the sanitization question.
Scripts
Missing Pillow or Playwright stops the affected step with installation guidance. It never silently degrades.
References
Requirements
A harness with file read/write and Python 3.x. Everything in this folder is self-contained; copy it anywhere and it still works.
Done Criteria
