# Generate HTML Report

> Generate a rich, self-contained HTML document instead of a long Markdown file — for specs & plans, PR/code-review explainers, design mockups & prototypes, research/status reports, or throwaway editing UIs. Use when the user asks to write a "report", wants a PR or piece of code explained visually, wants to compare design options, needs a research or status writeup, wants a diagram/flowchart, or when a Markdown plan/spec is getting too long to read comfortably.

- Skill: `atman-33/generate-html-report` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add atman-33/generate-html-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/atman-33/generate-html-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: atman-33 (https://skillmd.com/u/atman-33)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/atman-33/generate-html-report

---


# Generate HTML Report

## Role

You are producing a rich, self-contained HTML document in place of a long Markdown file, because HTML can express tables, CSS, SVG diagrams, and interactivity that Markdown cannot, and people actually read it.

## The 100-line rule

Default to HTML whenever a Markdown document would credibly cross ~100 lines, or needs a diagram, table, side-by-side comparison, color-coding, or interaction. Below that, plain Markdown is still fine — don't reach for HTML for a quick note.

## 1. Pick the mode

Each mode shapes the content differently; read its detail in [MODES.md](MODES.md) before writing.

- **Spec / plan** — brainstorming multiple options, mockups, an implementation plan.
- **Code review / PR explainer** — annotated diffs, flowcharts of changed logic, severity-coded findings.
- **Design / prototype** — mockup comparisons, tunable sliders/knobs for animations or components.
- **Research / status report** — synthesis across code, git history, connected MCPs, or the web into a readable writeup.
- **Editing interface** — a throwaway single-purpose UI (drag-sort, form editor, side-by-side tuner) ending in a "copy as …" export.

If nothing fits cleanly, default to the Research / status report shape.

## 2. Gather the content

Read whatever the mode needs before writing a line of HTML: source files, `git log`/`git diff`, MCPs already connected in this session (Slack, Linear, etc.), or the web. Never fabricate data, diagrams, or diffs you haven't actually read.

## 3. Write one self-contained file

- Single `.html` file: inline `<style>` and `<script>`, no build step, no external CDN unless the user asks — this is what makes it a one-file upload someone else can just open.
- Use real HTML structure for the content: `<table>` for tabular data, inline SVG for diagrams/flowcharts, `<script>` for interactions, CSS for layout and color coding.
- If the project already has a design-system HTML file, read it first and match its look; otherwise keep styling clean and readable.
- For an editing interface, always end with an export control (a "copy as JSON / Markdown / diff" button) that turns the user's in-browser edits back into something pasteable into a prompt.

## 4. Finish

- Save the file (ask where if the mode/user hasn't implied a path) and open it: `start <path>` (fall back to `explorer.exe <path>` if `start` errors).
- Report the path, the mode chosen, and one line on how to share it (open locally, or upload it somewhere to get a link).

## Tradeoffs to keep in mind

- HTML takes noticeably longer to generate than Markdown — worth it past the 100-line rule, not for a quick note.
- HTML diffs are noisy in version control; don't replace a Markdown file that's actively reviewed as text (e.g. a spec living in a PR review flow) unless the user wants that tradeoff.
- Token cost is higher than Markdown but rarely the real bottleneck with large context windows — don't let it stop you from using the richer format when the content warrants it.