htmlify + deckify skills: agent answers become self-contained HTML documents and decks, validated by a bundled CLI. Optional Stop hook archives long answers automatically.

GitHub stars
20

Install

/plugin install htmlify@htmlify

Run it inside Claude Code after adding the marketplace with /plugin marketplace add zakelfassi/htmlify.

Contents

Discovered from source

Skills 2

deckify

Deckify turns dense context into a browser-ready HTML deck plus a downloadable guide. It is an off-the-shelf content-creator skill: the output should be usable for a YouTube talk, live workshop, recorded lecture, webinar, internal enablement session, or publishable companion PDF.

Deckify generates HTML by default. It extends its sibling skill htmlify with:

  • deck-first narrative structure
  • speaker notes and detachable notes
  • run-of-show and chapter timing
  • demo/lab panels
  • downloadable guide/PDF mode
  • 40-60% visual coverage planning
  • image-generation illustration slots
  • browser screenshot capture when useful for visual references
  • validation for presentation and print/download use

Operating Rules

  1. Gather evidence first. Read the supplied source, repo files, docs, screenshots, existing deck/page, or prior artifact before designing the deck.
  2. Choose the smallest deck mode that fits:
    • talk-deck: YouTube/live presentation with speaker notes and run-of-show.
    • workshop-deck: talk plus exercises, labs, checkpoints, and handouts.
    • essay-deck: presentation plus downloadable long-form guide.
    • demo-deck: presentation centered around live demos and fallback screenshots.
    • launch-deck: product narrative, proof, risks, roadmap, and CTA.
    • teaching-guide: PDF-first guide with optional slide mode.
  3. Keep the output self-contained unless the user explicitly wants external assets. Inline CSS and JS. If generated images or screenshots are used, save them into the project and reference them locally.
  4. Make the first viewport presentation-ready: title, promise, audience, timing, and navigation controls.
  5. Add speaker notes for every substantive slide. Include detachable notes when the deck is for live presentation.
  6. Include a run-of-show with timestamps and chapter labels for YouTube.
  7. Include a guide/PDF mode when the user asks for a download, companion essay, handout, or post-watch material.
  8. Aim for 40-60% visual coverage for content decks unless the user asks for a text-only brief. Count full-slide visuals, companion graphics, screenshots, diagrams, demos, charts, and worksheet panels.
  9. Use visuals to clarify systems, flows, tradeoffs, proof, or examples. Do not add decorative stock-like images.
  10. When an image, screenshot, or figure references a link, article, documentation page, post, paper, or source screenshot, put the source in the visible caption/ref near the image (e.g. Source: <a href="...">Exact source title</a>). Do not leave source URLs only in a hidden manifest.
  11. Validate before final response: standalone HTML, keyboard navigation, notes, guide/print mode, media references, visual coverage, and no obvious layout overlap.

Visual Direction

Default to the Hardcopy design system in its deck tempo: paper-field slides, serif display headlines (one idea per slide), mono-uppercase metadata, a compressed plate footer with slide number and progress, one international-orange accent for the active state, and carbon (dark) surfaces for presenter chrome and speaker notes so chrome never competes with the slide. Load references/hardcopy.md for tokens, devices, and print rules before styling.

When the project supplies AGENTS.md, PRODUCT.md, DESIGN.md, brand tokens, or an existing design system, treat them as authoritative over Hardcopy.

Image Generation Workflow

Use an image-generation skill or tool (if one is available in the environment) when the deck or guide benefits from AI-created bitmap visuals:

  1. Generate images as reusable slide/guide assets. Prefer 16:9 landscape for slides and 4:3 or wide worksheet panels for guides.
  2. For project-bound assets, move or copy selected outputs into the workspace and reference them locally; never reference only a tool's temporary output path.
  3. Avoid embedded text in generated images unless exact text is essential. Put labels and explanations in HTML captions.
  4. Store the final prompt near the consuming markup: data-imagegen-prompt="...", an adjacent source manifest, or a visuals.md/visuals.json file when there are many assets.
  5. Inspect generated images before using them. Check subject, style, readability, text artifacts, composition, and whether the asset supports the point.
  6. If image generation is rate-limited or unavailable, do not draw SVG illustration substitutes for what should be a bitmap. Surface the blocker clearly, keep a non-illustrated pending visual slot with data-imagegen-prompt, and report that generated bitmap creation remains pending. (Deterministic system diagrams as inline SVG are always fine — this rule is about illustrations.)

Recommended prompt scaffold:

Use case: scientific-educational
Asset type: slide and PDF companion illustration
Primary request: <specific concept>
Visual style: flat technical-plate illustration, warm paper field, dark ink linework,
hairline structure, a single international-orange accent, schema-like boxes and arrows.
Composition: <full slide / companion graphic / worksheet panel>
Text policy: no readable embedded text; captions and labels will be in HTML.
Avoid: photorealism, glossy gradients, stock-photo look, logos, decorative blobs, tiny illegible labels.
Aspect: 16:9 landscape unless guide-specific.

Screenshot Workflow

Use browser automation/screenshot tooling (whatever the environment provides) when the visual would be stronger with real evidence:

  • Capture screenshots of documents, dashboards, tools, traces, eval reports, product screens, source docs, or demo states when they help explain or prove the talk.
  • Redact sensitive data before publishing. Do not capture credentials, private user data, inbox content, tokens, secrets, or tenant data unless explicitly approved.
  • Save screenshots into the project and reference them locally. Include source URL/file, capture date, and any redaction note.
  • If screenshot tooling is unavailable, use deterministic diagrams or mark screenshot capture as pending rather than inventing evidence.

HTML Deck Shape

Use one HTML file with deck and guide modes. The full contract — required DOM, keyboard handler, notes panel, guide mode, print rules, and what the validator checks — is in references/deck-template.md. Skeleton:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Exact Talk Title</title>
  <style>
    /* Inline, responsive, print-aware CSS. */
  </style>
</head>
<body>
  <header class="topbar">
    <!-- deck controls, progress, notes, guide/print -->
  </header>
  <main class="deck-shell">
    <section class="slide active" data-title="Opening">
      <!-- slide content -->
      <aside class="notes">...</aside>
    </section>
  </main>
  <aside class="notes-panel">...</aside>
  <article class="guide">
    <!-- downloadable guide/PDF companion -->
  </article>
  <script>
    /* keyboard navigation, notes, guide mode, print */
  </script>
</body>
</html>

Validate the Deck

Before the final response, run the bundled validator with the deck profile:

npx -y @zakelfassi/htmlify htmlify-answer --validate path/to/deck.html --profile deck

From a repo or plugin checkout, use node <checkout>/bin/htmlify-answer.js (in Claude Code plugin context: node "${CLAUDE_PLUGIN_ROOT}/bin/htmlify-answer.js"). The deck profile checks standalone structure, slide sections, keyboard navigation, speaker notes on substantive slides, script safety, external-asset bans, and size. Fix every reported error before responding; report remaining warnings. If the validator cannot run in the environment, perform the checklist below manually and say so.

Recommended Sections

For most talk artifacts:

  1. Opening title: audience, promise, duration, core thesis.
  2. Cold open or problem story.
  3. Mental model or map.
  4. Main teaching acts, each with 2-4 slides.
  5. Tradeoff matrices or decision tables.
  6. Live demo or prepared demo section.
  7. Failure modes and how to detect them.
  8. Run-of-show with timestamps.
  9. Closing checklist.
  10. Downloadable guide: summary, modules, exercises, checklist, sources.
  11. Source shelf and verification notes.

Slide Rules

  • One idea per slide.
  • Use big claims sparingly and support them with diagrams, tables, proof, or demos.
  • Keep slide text presentable at 1080p and readable in a YouTube player.
  • Put extra explanation in speaker notes or guide mode.
  • Every slide should have a reason to exist in the spoken arc.
  • Every visual should either explain a system, compare options, show proof, or create a memory hook.

Guide/PDF Rules

  • The guide is not a transcript. It should be useful after the video.
  • Include summaries, exercises, checklists, references, and implementation heuristics.
  • Print CSS must hide deck controls and print the guide.
  • Links should be visible and useful. For offline handouts, include source titles and dates when relevant.

Validation Checklist

Run lightweight validation before final response (the --profile deck validator covers the structural items automatically):

  • HTML parser accepts the file.
  • Embedded JavaScript syntax checks.
  • Exactly one <html> and one normal <body> tag.
  • Slide count is intentional.
  • Speaker notes exist for each substantive slide.
  • Guide/PDF mode exists when requested.
  • Print CSS exists for guide/download artifacts.
  • Visual coverage is counted and is roughly 40-60% when requested.
  • Every local image/screenshot reference exists.
  • Every image that references a link, post, doc, paper, or screenshot source has a visible source link in its caption/ref.
  • No external fonts, CDNs, analytics, or remote assets unless approved.
  • Screenshot capture was used when useful and available, or its absence is reported.
  • Image generation was used for bitmap visuals when available, or pending slots are marked with prompts without SVG illustration substitutes.

Final Response

Report:

  • HTML file path.
  • Artifact mode.
  • Slide count, visual coverage, and guide/PDF status.
  • Generated-image outputs or pending prompt slots.
  • Screenshot sources used, or why they were not used.
  • Validation performed (including the validator command and result) and any remaining gaps.

htmlify

Use HTML when the answer needs shape, scanning, comparison, annotation, print/PDF sharing, or browser-native interaction. Produce a single .html file by default.

Operating Rules

  1. Gather evidence first. Read the repo, docs, git state, PR/CI/deploy state, logs, screenshots, or supplied source material needed for the artifact. Mark uncertain claims as needs verification.
  2. Pick the smallest artifact mode that fits the request:
    • operator-brief: what happened, what is next, blockers, risks, attention.
    • build-plan: problem, target shape, phases, owners, validation, rollback.
    • implementation-map: modules, files, data flow, hot path, edit sequence.
    • pr-review-packet: motivation, before/after, diff tour, reviewer checklist.
    • release-brief: PRs, checks, deploy state, proof, rollback.
    • incident-report: impact, timeline, root cause, mitigations, follow-ups.
    • decision-brief: options, tradeoffs, recommendation, decision needed.
    • status-report: shipped, slipped, carryover, blockers, next period.
    • explainer: concept, request path, examples, glossary, FAQs.
    • prototype or editor: clickable flow, tuning panel, triage board, or exportable UI.
  3. Make the artifact visual before verbose. Prefer cards, lanes, timelines, matrices, charts, diagrams, annotated diffs, tabs, accordions, and compact tables over long paragraphs.
  4. Keep it self-contained. Inline CSS and JS; no external fonts, CDNs, assets, analytics, or build step unless the user explicitly asks.
  5. Make it operator useful. The first viewport should reveal the subject, current status, and where attention should go.
  6. Keep copy tight. Labels, numbers, and short evidence-backed statements beat generic prose.
  7. Include print CSS for artifacts intended to share, archive, or export as PDF.
  8. Add keyboard navigation for deck-style artifacts. For full presentation decks with speaker notes and run-of-show, use the companion deckify skill instead.
  9. Make mobile acceptable, but optimize dense operational artifacts for desktop review.
  10. When an image, screenshot, figure, or thumbnail references a link, article, documentation page, post, paper, dashboard, or source page, attach the source in the visible caption/ref near the image. Prefer a caption anchor such as Source: <a href="...">Exact source title</a> or weave the linked title into the caption. Do not leave source URLs only in hidden metadata.
  11. Validate before final response: doctype, standalone <html>/<body>, no missing local assets, expected sections, source-linked captions for referenced images, and no obvious layout overlap.

Visual Direction

Default to the Hardcopy design system — the document language of engineering plates and datasheets: warm paper field, ink hairlines, serif display headings, mono-uppercase metadata, one international-orange accent, carbon code wells, stamps for status, crop marks, and a plate-style title block. Load references/hardcopy.md for the token block, the seven devices, and print rules before styling any artifact.

When the project supplies DESIGN.md, brand tokens, or an established design system, those are authoritative over Hardcopy.

Validate the Artifact

Before the final response, run the bundled validator on the written file:

npx -y @zakelfassi/htmlify htmlify-answer --validate path/to/artifact.html --profile rich

Use --profile app for artifacts that legitimately carry inline interactivity (editors, prototypes, boards). From a repo or plugin checkout, use node <checkout>/bin/htmlify-answer.js (in Claude Code plugin context: node "${CLAUDE_PLUGIN_ROOT}/bin/htmlify-answer.js"). Fix every reported error before responding; report any remaining warnings in the final response. If the validator cannot run in the environment, perform rule 11 manually and say so.

HTML Shape

Use semantic structure:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Exact Artifact Title</title>
  <style>
    /* Inline, responsive, print-aware CSS. */
  </style>
</head>
<body>
  <main>
    <section aria-labelledby="title">
      <p class="eyebrow">Mode / repo / date</p>
      <h1 id="title">Exact subject</h1>
    </section>
  </main>
</body>
</html>

Use restrained, purposeful UI. Avoid generic purple gradients, decorative blobs, nested cards, huge marketing heroes for operational work, and filler copy that restates headings.

Recommended Sections

For most operator/build artifacts:

  1. Title: exact subject, date, repo/branch/environment.
  2. Scoreboard: green/yellow/red status cards.
  3. What changed: timeline or shipped cards.
  4. System shape: flow, module map, ownership lanes, or annotated diff.
  5. On deck: next actions with owner/context/gate.
  6. Risks and blockers: severity, evidence, mitigation, decision needed.
  7. Better next time: process, architecture, or product improvements.
  8. Alpha: non-obvious learning worth preserving.
  9. Validation: tests, deploy proof, manual checks, gaps.
  10. Closeout: next focus and stop/continue/kill recommendation.

Rich Artifact Patterns

Load references/htmlify-principles.md when the artifact needs deeper mode selection, design guidance, or examples inspired by the HTML effectiveness catalogue.

Load references/agent-integrations.md when the user asks how to install htmlify into Codex, Claude Code, Cursor, Windsurf, Aider, Pi/OMP, or other coding agents, or asks for hook-based automatic long-answer export.

Use these modules when useful:

  • Scoreboard cards for state, counts, proof, blockers.
  • Timeline for discovery, fix, validation, deploy, follow-up.
  • Swimlanes for frontend/backend/infra/test/docs ownership.
  • Dependency graph for modules, services, and hot paths.
  • Risk matrix for issue, evidence, severity, owner, mitigation.
  • File tour for path, change, why it matters, validation.
  • Decision panel for options, tradeoffs, recommendation.
  • Review annotation layer for comments, evidence, and follow-up prompts.
  • Lightweight editor when the user needs to manipulate ordering, flags, prompts, or triage state and export the result.

Final Response

Report the HTML file path, artifact mode, evidence sources checked, and validation performed (including the validator command and result). State any verification not run.

If using the bundled Pi/OMP runtime, see the repository README for /htmlify commands and install paths.

Hooks 1

Sponsors

Details

Marketplace
zakelfassi/htmlify
Category
Productivity
Keywords
html, artifacts, decks, reports, presentations