html-report
Generate a self-contained, polished, interactive HTML report and publish it to the user's GitHub Pages site.
Why this skill exists (read this first)
Claude defaults to markdown for everything. Markdown is fine for plain text, but it's a failure mode for any output that has data, comparisons, code, or detail that the reader will want to navigate. This skill exists to push you toward HTML's strengths. If you generate a wall of <p> tags and <h2> headings, you have wasted this skill — markdown would have done the same job.
Concretely, HTML can do all of these and markdown cannot:
| Capability |
Use it for |
| Interactive charts (Chart.js / Plotly / ApexCharts) |
any numeric data, trends, distributions |
| Sortable / filterable / searchable tables (DataTables, grid.js) |
any tabular data with >5 rows |
| Tabs |
comparing alternatives, before/after, multiple views of same data |
Collapsible <details> sections |
proofs, raw output, optional deep-dives, long appendices |
| Syntax-highlighted code with copy buttons (highlight.js / Prism) |
any code snippet |
| Mermaid / Graphviz diagrams |
architecture, flows, state machines, dependency graphs |
| KaTeX / MathJax |
any equation |
| Hover tooltips, popovers, modals |
term definitions, footnotes, citations |
| Animations / transitions |
state changes, reveals, focus shifts |
| Dark mode toggle |
every report |
| Sticky table-of-contents with scroll-spy |
any report >2 sections |
| Responsive layout |
mobile reading |
Print stylesheet (@media print) |
shareable PDFs |
| Embedded video / audio |
media-heavy work |
| Search / filter inputs over content |
long lists, FAQs, glossaries |
Every report you produce should use at least three of these. If you can't find three that apply, the user probably wanted markdown — push back and ask.
Configuration
Read config.json next to this file. Fields:
local_repo_path — local clone of the GitHub Pages repo. Optional — if empty, the script auto-detects it from where this skill lives on disk (works whether installed in-place or symlinked).reports_dir — subdirectory for reports (default: reports).base_url — GitHub Pages base URL. Optional — auto-detected from git remote origin if empty.
The user should normally not need to edit anything.
Workflow
Plan the report. Before writing HTML, decide:
- What's the headline finding? (Goes at the top, big.)
- What sections does it have?
- For each section, which interactive element fits? (data → chart, comparison → tabs, code → highlighted block, long → collapsible, etc.)
- Will it have a TOC? (Yes if >2 sections.)
Generate ONE self-contained HTML file at <repo>/<reports_dir>/<YYYY-MM-DD>-<slug>.html.
- Slug should be short, kebab-case, descriptive (
gpt5-vs-claude-benchmark, not report-1).
- Start from
templates/base.html — it already wires up Tailwind, highlight.js, Chart.js, Mermaid, KaTeX, dark mode, sticky TOC, and print styles.
- All libraries via CDN (no build step).
- Custom CSS in a single
<style> block; custom JS in a single <script> block at the bottom.
- Set
<title>, <meta name="description">, <meta name="viewport">, and Open Graph tags (the report will be shared as a link — OG tags make link previews work).
Publish. Run the publish script from anywhere:
python3 <skill-dir>/scripts/publish.py <html-path-relative-to-repo> "<title>" "<one-line description>"
The script:
- Updates
reports/manifest.json (which the index page reads).
git add -A, git commit -m "report: <title>", git push.- Prints the public URL.
Return the URL to the user. Don't fabricate it — use the script's output.
Quality bar — required for every report
- Single file, no build step, CDN-only deps.
- Mobile-responsive — test in your head: does it work on a 375px viewport?
- Dark mode with a toggle, persisted to localStorage.
- Title + description + OG tags in
<head>.
- Prefers-reduced-motion respected — no jarring animations for users who opted out.
- Sticky TOC for any report with >2 top-level sections.
- Anchor links on all section headings (
id="...").
- No inline
style="" — use a single <style> block.
- No hardcoded light-mode colors — use Tailwind's
dark: variants or CSS variables.
Strongly recommended (pick what fits the content)
- Tables → DataTables.js (sort, filter, paginate). Drop-in: load
datatables.net CDN, wrap with $('table').DataTable().
- Numeric data → Chart.js (bar/line/pie/scatter/radar). Always set
responsive: true, maintainAspectRatio: false.
- Code → highlight.js, plus a "copy" button per block.
- Comparisons (3+ alternatives) → tabs. Hand-roll with
<input type="radio"> + CSS or use the snippet in templates/base.html.
- Long detail →
<details> collapsibles with descriptive <summary>.
- Architecture / flow → Mermaid.
<pre class="mermaid">graph TD; A-->B</pre>.
- Math → KaTeX auto-render (faster than MathJax). Inline:
$x^2$. Display: $$\int...$$.
- Multiple views of same data → segmented control / toggle.
- Long lists (>20 items) → search/filter input at the top.
- Citations / footnotes → popovers that show the source on hover, not at the bottom of the page.
Anti-patterns (do not ship these)
- ❌ Markdown disguised as HTML — paragraphs and bullets only.
- ❌ Static images of charts when the data is small enough to render live.
- ❌ Tables of >10 rows with no sort or filter.
- ❌ Walls of code with no syntax highlighting.
- ❌ 5MB of JS for a 200-word report. Pick libraries that fit the content.
- ❌ Light-only color choices.
- ❌ "Click here" links — use descriptive link text.
- ❌ Charts that overflow on mobile.
Example: planning a "model benchmark" report
| Element |
Choice |
| Headline number |
Big number at the top, with sparkline trend |
| Per-task results |
DataTable, sortable by score |
| Two models compared head-to-head |
Bar chart |
| Three configs compared |
Tabs |
| Per-task example outputs |
Collapsibles |
| Methodology |
Collapsible at the bottom |
| Math (eg. ELO formula) |
KaTeX |
Draft mode
If the user says "just draft it" or "don't push yet", pass --draft to the publish script. It updates the manifest locally, skips commit + push, and prints the local file path instead of the URL.
After publishing
The script prints the URL. Pass it through verbatim. If the script printed a warning about a failed push, surface that to the user — don't bury it.
When NOT to use this skill
- One-line answers.
- Throwaway debug output.
- Anything the user explicitly asked for as markdown / plain text.
- Code that goes into a file in the user's project.
1---2name: html-report3description: Generate a rich, INTERACTIVE HTML report (not markdown!) and publish it to GitHub Pages. Use when the user asks for a "report", "writeup", "summary page", "dashboard", "share link", or anything that benefits from interactivity, charts, sortable tables, tabs, search, syntax highlighting, math, diagrams, or visual polish that markdown cannot deliver. Returns a public URL the user can share.4---56# html-report78Generate a self-contained, polished, **interactive** HTML report and publish it to the user's GitHub Pages site.910## Why this skill exists (read this first)1112Claude defaults to markdown for everything. Markdown is fine for plain text, but it's a **failure mode** for any output that has data, comparisons, code, or detail that the reader will want to navigate. This skill exists to push you toward HTML's strengths. If you generate a wall of `<p>` tags and `<h2>` headings, **you have wasted this skill** — markdown would have done the same job.1314Concretely, HTML can do all of these and markdown cannot:1516| Capability | Use it for |17|---|---|18| **Interactive charts** (Chart.js / Plotly / ApexCharts) | any numeric data, trends, distributions |19| **Sortable / filterable / searchable tables** (DataTables, grid.js) | any tabular data with >5 rows |20| **Tabs** | comparing alternatives, before/after, multiple views of same data |21| **Collapsible `<details>` sections** | proofs, raw output, optional deep-dives, long appendices |22| **Syntax-highlighted code with copy buttons** (highlight.js / Prism) | any code snippet |23| **Mermaid / Graphviz diagrams** | architecture, flows, state machines, dependency graphs |24| **KaTeX / MathJax** | any equation |25| **Hover tooltips, popovers, modals** | term definitions, footnotes, citations |26| **Animations / transitions** | state changes, reveals, focus shifts |27| **Dark mode toggle** | every report |28| **Sticky table-of-contents with scroll-spy** | any report >2 sections |29| **Responsive layout** | mobile reading |30| **Print stylesheet** (`@media print`) | shareable PDFs |31| **Embedded video / audio** | media-heavy work |32| **Search / filter inputs** over content | long lists, FAQs, glossaries |3334Every report you produce should use **at least three** of these. If you can't find three that apply, the user probably wanted markdown — push back and ask.3536## Configuration3738Read `config.json` next to this file. Fields:39- `local_repo_path` — local clone of the GitHub Pages repo. **Optional** — if empty, the script auto-detects it from where this skill lives on disk (works whether installed in-place or symlinked).40- `reports_dir` — subdirectory for reports (default: `reports`).41- `base_url` — GitHub Pages base URL. **Optional** — auto-detected from `git remote origin` if empty.4243The user should normally not need to edit anything.4445## Workflow46471. **Plan the report.** Before writing HTML, decide:48 - What's the headline finding? (Goes at the top, big.)49 - What sections does it have?50 - For each section, which interactive element fits? (data → chart, comparison → tabs, code → highlighted block, long → collapsible, etc.)51 - Will it have a TOC? (Yes if >2 sections.)52532. **Generate ONE self-contained HTML file** at `<repo>/<reports_dir>/<YYYY-MM-DD>-<slug>.html`.54 - Slug should be short, kebab-case, descriptive (`gpt5-vs-claude-benchmark`, not `report-1`).55 - Start from `templates/base.html` — it already wires up Tailwind, highlight.js, Chart.js, Mermaid, KaTeX, dark mode, sticky TOC, and print styles.56 - All libraries via CDN (no build step).57 - Custom CSS in a single `<style>` block; custom JS in a single `<script>` block at the bottom.58 - Set `<title>`, `<meta name="description">`, `<meta name="viewport">`, and Open Graph tags (the report will be shared as a link — OG tags make link previews work).59603. **Publish.** Run the publish script from anywhere:61 ```bash62 python3 <skill-dir>/scripts/publish.py <html-path-relative-to-repo> "<title>" "<one-line description>"63 ```64 The script:65 - Updates `reports/manifest.json` (which the index page reads).66 - `git add -A`, `git commit -m "report: <title>"`, `git push`.67 - Prints the public URL.68694. **Return the URL** to the user. Don't fabricate it — use the script's output.7071## Quality bar — required for every report7273- **Single file**, no build step, CDN-only deps.74- **Mobile-responsive** — test in your head: does it work on a 375px viewport?75- **Dark mode** with a toggle, persisted to localStorage.76- **Title + description + OG tags** in `<head>`.77- **Prefers-reduced-motion respected** — no jarring animations for users who opted out.78- **Sticky TOC** for any report with >2 top-level sections.79- **Anchor links** on all section headings (`id="..."`).80- **No inline `style=""`** — use a single `<style>` block.81- **No hardcoded light-mode colors** — use Tailwind's `dark:` variants or CSS variables.8283## Strongly recommended (pick what fits the content)8485- **Tables → DataTables.js** (sort, filter, paginate). Drop-in: load `datatables.net` CDN, wrap with `$('table').DataTable()`.86- **Numeric data → Chart.js** (bar/line/pie/scatter/radar). Always set `responsive: true, maintainAspectRatio: false`.87- **Code → highlight.js**, plus a "copy" button per block.88- **Comparisons (3+ alternatives) → tabs**. Hand-roll with `<input type="radio">` + CSS or use the snippet in `templates/base.html`.89- **Long detail → `<details>` collapsibles** with descriptive `<summary>`.90- **Architecture / flow → Mermaid**. `<pre class="mermaid">graph TD; A-->B</pre>`.91- **Math → KaTeX** auto-render (faster than MathJax). Inline: `$x^2$`. Display: `$$\int...$$`.92- **Multiple views of same data → segmented control / toggle**.93- **Long lists (>20 items) → search/filter input** at the top.94- **Citations / footnotes → popovers** that show the source on hover, not at the bottom of the page.9596## Anti-patterns (do not ship these)9798- ❌ Markdown disguised as HTML — paragraphs and bullets only.99- ❌ Static images of charts when the data is small enough to render live.100- ❌ Tables of >10 rows with no sort or filter.101- ❌ Walls of code with no syntax highlighting.102- ❌ 5MB of JS for a 200-word report. Pick libraries that fit the content.103- ❌ Light-only color choices.104- ❌ "Click here" links — use descriptive link text.105- ❌ Charts that overflow on mobile.106107## Example: planning a "model benchmark" report108109| Element | Choice |110|---|---|111| Headline number | Big number at the top, with sparkline trend |112| Per-task results | DataTable, sortable by score |113| Two models compared head-to-head | Bar chart |114| Three configs compared | Tabs |115| Per-task example outputs | Collapsibles |116| Methodology | Collapsible at the bottom |117| Math (eg. ELO formula) | KaTeX |118119## Draft mode120121If the user says "just draft it" or "don't push yet", pass `--draft` to the publish script. It updates the manifest locally, skips commit + push, and prints the local file path instead of the URL.122123## After publishing124125The script prints the URL. Pass it through verbatim. If the script printed a warning about a failed push, surface that to the user — don't bury it.126127## When NOT to use this skill128129- One-line answers.130- Throwaway debug output.131- Anything the user explicitly asked for as markdown / plain text.132- Code that goes into a file in the user's project.
voidful