html-research-reports

HTML Research, Reports & Learning

HTML reports get read; markdown reports of the same length don't. Use HTML whenever the goal is for a human (often someone other than the user) to actually absorb information — concept explainers, status reports, incident reports, knowledge transfer.

Pre-flight — run BEFORE writing the artifact

Invoke html-skills:html-skills-listen (Skill tool) first; it is idempotent. If it returns a URL, inject it verbatim as window.__CLAUDE_SUBMIT_URL__ in the HTML you are about to write, ?t= query string included (a local, single-session loopback handshake — not a credential). If it reported web/sandbox mode, leave that line out; submitToClaude then falls back to clipboard mode.

When to use this skill

• "Summarize how X works"
• "Explain the Y system to me / to my team / to leadership"
• "Write up the incident from yesterday"
• "Weekly status update for my manager"
• "I want to learn about X — synthesize from the codebase + git history + web"
• "Prepare a technical brief on Z"
• Any time the goal is comprehension or sharing, not implementation

Output requirements

Designed for one-time reading — optimize for the reader who opens it once, gets what they need, closes it. Navigable by scrolling and, for longer reports, a sticky sidebar TOC or tab strip.

Include:

• Title + one-sentence framing
• A source list at the bottom — what was synthesized to produce this (files, commits, threads, URLs). Concrete enough that a reader can verify a claim without asking. Cite locations — don't paste raw dumps of third-party content into the sources section, and strip query strings from cited URLs unless they're load-bearing for verification.

Secret hygiene (mandatory)

Reports are built to be shared — treat every artifact as if it will leave the machine. Before embedding any code snippet, config excerpt, log line, command output (including env/printenv and .env contents), quoted Slack/Linear/MCP message, diff, or URL, scan it for credentials and replace each with a typed placeholder that keeps the explanatory value: <REDACTED:AWS_KEY>, Authorization: Bearer <REDACTED>, postgres://app:<REDACTED>@db:5432/prod. Never include real values, even truncated. Watch for: