# Html Report

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

- **Type:** Skill
- **Install:** `agentstack add skill-voidful-claude-html-report-skill-html-report`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [voidful](https://agentstack.voostack.com/s/voidful)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [voidful](https://github.com/voidful)
- **Source:** https://github.com/voidful/claude-html-report-skill/tree/main/.claude/skills/html-report

## Install

```sh
agentstack add skill-voidful-claude-html-report-skill-html-report
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 `` tags and `` 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 `` 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

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

2. **Generate ONE self-contained HTML file** at `//-.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 `` block; custom JS in a single `` block at the bottom.
   - Set ``, ``, ``, and Open Graph tags (the report will be shared as a link — OG tags make link previews work).

3. **Publish.** Run the publish script from anywhere:
   ```bash
   python3 /scripts/publish.py  "" ""
   ```
   The script:
   - Updates `reports/manifest.json` (which the index page reads).
   - `git add -A`, `git commit -m "report: "`, `git push`.
   - Prints the public URL.

4. **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 ``.
- **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 `` 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 `` + CSS or use the snippet in `templates/base.html`.
- **Long detail → `` collapsibles** with descriptive ``.
- **Architecture / flow → Mermaid**. `graph TD; A-->B`.
- **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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [voidful](https://github.com/voidful)
- **Source:** [voidful/claude-html-report-skill](https://github.com/voidful/claude-html-report-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-voidful-claude-html-report-skill-html-report
- Seller: https://agentstack.voostack.com/s/voidful
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.