create-html-report

create-html-report

Based on $ARGUMENTS, convert the analysis results into a self-contained HTML report where "you can grasp the key points just by reading, and check the details if needed."

As a rule, the final deliverable is a single .html as a file.

Usage

Pass the content you want turned into a report (comparison targets, data, purpose) as arguments. If the arguments are ambiguous, confirm with the user in Step 1.

• If the user does not specify an output destination, _/reports/<report-name>.html
• --interactive Allow inline JavaScript only when specified, or when there is a large amount of data that is difficult to handle with static display
• --output <path> lets you explicitly specify the output destination

Core contract

The following must always be satisfied.

1. Insight first — Do not make creating charts an end in itself. First identify the most important conclusions, changes, risks, and decision-making materials, and use only the visualizations that help understand them.
2. Do not invent data — Do not fill in unknown values, dates, ratios, units, or statuses by guessing. Treat missing as missing. If necessary assumptions are made, state them explicitly in the report.
3. Self-contained — Do not depend on external CDNs, external fonts, external JavaScript libraries, external stylesheets, or external images. Include CSS, SVG, and any necessary JavaScript within the HTML. The usual handling of data sources <a href="https://..."> is not considered an external dependency. There must be no external communication at page load.
4. Accessible by default — Do not rely on color alone for information. Ensure that the main content of charts can also be checked in text or tables. Consider keyboards, screen readers, dark mode, and enlarged display.
5. Progressive enhancement — Ensure that the main conclusions and data can be read without JavaScript. Add interaction only when it assists understanding.
6. Deterministic rendering — Leave SVG coordinate calculations, escaping, themes, and basic components to the bundled renderer. Claude should not manually reimplement the same SVG boilerplate every time.

Flow

Step 1: Understand the Context and input data

Identify the following from the conversation, arguments, specified files, and existing data.

• The report's purpose, intended readers, and what decision needs to be made
• Scope/period, metrics and units, data sources
• Comparison targets, schedule and dependencies, uncertainty and missing values

Do not ask questions if the information can be sufficiently inferred from the conversation or existing data. If a useful partial report can be created even with insufficient information, do not fill in values arbitrarily; instead, state it as "constraints/missing information" and proceed. Only perform minimal confirmation when the purpose or input is so ambiguous that a correct report cannot be created.

Step 2: Design the narrative

Before writing HTML, organize the following internally.

• The single most important message, 3–5 key findings
• Decisions and recommendations, data supporting the findings, information for detailed confirmation

In principle, order the information hierarchy as follows.

1. Title / scope
2. Executive summary
3. KPI / key findings
4. Decision / recommendation (if applicable)
5. Main visual analysis
6. Schedule / risks / dependencies (if applicable)
7. Detailed data
8. Methodology / assumptions
9. Sources / generated metadata

Do not cram everything into a single-screen dashboard. Place important information at the top, and continue with details below.

Step 3: Choose a chart type from the "relationships" in the data

The chart types supported by the renderer are bar / line / scatter / heatmap / waterfall / donut / radar / gantt only these 8. Do not choose based on the chart type being available; select based on the relationship you want to convey.

Relationship to convey	chart type	Notes
Size and ranking comparison between categories	bar	Horizontal bars recommended, axis starting at 0
Trends and transitions over time	line	Express missing data as gaps; do not fabricate interpolation
Correlation between two variables	scatter	Supplement the explanation of correlation with annotations
Volume per period, distribution of time × category	heatmap	Use perceptually uniform color schemes for continuous values
Contribution to increase/decrease, cumulative change	waterfall	Clearly state the start value, end value, and difference
Part-to-whole (composition ratio)	donut	6 segments or fewer; also provide a table with exact values
Multivariate profile	radar	Do not make this the default (see below)
Task duration, dependencies, and milestones	gantt	If dependencies are dense, also provide a table

For relationships not covered above (distributions, before/after, multi-series comparison, etc.), avoid easy substitution with a supported chart type, and prioritize expression via a data table. Do not add custom SVG that imitates an unsupported chart type.

Do not make radar charts the default. There is value in getting an overview of the "shape" of a multi-axis profile itself, so use them only when there are few axes and they can be legitimately normalized to the same scale.

Chart anti-patterns

As a rule, avoid the following.

• 3D charts, gauge / speedometer, unnecessary gradients and excessive shadows
• Dual-axis charts, line charts with 10 or more overlaid series, donuts with a large number of slices
• Charts for decorative purposes only, charts with inconsistent baselines even though the purpose is comparison
• Charts that force strict comparison based only on area or color

Step 4: When using gantt / schedule

For plans with start dates, end dates, milestones, and dependencies, prioritize gantt . gantt satisfies the following.

• Task / workstream names on the left, actual dates on the horizontal axis, appropriate ticks such as week / month
• Grouping by phase; milestones displayed with a shape other than a bar, such as a diamond
• If there is progress, overlay progress on the planned bar
• If the current date falls within the period, display a today line
• Distinguish status not only by color but also by text, pattern, or symbol
• If dependency arrows are densely packed, do not force their rendering; also provide a dependency table
• On mobile, do not crush it; .chart-wrap to enable horizontal scrolling
• Make the same task / start / end / status / progress as in the SVG viewable in a table as well

Do not assign fictitious dates to tasks whose dates are unknown.

Step 5: Create a report spec

Before directly assembling HTML, create an intermediate report spec (JSON) that the renderer can handle. For the specification, refer to references/report-spec.md .

The report spec must include at least the following.

• metadata、title / subtitle、scope、executive summary、findings
• sections、chart definitions、tables、annotations、assumptions、sources

Each chart definition must include at least the following.

• chart type (one of the above 8 types), semantic title, takeaway, units
• series、labels、raw numeric/date data、source、accessibility summary

Do not store computed SVG coordinates in the report spec. Coordinate calculation is the renderer's responsibility. If they do not need to be kept as artifacts within the project, treat them as temporary files.

Step 6: Generate HTML with the renderer

First, check for the presence of the required CLI python3 .

command -v python3 >/dev/null || echo "python3 が見つからない"

If it is not installed, stop the process and provide guidance on how to install it (macOS: brew install python3. For other environments: check the official setup procedure for each environment or consult the environment administrator. Re-run after installation. Do not provide guidance on commands that require privilege escalation).

python3 "${CLAUDE_SKILL_DIR}/scripts/render_report.py" \
  --spec "<report-spec.json>" \
  --output "<output.html>"

If the user does not specify, the output destination is _/reports/<descriptive-report-name>.html. Create the output directory first if necessary.

The renderer is designed to run using only the Python standard library, and does not assume external package installation. For details, refer to references/report-design.md .

HTML information design

Page shell

Required: <!doctype html> / <html lang="..."> / <meta charset="utf-8"> / viewport meta / descriptive <title> / <header> / <main> / semantic <section> / <footer>。

Add a table of contents to long reports.Skip to main content link. Even when using sticky navigation on desktop, do not make the main content width too narrow, and return to the normal flow on mobile.

Visual hierarchy

• Set a max content width and use a single column as the basis. Use a responsive grid only for KPIs and small comparisons
• Limit the line length of long text and provide sufficient whitespace between sections
• Treat a chart and its explanation as a single visual unit
• Do not line up large numbers of KPI cards only. Limit KPIs to "values that are highly worth knowing first for the user"

Chart unit

In principle, each chart should have the structure figure > figcaption(chart title) > takeaway/explanation > SVG > annotation/source > exact-data table .

If possible, the chart title should convey the main trend rather than being a mere noun. Bad example: "Sales Trend". Good example: "Sales have increased for 3 consecutive months since April".

Tables

<caption> / <thead> / <tbody> / <th scope="col"> and use <th scope="row"> as needed. Right-align numbers and keep units and decimal places consistent. Enclose wide tables in .table-wrap { max-width: 100%; overflow-x: auto; } and do not make the entire body scroll horizontally.

Data visualisation rules

For chart-specific details, refer to references/chart-selection.md . Common rules:

• Use the same visual identity for the same series / entity throughout the report, and do not distinguish by color alone
• Use direct labels, line styles, markers, and patterns together as needed
• Place annotations briefly and near the target, and use only as many gridlines as needed for reading
• Do not make axes, units, or periods ambiguous, and place source / note below the chart
• Write key findings in the body text as well, not confined to the chart alone

Axis integrity

bar Axes representing quantity by length should in principle start at 0.line / scatter may use a non-zero baseline as needed, but the scale must not be misleading, and if the truncated range matters, state it explicitly.

Missing values

Do not convert missing data to 0.line represent the missing interval as a gap.N/A・unknown・not measured if they have different meanings, distinguish them.

SVG accessibility

Use inline SVG. As a rule, pair meaningful charts with <svg role="img" aria-labelledby="chart-title-id chart-desc-id"> に <title> / <desc> . Only when the SVG information is completely duplicated by the immediately preceding text and data table, and double reading by a screen reader would have an adverse effect, may aria-hidden="true" be chosen. In either case, do not let important data exist only in the SVG.

Colour and contrast

Use CSS custom properties as design tokens. At minimum, define them in --bg --surface --fg --muted --border --grid --focus --series-1〜 を :root and correspond to color-scheme: light dark と prefers-color-scheme .

Use the Okabe-Ito palette (the de facto standard for color vision diversity support) for categorical series.

#0072B2 #E69F00 #56B4E9 #009E73 #D55E00 #CC79A7 #F0E442 #000000

For up to 4 series, prioritize blue (#0072B2), orange (#E69F00), sky blue (#56B4E9), and vermilion (#D55E00). Keep categorical colors to 6 or fewer.heatmap For continuous values such as these, use perceptually uniform colormaps from the Viridis / Cividis family (distinguishable even in grayscale printing).

Contrast targets: normal text at least 4.5:1, large text at least 3:1, and meaningful chart elements / controls at least 3:1 against the adjacent background.

Do not express positive / negative using only red / green. For example, combine symbols / text as in "↑ +12.4% Increase" and "↓ -8.1% Decrease".

Responsive behaviour

• SVG は viewBox and .chart { width: 100%; height: auto; } as
• layout is Grid / Flexbox, font size includes clamp() may be used
• wide chart は .chart-wrap and do not shrink the chart to the point where meaning is lost on small screens
• On mobile, reduce decorative elements, and when chart labels overlap, use abbreviated labels + a table

Print / PDF-friendly CSS

Always @media print must be provided. For printing, use a light background and dark text, and hide navigation / interactive controls. Ensure URLs and charts do not get cut off outside the page, reduce unnatural page breaks in cards / figures / table rows with break-inside: avoid-page etc., and remove shadows and ink-heavy backgrounds. Do not place important information only inside a closed disclosure.

Interaction policy

In standard mode, do not require JavaScript; first use native HTML / CSS (<details><summary>, anchor navigation, CSS sticky header).

--interactive is specified, or only when there is a large amount of data that is clearly difficult to use in a static display, inline vanilla JavaScript may be added (table search / sort, series visibility, section collapse, theme override, gantt detail toggle, etc.). Because the validator only permits exact matches with the bundled JS injected by the renderer, do not write custom scripts directly into the HTML (to add functionality, extend the renderer's INTERACTIVE_JS ).

However, always observe the following.

• Do not require a click to see the most important message, and do not use hover-only tooltips
• Must be operable by keyboard and do not remove visible focus
• Main information can be read even with JavaScript disabled; animation is generally unnecessary

When adding motion, prefers-reduced-motion: reduce で animation-duration / transition-duration etc. to 0.01ms prepare a branch that shortens it to

Security

For details, refer to references/accessibility-security.md .

Untrusted data

Do not treat user input, external files, or data fetched from the Web as trusted markup. Always centrally use the renderer's escaping function (in Python, the equivalent of html.escape(value, quote=True) ) for strings that go into HTML / SVG text nodes and attributes. Do not reuse the same escape processing for JavaScript / CSS / URL contexts. Do not embed untrusted data directly into <script> / <style> / event handler attributes / raw URLs / raw HTML. After parsing numbers, confirm that they are finite values.

JavaScript

When using inline JavaScript, prohibit external libraries,eval・new Function・untrusted string の innerHTML assignments,onclick="..." and other inline handlers. For DOM insertion, prefer textContent / createElement and use addEventListener .fetch / XMLHttpRequest / WebSocket / EventSource / sendBeacon Do not perform network access such as

Links と external dependency

In principle, allowing external links is limited to source / reference <a href> only, and the URL scheme is https: , and javascript: URLs are prohibited. When opening in a new tab, add rel="noopener noreferrer" .

Prohibited: <script src="https://...">、external stylesheet / font、remote <img>、<iframe src="https://...">、<object data="https://...">、CSS @import / url(https://...)、remote SVG <image> / <use>、runtime network request。

Sensitive data

Do not carelessly embed tokens, credentials, secrets, personal information, or non-public internal information into reports. If a secret is found in the input, redact it as in sk-abc...xyz . If confidential information whose public disclosure status is unknown is included, do not write it to an output destination that is assumed to be public.

Verification

After generation, always run the validator and confirm completion using the following five-stage gate (compliant with.claude/rules/verification.md ).

1. Identification: validate_report.py consider completion to be achieved by executing and checking the exit code of
2. Execution:

   python3 "${CLAUDE_SKILL_DIR}/scripts/validate_report.py" "<output.html>"
   

3. Reading: Check the entire output (PASS/FAIL, failure list) and the exit code
4. Verification: Confirm that there are 0 failures. If there are failures, fix the HTML or report spec, regenerate, and then rerun the validator
5. Declaration: Declare completion only when the validator passes. Do not claim completion based on guesses such as "it will probably pass"

The validator checks at least the following.

• The output file exists and is non-empty, doctype / html / head / body, charset / viewport / title
• duplicate IDs、SVG opening / closing consistency
• There are no external resource dependencies, and no network APIs are used
• unsafe event handler / javascript: no URL
• meaningful chart has an accessible name / description
• Data tables have caption / headers, and there are no serious problems with heading order
• There are no known patterns that induce horizontal body overflow, and print CSS exists
• Source hyperlinks and external resource dependencies are not confused

If possible, also visually check in a browser. Do not treat generation as failed solely because there is no browser tool.

Notes

• The supported chart types are bar / line / scatter / heatmap / waterfall / donut / radar / gantt only. For unsupported relationships, do not force a substitute; use a data table
• Do not use any external CDN, external font, external image, or external JS library. Do not communicate externally on page load
• Do not treat it as complete until the validator passes
• If the report will contain confidential information, confirm with the user in advance that the output destination is not a public area
• If the data to be included in the report contains confidential information or untrusted externally sourced data, and whether it can be embedded is unclear, stop generation and ask the user for confirmation
• If the output destination directory (_/reports/ etc.) does not exist, create it with mkdir -p and then write out

Final Report

On completion, report the following concisely.

• Absolute path of the generated report
• validation result
• One sentence summarizing the main report content
• If interactive mode was used, state that

Example:

HTML レポートを生成しました:
<absolute-path>

Validation: PASS
内容: 3案の性能・コスト・リスク比較と、実装スケジュールの gantt を含みます。

Reference Files

Read only if necessary.

• references/chart-selection.md — details such as selection criteria per chart type, scale, annotation, gantt, heatmap, scatter, etc.
• references/report-design.md — page layout・design tokens・responsive・print・component implementation
• references/report-spec.md — schema and examples of the JSON report spec passed to the renderer
• references/accessibility-security.md — WCAG-oriented checklist、SVG/table accessibility、escaping、safe JavaScript policy
• samples/comparison.json — report spec examples for comparison reports
• samples/project-gantt.json — examples including gantt / milestone / dependency
• samples/time-series.json — examples of time series and annotation

Execution in a sandbox environment

This skill can be executed in a sandbox environment. The renderer (scripts/render_report.py) is purely local Python processing and does not perform operations over the network. The default output destination _/reports/ is inside the workspace, but if an absolute path or a relative path containing--output <path> is specified for ../ , it may write outside the workspace (no constraint is imposed to limit it to within the workspace). Therefore, it cannot be definitively said that "no network is required and there is also no path for writing outside the workspace."--output or specify a path that resolves under the workspace after normalization, the execution results will stay within the workspace.