# HTML Report > Default output format for reports, summaries, analyses, dashboards, audits, comparisons, digests, briefings, and any deliverable with structured/spatial information. Generates a single self-contained HTML file (no external dependencies) the user can open in a browser, share, print to PDF, or paste into Notion. Lightweight cousin of /design and /magazine — no AI generation server, no editorial chrome, just clean Tailwind-via-CDN HTML that beats Markdown on scannability, comparison, and feel. Use whenever the user asks for a report, summary, breakdown, analysis, audit, dashboard, comparison, or any deliverable that previously would have been a .md file. Triggers: 'report', 'summary', 'audit', 'analysis', 'dashboard', 'compare', 'breakdown', 'rundown', 'brief', 'digest', 'overview', 'recap', 'write up', 'document', 'deliverable'. Reference: https://thariqs.github.io/html-effectiveness/ - Skill: `barkleesanders/html-report` (Agent Skill) - Install (CLI): `npx skillmds@latest add barkleesanders/html-report` - Raw SKILL.md: https://api.skillmd.com/api/skills/barkleesanders/html-report/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: barkleesanders (https://skillmd.com/u/barkleesanders) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/barkleesanders/html-report --- # /html-report — HTML by default, not Markdown **Core thesis** (per [thariqs.github.io/html-effectiveness](https://thariqs.github.io/html-effectiveness/)): HTML beats Markdown for AI-generated outputs because it transforms linear, text-heavy documents into spatial, interactive, visually scannable artifacts that users actually engage with. Diffs, comparisons, status grids, timelines, and call graphs are spatial information; Markdown flattens them. **This skill is the default.** When the user asks for a report / summary / audit / breakdown / dashboard / comparison / brief / digest / analysis / write-up / deliverable, write a single self-contained `.html` file — not `.md`. ## When to use HTML (default) Use HTML for anything with structure, comparison, or status: - Reports, audits, post-mortems, status updates - Side-by-side comparisons (before/after, A/B, vendors, options) - Dashboards: KPIs, metrics, health checks, score cards - Timelines, roadmaps, gantt-ish layouts - Tables of records (vendors, tasks, files, findings) with badges/states - Architecture diagrams, flow descriptions, decision trees - Reading lists / link roundups / research summaries - Anything you'd otherwise reach for Markdown headers + bullet lists for ## When to keep Markdown Markdown is still right for: - Inline chat replies and conversational answers - Code review notes posted as PR comments - Technical specs / design docs / RFCs that live in a repo and need diffing - Beads descriptions, git commit messages, README sections - Any output explicitly headed for a Markdown-rendering destination (GitHub, Linear, Notion-as-MD, blog post source) If unsure: ask the user where the output is going. Notion / Slack / "send to my team" / "I want to share this" / "open it" → HTML. PR / commit / repo file → Markdown. ## Output rules (hard) 1. **Single self-contained `.html` file.** No external CSS files, no separate JS, no asset folders. Tailwind via CDN is allowed and encouraged. 2. **Document order: `` → ` ``` ## Component palette (mix and match) Pick the components that fit the data, then write content. Don't write content first then try to retrofit structure. | If you have… | Use this | |---|---| | 3-6 KPIs / metrics | KPI grid (4-col on desktop) | | Repeating records with status | Findings table with badge column | | Before vs after / option A vs B | Side-by-side comparison (rose/emerald) | | Sequential steps or events | Vertical timeline with date column | | 2-5 mutually exclusive options | Tab strip (or just stacked cards) | | Hierarchical or tree data | Indented list with monospace prefixes | | Quote / callout | Left-bordered blockquote with kicker | | Code or terminal output | `

` |
| Source citations | Inline `` with subtle underline; numbered superscript optional |

1. **Decide HTML vs MD.** Default = HTML. Only switch to MD if destination is clearly a Markdown surface (PR, commit, README, blog source).
2. **Pick components from the palette** based on the data shape — not based on aesthetic.
3. **Write the file** using the skeleton + selected components.
4. **Save** to `~/Claude-Reports/-.html` (override only if user gave a path). This lands in the Google-Drive-synced folder automatically.
5. **Render the PDF**: `~/tools/report-pdf ~/Claude-Reports/-.html`. Always. It prints the verified page/byte/char counts to stderr — report them. If it exits 2, you omitted ``; add it and re-run.
6. **Open it**: `open ~/Claude-Reports/-.html`. Don't ask permission — opening a local file is harmless and the user wants to see the result.
7. **Tell the user** both paths in your reply (note they're in Google Drive → `My Drive/Claude Reports`), and offer to: (a) share the **PDF** link, (b) paste into Notion, (c) iterate on the design.

### If the user asks for a shareable link
Share the **PDF**, never the `.html` — Drive renders PDFs inline and cannot render HTML.

```bash
# find the synced fileId (wait for Drive sync; do NOT `gog drive upload` into a
# synced folder — that creates a duplicate instead of versioning)
# -> mcp__claude_ai_Google_Drive__search_files:
# title contains '' and mimeType = 'application/pdf'
gog -a you@example.com drive share --to=anyone --role=reader --force
# then PROVE it works with no session:
curl -sSL -o /tmp/a.pdf -w '%{http_code} %{size_download}\n' "https://drive.google.com/uc?export=download&id="
```
`--force` is required for public shares (gog's own guard). Omit `--discoverable` so it stays link-only and out of search. **Before sharing publicly, confirm the report contains no PII** — if it does, keep it owner-only and attach the file to an email instead (per the Drive-PII rule).

## Anti-patterns

- Generating a `.md` file when the user said "report" or "summary" or "dashboard" — that's the bug this skill exists to fix.
- Using Markdown headings + bullet lists where a table or grid would communicate faster.
- Writing a 6-paragraph "Executive Summary" when 5 bullets in a TL;DR card would do.
- Adding JavaScript for interactivity the user didn't ask for.
- External CSS files / asset folders — breaks portability. The whole file should travel as one attachment.
- Heavy gradients, drop shadows, or animation flourish — clean and scannable beats decorated.
- **Omitting ``** — silently mojibakes every em-dash, `·`, `§`, `×`, `→` in the PDF and in Drive's preview. The template has it; keep it.
- **Delivering only the `.html`** — then handing over a Drive link the recipient can't read. Run `~/tools/report-pdf` and share the PDF.
- **Verifying a PDF by eye alone.** Render a page or two (`pdftoppm -r 70 -png -f 1 -l 1 x.pdf /tmp/pg`) and actually look at it. Tag-balance checks and a 200 status do not catch corrupted glyphs or a table overflowing the page box.

## Relationship to other skills

- **`/design`** (Stitch MCP) — for designing actual product UIs that will become real frontend code. Heavy, AI-generative, project-scoped.
- **`/magazine`** — for editorial digests where each item gets its own full-viewport spread. Heavy, prescribed treatments per spread.
- **`/visualise`** — for inline-in-conversation SVG/HTML fragments rendered in a sandboxed iframe (no `` wrapper).
- **`/html-report`** (this skill) — lightweight default for any deliverable previously written as `.md`. One file, one open command, done.

When in doubt between this and another HTML skill: this one is the default. The others are when the user explicitly invokes them or when the content clearly fits their format (UI design → /design, multi-spread editorial → /magazine, inline diagram → /visualise).