html-report

html-report is a portable agent skill that turns evidence-backed analysis and source material into a standalone, responsive HTML report. It supports Review, Investigation, Decision, Plan, Overview, and Brief structures; typed evidence; human-input controls; local Mermaid diagrams; light and dark themes; and named visual brands.

The generated report is one offline .html file. Rendering and validation use only Python's standard library and bundled assets.

Install

Clone or download this repository, then copy or symlink skill/html-report into the skill directory used by your agent. Installing the skill folder—not the whole development repository—is sufficient.

Codex

Install globally:

mkdir -p ~/.agents/skills
ln -s /absolute/path/to/this-repo/skill/html-report ~/.agents/skills/html-report

For one repository, use <project>/.agents/skills/html-report instead. Codex can invoke the skill automatically or explicitly with $html-report. Codex supports symlinked skill folders and normally detects changes automatically.

Claude Code

Install globally:

mkdir -p ~/.claude/skills
ln -s /absolute/path/to/this-repo/skill/html-report ~/.claude/skills/html-report

For one repository, use <project>/.claude/skills/html-report. Invoke it with /html-report, or let Claude select it from the skill description. If the top-level skills directory is created while Claude Code is already running, restart that session once.

Zed Agent

Install globally:

mkdir -p ~/.agents/skills
ln -s /absolute/path/to/this-repo/skill/html-report ~/.agents/skills/html-report

For one worktree, use <worktree>/.agents/skills/html-report. Invoke it with /html-report or an @-mention in the Agent Panel. These locations apply to the native Zed Agent; an external agent running inside Zed uses that agent's own skill locations.

Other Agent Skills-compatible harnesses

Copy the complete skill/html-report directory to the harness's user-level or project-level skills directory. The harness must support SKILL.md, allow the agent to read bundled references/assets, and provide Python 3 if reports should be rendered locally.

Use

Ask for the reader outcome and provide the source material. Examples:

Use $html-report to investigate these service logs without overstating root cause.

Use /html-report to compare these deployment options and ask me for a decision.

Create a plan report from this migration context. Keep facts, assumptions, risks,
and human decisions distinct.

The skill returns the generated .html artifact as its primary result. See the two-brand, six-intent gallery for representative Review, Investigation, Decision, Plan, Overview, and Brief outputs.

Render directly

The agent normally builds the typed JSON specification and runs these commands:

python3 skill/html-report/scripts/render_report.py report.json report.html
python3 skill/html-report/scripts/validate_report.py report.html

The specification is documented in skill/html-report/references/specification.md. Content values are plain text; raw HTML, CSS, scripts, event handlers, unknown brands, unresolved evidence references, and remote dependencies are rejected.

Brands

Reports select a registered brand in their JSON specification:

{"brand": "personal"}

Bundled brands are personal and work. Use personal by default and use work only when the user explicitly requests it. Brand selection changes presentation, not report semantics, and is intentionally not displayed as report metadata.

To add a brand:

1. Add a local stylesheet under skill/html-report/assets/. Define every token used by core.css for both light and dark modes.
2. Register its ID, human label, and stylesheet in skill/html-report/assets/brands.json.
3. Do not change semantic markup, reading order, evidence roles, accessibility, offline behavior, or inject per-report CSS.
4. Run the palette, runtime, browser, gallery, and skill validation commands below.

See docs/BRANDS.md for the brand contract, required tokens, responsive rules, and review checklist.

Develop and verify

python3 -m unittest discover -s tests -v
python3 examples/gallery/generate_gallery.py
python3 /path/to/skill-creator/scripts/quick_validate.py skill/html-report

Chromium is the supported and automated browser target. Reports remain ordinary semantic HTML and may work elsewhere, but other engines are not part of the project's compatibility claim.

Architecture, product decisions, browser support, portability, and brand guidance live in docs/.

Upstream documentation

• Codex skills
• Claude Code skills
• Zed skills