create-html-report

create-html-report

Based on $ARGUMENTS, convert the analysis results into a self-contained HTML report that "lets you 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.

How to use

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> You can explicitly specify the output destination with

Core contract

The following must always be satisfied.

1. Insight first — Do not make creating a graph an end in itself. First identify the most important conclusions, changes, risks, and decision-making materials, and use only visualizations that help understand them.
2. Do not invent data — Do not fill in unknown values, dates, percentages, units, or statuses by guessing. Treat missing data 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. Regular <a href="https://..."> to data sources is not considered an external dependency. Do not communicate externally on page load.
4. Accessible by default — Do not rely on color alone to convey information. Ensure the main content of graphs can also be checked in text or tables. Consider keyboards, screen readers, dark mode, and enlarged display.
5. Progressive enhancement — Ensure key conclusions and data can be read without JavaScript. Add interaction only when it aids 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 decisions are to be made
• Targets and period, metrics and units, data sources
• Comparison targets, schedules and dependencies, uncertainties and missing values

Do not ask questions if these can be sufficiently inferred from the conversation or existing data. If a useful partial report can be created despite insufficient information, do not fill in values on your own; state them explicitly as "constraints and missing information" and proceed. Ask minimal confirming questions only when the purpose or inputs are 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 and 3–5 key findings
• Decisions/recommendations, data supporting findings, information for detailed review

In principle, organize the information hierarchy in the following order.

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 details below.

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

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

Relationship to convey	chart type	Notes
Comparing magnitude/ranking between categories	bar	Horizontal bars recommended, axis starting at 0
Trends/changes over time	line	Express missing data as gaps; do not fabricate data
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 show 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 durations, dependencies, milestones	gantt	If dependencies are dense, also provide a table

For relationships not covered above (distribution, before/after, multi-series comparison, etc.), avoid easily substituting a supported chart type, and prioritize expressing them with 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 overviewing the "shape" of a multi-axis profile itself, so use them only when the axes are few and can be legitimately normalized to the same scale.

Chart anti-patterns

As a rule, avoid the following.

• 3D charts, gauge / speedometer, unnecessary gradients, excessive shadows
• Dual-axis charts, line charts overlaying 10 or more series, donuts with a large number of slices
• Charts for decorative purposes only, charts with inconsistent baselines despite being intended for 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 charts satisfy 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 shapes other than bars, such as diamonds
• 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 make it horizontally scrollable with
• Make the same task / start / end / status / progress as 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 assembling HTML directly, create an intermediate report spec (JSON) that the renderer can handle. For the specification, refer to references/report-spec.md .

The report spec must contain at least the following.

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

Each chart definition must contain at least the following.

• chart type (one of the above 8), 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 it does not need to be kept as an artifact within the project, treat it as a temporary file.

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 processing and provide guidance on how to install it (macOS: brew install python3. Other environments: check the official setup procedure for each environment or consult the environment administrator. Re-run after installation. Do not suggest commands that require privilege escalation).

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

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

The renderer shall be designed to work with only the Python standard library, and shall 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>。

For long reports, add a table of contents.Skip to main content links. 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 take sufficient whitespace between sections
• Treat a chart and its explanation as one visual unit
• Do not line up only a large number of KPI cards. Limit KPIs to "values that are most valuable for the user to know first"

Chart unit

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

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 necessary. Right-align numbers and keep units and number of digits consistent. Wrap wide tables in .table-wrap { max-width: 100%; overflow-x: auto; } and do not make the entire body horizontally scrollable.

Data visualisation rules

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

• Use the same visual identity throughout the report for the same series / entity, and do not distinguish by color alone
• Use direct labels, line styles, markers, and patterns in combination as necessary
• Place annotations briefly near the target, and use only as many gridlines as necessary 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 In principle, axes that represent the quantity of something by length start from 0.line / scatter may use a non-zero baseline as needed, but use a scale that does not mislead, and make it explicit if the truncated range is important.

Missing values

Do not convert missing data to 0.line In this case, represent missing intervals as gaps.N/A・unknown・not measured if they have different meanings, distinguish them.

SVG accessibility

Use inline SVG. In principle, for meaningful charts, <svg role="img" aria-labelledby="chart-title-id chart-desc-id"> に <title> / <desc> and correspond them. Only when the information in the SVG is completely duplicated by the immediately preceding prose and the data table, and double reading by screen readers would have an adverse effect, aria-hidden="true" may 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 a minimum, define them in --bg --surface --fg --muted --border --grid --focus --series-1〜 を :root and correspond to color-scheme: light dark と prefers-color-scheme .

For categorical series, use the Okabe-Ito palette (the de facto standard for color vision diversity accessibility).

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

For four or fewer series, prioritize blue (#0072B2), orange (#E69F00), sky blue (#56B4E9), and vermilion (#D55E00). Keep categorical colors to six or fewer.heatmap and other continuous values use perceptually uniform color schemes such as Viridis / Cividis (discriminable even in grayscale printing).

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

Do not express positive / negative using only red / green. For example, use symbols / text together, such as "↑ +12.4% Increase" or "↓ -8.1% Decrease".

Responsive behaviour

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

Print / PDF-friendly CSS

Always @media print provide. When printing, use a light background and dark text, and hide navigation / interactive controls. Prevent URLs and charts from being 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 allows an exact match 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, do not use hover-only tooltips
• Make it operable by keyboard and do not remove visible focus
• Main information is readable even when JavaScript is disabled; animation is in principle unnecessary

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

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. Strings that enter HTML / SVG text nodes and attributes must always be handled through the renderer's escaping function in a centralized way (in Python, the equivalent of html.escape(value, quote=True) ). 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, verify that they are finite values.

JavaScript

When using inline JavaScript, prohibit external libraries, assignment toeval・new Function・untrusted string の innerHTML , inline handlers such asonclick="..." , etc. For DOM insertion, prefer textContent / createElement and use addEventListener . Do not perform network access such asfetch / XMLHttpRequest / WebSocket / EventSource / sendBeacon .

Links と external dependency

In principle, allow external links only for the <a href> only, and the URL scheme is https: of sources / references, and prohibit javascript: URLs. 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 the report. If a secret is found in the input, redact it as in sk-abc...xyz . If confidential information whose public disclosure status is unclear is included, do not write it to an output destination intended for publication.

Validation

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

1. Identify: validate_report.py consider completion to be established by execution of and exit code
2. Run:

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

3. Read: Check the entire output (PASS/FAIL, list of failures) and the exit code
4. Verify: Confirm that there are 0 failures. If there are failures, fix the HTML or report spec, regenerate, and then rerun the validator
5. Declare: Declare completion only when the validator has passed. 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 with each other

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 only bar / line / scatter / heatmap / waterfall / donut / radar / gantt . For unsupported relationships, do not force a substitute; use a data table
• Do not use any external CDN, external fonts, external images, or external JS libraries. Do not communicate externally during page load
• Do not treat it as complete until the validator passes
• If the report will contain confidential information, confirm with the user beforehand that the output destination is not a public area
• If the data to be turned into a report contains confidential information or untrusted externally sourced data, and whether it can be embedded is unclear, stop generation and ask the user to confirm
• If the output destination directory (_/reports/ etc.) does not exist, create it with mkdir -p before writing out

Final report

When complete, report the following concisely.

• Absolute path of the generated report
• validation result
• A one-sentence summary of the main report content
• If interactive mode was used, state that

Example:

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

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

Reference files

Read only when 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 — Example report spec for a comparison report
• 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 inside the workspace). Therefore, it cannot be said definitively that "no network is required and there is no path for writing outside the workspace."--output is omitted, or a path that resolves under the workspace after normalization is specified, the execution result stays within the workspace.