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:

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:

• localrepopath — 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

1. 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.)

1. 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).

1. Publish. Run the publish script from anywhere:

``bash 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.

1. 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

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.