HTML Report Artifact
Use this skill when a substantial answer, review, analysis, decision memo, or research summary should become a durable artifact instead of a long chat response.
Produce exactly two primary outputs:
artifact.html— the human-facing report.artifact.json— the agent-facing manifest.
The JSON manifest is not a prose duplicate. It is a structured record of sections, components, claims, evidence, limitations, source hashes, and verification.
Files to read first
Resolve paths relative to this SKILL.md.
SPEC.md— the public contract.templates/desktop-report-template.html— the canonical HTML baseline.components/report-components.md— allowed report components.references/anti-slop.md— visual anti-patterns to avoid.- One complete example under
examples/.
Workflow
- Identify the reader, decision, evidence, and source material.
- Draft the semantic outline before writing HTML:
- summary
- sections
- components
- claims
- evidence
- verification
- limitations
- Create
artifact.jsonfrom the outline. - Create
artifact.htmlfromtemplates/desktop-report-template.html. - Ensure HTML and JSON section IDs match exactly, with no duplicates or unregistered extras.
- Ensure HTML and JSON component IDs match exactly, with no duplicates or unregistered extras.
- Hash every local evidence file listed in
artifact.json. - Run:
python3 scripts/check_html_artifact.py artifact.html
python3 scripts/check_artifact_json.py artifact.json --html artifact.html
For repository examples, run:
python3 scripts/check_examples.py
python3 -m unittest discover -s tests
HTML requirements
- Start with
<!doctype html>. - Include
<meta name="artifact-contract" content="artifact-report.v1">. - Use a single
.pagemain column atmax-width:1180px. - Use the canonical font tokens:
--serif: ui-serif, Georgia, "Times New Roman", serif--sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif--mono: ui-monospace, "SF Mono", Menlo, Monaco, monospace
- Use the canonical warm palette tokens:
#FAF9F5#141413#D97757
- Include:
- answer-first TL;DR
- summary cards
- decision note cards for
Adopt Now/Hold Back/Revisit Laterstyle buckets when the report needs plain-language judgment - real sections with a small numbered pill, a short
.sec-intro, and quiet article-like spacing - at least one visual or table
- folded evidence
- verification and limitations
JSON requirements
The manifest must validate against contract/artifact-report.schema.json.
Required top-level fields:
schema_versionartifact_idtitletemplate_versionsource_hashessectionscomponentsclaimsevidenceverificationlimitations
Style rules
- Be answer-first.
- Keep the visible page like a language report, not a component audit. Put typography tokens, commands, raw tables, and implementation notes in folded evidence unless the report is specifically about those details.
- Keep dense raw evidence folded behind
<details>. - Do not invent data.
- Label missing evidence clearly.
- Do not show format-compliance notes to the reader.
- Do not add a sticky sidebar, a default table of contents, or tab-hidden main content.
- Do not use decorative emoji as structural icons.
- Do not use purple gradients, neon colors, GitHub-dark
#0D1117, or generic SaaS dashboard shells.