# HTML Report
> コードレビュー・調査・バグ解析・リサーチ・セキュリティ監査・改善提案の結果を、見やすいHTMLレポートとして保存・表示するスキル。「レポートを保存して」「結果をまとめて」「HTMLに出力して」「ドキュメントに残して」「レポートにして」などと言われたときに必ず使用する。また、明示的に依頼されていなくても、調査・レビュー・比較検討・改善提案の結果が長く構造を持つ（複数の指摘、比較表、複数観点の調査結果、「改善アイデア」「ブラッシュアップ案」「〜の仕様書」など）場合は、このスキルの使用をユーザーに提案する。種別を自動判定し、設定された保存先へ番号付きHTMLを生成してブラウザで表示する。Mermaid図・SVG図・進捗バー・重要度バッジ・目次・ダークモードに対応。
- Skill: `ntaksh42/html-report` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add ntaksh42/html-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ntaksh42/html-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ntaksh42 (https://skillmd.com/u/ntaksh42)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/ntaksh42/html-report
---
# html-report
会話で出したレビュー・調査・バグ解析などの結果を、読みやすい HTML レポートとして保存する。
ターミナルの平文は、指摘が 10 件並んだり比較軸が 3 つ以上あると急に読みづらくなる。このスキルは、そういう「構造を持つ長い成果物」を一覧できる形に変えるためにある。
## 進め方
本文を Markdown で書き、スクリプトに渡す。HTML の組み立て・番号採番・保存先解決はスクリプトが行うので、**中身の執筆に集中する**。
```
1. 種別を判定
2. 本文を Markdown で書く（一時ファイルへ）
3. New-HtmlReport.ps1 を実行
```
### Step 1: 種別を判定
会話の内容から選ぶ。判断に迷ったら `investigation`。
| 種別 | 対象 | 色 |
|---|---|---|
| `review` | コードレビュー、PR レビュー | 青 |
| `bug` | バグ調査、不具合解析 | 赤 |
| `investigation` | コード調査、動作調査 | 紫 |
| `research` | 技術調査、リサーチ、比較検討 | シアン |
| `security` | セキュリティ監査 | オレンジ |
| `proposal` | 改善提案、ブラッシュアップ案、設計案、仕様書 | ティール |
`investigation` と `proposal` は紛らわしい。**今どうなっているかを説明するなら `investigation`、これからどうするかを提案するなら `proposal`**。「改善アイデア」「〜案」は後者。
種別は色とバッジと保存先を決めるだけで、本文の書き方に制約は無い。
### Step 2: 本文を書く
Markdown で書いて一時ファイルに保存する。使える記法は `references/markdown-syntax.md` を参照 — 表・Mermaid 図・SVG・進捗バー・重要度バッジなどがある。
**`##` がセクションカードになる**ので、これがレポートの骨組みになる。3〜6 個が読みやすい。5 個以上になると目次が自動で付く。
種別ごとの構成例（そのまま使う必要はなく、内容に合わせて調整してよい）:
- **review**: レビュー概要 / 重大な指摘 / 改善提案 / 良い点 / まとめ
- **bug**: 概要・再現方法 / 調査結果 / 根本原因 / 修正方針 / まとめ
- **investigation**: 背景・目的 / 調査結果 / 原因分析 / 推奨対応 / まとめ
- **research**: 調査目的 / 調査結果 / 比較・評価 / 結論・推奨 / 参考情報
- **security**: 監査概要 / 脆弱性 / リスク / 問題なし / まとめ
- **proposal**: 現状と課題 / 提案内容 / 案の比較 / 想定コスト・リスク / 推奨
構成を機械的に埋めるより、**その調査で実際に分かったことの形に合わせる**ほうがよい。原因が特定できなかった調査に「根本原因」の空セクションを置くくらいなら、「絞り込んだ範囲」と書いたほうが伝わる。
#### 内容の忠実さ
会話で出した結論を要約し直さない。指摘が 12 件あったなら 12 件すべて載せる。レポートは後から見返すためのもので、そのとき「会話ではもっと詳しく言っていたはず」となるのが一番困る。
一方、会話の試行錯誤（読んだファイル、外した仮説）は不要。**結論と根拠を残し、過程は落とす**。
会話から読み取れない項目（PR 番号など）は推測せず「-」と書く。
#### 図を使う判断
文章で説明すると 3 文以上かかる関係性があるなら図にする。処理フロー、状態遷移、コンポーネント間の依存などが該当する。装飾目的では入れない。
Mermaid は CDN で描画する。オフラインでは図の代わりに定義がコードとして表示される（読めなくはないが図にはならない）ので、確実に残したい図は SVG で書く。
### Step 3: 生成する
```powershell
& "$HOME\.claude\skills\html-report\scripts\New-HtmlReport.ps1" `
-Kind bug `
-Title "ログイン断続失敗の調査" `
-Subtitle "src/auth/session.ts" `
-BodyPath "<本文.md のパス>" `
-Cards "バグID|#142","ステータス|原因特定","影響範囲|認証全体"
```
| パラメータ | 説明 |
|---|---|
| `-Kind` | 種別（必須） |
| `-Title` | タイトル（必須） |
| `-Subtitle` | 対象の説明。ブランチ名、調査対象など |
| `-BodyPath` | 本文 Markdown のパス（必須） |
| `-Cards` | サマリーカード。`ラベル\|値\|補足` を最大 3 つ |
| `-Number` | 番号を明示指定。省略時は自動採番 |
| `-NoOpen` | ブラウザで開かない |
ユーザーが「PR #123」のように番号に言及していれば `-Number 123` を渡す。無ければ自動採番に任せる。
サマリーカードは「開いた瞬間に把握したい 3 つ」を選ぶ。値は 12 文字以内が収まりよく、長いと自動で縮小される。
**件数だけを並べない**。`アイデア数 28件 / 対応不要 18件 / 推奨 6件` のようなカードは、要約に見えて「28 件を読め」と言っているだけで、読み手の負荷はむしろ増える。同じ枠を使うなら、読まなくても行動が決まる一言を入れる。
- 良い: `まず着手\|内訳タブの拡張`、`結論\|Grafana 採用`、`ステータス\|修正済み`
- 惜しい: `改善案\|30件`、`調査対象\|3製品`
件数そのものは、重大度サマリー（`[!red]` の総数を自動集計してヘッダー下に表示）と目次の項目数バッジが自動で見せるので、カードで重ねる必要はない。
生成後は保存先パスを報告する。スクリプトが自動でブラウザを開く。
## 保存先
`output-config.toml` で設定する。既定は `~/reports/<種別>/<番号>.html`。
番号は保存先の既存ファイルから自動採番される（最大番号 + 1）。
## トラブル時
**文字化けする**: 本文 Markdown を UTF-8 で保存しているか確認する。
**図が出ない**: 「図を描画できませんでした（オフライン）」と出ていれば CDN に届いていない。SVG に書き換えれば依存なしで残せる。注記が出ずに図だけ崩れる場合は Mermaid 記法自体の誤りで、[Mermaid Live Editor](https://mermaid.live) で確認できる。
**表が崩れる**: セル内の `|` は `\|` にエスケープする。
**スクリプトが見つからない**: `claude/install.ps1` を再実行して `~/.claude/skills/` へ展開する。